Alibaba

Qwen Image 2.1

qwen-image-2.1-turbo

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-turbo per image

Unit Price	$0.020

Positioning Overview

qwen-image-2.1-turbo is a model in the Qwen Image 2.1 series designed for high-frequency image generation and editing calls. It supports two types of tasks, text-to-image and image-to-image: generating an image directly from a given prompt, or passing in up to 10 reference images and making local edits to a specified image by referring to its index number. The output is a static image, available in aspect ratios such as 1:1 and 16:9, and it supports a fixed random seed to reproduce results. It is suitable for developers who need to produce visual assets in bulk and to rapidly iterate on prompts and validate prototypes.

Core Highlights

Generation and editing share the same set of call parameters — for text-to-image, no reference images are passed; for image editing, 1–10 image URLs are passed, while the prompts and the rest of the parameter structure stay the same, keeping integration cost low.
Multiple reference images can be referenced by number — multiple input images are numbered in array order, and prompts can use "image 1" and "image 2" to precisely specify the editing target, reducing ambiguity.
Controllable randomness — seed covers 0–2147483647; once fixed, results are relatively stable, which facilitates regression testing and reproducibility for batch tasks.

Capabilities

Unified calls for text-to-image and image-to-image: prompt is required; if image_urls is not passed, it is pure text generation, while passing 1–10 public web images turns it into an editing task, so a single API covers both needs.

Multiple reference images and referenced editing: up to 10 reference images can be supplied at once and are automatically numbered; prompts can make local changes to specified images, which suits compositing multiple assets or region-based editing.

Controlled aspect ratio and size: aspect_ratio offers five options — 1:1, 16:9, 9:16, 4:3, and 3:4 — corresponding to fixed pixel sizes such as 2048×2048 and 2688×1536; if not passed, the model selects automatically based on the prompt and reference images.

Prompt extension switch: prompt_extend is enabled by default and can automatically optimize short prompts, at the cost of a few extra seconds of processing time; when text must strictly follow the original layout or render specified characters, it can be disabled to ensure controllability.

Long prompts and text rendering: prompt supports up to 4500 characters in either Chinese or English; text that should appear in the image can be written into the prompt verbatim, and a transparent background can also be declared in the prompt.

Use Cases

Design teams producing initial visual drafts in bulk — generate finished images from a text description as input and choose the aspect ratio as needed, for quickly producing large volumes of first drafts for event materials, social media graphics, and similar scenarios.
E-commerce operations recoloring parts of product images — upload the original product image and describe the region to change; the output keeps the same composition, and the modified version can be used directly for detail-page replacement and multi-color SKU display.
Multi-asset compositing and reference-image editing — pass in multiple reference images at once and refer to them by number; the output is a single fused or replaced image, for compositing scenarios and asset integration.
Batch pipelines with reproducible results — by fixing the seed and prompt combination and calling repeatedly, relatively stable output is obtained, making it easy to integrate into automated testing and asset rollback workflows.

Limitations and Selection Advice

This model outputs static images only and does not support video or dynamic content. Reference images must be publicly accessible URLs, no larger than 10 MB each, with width and height between 1 and 8000 pixels and a long-to-short side ratio no greater than 10:1; anything outside this range must be handled beforehand. The aspect ratio can only be chosen from the five fixed options, and resolution cannot be specified arbitrarily. Enabling prompt extension adds a few seconds of processing time; for text rendering that requires strict layout, it is recommended to disable it and verify the result manually. It is suitable for medium-scale generation and editing tasks where speed and cost are the priority; for higher image quality or larger call quotas, choose the pro version in the same series.

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-turbo

routestringOptional

Current fixed value: default

inputobjectRequired

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

seedintegerOptionalmin 0max 2147483647

Random seed, an integer from 0 to 2147483647; fixing the seed makes the generated result relatively stable, while leaving it unset gives a random seed.

promptstringRequiredminLength 1maxLength 4500

Describe the image to generate, or explain what modifications to make to the reference image; both Chinese and English are supported. Text to be rendered must be written verbatim into the prompt; if a transparent background is needed, state "transparent background" in the prompt.

image_urlsarrayOptionalminItems 1maxItems 10

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

Array [ string ]

aspect_ratiostringOptional

Output aspect ratio, corresponding to 2048×2048, 2688×1536, 1536×2688, 2368×1728, 1728×2368; if not provided, the model automatically selects the size based on the prompt and reference image.

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

prompt_extendbooleanOptionalDefault: true

Whether to automatically optimize the prompt, default true. When enabled, it noticeably improves short prompts but adds a few seconds of processing time; it can be disabled when strict adherence to the original text layout is required.

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-turbo",
  "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-turbo",
    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-turbo",
        "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"
    }
  }
}