Wan Image Series - QWave API

POST

tasks

Wan Image Series

curl --request POST \
  --url https://www.qingbo.dev/v1/tasks \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "action": "<string>",
  "prompt": "<string>",
  "n": 123,
  "seed": 123,
  "aspect_ratio": "<string>",
  "resolution": "<string>",
  "image_urls": [
    "<string>"
  ],
  "callback_url": "<string>",
  "callback_events": [
    "<string>"
  ],
  "watermark": true,
  "thinking_mode": true,
  "enable_sequential": true,
  "color_palette": [
    {}
  ],
  "bbox_list": [
    {}
  ]
}
'

import requests

url = "https://www.qingbo.dev/v1/tasks"

payload = {
    "model": "<string>",
    "action": "<string>",
    "prompt": "<string>",
    "n": 123,
    "seed": 123,
    "aspect_ratio": "<string>",
    "resolution": "<string>",
    "image_urls": ["<string>"],
    "callback_url": "<string>",
    "callback_events": ["<string>"],
    "watermark": True,
    "thinking_mode": True,
    "enable_sequential": True,
    "color_palette": [{}],
    "bbox_list": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    action: '<string>',
    prompt: '<string>',
    n: 123,
    seed: 123,
    aspect_ratio: '<string>',
    resolution: '<string>',
    image_urls: ['<string>'],
    callback_url: '<string>',
    callback_events: ['<string>'],
    watermark: true,
    thinking_mode: true,
    enable_sequential: true,
    color_palette: [{}],
    bbox_list: [{}]
  })
};

fetch('https://www.qingbo.dev/v1/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.qingbo.dev/v1/tasks"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"action\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"n\": 123,\n  \"seed\": 123,\n  \"aspect_ratio\": \"<string>\",\n  \"resolution\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"callback_url\": \"<string>\",\n  \"callback_events\": [\n    \"<string>\"\n  ],\n  \"watermark\": true,\n  \"thinking_mode\": true,\n  \"enable_sequential\": true,\n  \"color_palette\": [\n    {}\n  ],\n  \"bbox_list\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.qingbo.dev/v1/tasks")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"action\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"n\": 123,\n  \"seed\": 123,\n  \"aspect_ratio\": \"<string>\",\n  \"resolution\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"callback_url\": \"<string>\",\n  \"callback_events\": [\n    \"<string>\"\n  ],\n  \"watermark\": true,\n  \"thinking_mode\": true,\n  \"enable_sequential\": true,\n  \"color_palette\": [\n    {}\n  ],\n  \"bbox_list\": [\n    {}\n  ]\n}")
  .asString();

{
  "task_id": "task-wave1775290140a830128812",
  "model": "wan2.7-image",
  "action": "generate",
  "status": "queued",
  "created_at": 1775290140120,
  "progress": 0
}

Alibaba Tongyi Wanxiang 2.7 unified interface for image generation and editing. Covers wan2.7-image-pro (professional, text-to-image up to 4K) and wan2.7-image (standard, up to 2K) tiers. The two tiers share the same interface via internal tier switching, and are exposed as a single model externally. Six call modes:

Text-to-image (generate) — prompt only, with optional thinking mode
Image-to-image (image2image) — Free-form generation from a single reference
Image edit (edit) — Inpainting / style transfer / element replacement
Multi-image reference (reference) — Fuse up to 9 reference images
Image group (group) — enable_sequential for comic strips / storyboards, max n = 12
Interactive editing (interactive_edit) — bbox_list targeted region editing (exclusive)

Per-image pricing, unified at $0.02295 per image.

Pricing

Model	Price (per image)
`wan2.7-image`	`$0.02295`

Mode Quick Reference

Mode	Trigger Field	action
Text-to-image	`prompt` only (optional `thinking_mode`)	`generate`
Image-to-image	`+ image_urls` (single)	`image2image`
Image edit	`+ image_urls` (single) + edit-instruction prompt	`edit`
Multi-image reference fusion	`+ image_urls` (2-9)	`reference`
Image group (comic / storyboard)	`enable_sequential: true` + `n` ≤ 12	`group`
Interactive bbox editing	`+ image_urls` + `bbox_list`	`interactive_edit`

Examples

curl -X POST https://www.qingbo.dev/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image",
    "prompt": "Classical Chinese landscape scroll, ink-wash mood, distant mountains in dark green, near water in mist",
    "resolution": "4K",
    "aspect_ratio": "16:9",
    "thinking_mode": true
  }'

curl -X POST https://www.qingbo.dev/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image",
    "action": "reference",
    "prompt": "Place the character from the first image into the scene from the second, with outfit inspired by the third",
    "image_urls": [
      "https://cdn.example.com/character.jpg",
      "https://cdn.example.com/scene.jpg",
      "https://cdn.example.com/outfit.jpg"
    ],
    "resolution": "2K",
    "aspect_ratio": "3:4"
  }'

