Image packs
Give this prompt to your AI agent. The agent does the task for you.
Read https://thirds.ai/docs/api-reference/image-packs and help me choose the right thirds.ai endpoint and write a request. Check the fields and credentials in this reference.
Render one saved template version at several sizes, poll each size, retry failed sizes, and download a ZIP of the files that succeeded.
See all API resources or read API keys and requests.
Endpoints
createImagePack
POST /v1/image-packs
Create an image pack
Render one saved template version at every requested size: original for the version's own canvas, a saved size id, a preset slug, or a WxH custom size adapted from the version's original. Creates one normal image job per size. A size that cannot be adapted fails immediately with resize_source_unsupported; the other sizes still run. The ledger reserves one credit per job, settles it on success, and releases it on failure.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
Idempotency-Key | header | Yes | {"type":"string","minLength":1,"maxLength":255,"pattern":"^[ -~]+$"} |
Request body: application/json, ImagePackCreate.
| Status | Meaning | Body |
|---|---|---|
| 201 | The pack was created, or an earlier request with the same idempotency key and body is replayed. | application/json: ImagePack |
| 400 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 404 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 409 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 413 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 415 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 429 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
| 500 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 503 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
getImagePack
GET /v1/image-packs/{id}
Get an image pack's status
Returns the pack with each member's own state and, once any member has succeeded, a signed archive_url for the ZIP of every succeeded file.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
id | path | Yes | {"type":"string","pattern":"^pack_[0-9a-f]{32}$"} |
| Status | Meaning | Body |
|---|---|---|
| 200 | The pack's current status. | application/json: ImagePack |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 404 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
| 500 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
retryImagePack
POST /v1/image-packs/{id}/retry
Retry an image pack's failed members
Creates one new job for every member whose last attempt failed or that never reached a job. A queued, running, or already succeeded member is left untouched.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
id | path | Yes | {"type":"string","pattern":"^pack_[0-9a-f]{32}$"} |
| Status | Meaning | Body |
|---|---|---|
| 200 | The pack after retry, with a new job for each member that was retried. | application/json: ImagePackRetry |
| 401 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 403 | The authenticated account is suspended. The code is account_suspended. | application/json: ErrorEnvelope |
| 404 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 429 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
| 500 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
getImagePackArchive
GET /v1/image-packs/archive/{token}
Download an image pack's ZIP archive
Stream a ZIP of one pack's succeeded members, in requested order with numbered filenames, plus manifest.json recording that order and any failed sizes. The link carries its own authority, so no other credential is read.
Authentication: no credential required.
| Parameter | Location | Required | Rule |
|---|---|---|---|
token | path | Yes | The signed archive link. {"type":"string"} |
| Status | Meaning | Body |
|---|---|---|
| 200 | The ZIP archive of succeeded members plus manifest.json. | application/zip: {"type":"string","format":"binary"} |
| 403 | The link is genuine but its time is over. | application/json: ErrorEnvelope |
| 404 | The link is not valid, or the pack has no succeeded member to archive. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 431 | The request has more than 64 headers or more than 32 KiB of header names and values. | application/json: ErrorEnvelope |
| 500 | An internal error occurred. | application/json: ErrorEnvelope |
Schemas
ImagePackCreate
| Field | Required | Description and type |
|---|---|---|
template_id | Yes | TemplateId |
version | No | Omitted to use the template's latest version at creation time. {"type":"integer","minimum":1} |
data | No | Template data. Each size's own saved data overrides apply over this data. Omitted to use an empty object. {"type":"object"} |
format | Yes | {"type":"string","enum":["png","jpeg","webp"]} |
sizes | Yes | 1 to 20 different entries: original for the version's own canvas, a saved size id, a preset slug, or a WxH custom size. {"type":"array","items":{"type":"string"},"minItems":1,"maxItems":20} |
Schema rules: {"type":"object","additionalProperties":false}.
ImagePackMember
| Field | Required | Description and type |
|---|---|---|
position | Yes | {"type":"integer","minimum":0} |
size_id | Yes | {"type":"string"} |
name | Yes | {"type":"string"} |
width | Yes | {"type":"integer","minimum":1} |
height | Yes | {"type":"integer","minimum":1} |
state | Yes | {"type":"string","enum":["queued","running","succeeded","failed"]} |
error | Yes | {"type":["object","null"],"properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false} |
download_url | Yes | {"type":["string","null"]} |
Schema rules: {"type":"object","additionalProperties":false}.
ImagePack
| Field | Required | Description and type |
|---|---|---|
id | Yes | {"type":"string","pattern":"^pack_[0-9a-f]{32}$"} |
template_id | Yes | TemplateId |
version | Yes | {"type":"integer","minimum":1} |
format | Yes | {"type":"string","enum":["png","jpeg","webp"]} |
created_at | Yes | {"type":"string","format":"date-time"} |
state | Yes | {"type":"string","enum":["queued","running","complete","partial","failed"]} |
members | Yes | {"type":"array","items":{"$ref":"#/components/schemas/ImagePackMember"}} — ImagePackMember |
archive_url | Yes | A signed ZIP download link, present once any member has succeeded. {"type":["string","null"]} |
Schema rules: {"type":"object","additionalProperties":false}.
ImagePackRetry
Schema rules: ImagePack.
Shared errors, headers, and authentication schemes are in shared types and security.