Image Model Guide

Call image models through the TokenHub inference gateway. Request body follows the standard synchronous HTTP shape: model + input [+ parameters]。

1. Basic Calling Information

Item	Description
Base URL	`https://tokenhub.link`
Endpoint	`POST https://tokenhub.link/v1/images/generations`
Authentication	`Authorization: Bearer <TokenHub API Key>`. Create the key in API Keys in console. It is shown only once when created.
Model Identifier	Use `model` in request body. For supported models, check Model Catalog. You can call with model name or provider/model format, for example `deepseek-v3.2` and `alibaba/deepseek-v3.2`.
Content-Type	Must be `application/json`.

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