Text-to-Image & Image-to-Image

Send a text description to /v1/images/generations to generate an image (text-to-image), or pass reference images and have the model redraw the whole image based on the original (image-to-image); models such as doubao-seedream-5-0-pro can also decompose a reference image into a base image plus independent layers on this endpoint (see the Seedream Layer Decomposition section below). Image models are mostly billed per call, independent of token count; for specific models and unit prices see the Model Plaza. Below we use qwen-image-2.0.

TIP
  • For localized editing and masked inpainting, use Image Editing (/v1/images/edits, multipart form upload of the original) instead
  • The Vega series (wand-vega-image-*) has moved to the Vega async task API — the synchronous endpoint no longer supports it

Endpoint

POST /v1/images/generations

Authentication

Pass the Bearer token in the request header (see Base URL & Authentication):

Authorization: Bearer sk-your-token

Request Body

FieldTypeRequiredNotes
modelstringYesImage model name
promptstringYesScene description
sizestringNoImage size, e.g. 1024x1024
nintegerNoNumber of images, default 1
NOTE

size values and billing tiers vary by model: Doubao Seedream models use tier strings like 2K / 4K, while Qwen models use widthxheight format (e.g. 1024x1024). Check each model's details on the Model Plaza.

Text-to-Image

cURL
Python (openai)
Node.js (openai)
curl https://api-model.shuntianchuang.cn/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "一只戴耳机的橘猫在写代码,扁平插画风格",
    "size": "1024x1024",
    "n": 1
  }'

Each image in the response comes in two formats:

  • url: download link for the image — fetch it directly to get the file
  • b64_json: Base64-encoded image string, for scenarios where external links are inconvenient (add "response_format": "b64_json" to the request)

Image-to-Image

Same endpoint /v1/images/generations: pass in reference images and the model redraws the whole image based on the original (change style, change scene, keep the composition and subject, etc.). To upload a local original or do localized inpainting edits, use Image Editing instead.

Common fields are listed below. How reference images are passed and which vendor-specific parameters apply vary by vendor — pick the matching format below for your model:

FieldTypeRequiredNotes
modelstringYesAn image model that supports image-to-image
promptstringYesRedraw description; explicitly state "keep the original image / design" and alike
sizestringNoOutput size; allowed values vary by model
response_formatstringNoReturn format: url / b64_json
TIP

Qwen image-to-image models (names containing edit, e.g. qwen-image-edit-plus) do not use this endpoint — use /v1/images/edits under Image Editing (multipart form upload of the original) instead.

Doubao Seedream Format

Doubao Seedream models such as doubao-seedream-4-5 and doubao-seedream-5-0 pass a publicly accessible reference image URL via the top-level image field:

FieldTypeRequiredNotes
modelstringYese.g. doubao-seedream-4-5
promptstringYesRedraw description, e.g. "cyberpunk night scene, keep the original composition and subject unchanged"
imagestring / string[]YesReference image URL — doubao-seedream-5-0 accepts multiple; public links only, local files not supported
sizestringNoOutput size, e.g. 2K, or 2048x2048; allowed values vary by model
sequential_image_generationstringNoSeedream-series group-image switch; must be disabled for image-to-image, otherwise generated in group mode; not supported by doubao-seedream-5-0
watermarkboolNoAdd a watermark
NOTE

The field combinations above were verified against doubao-seedream-4-5 and doubao-seedream-5-0; some Seedream models accept multiple reference images — defer to the model details on the Model Plaza and actual responses.

cURL
Python (openai)
Node.js (openai)
curl -X POST https://api-model.shuntianchuang.cn/v1/images/generations \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-5",
    "prompt": "赛博朋克夜景,保持原图构图主体不变",
    "image": "https://xxx/reference-image.png",
    "size": "2K",
    "sequential_image_generation": "disabled",
    "response_format": "url",
    "watermark": false
  }'

Seedream Layer Decomposition

Layer-decomposition models such as doubao-seedream-5-0-pro take a top-level layer_decomposition: true on the same endpoint and output a base image plus several independent layers. The request must pass exactly 1 reference image:

FieldTypeRequiredNotes
modelstringYesA model that supports layer decomposition, e.g. doubao-seedream-5-0-pro
promptstringNoSplit instructions; may be omitted
imagestringYesReference image URL — public links only, and exactly 1 image
sizestringNo1K / 1.5K / 2K / auto, default auto
layer_decompositionboolYesAlways true
response_formatstringNoAlways url
watermarkboolNoAdd a watermark
NOTE
  • Currently only doubao-seedream-5-0-pro and doubao-seedream-5-0-flash-260915 support it; 4.5, 5.0 lite, and 5.0 do not
  • The output is the base image plus layers, up to 17 images; each item in data carries one url
cURL
Python (openai)
Node.js (openai)
curl -X POST https://api-model.shuntianchuang.cn/v1/images/generations \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "把这张图拆成底图和独立图层",
    "size": "1.5K",
    "image": "https://xxx/reference-image.png",
    "layer_decomposition": true,
    "response_format": "url",
    "watermark": false
  }'