curl -X POST https://www.qingbo.dev/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image",
    "action": "group",
    "prompt": "A day in the life of a little fox: morning / foraging / playing / sleeping, 4-panel comic strip",
    "enable_sequential": true,
    "n": 4,
    "resolution": "2K",
    "aspect_ratio": "1:1"
  }'

curl -X POST https://www.qingbo.dev/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image",
    "action": "interactive_edit",
    "prompt": "Replace the cat in the box with a Shiba Inu, keep pose and lighting",
    "image_urls": ["https://cdn.example.com/cat.jpg"],
    "bbox_list": [[[120, 80, 540, 460]]],
    "resolution": "2K"
  }'

curl -X POST https://www.qingbo.dev/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image",
    "prompt": "Minimalist poster, geometric composition, restrained whitespace",
    "color_palette": [
      {"hex": "#0A2540", "ratio": 50},
      {"hex": "#F5F5F0", "ratio": 35},
      {"hex": "#E04B3A", "ratio": 15}
    ],
    "resolution": "4K",
    "aspect_ratio": "2:3"
  }'

{
  "task_id": "task-wave1775290140a830128812",
  "model": "wan2.7-image",
  "action": "generate",
  "status": "queued",
  "created_at": 1775290140120,
  "progress": 0
}

After submission, poll status with GET /v1/tasks/{task_id}. See Task System for details.

Available Models

Model ID	Description
`wan2.7-image`	Alibaba Tongyi Wanxiang 2.7. Unified interface for text-to-image / image-to-image / editing / multi-image reference / image groups / interactive bbox editing. Up to 4K

Common Parameters

model

string

required

Choose one from the Available Models list. Currently wan2.7-image

action

string

default:"generate"

Operation type. Options:

generate — Text-to-image (default)
image2image — Image-to-image (use with single image_urls)
edit — Image editing (inpainting / style transfer)
reference — Multi-image reference fusion (up to 9)
group — Image group generation (use with enable_sequential)
interactive_edit — Interactive bbox editing (use with bbox_list)

prompt

string

required

Image description. Supports Chinese and English. For image-group mode, storyboard-style descriptions work best

integer

default:"1"

Number of images. Standard mode is bounded by service-side limits; image-group mode (enable_sequential: true) allows up to 12

seed

integer

default:"-1"

Random seed. -1 for random; a fixed value reproduces similar results

aspect_ratio

string

default:"1:1"

Aspect ratio, 7 options:

1:1 — Square
16:9 / 9:16 — Widescreen landscape / portrait
4:3 / 3:4 — Standard landscape / portrait
3:2 / 2:3 — Camera ratio landscape / portrait

resolution

string

default:"2K"

Output resolution. Options: 1K / 2K / 4K. Note: image-group mode caps at 2K

image_urls

string[]

Array of reference image URLs:

image2image / edit / interactive_edit: 1 image
reference: 2-9 images

callback_url

string

Webhook callback URL, invoked when the task reaches a terminal state. See Callback Mechanism

callback_events

string[]

Subscribed callback event types. See Callback Mechanism

Model-Specific Parameters

watermark

boolean

default:"false"

AI-generated watermark

thinking_mode

boolean

default:"true"

Thinking mode — when enabled, the model performs visual reasoning before generation, improving parsing accuracy on complex prompts.Activation conditions: only applies when not in image-group mode (enable_sequential not true) and without image input (image_urls not provided); ignored otherwise

enable_sequential

boolean

default:"false"

Image-group mode (comic strip / storyboard). When enabled:

n cap raises to 12
resolution capped at 2K
thinking_mode and color_palette have no effect

Suited for storyboards, comic strips, and themed e-commerce sets — any “themed group of related images” use case

color_palette

array

Custom color palette. 3-10 items of {hex, ratio}, with ratio summing to 100%.Activation condition: only applies in non-group mode. See Composite Field Reference

bbox_list

array

Interactive editing bbox list, one-to-one with image_urls, max 2 boxes per image.Only applies when action: "interactive_edit". See Composite Field Reference

Composite Field Reference

`color_palette` — Custom Color Palette

Specifies primary colors and their proportions for the output. The model distributes color coverage in the image based on the given ratios. Structure: array, each item is {hex, ratio}

Field	Type	Description
`hex`	string	Hex color, e.g. `#0A2540`, case-insensitive
`ratio`	number	Percentage coverage in the image. All items must sum to 100

Constraints:

Item count: 3-10
Sum of ratio: strictly 100 (integer percentages)
Only effective in non-group mode (ignored when enable_sequential is true)

Example:

"color_palette": [
  {"hex": "#0A2540", "ratio": 50},
  {"hex": "#F5F5F0", "ratio": 35},
  {"hex": "#E04B3A", "ratio": 15}
]

`bbox_list` — Interactive Editing Boxes

Draw boxes on a reference image to tell the model “edit only inside the box,” leaving the outside unchanged. Exclusive capability of the Wan series for interactive editing. Structure: triple-nested array [[[x1, y1, x2, y2], ...], ...]

