Guides

Generations

Every accepted render, edit, decoration or upscaling creates a generation (gen_…): its status, its cost and its result. A generation is visible only to the keys of its organization and its mode; elsewhere: 404 resource_not_found.

The `generation` object

json
{
  "object": "generation",
  "id": "gen_3Wd8KpQ2xLm7Vb9NcT4hRz",
  "type": "render",
  "status": "succeeded",
  "cancelable": false,
  "livemode": true,
  "created_at": 1791453612,
  "completed_at": 1791453648,
  "input": {
    "quality": "2k",
    "scale": null
  },
  "output": [
    {
      "url": "https://…",
      "url_expires_at": 1791454548,
      "content_type": "image/webp",
      "width": 2752,
      "height": 1536
    }
  ],
  "error": null,
  "cost": {
    "amount": 23,
    "currency": "eur",
    "unit": "cents",
    "discount_percent": 0,
    "amount_refunded": 0
  },
  "metadata": { "project_id": "PRJ-1042" },
  "expires_at": 1791540048
}

Field	Type	Description
`object`	string	Always `generation`.
`id`	string	Identifier, `gen_…`.
`type`	string	`render`, `edit`, `decoration` or `upscale`.
`status`	string	`in_progress`, `succeeded`, `failed` or `canceled`.
`cancelable`	boolean	`true` while the generation can still be canceled (see Cancel a generation).
`livemode`	boolean	`false` in test mode.
`created_at`	integer	Acceptance, Unix timestamp in seconds.
`completed_at`	integer or `null`	End, or `null`.
`input`	object	The request settings, without its images: `quality` or `scale` (the other `null`), and those of the edit or decoration.
`output`	array	Produced images; empty until the generation ends, on failure and after the images are deleted.
`error`	object or `null`	`code` and `message` of a `failed` generation.
`cost`	object	Price of the generation (see Cost).
`metadata`	object	Your metadata (see Metadata); `{}` if the request carried none.
`expires_at`	integer	Deletion of the input and output images: 24 hours after the generation ends. The generation can still be retrieved for 13 months.

output[].url is a signed URL, readable without a key, valid for 15 minutes after the read (url_expires_at): retrieve the generation again to get a new one. It can also be sent as the image of another generation (see Images). The format is normally WebP.

The instruction of an edit by instruction is erased 30 days after creation: input.prompt is then "".

A generation is deleted 13 months after its creation: reading it then returns 404 resource_not_found, as for an unknown id, and it no longer appears in the list. Its charge and refund stay in the balance transactions (see Billing).

Statuses

`status`	Description
`in_progress`	Accepted, in progress.
`succeeded`	Ended: `output` contains the produced image.
`failed`	Failed and refunded. `error.code` is `generation_failed` (start it again later) or `content_policy_violation` (refused by moderation: do not resend the same request).
`canceled`	Canceled before it started, and refunded.

The last three statuses are final. A failure is not an HTTP error: the read responds 200.

Cost

Field	Type	Description
`amount`	integer	Price excluding tax in euro cents, tier discount applied, fixed at acceptance.
`currency`	string	`eur`.
`unit`	string	`cents`.
`discount_percent`	number	Tier discount, as a percentage.
`amount_refunded`	integer	Amount returned to the balance, in cents. Equal to `amount` for a `failed` or `canceled` generation.

amount does not change after a refund; in test mode, it gives the live mode price, with no charge (see Pricing).

Metadata

metadata attaches data of your choice to a generation, such as the ID of the project, customer or user it relates to in your application. RenderThink does not interpret it: it comes back unchanged in the generation, in the list and in webhooks. This lets you link a result to your own records without a lookup table.

json
{
  "image": "https://…",
  "quality": "2k",
  "metadata": { "project_id": "PRJ-1042", "customer_id": "C-318" }
}

At most 16 pairs.
Keys of 1 to 40 characters; string values of 500 characters at most. Beyond that: 400 parameter_invalid.
Do not store sensitive data in it: passwords, payment details, unnecessary personal data.

Synchronous or in the background

By default, a creation responds when the generation ends, usually within 1 to 3 minutes: 200 with the succeeded or failed generation.

Set your HTTP client timeout to at least 5 minutes (Python requests: timeout=300). The .NET HttpClient gives up after 100 seconds by default: raise its Timeout.
Under heavy load, 4 min 30 s after the request is received (image downloads included), or if the server restarts, the response is 202 with the in_progress generation: read it or wait for its webhook.
Connection lost: the generation continues. Resend the creation with the same Idempotency-Key to get the same generation, with no second charge (see Idempotency).

With "background": true in the body, the creation responds at once with 202 and the in_progress generation, cancelable while cancelable is true. The result comes by webhook, the recommended path for a server that starts many generations, or by reading it.

generation.* events are sent when every generation ends, in both modes. The number of generations launched per minute and per hour depends on the tier (see Rate limits).

Retrieve a generation

GET /v1/generations/{id} returns the generation at once (200); status tells whether it has ended. Key permission: generations_read. To follow a background generation without a webhook, read it every few seconds: each read counts toward the rate limit.

curl https://api.renderthink.com/v1/generations/gen_3Wd8KpQ2xLm7Vb9NcT4hRz \
  -H "Authorization: Bearer $RENDERTHINK_API_KEY"

List generations

GET /v1/generations returns a paginated list, from the most recent to the oldest. Key permission: generations_read.

Name	Type	Description
`limit`	integer	From 1 to 100. Default: 20.
`after`	string	`id` of the last generation of the previous page.
`type`	string	`render`, `edit`, `decoration` or `upscale`.
`status`	string	`in_progress`, `succeeded`, `failed` or `canceled`.

Cancel a generation

POST /v1/generations/{id}/cancel cancels a generation whose processing has not started and refunds it: 200 with the canceled generation. A generation that has started can no longer be canceled; it runs to its end.

cancelable tells whether canceling is still possible. It is a hint: the generation may start between the read and the cancel, which then responds 409 generation_not_cancelable.

Key permissions: generations_read and the one of the generation's type (renders, edits, decorations or upscales).

Errors

Status	Code	Cause
400	`parameter_invalid`	Invalid `limit`, `after`, `type` or `status`.
403	`permission_denied`	Missing permission, including the generation's type to cancel it.
404	`resource_not_found`	Unknown generation, deleted (13 months after its creation), or one from another organization or the other mode.
409	`generation_not_cancelable`	The generation has started or has ended.

Errors shared by every route (key, balance, images, limits) are in Errors.