Image assets
Give this prompt to your AI agent. The agent does the task for you.
Read https://thirds.ai/docs/api-reference/image-assets and help me choose the right thirds.ai endpoint and write a request. Check the fields and credentials in this reference.
Upload private images for your templates and renders, preview them, and check supported files and limits.
See all API resources or read API keys and requests.
Endpoints
previewImageUrl
POST /v1/image-assets/preview
Preview a URL image
Read a public HTTP or HTTPS PNG, JPEG, or WebP through the checked asset transport. Credentials, private destinations, unsafe DNS answers, and redirects to them are refused. At most five redirects and 15 seconds total. The same upload decoder checks the 10 MiB, dimension, pixel, and memory limits. Returns verified bytes without storage or a render charge. Browser sessions require CSRF.
Authentication: bearer API key. See authentication.
Request body: application/json, {"type":"object","properties":{"url":{"type":"string","maxLength":4096}},"required":["url"],"additionalProperties":false}.
| Status | Meaning | Body |
|---|---|---|
| 200 | The verified image bytes and dimensions after orientation. | image/png: {"type":"string","format":"binary"}; image/jpeg: {"type":"string","format":"binary"}; image/webp: {"type":"string","format":"binary"} |
| 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 one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 405 | The method is not allowed on this route. | application/json: ErrorEnvelope |
| 413 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 422 | 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 |
uploadImage
POST /v1/image-assets
Upload an image
Store one private, immutable PNG, JPEG, or WebP image. Send the raw bytes with the matching Content-Type. Maximum 10 MiB, 7680 by 4320 stored pixels, 32 million pixels, and 64 MiB decoded memory. Animated images are refused. Images and brand assets share an account limit of 100 files and 100 MiB. Use the returned reference in an HTML body img src, or in template data for an img src. Render creation checks ownership after template expansion and captures the exact bytes. References are not public URLs. PDF header and footer templates do not support image references. No render credit is charged for an upload.
Authentication: bearer API key. See authentication.
Request body: image/png, {"type":"string","format":"binary"}.
Request body: image/jpeg, {"type":"string","format":"binary"}.
Request body: image/webp, {"type":"string","format":"binary"}.
| Status | Meaning | Body |
|---|---|---|
| 201 | The image is stored. | application/json: UploadedImage |
| 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 one error envelope every backend response uses. | 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 |
| 413 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 422 | 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 |
readImageContent
GET /v1/image-assets/{id}/content
Read an owned image
Return verified image or captured brand logo/font bytes to their owner. Missing and foreign assets return the same 404 error. The response uses private, no-store caching and nosniff.
Authentication: bearer API key. See authentication.
| Parameter | Location | Required | Rule |
|---|---|---|---|
id | path | Yes | {"type":"string","pattern":"^asset_[a-f0-9]{32}$"} |
| Status | Meaning | Body |
|---|---|---|
| 200 | The exact image bytes. | font/woff2: {"type":"string","format":"binary"}; image/png: {"type":"string","format":"binary"}; image/jpeg: {"type":"string","format":"binary"}; image/webp: {"type":"string","format":"binary"} |
| 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 one error envelope every backend response uses. | 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 |
| 413 | The one error envelope every backend response uses. | application/json: ErrorEnvelope |
| 422 | 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 |
Schemas
UploadedImage
| Field | Required | Description and type |
|---|---|---|
id | Yes | {"type":"string","pattern":"^asset_[a-f0-9]{32}$"} |
reference | Yes | Private template reference. This is not a fetchable URL. {"type":"string","pattern":"^asset://asset_[a-f0-9]{32}$"} |
media_type | Yes | {"type":"string","enum":["image/png","image/jpeg","image/webp"]} |
byte_size | Yes | {"type":"integer","minimum":1,"maximum":10485760} |
width | Yes | Display width after image orientation. {"type":"integer","minimum":1,"maximum":7680} |
height | Yes | Display height after image orientation. {"type":"integer","minimum":1,"maximum":7680} |
Schema rules: {"type":"object","additionalProperties":false}.
Shared errors, headers, and authentication schemes are in shared types and security.