Skip to content

Rate limits

View as Markdown

Limits protect the service and your credits from runaway loops. They are generous for normal use: a video takes minutes, so a well behaved client makes few requests.

Limit Applies to Scope On limit
60 requests per minute Every REST and MCP request Per API key (REST and MCP share one budget) 429, retry_after_sec: 5, Retry-After: 5
10 song imports per hour POST /v1/songs, create_video_from_song_url with song_url Per account 429, retry_after_sec: 360
4 new videos per hour POST /v1/videos, create_video_from_song_url Per account 429, retry_after_sec: 900
1 video in progress POST /v1/videos, create_video_from_song_url Per account 409 video_in_progress
5 active API keys Key creation in Studio Per account Revoke a key first

The per-key limit refills continuously (one request per second), so short bursts are fine. Imports and videos that fail before they start (for example a rejected brief or a bad link) do not count toward the hourly limits.

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json
{ "error": "rate_limited", "message": "Too many requests for this key.", "retry_after_sec": 5 }
  • Wait at least retry_after_sec seconds (or the Retry-After header when present) before retrying.
  • For other temporary errors (502, 503) retry with exponential backoff: 2, 4, 8, 16 seconds, then give up and show the error.
  • Do not retry 400, 401, 402, 403, 404 or 422 without changing the request.
  • POST /v1/videos is not idempotent. If a start request times out on your side, call GET /v1/videos?limit=1 before starting again: the video may already be running, and a second start returns 409 video_in_progress.

Polling one video every 30 seconds uses 2 requests per minute. The per-key limit leaves plenty of room for several integrations on one key, but one key per integration makes problems easier to trace.

Need higher limits? Write to hello@clipbeat.app with your use case.