Integration guide

1Create your personal API key

Click path

Open Sign up and create your account.
Sign in, then open Dashboard.
Select the API keys tab.
Enter a label such as production.
Click Create key.
Copy both the key and base URL immediately.

Why the key appears once

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.

Keep it secret. Do not put a cl_ key in browser JavaScript, a public repository, screenshots or chat. Call Cliplus from your server.

2Paste your two values

These fields stay in this browser tab. They update every example below and are never sent anywhere by this documentation page.

Base URL

API key

Base URLMust end with /v1. Do not add /videos here; the examples add it.

API keyMust begin with cl_. It belongs to your account, so your dashboard shows only your usage.

Optional terminal setup

export BASE_URL="https://cliplus-router.YOUR-SUBDOMAIN.workers.dev/v1"
export API_KEY="cl_PASTE_YOUR_KEY_HERE"

Windows PowerShell uses $env:BASE_URL="..." and $env:API_KEY="...".

3Submit a video

A successful submission returns HTTP 202 Accepted and a job id. Save that id; you use it to poll.

Request fields

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`, `2k`, `4k`. Default: 480p.
`duration`	No	1–60 seconds. Default: 5.
`fps`	No	1–120. Default: 24.
`ratio`	No	Aspect ratio such as `16:9`. Default: 16:9.
`bit_depth`	No	8 or 10. 1080p and 4K default to 10-bit.

Automatic routing: Every job is one submit call and one poll loop, no matter which resolution you request. You always receive one job id and one final video URL.

4Poll until completion

Poll every 3–5 seconds. Stop when status is succeeded or failed. The final url is the temporary video URL.

queued / running

Wait and poll the same job id again. stage shows generating or enhancing.

succeeded

Read url. Download or copy the result before its upstream expiry.

failed

Read error.code and error.message. Do not keep polling.

Minimal end-to-end shell script

Useful endpoints

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.

Troubleshooting

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.
`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 test without coding? Use Dashboard → Test it.

From sign-up to your first video