Getting Started

Getting Started

API

MCP Server

Rate Limits

Request quotas, 429 responses, and how to back off correctly

Rate Limits

Every /api/v1/* request counts against one budget per account:

ScopeLimit
All /api/v1/* endpoints60 requests per minute

The window is a fixed 60-second bucket keyed by your account — not per endpoint and not per API key. Two keys on the same account share the budget, and polling a task costs exactly as much as creating one.

This number is small on purpose: a 2-second poll loop uses 30 of your 60 requests. If you run several tasks at once, poll less often or batch your reads — see Tasks & Polling.

When you exceed it

HTTP/2 429
retry-after: 12
x-ratelimit-remaining: 0
x-ratelimit-reset: 1723000060
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": null,
    "param": null
  }
}
HeaderMeaning
Retry-AfterSeconds to wait before your next request will be accepted
X-RateLimit-RemainingAlways 0 on a 429
X-RateLimit-ResetUnix timestamp (seconds) when the window resets

Honour Retry-After rather than guessing. Requests rejected with 429 are not charged credits and did not create a task.

Backing off

async function requestWithRetry(url: string, init: RequestInit) {
  for (let attempt = 0; attempt < 4; attempt++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;

    const retryAfter = Number(res.headers.get('retry-after') ?? '5');
    // jitter, so parallel workers don't all wake at the same instant
    const wait = retryAfter * 1000 + Math.random() * 500;
    await new Promise((r) => setTimeout(r, wait));
  }
  throw new Error('Still rate limited after 4 attempts');
}

Two rules that matter more than the retry count:

  1. Never retry a POST /3d/generations blindly. A 429 means the request was rejected before any task existed, so retrying is safe. But a 5xx is not the same thing — see Error Handling.
  2. Back off, don't tighten the loop. Doubling the interval is usually enough; shortening it after a 429 guarantees you stay throttled.

Practical budget planning

WorkloadRequests per taskTasks/minute at 60 rpm
Async + 5s polling, ~60s generation~13~4
Async + 10s polling, ~60s generation~7~8
Sync mode (single request)1~60

For batch jobs, prefer mode: "sync" where the generation reliably finishes under 55 seconds, or drive async tasks from a queue with a small number of workers rather than polling everything in parallel.

Table of Contents

Rate Limits
When you exceed it
Backing off
Practical budget planning