API reference
OpenAI-shaped, so most SDKs need only a base-URL change. Submit returns
202 immediately; poll the job id until it reaches a terminal state. The
everything happens in one job id.
| Endpoint | Purpose |
|---|---|
POST /v1/videos |
Submit a job. Returns 202 with an id, or 429 + Retry-After when your concurrency bucket is full. |
GET /v1/videos/{id} |
Poll. Advances the state machine, so poll steadily — an unpolled job is reclaimed. |
GET /v1/models |
The masked catalogue. Aliases only; real upstream ids are never exposed. |
GET /v1/usage |
Daily and monthly rollups at list price, split by resolution, duration and model. |
GET /v1/capacity |
Live headroom for your own bucket plus hub_total. Check before submitting a burst. |
GET /v1/billing/balance |
Plan, granted credit and consumed credit for hosted-key tenants. |
GET /healthz |
Liveness, provider identities and a capacity snapshot. No auth required. |
Only model and a prompt (or
image_url) are required. Everything else has a default. Bad input is
rejected with 400 before a concurrency slot is reserved, so a
malformed request never costs you capacity.
curl -X POST https://cliplus.byteplus.workers.dev/v1/videos \
-H "Authorization: Bearer cl_15f19a4c7b2e..." \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"prompt": "a paper boat crossing a rain puddle at dusk",
"metadata": {
"resolution": "1080p",
"duration": 5,
"fps": 24,
"ratio": "16:9"
}
}'// 202 Accepted
{
"id": "job_8f3c21a0",
"object": "video.generation",
"status": "queued",
"stage": "generating"
}# status: queued -> running -> succeeded | failed
# stage: generating -> done
curl https://cliplus.byteplus.workers.dev/v1/videos/job_8f3c21a0 \
-H "Authorization: Bearer cl_15f19a4c7b2e..."{
"id": "job_8f3c21a0",
"status": "succeeded",
"url": "https://.../job_8f3c21a0-1080p.mp4",
"metadata": {
"resolution": "1080p",
"requested_resolution": "1080p",
"duration": 5,
"fps": 24,
"ratio": "16:9",
"output": { "codec": "h264",
"container": "mp4" }
},
"usage": { "currency": "USD",
"cost": 0.859 }
}Every Cliplus key is a hosted key. You create it on your dashboard, it is scoped to your account, and you can revoke it at any time without affecting anyone else.
cl_…40 random hex characters, minted when you click Create key. Only a SHA-256 hash, a 9-character prefix and the last 4 characters are stored, so the plaintext exists exactly once — in the response that created it. Copy it then; it is never shown again.
You get: real revocation, per-key usage and spend attribution, and as many keys as you want — one per environment, one per project, whatever suits your setup.
Every account calls the same endpoint. There is no per-customer hostname to
provision and no DNS to configure — the key in your Authorization
header is what identifies you.
Upstream provider credentials live server-side and never reach the caller, so nothing in your key can be replayed against a vendor API directly.
Create your key on the dashboard, then follow the copy-paste examples in the API guide.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Missing prompt and image. No slot is consumed. |
| 400 | invalid_duration | Longer than the model renders — 30s on seedance-2.5, 15s on every 2.0 variant. The ceiling comes back in max_duration. |
| 400 | invalid_fps | Outside 1–30. Default is 24. |
| 400 | invalid_ratio | Not one of 16:9, 9:16, 1:1, 4:3, 3:4, 21:9. |
| 400 | invalid_model | Unknown model alias. |
| 401 | unauthorized | Missing, malformed or revoked key. A revoked key says so in the message. |
| 404 | not_found | Unknown job id or unrouted path. |
| 429 | capacity | Your bucket is full. Honour Retry-After. |
| 500 | router_error | Unexpected fault. Upstream failures surface as a failed job, not a 500. |
| 503 | hub_not_linked | Not your key — the hub is not linked to the dashboard that issued it, so it cannot recognise any key from here. The body carries the operator's fix; the same key works once it is applied. |
| 503 | hub_link_broken | Also not your key — the hub is linked but the dashboard refused or dropped the lookup, so no key can be verified right now. link_state reads unauthorized (the two halves hold different shared secrets) or unreachable. Retry the same key once the operator has applied the fix in the body. |
Pass any of these in the model field. Switching models is a
one-word change — the request and response shapes are identical across all of them.
| Model | Resolutions | Best for |
|---|---|---|
| seedance-2.5 | 480p – 4K | Highest fidelity, cinematic motion |
| seedance-2.0 | 480p – 1080p | Balanced quality and cost |
| seedance-2.0-fast | 480p – 1080p | Lower latency, iteration and previews |
| seedance-2.0-mini | 480p – 720p | Cheapest per second, high volume |
Per-second pricing for every model and resolution is on the pricing page. Your dashboard shows your effective price after any discount applied to your account.