Skip to content

REST API overview

View as Markdown

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.json

The API reference on this site is generated from that document at every build.

https://api.clipbeat.app

All endpoints are under /v1. HTTPS only.

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.
  • 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 returns 400 invalid_body.
  • Unknown body fields are ignored.
  • Text fields are trimmed, control characters are removed and long values are cut to the documented maximum.
  • 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.

  • The version is in the path: /v1. Within v1 changes are additive: new endpoints, new optional fields, new response fields, new error codes and new enum values. Write clients that ignore unknown fields and treat unknown statuses as “not final”.
  • Anything that would break a v1 client ships as a new version, announced in the Changelog first.

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.

60 requests per minute per key, 10 song imports and 4 new videos per hour per account. See Rate limits.