Qwen Image 2.0 API Documentation

Overview

Generate and edit images with Qwen Image models using text prompts and optional reference images.

Primary Endpoint

POST/api/v1/userQwen2Image/start

Create an asynchronous Qwen Image 2.0 or 3.0 task. The server infers image editing when `input_images` contains a valid HTTP(S) image URL and text-to-image generation otherwise. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userQwen2Image/list` — List Qwen image tasks. - `GET /api/v1/userQwen2Image/detail/{id}` — Get Qwen image task details. - `DELETE /api/v1/userQwen2Image/{id}` — Delete a Qwen image task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	Yes	Task name
prompt	string	Yes	Image generation or editing prompt
creation_mode	enum: text-to-image \| image-edit	No	Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider.
model	enum: qwen-image-2.0 \| qwen-image-2.0-pro \| qwen-image-3.0 \| qwen-image-3.0-pro	No	default: "qwen-image-2.0"
input_images	array<string>	No	Optional public reference image URLs
size	enum: 10241024 \| 1328880 \| 8801328 \| 1152864 \| 8641152 \| 1280720 \| 7201280 \| 1512648 \| 20482048 \| 20481365 \| 13652048 \| 20481536 \| 15362048 \| 20481152 \| 1152*2048	No	1K sizes are supported by all Qwen Image models. 2K sizes (2048) are supported only by qwen-image-3.0-pro.; default: "10241024"
negative_prompt	string	No	default: ""
prompt_extend	boolean	No	default: true
force_generate	boolean	No	Explicitly retry an NSFW soft block. Does not bypass other checks.
minor_suspected_skip	boolean	No	Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.; default: false
webhook_url	string	No	HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.; maxLength: 2048
webhook_token	string	No	Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.; maxLength: 256

Request schema and conditional rules

{
  "allOf": [
    {
      "type": "object",
      "required": [
        "name",
        "prompt"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Task name"
        },
        "prompt": {
          "type": "string",
          "description": "Image generation or editing prompt"
        },
        "creation_mode": {
          "type": "string",
          "enum": [
            "text-to-image",
            "image-edit"
          ],
          "description": "Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."
        },
        "model": {
          "type": "string",
          "enum": [
            "qwen-image-2.0",
            "qwen-image-2.0-pro",
            "qwen-image-3.0",
            "qwen-image-3.0-pro"
          ],
          "default": "qwen-image-2.0"
        },
        "input_images": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Optional public reference image URLs"
        },
        "size": {
          "type": "string",
          "enum": [
            "1024*1024",
            "1328*880",
            "880*1328",
            "1152*864",
            "864*1152",
            "1280*720",
            "720*1280",
            "1512*648",
            "2048*2048",
            "2048*1365",
            "1365*2048",
            "2048*1536",
            "1536*2048",
            "2048*1152",
            "1152*2048"
          ],
          "description": "1K sizes are supported by all Qwen Image models. 2K sizes (2048*) are supported only by qwen-image-3.0-pro.",
          "default": "1024*1024"
        },
        "negative_prompt": {
          "type": "string",
          "default": ""
        },
        "prompt_extend": {
          "type": "boolean",
          "default": true
        },
        "force_generate": {
          "type": "boolean",
          "description": "Explicitly retry an NSFW soft block. Does not bypass other checks."
        },
        "minor_suspected_skip": {
          "type": "boolean",
          "default": false,
          "description": "Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."
        }
      }
    },
    {
      "$ref": "#/components/schemas/WebhookInput"
    }
  ]
}

Response Fields

code: enum: 0
data: object
data._id: string: Task ID for detail and batch polling.
data.name: string
data.prompt: string
data.is_downloaded: boolean
data.is_previewed: boolean
data.current_status: string: Persisted task state; use the concrete task family schema for its allowed values and terminal states.
data.createdAt: string
data.updatedAt: string
data.expirationDate: string
data.remainingDays: number
data.isExpired: boolean
data.coins: number
data.hasRefundCoin: boolean: Whether charged credits were refunded.
data.failed_code: string
data.failed_message: string
data.failed_reason: string: Public failure category when available.
data.creation_mode: string
data.image_url: string
data.image_urls: array<string>
data.result_image_url: string
data.result_image_urls: array<string>
data.input_images: array<string>
data.nsfw_detected: enum: true
data.message: string
trace_id: string: Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.

Request Example

curl -X POST "https://headswap.app/api/v1/userQwen2Image/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My Task",
  "prompt": "high quality, clear, cinematic"
}'

Related Endpoints

GET/api/v1/userQwen2Image/detail/{id}

Get Qwen image task details

POST/api/v1/userQwen2Image/start

Start a new Qwen image generation/edit task

GET/api/v1/userQwen2Image/list

List Qwen image tasks

POST/api/v1/userQwen2Image/batchDetail

Batch get Qwen image task details

DELETE/api/v1/userQwen2Image/{id}

Delete a Qwen image task

Responses

200

Task created successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.

401

Unauthorized - Invalid or missing bearer token