Tài liệu API
voice-clone
Nhân bản giọng nói AI — Tải lên 1 đoạn thu âm giọng mẫu (5–20 giây) kèm câu thoại mẫu để AI học âm sắc và đọc bất kỳ kịch bản mới nào bằng chính giọng đó.
type: giong-noi-aioutput: audioMiễn phí
Input — tham số đầu vào
POST
/v1/generationsGửi JSON gồm "model": "voice-clone" 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 | voice-clone | Mã model |
ref_audio_urlrequired | string (URL audio) | File giọng mẫu (5–25 giây) — Chọn đoạn thu âm 1 người nói rõ ràng, không dính nhạc nền hay tiếng ồn (hỗ trợ WAV, MP3, M4A thu âm điện thoại, FLAC, OGG). | |
ref_textrequired | string | Tối đa 2.000 ký tự | Lời nói chính xác trong file mẫu — Càng khớp chính xác lời trong file mẫu thì giọng nhân bản ra càng giống và tròn chữ. |
textrequired | string | Tối đa 100.000 ký tự | Văn bản muốn đọc bằng giọng nhân bản |
languagerequired | enum | vienzhesfrdejakoitptruarhibnidmsthtlnltrplsvdanofielhecshuro Mặc định: | Ngôn ngữ giọng mẫu |
genderrequired | enum | femalemale Mặc định: | Giới tính giọng mẫu |
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": "voice-clone",
"ref_audio_url": "https://example.com/audio.mp3",
"ref_text": "Một chú mèo phi hành gia",
"text": "Một chú mèo phi hành gia",
"language": "vi",
"gender": "female",
"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"
API_KEY = os.environ["API_KEY"]
HEADERS = {"X-API-Key": API_KEY}
with open("./input.mp3", "rb") as f:
up = requests.post(f"{BASE}/account/ai/uploads", headers=HEADERS, files={"file": f}, timeout=120).json()
payload = {
"model": "voice-clone",
"ref_audio_url": "https://example.com/audio.mp3",
"ref_text": "Một chú mèo phi hành gia",
"text": "Một chú mèo phi hành gia",
"language": "vi",
"gender": "female",
"speed": "1.0",
"pause_preset": "default",
"format": "mp3"
}
payload["ref_audio_url"] = up["url"]
gen = requests.post(f"{BASE}/v1/generations", headers=HEADERS, json=payload, 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ả:", [f["url"] for f in gen["output"]["files"]])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": "voice-clone",
"ref_audio_url": "https://example.com/audio.mp3",
"ref_text": "Một chú mèo phi hành gia",
"text": "Một chú mèo phi hành gia",
"language": "vi",
"gender": "female",
"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": "voice-clone",
"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": "voice-clone", "cost": 2400, "currency": "VND" }