Generations

Create generation

Create an asynchronous image or video task with an idempotent request and formal account credits.

Endpoint

POST/api/v1/developer/generations

Authentication & scope

Authorization: Bearer <credential>; formal account API Key / OAuth only.

Scope: generations:write

Idempotency-Key — Required; reuse the same value for retries of an identical request.

Replace the example model_key and parameters with values from the current catalog. Unknown fields and provider/URL/storage/endpoint injection are rejected.

202 means accepted, not finished. Retry an uncertain submission with the same Idempotency-Key and identical payload; use a new key for a new intent. Poll generation_id until terminal.

Request parameters

Field	Type	Required	Description
`model_key`	string	Yes	Exact key from the current public model catalog.
`operation`	string	Yes	image_generation or video_generation; must be supported by the selected model.
`prompt`	string	Yes	Nonempty prompt, at most 8,000 characters.
`negative_prompt`	string	No	At most 8,000 characters, subject to model support.
`parameters`	object	No	Only parameters accepted by this model's input_schema; include required size/duration settings where applicable.
`reference_upload_ids`	UUID[]	No	Completed upload_id values, at most 8; model-specific limits may be lower.
`client_trace_id`	string	No	At most 128 characters matching [A-Za-z0-9._:-]+.

curl --request POST \
  --url 'https://api.perchanceai.art/api/v1/developer/generations' \
  --header 'X-App-Id: perchanceai' \
  --header 'X-Request-Id: docs-example' \
  --header 'Authorization: Bearer <formal_account_credential>' \
  --header 'Idempotency-Key: <unique_request_uuid>' \
  --header 'Content-Type: application/json' \
  --data '{"model_key":"<model_key_from_catalog>","operation":"image_generation","prompt":"A bright editorial product still life","parameters":{}}'

Response HTTP 202

Illustrative response shape, not a live API response. Example numbers and USD do not imply fixed pricing or a cash balance. Null fields are omitted.

REST success responses contain success, code, message, request_id and data; the table describes data.

Field	Type	Required	Description
`generation_id`	UUID	Yes	Durable task identifier owned by the credential's account and App.
`status`	string	Yes	Poll until succeeded, failed or cancelled; an accepted request is not completion.
`model_key / modality / operation`	string	Yes	Selected model, image/video modality and public operation.
`created_at / updated_at`	ISO UTC string	Yes	UTC timestamps.
`completed_at`	ISO UTC string	No	Completion time when present.
`poll_after_ms`	integer	No	Suggested delay for nonterminal tasks (currently 2000); omitted for terminal tasks.
`estimated_credits / reserved_credits / charged_credits`	integer	Yes	Estimated, reserved and actually charged account credits.
`outputs`	object[]	Yes	media_id, media_type, url, and optional width, height, duration_ms.
`error`	object	No	Task failure: code, message, retryable. Omitted when absent.
`client_trace_id`	string	No	Echoed client correlation identifier when provided.

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "generation_id": "11111111-1111-4111-8111-111111111111",
    "status": "queued",
    "model_key": "<model_key_from_catalog>",
    "modality": "image",
    "operation": "image_generation",
    "created_at": "2026-10-14T00:00:00.000Z",
    "updated_at": "2026-10-14T00:00:00.000Z",
    "poll_after_ms": 2000,
    "estimated_credits": 10,
    "reserved_credits": 10,
    "charged_credits": 0,
    "outputs": []
  }
}

Errors

401 — DEVELOPER_TOKEN_REQUIRED
401 — DEVELOPER_TOKEN_INVALID / DEVELOPER_TOKEN_EXPIRED / DEVELOPER_TOKEN_REVOKED
403 — DEVELOPER_SCOPE_INSUFFICIENT
400 — IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALID
422 — FIELD_REQUIRED / FIELD_INVALID
402 — CREDITS_INSUFFICIENT
409 — IDEMPOTENCY_PAYLOAD_MISMATCH / IDEMPOTENCY_IN_PROGRESS / IDEMPOTENCY_REPLAY_EXPIRED

Missing bearer returns REQUIRED; invalid credentials, including historical anonymous tokens, return INVALID. Expired or revoked credentials use their corresponding codes.

{
  "success": false,
  "code": "DEVELOPER_TOKEN_REQUIRED",
  "message": "A developer bearer token is required.",
  "request_id": "docs-example"
}