Image assets

Upload or generate private images for your templates, read prompt history, and check file limits.

See all API resources or read the PDF generation API guide.

Endpoints

getAiImageHistory

GET /v1/image-assets/{id}/ai-history

Read private generated image history

Read the generated image history for an image asset you own.

Authentication: bearer API key. See authentication.

generateAiImage

POST /v1/ai-images

Generate an AI image

Generate one image with Seedream 5.0 Lite. Each successful image costs 50 credits, including free monthly credits. Failed requests and requests cancelled while queued release the credits. Send only after the customer approves the prompt and cost. Reuse the same Idempotency-Key when retrying an uncertain request. A matching replay returns the same image request; a changed body returns 409. Account AI concurrency, storage, and failed-operation limits apply. The prompt is at most 65536 UTF-8 bytes.

Authentication: bearer API key. See authentication.

Request body: application/json, AiImageCreate.

getAiImage

GET /v1/ai-images/{id}

Read AI image progress

Read only your account’s request. This does not start generation or spend credits.

Authentication: bearer API key. See authentication.

cancelAiImage

DELETE /v1/ai-images/{id}

Cancel an AI image request

Cancel a queued image and release its credits. A running image has already reached the image service, so it keeps running, costs 50 credits when it succeeds, and returns its current state. A finished request keeps its final state. This action never starts a generation.

Authentication: bearer API key. See authentication.

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}.

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"}.

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.

Schemas

AiImageVersion

Schema rules: {"type":"object","additionalProperties":false}.

AiImageHistory

Schema rules: {"type":"object","additionalProperties":false}.

AiImageCreate

Schema rules: {"type":"object","additionalProperties":false,"not":{"required":["parent_image_id","proposal_message_id"]}}.

AiImageGeneration

Schema rules: {"type":"object","additionalProperties":false}.

UploadedImage

Schema rules: {"type":"object","additionalProperties":false}.

Shared errors, headers, and authentication schemes are in shared types and security.