Sota Voice
Tài liệu

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.

Xem dạng Markdown

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
}
  • input tố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ài input phải dưới 16 KiB.
  • webhook_url phải là https và 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).
  • failed hoặc cancelled: phần giữ trước được trả lại. error có 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.