Job bất đồng bộ
Đọc văn bản dài (đến 100.000 ký tự), theo dõi trạng thái và tải file audio.
Với văn bản dài (sách, bài báo, kịch bản), tạo một job: API trả về ngay với status: "queued", việc sinh audio chạy nền. Khi xong, bạn nhận webhook hoặc hỏi lại trạng thái, rồi tải file.
Tạo job
curl https://voice-be.sotalabs.io/v1/audio/speech/jobs \
-H "Authorization: Bearer $SOTA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7d3f6c1e-4a52-4c1b-9a86-2f0e5b8d1c34" \
-d '{"model":"sota-voice-v1","voice":"default","input":"Chương một. Ngày xửa ngày xưa...","response_format":"mp3","webhook_url":"https://example.com/hooks/sota"}'{
"id": "job_01jd8x3k9q4m7n2p5r6s8t0v1w",
"object": "speech.job",
"status": "queued",
"model": "sota-voice-v1",
"voice": "default",
"response_format": "mp3",
"characters": 1840,
"webhook_url": "https://example.com/hooks/sota",
"created_at": 1763366400,
"started_at": null,
"completed_at": null,
"expires_at": null,
"error": null
}inputtối đa 100.000 ký tự (code point NFC). Các field khác nhưPOST /v1/audio/speech(voice,response_format,literal_punctuation; không cósplit_granularity, tùy chọn chỉ dành cho WebSocket); tùy chọn stream bị bỏ qua. Tổng các field ngoàiinputphải dưới 16 KiB.webhook_urlphải làhttpsvà không trỏ tới địa chỉ IP nội bộ, nếu không:422 invalid_webhook_url.
Idempotency
Gửi header Idempotency-Key (1-255 ký tự, ví dụ một UUID) để retry không tạo và tính phí job thứ hai:
- Cùng key, cùng body: trả lại job ban đầu, kèm header
Idempotent-Replayed: true. - Cùng key, body khác:
409 idempotency_key_reused. - Key không dài 1-255 ký tự:
422 idempotency_key_invalid.
Vòng đời và tính phí
queued ──▶ in_progress ──▶ completed (trừ credit, lưu audio 7 ngày)
│ └──▶ failed (trả lại credit giữ trước, có error)
└──▶ cancelled (trả lại credit giữ trước)- Khi tạo, credit bằng số ký tự của
inputđược giữ trước. Không đủ:402 insufficient_credit. completed: bị tính phí; audio lưu 7 ngày (expires_at).failedhoặccancelled: phần giữ trước được trả lại.errorcócode(cùng bảng mã lỗi) vàmessage.- Job bất đồng bộ không tính vào giới hạn request realtime đồng thời.
Theo dõi trạng thái
Ưu tiên webhook. Nếu cần hỏi lại, gọi GET /v1/audio/speech/jobs/{id} với khoảng cách vài giây:
curl https://voice-be.sotalabs.io/v1/audio/speech/jobs/job_01jd8x3k9q4m7n2p5r6s8t0v1w \
-H "Authorization: Bearer $SOTA_API_KEY"Liệt kê job: GET /v1/audio/speech/jobs (mới nhất trước), phân trang bằng limit (1-100, mặc định 20), after, before, order.
Hủy job
POST /v1/audio/speech/jobs/{id}/cancel hủy job còn queued và trả lại credit. Job đang chạy hoặc đã xong: 409 job_not_cancellable.
Tải audio
GET /v1/audio/speech/jobs/{id}/content trả 302 tới một URL tải có chữ ký, hiệu lực 15 phút. Khi theo redirect, đừng gửi header Authorization tới máy chủ lưu trữ (curl -L và hầu hết HTTP client tự bỏ header này khi đổi host).
curl -L https://voice-be.sotalabs.io/v1/audio/speech/jobs/job_01jd8x3k9q4m7n2p5r6s8t0v1w/content \
-H "Authorization: Bearer $SOTA_API_KEY" \
--output chapter-1.mp3- Job chưa
completed:409 job_not_ready. - Sau 7 ngày audio bị xóa:
410 job_expired.