Create a Generation
Use POST /v1/generations to submit an asynchronous generation task. Choose model and endpoint values from the corresponding model documentation, then provide input that follows the selected Endpoint and Provider requirements.
Before you submit
Open a model guide from Image Models or Video Models in the Docs sidebar. Copy its model, endpoint, and optional provider values, then review the parameter requirements and pricing.
Create a new stable Idempotency-Key no longer than 255 characters.
Keep API keys on a trusted server and send Authorization: Bearer YOUR_API_KEY.
Idempotent retries
After a network timeout, retry with the exact same Idempotency-Key and request body. A new task normally returns HTTP 202. An idempotent replay returns HTTP 200 with X-Idempotent-Replay: true; reusing the key with a different body returns HTTP 409.
Track the task
Save the complete generation.id. Poll GET /v1/generations/{task_id} with backoff, or supply callback_url to receive terminal status updates. Stop polling when the task becomes succeeded, failed, canceled, refunded, or expired.
Query Task Status
After submitting a task, use the unified query endpoint to check progress and retrieve results:
For production integrations, receive terminal status updates through a callback instead of polling continuously.
Request
/v1/generationsHeader Params
A unique key for this request. Reuse it only when retrying an identical request body.
- Example:
order-20260820-001
Body Params
application/jsonThe model ID shown in the selected model's API documentation.
- Example:
model-id
The Endpoint ID shown in the selected model's API documentation.
- Example:
text-to-image
An optional public Provider ID. Omit it to use the Endpoint default Provider.
- Example:
seeapi
Model parameters that follow the selected Endpoint and Provider requirements in the model documentation.
- Example:
{"prompt":"A cinematic city at night"}
An optional absolute HTTPS URL that receives terminal task updates.
- Use an HTTPS endpoint you control. Verify webhook signatures, and keep polling available as a recovery path.
- Example:
https://client.example.com/webhooks/seeapi
Responses
202Generation accepted. Save the returned task ID and track it until the task reaches a terminal state.
- Save the complete generation.id before starting status checks.
- HTTP 202 means the task was accepted, not that generation has finished.
objectrequiredThe accepted asynchronous generation task.
The accepted asynchronous generation task.
The complete task ID used with GET /v1/generations/{task_id}.
- Example:
task_xxx
The model ID used for the accepted task.
- Example:
model-id
The model Endpoint used for the accepted task.
- Example:
text-to-image
The public Provider ID selected for the accepted task.
- Example:
seeapi
The current task state. A newly accepted generation starts as processing.
processing- Example:
processing
The estimated credit usage calculated when the task is accepted. Query task details after completion for actual usage.
- Example:
10
Credit usage reported at response time. Query task details after a terminal state for the actual usage.
- Example:
0
Credits refunded at response time. Query task details after a terminal state for the final value.
- Example:
0
The time when the task was created.
- Example:
2026-08-18T10:00:00Z
The time of the most recent task update.
- Example:
2026-08-18T10:00:00Z
False for a newly accepted task; true when HTTP 200 replays an earlier request with the same idempotency key and body.
- Example:
false
200Idempotent replay of an existing generation request
- This response returns the existing task and does not create a second generation.
- X-Idempotent-Replay is true for this response.
objectrequiredThe accepted asynchronous generation task.
The accepted asynchronous generation task.
The complete task ID used with GET /v1/generations/{task_id}.
- Example:
task_xxx
The model ID used for the accepted task.
- Example:
model-id
The model Endpoint used for the accepted task.
- Example:
text-to-image
The public Provider ID selected for the accepted task.
- Example:
seeapi
The current task state. A newly accepted generation starts as processing.
processing- Example:
processing
The estimated credit usage calculated when the task is accepted. Query task details after completion for actual usage.
- Example:
10
Credit usage reported at response time. Query task details after a terminal state for the actual usage.
- Example:
0
Credits refunded at response time. Query task details after a terminal state for the final value.
- Example:
0
The time when the task was created.
- Example:
2026-08-18T10:00:00Z
The time of the most recent task update.
- Example:
2026-08-18T10:00:00Z
False for a newly accepted task; true when HTTP 200 replays an earlier request with the same idempotency key and body.
- Example:
false
Invalid JSON, parameters, Schema, or API Policy
- Correct the JSON or the documented model, Endpoint, Provider, and input parameters before retrying. Do not retry an unchanged invalid request.
Invalid API Key or authentication failed
- Stop automatic retries and verify that Authorization uses the Bearer scheme with a valid API key.
Insufficient credits
- Add sufficient credits before retrying the request.
The current request is not allowed
- Check that the API key is allowed to use the selected model, Endpoint, and Provider. Do not retry unchanged credentials indefinitely.
Model, Endpoint, or task not found
- Verify the model and Endpoint IDs against the selected model documentation, then correct the request before retrying.
Idempotency conflict or the same request is still being created
- If the same request is still being created, retry later with the same key and identical body. Use a new Idempotency-Key when the request body changes.
Request body is too large
- Reduce the JSON request body and follow the selected model documentation for media inputs before retrying.
Too many requests
- Honor Retry-After when provided and retry with backoff using the same Idempotency-Key and request body.
Service temporarily unavailable
- Retry with backoff using the same Idempotency-Key and identical request body so a temporary failure cannot create a duplicate task.