Create visual request

POST 
/v1/visual

Create a new visual content generation request. The request will be processed asynchronously.

Request

Responses

201

Visual request created successfully

Response Headers

X-RateLimit-Limit
Requests allowed in the window named by X-RateLimit-Window. Sent by POST /v1/visual, the only rate-limited endpoint, once a call has reached its limiter: a refusal that answers earlier, such as 403, 405, 413 or a 429 for repeated bad credentials, carries none of these four headers. Your own numbers depend on your plan, so read them here rather than assuming a figure. A value of 0 with window fallback means the limiter could not be reached and the call was let through; treat it as no reading, not as a limit of zero.
Example: 10
X-RateLimit-Remaining
Requests left in that window. Pace on this rather than on a fixed delay.
Example: 7
X-RateLimit-Reset
Unix timestamp when that window resets
Example: 1704067260
X-RateLimit-Window
The window the two counts above describe. It is the window with the fewest requests left in absolute terms, not the one nearest its own limit proportionally, so a successful call usually reports second: the per-second allowance is the smallest number on every tier. Read the pair as how many you may send right now rather than as naming the quota that will stop you next. The value fallback means the limiter could not be reached.
Example: minute

400

The body could not be read, or a field is missing or out of range

401

The bearer token was accepted once and is no longer usable. Mint or refresh a token; retrying the same one never succeeds.

402

The account has no credits left. Top up or upgrade; retrying without doing so never succeeds.

403

No usable credential was sent, the credential is not one this API accepts, the grant lacks the scope, or the resource belongs to another caller.

405

The path exists and does not answer this HTTP method

413

The request body exceeds the accepted size

429

Three different refusals share this status, and the retry advice differs for each, so branch on error rather than on the status.

• rate_limit_exceeded: a per-second, minute, hour or day window is full. Wait the Retry-After seconds and retry. This is the only one of the three that carries that header or the window fields.
• generation_limit_exceeded: the account's lifetime generation allowance is spent. Waiting never clears it; contact us to raise the limit. It carries limit and used instead.
• too_many_failed_attempts: repeated bad credentials from this address are being refused. Fix the credential before calling again; retrying with the same one extends the refusal.

Response Headers

Retry-After
Seconds to wait before retrying. Sent only for rate_limit_exceeded.
Example: 45
X-RateLimit-Limit
Requests allowed in the window named by X-RateLimit-Window. Sent by POST /v1/visual, the only rate-limited endpoint, once a call has reached its limiter: a refusal that answers earlier, such as 403, 405, 413 or a 429 for repeated bad credentials, carries none of these four headers. Your own numbers depend on your plan, so read them here rather than assuming a figure. A value of 0 with window fallback means the limiter could not be reached and the call was let through; treat it as no reading, not as a limit of zero.
Example: 10
X-RateLimit-Remaining
Requests left in that window. Pace on this rather than on a fixed delay.
Example: 7
X-RateLimit-Reset
Unix timestamp when that window resets
Example: 1704067260
X-RateLimit-Window
The window the two counts above describe. It is the window with the fewest requests left in absolute terms, not the one nearest its own limit proportionally, so a successful call usually reports second: the per-second allowance is the smallest number on every tier. Read the pair as how many you may send right now rather than as naming the quota that will stop you next. The value fallback means the limiter could not be reached.
Example: minute

500

The call failed on our side and may be retried

503

A dependency is down or slow: the database, the queue, or the storage a download reads from. The call may be retried with backoff. A download answering this has not lost the file; storage could not be read.