Tài liệu API
tts-3
Chuyển văn bản thành giọng nói — Chuyển văn bản dài tới 100.000 ký tự thành giọng đọc AI tiếng Việt & đa ngôn ngữ tự nhiên như người thật, tuỳ chỉnh tốc độ và nhịp ngắt nghỉ dấu câu.
type: giong-noi-aioutput: audioTheo tham số — dùng POST /v1/generations/estimate để báo giá
Input — tham số đầu vào
POST
/v1/generationsGửi JSON gồm "model": "tts-3" và các tham số dưới đây ở cùng cấp. Tham số không có trong bảng sẽ bị từ chối (400).
| Tham số | Kiểu | Giá trị hỗ trợ | Mô tả |
|---|---|---|---|
modelrequired | string | tts-3 | Mã model |
voicerequired | enum | vi_male_adamvi_male_anhquan_1vi_male_duyonyx_1vi_hoangnam_storyvi_hoangnam_story_ipavi_male_ngocngan_ipavi_male_ngocngan_ipa_2vi_quynhanh_ipavi_female_quynh_anhvi_taman_phatvi_male_baotrung_1clone_b8f7f83b_b_nh_ng__pro_59e323clone_b8f7f83b_ch__m_nh_7722abclone_b8f7f83b_david_pro_ea54e9clone_b8f7f83b_huy_n_v__82a46fclone_b8f7f83b_kim_v_n_64cb11clone_b8f7f83b_ph_t_ph_p_42d7beclone_b8f7f83b_qu_nh_69ac98clone_b8f7f83b_rivew_phim_4bc2eeclone_b8f7f83b_rivew_phim_trung_bac91cclone_b8f7f83b_t_m_an_7b6232clone_b8f7f83b_th_y_trang_25e7ffclone_b8f7f83b_thuy_trang_2_0_2db255clone_b8f7f83b_t__phan_b3eba7tl_female_fil_2en_male_dung_1tl_female_fil_1en_male_history_1en_female_kawaii_1en_male_review_1en_male_review_bau_1ja_female_doanh_1ko_female_sellyhan_1clone_b8f7f83b_adas_4dd8f2clone_b8f7f83b_anna_van_1a954cclone_b8f7f83b_documentary_a_c3b72eclone_b8f7f83b_duyxx_22c001clone_b8f7f83b_frieren_5355c3clone_b8f7f83b_frierenf_5_0_c32368clone_b8f7f83b_hauda_3e78d5clone_b8f7f83b_hyau_b119c1clone_b8f7f83b_hyuna_2336e0clone_b8f7f83b_lia_a1e09dclone_b8f7f83b_manhwa_fresh_5_0_6dc744clone_b8f7f83b_manhwa_fresh_6_0_11a349clone_b8f7f83b_mask_us_9d5c04clone_b8f7f83b_msea_63c733clone_b8f7f83b_old_man_53180fclone_b8f7f83b_otana_72cfc6clone_b8f7f83b_podcast_mrdung_5c8e70clone_b8f7f83b_ruysea_94fbb5clone_b8f7f83b_seui_9cddd5clone_b8f7f83b_thanh_chung_198dd0clone_b8f7f83b_th_nh_chung_2_0_343c8a Mặc định: | Giọng đọc AI |
textrequired | string | Tối đa 100.000 ký tự | Văn bản cần chuyển thành giọng nói — Hỗ trợ tới 100.000 ký tự mỗi lượt. Nên dùng dấu chấm, dấu phẩy và xuống dòng rõ ràng để AI ngắt nhịp tự nhiên nhất. |
languagerequired | enum | autovienzhesfrdejakoitptruarhibnidmsthtlnltrplsvdanofielhecshuro Mặc định: | Ngôn ngữ đọc |
speedrequired | enum | 0.750.91.01.11.251.51.752.0 Mặc định: | Tốc độ đọc |
pause_presetrequired | enum | defaultnaturalstoryfast Mặc định: | Nhịp ngắt nghỉ dấu câu |
formatrequired | enum | mp3wav Mặc định: | Định dạng xuất âm thanh |
- Tham số file (string URL) nhận link công khai http(s) — máy chủ tự tải về — hoặc URL trả về từ API tải file POST /account/ai/uploads.
- Bỏ trống tham số không bắt buộc thì dùng giá trị mặc định.
Ví dụ request (cURL)
curl -X POST https://dopie.ai.vn/api/v1/generations \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
-d '{
"model": "tts-3",
"voice": "vi_male_adam",
"text": "Một chú mèo phi hành gia",
"language": "auto",
"speed": "1.0",
"pause_preset": "default",
"format": "mp3"
}'Code mẫu tích hợp đầy đủ (Upload file → Tạo tác vụ → Nhận kết quả)
Python 3
import os, time, requests
BASE = "https://dopie.ai.vn/api"
HEADERS = {"X-API-Key": os.environ["API_KEY"]}
gen = requests.post(f"{BASE}/v1/generations", headers=HEADERS, json={
"model": "tts-3",
"voice": "vi_male_adam",
"text": "Một chú mèo phi hành gia",
"language": "auto",
"speed": "1.0",
"pause_preset": "default",
"format": "mp3"
}, timeout=60).json()
while gen.get("status") in ("queued", "processing"):
time.sleep(5)
gen = requests.get(f"{BASE}/v1/generations/{gen['id']}", headers=HEADERS, timeout=60).json()
if gen.get("status") != "succeeded":
raise RuntimeError(gen.get("error") or gen.get("status"))
print("Kết quả:", gen["output"])Node.js (18+)
const BASE = "https://dopie.ai.vn/api";
const headers = { "X-API-Key": process.env.API_KEY, "Content-Type": "application/json" };
let gen = await fetch(`${BASE}/v1/generations`, {
method: "POST",
headers,
body: JSON.stringify({
"model": "tts-3",
"voice": "vi_male_adam",
"text": "Một chú mèo phi hành gia",
"language": "auto",
"speed": "1.0",
"pause_preset": "default",
"format": "mp3"
}),
}).then((r) => r.json());
while (["queued", "processing"].includes(gen.status)) {
await new Promise((r) => setTimeout(r, 5000));
gen = await fetch(`${BASE}/v1/generations/${gen.id}`, { headers }).then((r) => r.json());
}
if (gen.status !== "succeeded") throw new Error(gen.error ?? gen.status);
console.log("Kết quả:", gen.output);Output — kết quả trả về
Tác vụ chạy bất đồng bộ. POST /v1/generations trả ngay đối tượng generation với status queued hoặc processing; hỏi lại GET /v1/generations/{id} mỗi 5–10 giây tới khi status là succeeded, failed hoặc cancelled.
GET
/v1/generations/{id}{
"id": "3f1c...-uuid",
"object": "generation",
"code": "T8KQ2M4X",
"model": "tts-3",
"status": "succeeded", // queued | processing | succeeded | failed | cancelled
"progress": 100,
"cost": 2400, // số tiền đã trừ
"currency": "VND",
"refunded": false,
"output": {
"type": "audio",
"files": [{ "url": "https://dopie.ai.vn/uploads/ai/outputs/....mp3", "type": "audio", "name": "audio.mp3" }],
"text": null
},
"error": null,
"created_at": "2026-10-30T08:00:00.000Z",
"completed_at": "2026-10-30T08:01:12.000Z"
}| Trường | Ý nghĩa |
|---|---|
| output.files[].url | Link file kết quả — nên tải về hệ thống của bạn, file trên máy chủ có thể được dọn sau một thời gian. |
| output.text | Nội dung văn bản (chỉ có với model trả văn bản). |
| cost | Số tiền VND đã trừ vào số dư; lỗi hoặc huỷ thì tự hoàn lại (refunded = true). |
| error | Lý do lỗi khi status = failed. |
Báo giá trước khi chạy
POST
/v1/generations/estimateCùng body với POST /v1/generations, không chạy và không trừ tiền.
# => { "object": "estimate", "model": "tts-3", "cost": 2400, "currency": "VND" }