Image Model Guide

Image models use different request shapes by supplier recipe. Pick a protocol tab below.

1. Basic Calling Information

Item	Description
Base URL	`https://tokenhub.link`
Endpoint	`POST /v1/images/generations` (sync)
Authentication	`Authorization: Bearer <TokenHub API Key>`. Create the key in API Keys in console.
Model Identifier	Use `model` in body. See Model Catalog — e.g. `wan2.6-t2i`, `tokenhub/gpt-image-2`.
Content-Type	`application/json`

2. Request body by supplier protocol

TokenHub routes by invocation recipe (bodyShape). Use the tab that matches your model supplier.

cURL example

curl -sS "https://tokenhub.link/v1/images/generations" \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tokenhub/gpt-image-2",
    "prompt": "一只橘猫在窗边，摄影风格",
    "size": "1024x1024",
    "n": 1
  }'

Key fields

prompt — required text prompt (flat JSON, no input.messages)
size — e.g. 1024x1024
output_format, watermark — optional

2. cURL Example (passthrough)

Text-to-image example using a single-turn input.messages payload:

curl -sS "https://tokenhub.link/v1/images/generations" \
              -H "Authorization: Bearer $TOKENHUB_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "wan2.6-t2i",
                "input": {
                  "messages": [
                    {
                      "role": "user",
                      "content": [
                        {
                          "text": "A flower shop with elegant windows, a beautiful wooden door, and fresh flowers on display."
                        }
                      ]
                    }
                  ]
                },
                "parameters": {
                  "prompt_extend": true,
                  "watermark": false,
                  "n": 1,
                  "negative_prompt": "",
                  "size": "1280*1280"
                }
              }'

On success, returns HTTP 200 with upstream JSON fields. Example response structure:

{
              "output": {
                "choices": [
                  {
                    "finish_reason": "stop",
                    "message": {
                      "content": [
                        {
                          "image": "https://dashscope-xxxx.oss-accelerate.aliyuncs.com/...png",
                          "type": "image"
                        }
                      ],
                      "role": "assistant"
                    }
                  }
                ],
                "finished": true
              },
              "usage": {
                "image_count": 1,
                "input_tokens": 0,
                "output_tokens": 0,
                "size": "1280*1280",
                "total_tokens": 0
              },
              "request_id": "815505c6-7c3d-49d7-b197-xxxxx"
            }

Image URLs are usually temporary (commonly around 24 hours). Save files to your own storage in time.

3. Parameter Reference

3.1 Top-level Request Body

Field	Type	Required	Description
`model`	`string`	Yes	Model name, for example `wan2.7-image-pro`.
`input`	`object`	Yes	Multimodal input object. Core field is `input.messages`.
`parameters`	`object`	No	Generation control parameters. See the table below.

3.2 Detailed Fields for input.messages / content

Field	Type	Required	Description
`input.messages`	`array`	Yes	Message array. Typical examples use a single `user` message.
`messages[].role`	`string`	Yes	Role. Typical value is `user`.
`messages[].content`	`array`	Yes	Multimodal content list; can combine `text` and `image` items.
`content[].text`	`string`	Conditional	Text prompt. In pure text-to-image scenarios, at least one `text` item is required.
`content[].image`	`string(URL)`	Conditional	Reference/edit image URL. Image editing and interactive editing commonly pass one or two images.

3.3 Detailed Fields for parameters

Field	Type	Required	Description
`negative_prompt`	`string`	No	Negative prompt to constrain unwanted elements.
`size`	`string`	No	Output size, for example `2K`. Must use size tiers supported by the model.
`n`	`integer`	No	Number of generated images. Group-image scenarios may use values such as `4`.
`prompt_extend`	`boolean`	No	Whether to enable prompt expansion.
`watermark`	`boolean`	No	Whether to add watermark.
`thinking_mode`	`boolean`	No	Whether to enable thinking mode (depending on model support).
`bbox_list`	`array`	No	Bounding-box coordinate list for interactive editing.
`enable_sequential`	`boolean`	No	Enable sequence consistency for grouped image generation.

4. Official Scenario Examples (updated with TokenHub endpoints)

4.1 Text-to-Image

curl --location 'https://tokenhub.link/v1/images/generations' \
            --header 'Content-Type: application/json' \
            --header "Authorization: Bearer $TOKENHUB_API_KEY" \
            --data '{
                "model": "wan2.7-image-pro",
                "input": {
                    "messages": [
                        {
                            "role": "user",
                            "content": [
                                {"text": "A flower shop with elegant windows, a beautiful wooden door, and fresh flowers on display."}
                            ]
                        }
                    ]
                },
                "parameters": {
                    "size": "2K",
                    "n": 1,
                    "watermark": false,
                    "thinking_mode": true
                }
            }'

4.2 Image Editing

curl --location 'https://tokenhub.link/v1/images/generations' \
            --header 'Content-Type: application/json' \
            --header "Authorization: Bearer $TOKENHUB_API_KEY" \
            --data '{
                "model": "wan2.7-image-pro",
                "input": {
                    "messages": [
                        {
                            "role": "user",
                            "content": [
                                {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"},
                                {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"},
                                {"text": "Apply the graffiti style from image 2 onto the car in image 1."}
                            ]
                        }
                    ]
                },
                "parameters": {
                    "size": "2K",
                    "n": 1,
                    "watermark": false
                }
            }'

4.3 Interactive Editing

curl --location 'https://tokenhub.link/v1/images/generations' \
            --header 'Content-Type: application/json' \
            --header "Authorization: Bearer $TOKENHUB_API_KEY" \
            --data '{
                "model": "wan2.7-image-pro",
                "input": {
                    "messages": [
                        {
                            "role": "user",
                            "content": [
                                {"image": "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp"},
                                {"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"},
                                {"text": "Place the alarm clock from image 1 into the selected box in image 2, keeping scene and lighting naturally blended."}
                            ]
                        }
                    ]
                },
                "parameters": {
                    "bbox_list": [[],[[989, 515, 1138, 681]]],
                    "size": "2K",
                    "n": 1,
                    "watermark": false
                }
            }'

4.4 Group Image Generation

curl --location 'https://tokenhub.link/v1/images/generations' \
            --header 'Content-Type: application/json' \
            --header "Authorization: Bearer $TOKENHUB_API_KEY" \
            --data '{
                "model": "wan2.7-image-pro",
                "input": {
                    "messages": [
                        {
                            "role": "user",
                            "content": [
                                {"text": "A cinematic four-image sequence featuring the same stray orange cat with consistent appearance: Image 1 (spring): the cat walks under blooming cherry blossoms; Image 2 (summer): the cat rests in the shade on an old street; Image 3 (autumn): the cat steps on golden fallen leaves; Image 4 (winter): the cat leaves footprints in the snow."}
                            ]
                        }
                    ]
                },
                "parameters": {
                    "enable_sequential": true,
                    "n": 4,
                    "size": "2K"
                }
            }'

5. Reference Links

cURL example

curl -sS "https://tokenhub.link/v1/images/generations" \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ark/doubao-seedream-4-0-250828",
    "prompt": "日落下的城市天际线，电影感光影",
    "size": "1024x1024"
  }'

Key fields

model + prompt + size — flat JSON (same shape as TokenHub)
Use ark/<model_id> or canonical id from catalog

Volcengine Ark documentation