curl -X POST /v1/jobs \
  -H "Authorization: Bearer dct_…" \
  -H "Idempotency-Key: phim-001" \
  -F srt=@phim.srt \
  -F voice_id=vo_… \
  -F language=vi \
  -F speed=1.0

language: auto hoặc một trong 646 ngôn ngữ được hỗ trợ, gửi mã (vi, en, yue…) hoặc tên tiếng Anh như app (Vietnamese). Danh sách đầy đủ: /languages.json. Riêng vi, en, zh, ru được kiểm tra câu sai ngôn ngữ trước khi nhận job.
Nhiều file: mỗi file SRT là một job. Máy chủ nhận cả loạt ngay (tối đa 100 job đang chờ), rồi chạy lần lượt theo số job song song của tài khoản. Job được chờ tối đa 72 giờ để bắt đầu, và có 24 giờ để chạy xong kể từ lúc bắt đầu; quá hạn thì phần chưa đọc được hoàn ký tự và có thể chạy lại. Chạy lại: POST /v1/jobs/{id}/retry với job lỗi, xong một phần hoặc đã huỷ tạo job mới chỉ gồm các câu còn thiếu (giữ số thứ tự và mốc thời gian gốc; gọi lại nhiều lần vẫn trả cùng một job). Kết quả tự xoá sau 48 giờ.
Phân vai nhiều giọng: câu trong SRT bắt đầu bằng #TênVai: (có thể kèm cảm xúc: #Nam [vui]: … hoặc [buồn] …). Gửi thêm role_voice_map={"#Nam":"vo_…","#Nữ":"vo_…"} và/hoặc role_speed_map={"#Nam":1.2} (JSON, tối đa 30 vai). Vai không gán dùng voice_id. Phân vai và cảm xúc chỉ dùng với giọng mẫu (voice_id); với instruct các nhãn này được bỏ qua. Nhãn vai/cảm xúc không tính phí.
Gợi ý: Dùng tham số instruct (ví dụ: female, young adult, moderate pitch) thay cho voice_id nếu không có sẵn file giọng mẫu. Gửi lại cùng Idempotency-Key trong vòng 24 giờ sẽ không bị trừ trùng credit. Tuỳ chọn thêm callback_url (HTTPS) để máy chủ tự động gọi Webhook khi job hoàn tất.
Văn bản không có mốc thời gian: gửi thêm layout=sequence — file WAV ghép sẽ nối liền các câu theo độ dài thật (nghỉ 0,3 giây) thay vì đặt theo mốc thời gian trong SRT.

curl /v1/jobs/job_… -H "Authorization: Bearer dct_…"

Trạng thái (status) trả về lần lượt: queued (chờ máy) → running (đang đọc) → done (hoàn tất) | partial | error | cancelled. Kèm theo done_segments, segments và thời gian ước tính eta_sec. voices cho biết tên các giọng job dùng (kể cả giọng đã xoá); result_expires_at là lúc kết quả tự xoá, hãy tải về trước thời điểm đó.

# Tải file ZIP chứa từng câu lẻ 1.wav, 2.wav... (theo số thứ tự trong file SRT) kèm manifest.json.
# File tải về mang tên file SRT; thêm ?name=ten_ban_muon để đặt tên khác.
curl -fL -o ket_qua.zip /v1/jobs/job_…/result -H "Authorization: Bearer dct_…"

# Hoặc tải file WAV đã ghép chuẩn mốc thời gian:
curl -fL -o ket_qua.wav "/v1/jobs/job_…/result?format=wav" -H "Authorization: Bearer dct_…"

# Phụ đề SRT khớp với file WAV ghép ở trên (thời gian thật của từng câu đã đọc):
curl -fL -o ket_qua.srt "/v1/jobs/job_…/result?format=srt" -H "Authorization: Bearer dct_…"

curl -X POST /v1/voices \
  -H "Authorization: Bearer dct_…" \
  -F audio=@mau.wav \
  -F name="Giọng A" \
  -F ref_text="Lời đọc chính xác trong file mẫu" \
  -F language=vi \
  -F consent=true

# Nghe lại file mẫu đã tải lên:
curl -fL -o mau.wav /v1/voices/vo_…/audio -H "Authorization: Bearer dct_…"

# Sửa tên, ngôn ngữ/quốc gia (cờ) hoặc câu mẫu:
curl -X PATCH /v1/voices/vo_… -H "Authorization: Bearer dct_…" \
  -H "Content-Type: application/json" -d '{"name":"Giọng A","language":"vi"}'

import time, requests

API = ""
HEADERS = {"Authorization": "Bearer dct_…"}

# 1. Gửi file SRT tạo job
with open("phim.srt", "rb") as f:
    job = requests.post(
        f"{API}/v1/jobs",
        headers={**HEADERS, "Idempotency-Key": "tap-01"},
        files={"srt": f},
        data={"voice_id": "vo_…", "language": "vi", "speed": "1.0"}
    ).json()

print(f"Đã tạo job: {job['id']}, chờ xử lý...")

# 2. Polling kiểm tra trạng thái
while True:
    s = requests.get(f"{API}/v1/jobs/{job['id']}", headers=HEADERS).json()
    if s["status"] not in ("queued", "running"):
        break
    time.sleep(10)

# 3. Tải kết quả âm thanh
if s["status"] in ("done", "partial"):
    with requests.get(f"{API}/v1/jobs/{job['id']}/result", headers=HEADERS, stream=True) as r, open("output.zip", "wb") as out:
        for chunk in r.iter_content(1024 * 1024):
            out.write(chunk)
    print("Tải kết quả hoàn tất!")