REST API overview
The Clipbeat REST API is a small JSON over HTTPS API. It is described by an OpenAPI 3.1 document that tools such as n8n, Postman, Insomnia, ChatGPT actions and code generators can import:
https://api.clipbeat.app/v1/openapi.jsonThe API reference on this site is generated from that document at every build.
Base URL
Section titled “Base URL”https://api.clipbeat.appAll endpoints are under /v1. HTTPS only.
Endpoints
Section titled “Endpoints”| Method | Path | Scope | What it does |
|---|---|---|---|
POST |
/v1/songs |
songs:write |
Import a song from a link. |
GET |
/v1/songs/{id} |
videos:read |
Song status. Wait for ready before starting a video. |
POST |
/v1/videos |
videos:write |
Start a video. Credits are reserved. |
GET |
/v1/videos/{id} |
videos:read |
Status, progress, cost and the download link when done. |
GET |
/v1/videos |
videos:read |
The account’s latest videos (limit 1 to 50, default 20). |
GET |
/v1/pricing |
account:read |
Price per tier. Add song_id for the price of a specific song. |
GET |
/v1/balance |
account:read |
Credit balance and the link to add credits. |
GET |
/v1/openapi.json |
none | The OpenAPI document. No key needed. |
Requests
Section titled “Requests”- Authenticate every request with
Authorization: Bearer cb_live_.... See Authentication. - Send bodies as JSON with
Content-Type: application/json. The body must be a JSON object; anything else returns400 invalid_body. - Unknown body fields are ignored.
- Text fields are trimmed, control characters are removed and long values are cut to the documented maximum.
Responses
Section titled “Responses”- Always JSON, with
Cache-Control: no-store. - Field names are
snake_case. Ids are UUIDs. Timestamps are ISO 8601 strings in UTC. - Success codes:
200 OK,201 Created(new song),202 Accepted(video started). - Errors share one shape, see Errors:
{ "error": "insufficient_credits", "message": "Not enough credits. Ask the account owner to add credits in Clipbeat Studio, then retry." }Branch on error (a stable machine code), show message to people.
Versioning
Section titled “Versioning”- The version is in the path:
/v1. Withinv1changes are additive: new endpoints, new optional fields, new response fields, newerrorcodes and new enum values. Write clients that ignore unknown fields and treat unknown statuses as “not final”. - Anything that would break a
v1client ships as a new version, announced in the Changelog first.
CORS and where to call from
Section titled “CORS and where to call from”Only GET /v1/openapi.json allows calls from any browser origin. Call the other endpoints from your server, never from
a browser or app where users could read your key.
Limits
Section titled “Limits”60 requests per minute per key, 10 song imports and 4 new videos per hour per account. See Rate limits.