Customer integration guide
You need two strings: the base URL shown by your Cliplus dashboard and one API key beginning with cl_. This page shows every click and every request.
Cliplus stores only a SHA-256 hash, a short prefix and the last four characters. It cannot reveal the key again. If it is lost, revoke it and create another one.
cl_ key in browser JavaScript, a public repository, screenshots or chat. Call Cliplus from your server.These fields stay in this browser tab. They update every example below and are never sent anywhere by this documentation page.
/v1. Do not add /videos here; the examples add it.cl_. It belongs to your account, so your dashboard shows only your usage.export BASE_URL="https://cliplus.byteplus.workers.dev/v1"
export API_KEY="cl_PASTE_YOUR_KEY_HERE"The base URL is the same for every Cliplus customer. Only your API key differs. Create one at Dashboard → API keys.
Windows PowerShell uses $env:BASE_URL="..." and $env:API_KEY="...".
A successful submission returns HTTP 202 Accepted and a job id. Save that id; you use it to poll.
| Field | Required | Accepted values |
|---|---|---|
model | Yes | Use GET /models for the current masked aliases. |
prompt | One input required | Text prompt. You may use image_url instead. |
image_url | One input required | Public HTTPS image URL for image-to-video. |
resolution | No | 480p, 720p, 1080p, 4k. Default: 480p. |
duration | No | Seconds, from 1 up to the model's ceiling: 30 for seedance-2.5, 15 for every seedance-2.0 variant. Default: 5. |
fps | No | 1–30. Default: 24. |
ratio | No | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9. Default: 16:9. |
seedance-2.0 for 20 seconds returns 400 invalid_duration with the ceiling in max_duration, rather than a failure two minutes into generation. GET /models publishes max_duration_seconds, max_fps and ratios per model, so a client can build its own pickers from the API instead of hard-coding these numbers.Poll every 3–5 seconds. Stop when status is succeeded or failed. The final url is the temporary video URL.
Wait and poll the same job id again. stage reads generating until the clip is ready.
Read url. Download or copy the result before its upstream expiry.
Read error.code and error.message. Do not keep polling.
| Method and path | Use |
|---|---|
POST /videos | Submit a video job. |
GET /videos/{id} | Poll and advance a job. |
GET /models | List available Cliplus model aliases. |
GET /usage | Read usage attributed to your API key. |
GET /capacity | Check live headroom before a burst. |
GET /billing/balance | Read your plan and credit snapshot. |
| What you see | What to do |
|---|---|
401 unauthorized | Confirm the header is exactly Authorization: Bearer cl_.... Create a replacement key if the original was lost or revoked. |
503 hub_not_linked | Not a problem with your key. The hub is not linked to the dashboard that issued it, so it cannot recognise any key from here — the response names the fix. Retry with the same key once it has been applied; nothing in your code needs to change. |
503 hub_link_broken | Also not a problem with your key. The link exists but the lookup itself failed, so the hub cannot verify any key at the moment. link_state: "unauthorized" means the hub and the dashboard hold different shared secrets; "unreachable" means the dashboard did not answer. Both are operator-side; retry the same key once the fix in the body has been applied. |
404 not_found | Check that the base URL ends in /v1 and that you did not add a second /v1. Jobs are scoped to the account that created them. |
429 capacity_exceeded | Wait for the number of seconds in the Retry-After response header, then retry. |
invalid_request | Supply a non-empty prompt or a public image_url. |
| Browser CORS error | Do not expose your API key in a public browser app. Call Cliplus from your own backend, then return only the result to the browser. |
| Job never advances | Keep polling. Polling drives the generation state machine. |
Need the full wire contract? Open the endpoint reference. Want to check your key works without writing any code? Open the connection tester — it submits a 5s 480p job and plays the result.