Conventions

Async task model

Most generation endpoints are asynchronous:

POST create  →  returns task_id
GET  status  →  poll until completed / failed

flowchart LR
  A[POST create] --> B(task_id)
  B --> C{GET poll status}
  C -- processing --> C
  C -- completed --> D[get result URL]
  C -- failed --> E[read error]

Status values

Four normalized statuses are exposed (each model's upstream states map into these):

Polling guidance

2s after submit  → first status check
then             → every 3–5s
video/podcast    → may take several minutes

Billing

• Per character (audio): CJK char = 2, others = 1; some capabilities have a minimum (e.g. voice design ≥10).
• Per second (video): rate-per-second × duration, rounded up.
• Fixed: some models charge a flat amount per call.
• Refund on failure: credits are auto-refunded when a task fails (Seedance, Sora2, Drama, …).
• Credits settle on completion — failed tasks are not charged.

Error codes

{ "error": "insufficient_credits", "message": "Not enough credits." }

Pagination

List endpoints share: