Skip to main content

​
Base URL and versioning

All endpoints in this documentation use:
Stable public APIs are mounted below /v1. Send JSON request bodies as UTF-8 with Content-Type: application/json.

​
Media endpoints

​
Headers

​
Response envelopes

Image and video endpoints generally return an APIPod envelope:
Create and status endpoints use different data objects. Use the OpenAPI contract on the exact model or task page instead of assuming that every media endpoint returns the same fields.

​
Idempotent media creation

Idempotency-Key is optional but strongly recommended for POST /v1/images/generations and POST /v1/videos/generations.
  • Maximum key length is 255 characters.
  • The key is scoped to the authenticated API key, HTTP method, and route.
  • Repeating the same key with an equivalent JSON body replays the stored response.
  • Reusing the key with a different request returns HTTP 409 and idempotency_conflict.
  • Retrying while the first request is still being processed returns HTTP 409, idempotency_in_progress, and Retry-After: 1.
  • Completed idempotency records are retained for seven days by the current service implementation.
A brand-new HTTP request is protected only when it carries the original Idempotency-Key. Persist the key with the logical operation before sending the first request.

​
IDs and timestamps

  • task_id identifies the public asynchronous media task and is required for status queries.
  • X-Request-ID identifies the HTTP request and should be included in operational logs.
  • completed_at in task status responses is a Unix timestamp in seconds.
  • Webhook created_at and completed_at values are JSON timestamps.