Outermost: each item corresponds to one image in image_urls, one-to-one (counts must match)
Middle: multiple boxes on a single image, max 2 boxes per image
Innermost: coordinates of one box, 4 numbers [x1, y1, x2, y2], top-left and bottom-right corners (pixel coordinates)

Constraints:

Only applies when action: "interactive_edit"
Max 2 boxes per image
Coordinates use the reference image’s original pixels

Example (single image, single box):

"image_urls": ["https://cdn.example.com/cat.jpg"],
"bbox_list": [[[120, 80, 540, 460]]]

Example (single image, two boxes):

"image_urls": ["https://cdn.example.com/scene.jpg"],
"bbox_list": [[[100, 100, 400, 400], [500, 200, 800, 500]]]

Example (multiple images, one box each):

"image_urls": [
  "https://cdn.example.com/img-a.jpg",
  "https://cdn.example.com/img-b.jpg"
],
"bbox_list": [
  [[120, 80, 540, 460]],
  [[200, 150, 600, 500]]
]

Resource Limits

Item	Limit
Reference images (`reference`)	2-9
Reference images (`image2image` / `edit` / `interactive_edit`)	1
Single image size	≤ 30MB, supports JPG/PNG/WEBP
Output resolution	`1K` / `2K` / `4K` (group mode caps at `2K`)
Group count `n`	Up to 12 (requires `enable_sequential: true`)
`bbox_list` boxes	Max 2 per image
`color_palette` items	3-10, `ratio` sums to 100%
Output file	JPG URL, valid for 24 hours

Task System — Task state machine / polling cadence / async push
Request & Response — Common error codes / Headers / rate limits
Authentication — API Key application and usage

Z.ai ImageZhipu Z.ai image generation — lightweight and fast, bilingual prompts, low latency and low cost

Wan Image Series

curl --request POST \
  --url https://www.qingbo.dev/v1/tasks \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "action": "<string>",
  "prompt": "<string>",
  "n": 123,
  "seed": 123,
  "aspect_ratio": "<string>",
  "resolution": "<string>",
  "image_urls": [
    "<string>"
  ],
  "callback_url": "<string>",
  "callback_events": [
    "<string>"
  ],
  "watermark": true,
  "thinking_mode": true,
  "enable_sequential": true,
  "color_palette": [
    {}
  ],
  "bbox_list": [
    {}
  ]
}
'

import requests

url = "https://www.qingbo.dev/v1/tasks"

payload = {
    "model": "<string>",
    "action": "<string>",
    "prompt": "<string>",
    "n": 123,
    "seed": 123,
    "aspect_ratio": "<string>",
    "resolution": "<string>",
    "image_urls": ["<string>"],
    "callback_url": "<string>",
    "callback_events": ["<string>"],
    "watermark": True,
    "thinking_mode": True,
    "enable_sequential": True,
    "color_palette": [{}],
    "bbox_list": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    action: '<string>',
    prompt: '<string>',
    n: 123,
    seed: 123,
    aspect_ratio: '<string>',
    resolution: '<string>',
    image_urls: ['<string>'],
    callback_url: '<string>',
    callback_events: ['<string>'],
    watermark: true,
    thinking_mode: true,
    enable_sequential: true,
    color_palette: [{}],
    bbox_list: [{}]
  })
};

fetch('https://www.qingbo.dev/v1/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.qingbo.dev/v1/tasks"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"action\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"n\": 123,\n  \"seed\": 123,\n  \"aspect_ratio\": \"<string>\",\n  \"resolution\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"callback_url\": \"<string>\",\n  \"callback_events\": [\n    \"<string>\"\n  ],\n  \"watermark\": true,\n  \"thinking_mode\": true,\n  \"enable_sequential\": true,\n  \"color_palette\": [\n    {}\n  ],\n  \"bbox_list\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.qingbo.dev/v1/tasks")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"action\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"n\": 123,\n  \"seed\": 123,\n  \"aspect_ratio\": \"<string>\",\n  \"resolution\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"callback_url\": \"<string>\",\n  \"callback_events\": [\n    \"<string>\"\n  ],\n  \"watermark\": true,\n  \"thinking_mode\": true,\n  \"enable_sequential\": true,\n  \"color_palette\": [\n    {}\n  ],\n  \"bbox_list\": [\n    {}\n  ]\n}")
  .asString();

{
  "task_id": "task-wave1775290140a830128812",
  "model": "wan2.7-image",
  "action": "generate",
  "status": "queued",
  "created_at": 1775290140120,
  "progress": 0
}

​Pricing

​Mode Quick Reference

​Examples

​Available Models

​Common Parameters

​Model-Specific Parameters

​Composite Field Reference

​color_palette — Custom Color Palette

​bbox_list — Interactive Editing Boxes

​Resource Limits

​Related Docs

Pricing

Mode Quick Reference

Examples

Available Models

Common Parameters

Model-Specific Parameters

Composite Field Reference

`color_palette` — Custom Color Palette

`bbox_list` — Interactive Editing Boxes

Resource Limits

Related Docs