Alibaba

Qwen Image 2.1

qwen-image-2.1-pro

A unified image model for text-to-image generation and image editing, with native support for 2K resolution and RGBA output with a real alpha channel, allowing multiple edit regions to be specified using circles, hand-drawn annotations, or masks

qwen-image-2.1-pro qwen-image-2.1-turbo

Pricing

qwen-image-2.1-pro per image

Unit Price	$0.050

Positioning Overview

Qwen Image 2.1 Pro is the high-quality tier in the Qwen team's image model series, called through the unified HiAPI.ai interface, and a single model supports both text-to-image and image editing. It can perform color changes, replacements, local repainting, and other edits based on 1 to 10 reference images, and can also do pure text-to-image, with output supporting various aspect ratios from 1:1 to 9:16, and results can be fixed with a seed and controlled transparent backgrounds via prompts. It is suitable for product and design workflows that require high-precision image generation and multi-image reference editing.

Core Highlights

Generation and editing share one model — no need to switch model weights between text-to-image and image-to-image; a single call chain covers both task types.
Up to 10 reference images referenced in order — multi-image input is numbered by array order and can be precisely referenced in the prompt as "image 1", "image 2", facilitating multi-asset composition and consistency editing.
Reproducible with seeds, convenient for regression verification — a fixed random seed from 0 to 2147483647 keeps results relatively stable, suitable for batch workflows and debugging that require repeated image generation.
Optional automatic prompt expansion switch — prompt_extend is enabled by default, noticeably improving short prompts; it can be disabled when strict adherence to the original layout is needed, preserving the original intent.

Capability Description

Unified text-to-image and image editing: the same model can both generate scenes from prompts and modify reference images according to prompts, reducing the style and workflow fragmentation caused by chaining multiple models.

Multi-reference image input: supports 1 to 10 public network image inputs, numbered by array order and referenced in the prompt, usable for multi-asset fusion and region-specific editing.

Multi-aspect-ratio output: five aspect ratios are available: 1:1, 16:9, 9:16, 4:3, and 3:4, corresponding to sizes up to 2688×1536, etc.; if not provided, the model automatically selects based on the prompt and reference images.

Transparent background control: simply state "transparent background" in the prompt to generate an image with a transparent background, saving the subsequent cutout step.

Reproducible results: by fixing the random seed through the seed parameter, relatively stable output can be obtained under the same input, facilitating batch generation and effect regression.

Applicable Scenarios

Asset retouching for e-commerce and design teams — upload product or model reference images, specify modifications such as color changes and clothing region replacement with prompts, and obtain finished images directly usable for detail pages and advertising assets.
Brand visuals composed from multiple assets — input multiple reference images and reference them in order to generate a composite scene with a unified style, for posters, social media graphics, and event materials.
Icons and product images requiring transparent backgrounds — request a transparent background in the prompt to directly produce image assets that can be overlaid onto interfaces or composite layers, reducing post-processing steps.
Automated pipelines for batch image generation — fix the seed and aspect ratio parameters, and embed generation or editing calls into the content production pipeline for stable output of serialized images.

Limitations and Selection Advice

This model is the high-quality tier in the series; single-image generation time and cost are higher than the turbo tier in the same series, making it suitable for scenarios with high requirements for image quality; for large-batch previews or low-cost initial screening, consider the turbo tier. Input reference images must be publicly accessible URLs, no more than 10 MB each, and the ratio of the longer side to the shorter side must not exceed 10:1. The prompt limit is 4500 characters; when strict adherence to the original layout is needed, it is recommended to disable automatic expansion. If the task prioritizes extremely low latency, or only requires simple batch generation, lighter options should be evaluated.

Create a generation task

POST https://api.hiapi.ai/v1/tasks

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.

Idempotency-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.

Body

modelstringRequired

Current fixed value: qwen-image-2.1-pro

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for qwen-image-2.1-pro and route default — see the parameter table below.

seedintegerOptionalmin 0max 2147483647

Random seed, an integer from 0 to 2147483647; fixing this value makes the generation result relatively stable, while leaving it out generates randomly.

promptstringRequiredminLength 1maxLength 4500

Describe the image content to generate, or explain what modifications need to be made to the reference image; both Chinese and English are acceptable. Any text that needs to be rendered must be written verbatim into the prompt. If a transparent background is needed, explicitly state "transparent background" in the prompt.

image_urlsarrayOptionalminItems 1maxItems 10

An array of public URLs for reference images or images to be edited, 1–10 images; if not provided, it becomes text-to-image. Multiple images are numbered in array order (they can be referred to as "image 1", "image 2"). Supports JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF, with each image no larger than 10 MB, width and height both between 1 and 8000 pixels (384–2048 recommended), and a long-side to short-side ratio no greater than 10:1.

Array [ string ]

aspect_ratiostringOptional

Output aspect ratio, with a string value corresponding to sizes such as 2048×2048, 2688×1536, 1536×2688, 2368×1728, and 1728×2368; if not provided, the model automatically selects based on the prompt and reference images.

Options:1:116:99:164:33:4

prompt_extendbooleanOptionalDefault: true

Whether to automatically optimize the prompt, a boolean value, default true; when enabled, the improvement is noticeable for short prompts, but it adds a few seconds of processing time. It can be disabled when the original text layout must be strictly followed.

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.

urlstringRequired

Required when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.

whenstringOptionalDefault: "final"

Only final is supported today — notified on both success and fail.

Options:final

storagestringOptionalDefault: "temp"

Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.

Options:temppersistent

Request examples

# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen-image-2.1-pro",
  "input": {
    "prompt": "…",
    "prompt_extend": true
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen-image-2.1-pro",
    input: {
      "prompt": "…",
      "prompt_extend": true
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "qwen-image-2.1-pro",
        "input": {
          "prompt": "…",
          "prompt_extend": True
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Get task detail

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

queued Queued, not started yet. handling Being processed. archiving Processing finished, artifacts being prepared. success Terminal: completed, artifacts available (output returned). fail Terminal: failed (error returned). After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix seconds when the task reached a terminal state; fixed to 0 while not terminal.

outputarrayOptional

Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).

Array [ object ]

Array items

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error description.

Response examples

Success

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Processing (non-terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Failed

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}