Rate limits
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.
Limits
Section titled “Limits”| 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.
The 429 response
Section titled “The 429 response”HTTP/1.1 429 Too Many RequestsRetry-After: 5Content-Type: application/json
{ "error": "rate_limited", "message": "Too many requests for this key.", "retry_after_sec": 5 }Retrying
Section titled “Retrying”- Wait at least
retry_after_secseconds (or theRetry-Afterheader 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,404or422without changing the request. POST /v1/videosis not idempotent. If a start request times out on your side, callGET /v1/videos?limit=1before starting again: the video may already be running, and a second start returns409 video_in_progress.
Polling budget
Section titled “Polling budget”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 [email protected] with your use case.