# Qwen Image 3.0 异步图像生成

> 图像生成

提交异步图像生成任务。请求成功后返回 `task_id`，可通过 `GET /v1/tasks/status` 查询任务状态与结果。

`input.prompt`、`input.images`、`input.img_url` 至少提供一项。仅提供 `input.prompt` 时为文生图（T2I）；
提供 `input.images` 或 `input.img_url` 时为图生图/图像编辑（I2I），支持 1-3 张参考图。

## 请求地址

`POST https://api.modelverse.cn/v1/tasks/submit`

## 请求体

## 响应

- **200** — 任务提交成功。
- **400** — 请求参数无效或任务提交失败。
- **default** — 错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "qwen-image-3.0接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 `qwen-image-3.0` 与 `qwen-image-3.0-pro` 的图片接口文档，说明如何发起文生图（T2I）或图生图/图像编辑（I2I）请求、填写参数、读取结果以及处理错误。\n接口路径包括 `POST /v1/images/generations`（同步）、`POST /v1/tasks/submit`（异步提交）与 `GET /v1/tasks/status`（异步状态查询）。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "该模型文档中使用的 ModelVerse API 端点。"
    }
  ],
  "tags": [
    {
      "name": "Qwen Image 3.0",
      "description": "qwen-image-3.0 与 qwen-image-3.0-pro 的同步与异步图像生成操作。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/images/generations": {
      "post": {
        "tags": [
          "qwen image 3.0"
        ],
        "operationId": "createQwenImage30Generation",
        "summary": "Qwen Image 3.0 图像生成",
        "description": "同步生成或编辑图像。模型支持 `qwen-image-3.0` 与 `qwen-image-3.0-pro`。\n\n`prompt`、`image`、`images` 至少提供一项。仅提供 `prompt` 时为文生图（T2I）；\n提供 `image` 或 `images` 时为图生图/图像编辑（I2I），支持 1-3 张参考图。\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QwenImage30GenerationRequest"
              },
              "examples": {
                "textToImage": {
                  "summary": "文生图",
                  "value": {
                    "model": "qwen-image-3.0-pro",
                    "prompt": "一只赛博朋克风格的猫，霓虹灯光，电影感构图",
                    "size": "1024*1024",
                    "n": 1,
                    "seed": 123456,
                    "watermark": false
                  }
                },
                "imageToImage": {
                  "summary": "图生图/图像编辑",
                  "value": {
                    "model": "qwen-image-3.0",
                    "prompt": "将参考图片转换为中国水墨画风格，保留主体与构图",
                    "image": "https://example.com/reference.png",
                    "size": "1536*1024",
                    "prompt_extend": true,
                    "watermark": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "图像生成响应。生成图片 URL 有效期为 24 小时。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenImage30GenerationResponse"
                },
                "examples": {
                  "generatedImages": {
                    "summary": "生成图像 URL",
                    "value": {
                      "created": 1775558400,
                      "data": [
                        {
                          "url": "https://example.com/generated-image-1.png"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效或图像生成失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenImage30ErrorResponse"
                },
                "examples": {
                  "agentWithImage": {
                    "summary": "图生图传入 agent 改写方式",
                    "value": {
                      "error": {
                        "code": "InvalidParameter",
                        "message": "prompt_extend_mode=agent is only supported for text-to-image (T2I)"
                      },
                      "request_id": "req_202604021530000001"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenImage30ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/QwenImage30InvalidParameterError"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "qwen image 3.0"
        ],
        "operationId": "submitQwenImage30Task",
        "summary": "Qwen Image 3.0 异步图像生成",
        "description": "提交异步图像生成任务。请求成功后返回 `task_id`，可通过 `GET /v1/tasks/status` 查询任务状态与结果。\n\n`input.prompt`、`input.images`、`input.img_url` 至少提供一项。仅提供 `input.prompt` 时为文生图（T2I）；\n提供 `input.images` 或 `input.img_url` 时为图生图/图像编辑（I2I），支持 1-3 张参考图。\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QwenImage30TaskSubmitRequest"
              },
              "examples": {
                "textToImage": {
                  "summary": "文生图任务",
                  "value": {
                    "model": "qwen-image-3.0-pro",
                    "input": {
                      "prompt": "一只赛博朋克风格的猫，霓虹灯光，电影感构图"
                    },
                    "parameters": {
                      "size": "1024*1024",
                      "prompt_extend": true,
                      "watermark": false
                    }
                  }
                },
                "imageToImage": {
                  "summary": "图生图/图像编辑任务",
                  "value": {
                    "model": "qwen-image-3.0",
                    "input": {
                      "prompt": "将参考图片转换为中国水墨画风格，保留主体与构图",
                      "images": [
                        "https://example.com/reference-1.png",
                        "https://example.com/reference-2.png"
                      ]
                    },
                    "parameters": {
                      "size": "1536*1024",
                      "prompt_extend": true,
                      "prompt_extend_mode": "direct",
                      "seed": 123456
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务提交成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenImage30TaskSubmitResponse"
                },
                "examples": {
                  "submitted": {
                    "summary": "已提交任务",
                    "value": {
                      "output": {
                        "task_id": "3c7d6b6c-7cdb-4f37-bf41-7f2b0f1a9f0d"
                      },
                      "request_id": "req_202604021530000001"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效或任务提交失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenImage30ErrorResponse"
                },
                "examples": {
                  "agentWithImage": {
                    "summary": "图生图传入 agent 改写方式",
                    "value": {
                      "error": {
                        "code": "InvalidParameter",
                        "message": "prompt_extend_mode=agent is only supported for text-to-image (T2I)"
                      },
                      "request_id": "req_202604021530000001"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenImage30ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/QwenImage30InvalidParameterError"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "Qwen Image 3.0"
        ],
        "operationId": "getQwenImage30TaskStatus",
        "summary": "Qwen Image 3.0 图像任务状态",
        "description": "查询异步图像任务的执行状态、结果 URL 与用量信息。",
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "由 `/v1/tasks/submit` 返回的异步任务标识。",
            "schema": {
              "type": "string"
            },
            "examples": {
              "documented": {
                "summary": "源文档占位值",
                "value": "<task_id>"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenImage30TaskStatusResponse"
                },
                "examples": {
                  "success": {
                    "summary": "成功任务",
                    "value": {
                      "output": {
                        "task_id": "3c7d6b6c-7cdb-4f37-bf41-7f2b0f1a9f0d",
                        "task_status": "Success",
                        "urls": [
                          "https://example.com/generated-image-1.png"
                        ],
                        "submit_time": 1775115000,
                        "finish_time": 1775115038
                      },
                      "usage": {
                        "image_count": 1,
                        "input_image_count": 0,
                        "pixel_count": 1048576
                      },
                      "request_id": ""
                    }
                  },
                  "failure": {
                    "summary": "失败任务",
                    "value": {
                      "output": {
                        "task_id": "3c7d6b6c-7cdb-4f37-bf41-7f2b0f1a9f0d",
                        "task_status": "Failure",
                        "submit_time": 1775115000,
                        "finish_time": 1775115012,
                        "error_message": "code=InvalidParameter, message=invalid image url"
                      },
                      "request_id": ""
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "任务标识无效或任务状态查询失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenImage30ErrorResponse"
                },
                "examples": {
                  "invalidTaskId": {
                    "$ref": "#/components/examples/QwenImage30InvalidTaskIdError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenImage30ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/QwenImage30InvalidTaskIdError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "通过 `Authorization: Bearer <MODELVERSE_API_KEY>` 请求头传入 ModelVerse API Key。"
      }
    },
    "schemas": {
      "QwenImage30Model": {
        "type": "string",
        "enum": [
          "qwen-image-3.0",
          "qwen-image-3.0-pro"
        ],
        "description": "模型名称。可选值为 `qwen-image-3.0`（标准版）与 `qwen-image-3.0-pro`（Pro 版），两者均支持文生图与图生图/图像编辑。"
      },
      "QwenImage30GenerationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model"
        ],
        "anyOf": [
          {
            "required": [
              "prompt"
            ]
          },
          {
            "required": [
              "image"
            ]
          },
          {
            "required": [
              "images"
            ]
          }
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/QwenImage30Model"
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "description": "正向提示词，描述期望生成或编辑的图像内容、风格和构图。支持中英文，推荐不超过 4500 Token。"
          },
          "image": {
            "$ref": "#/components/schemas/QwenImage30InputImage"
          },
          "images": {
            "$ref": "#/components/schemas/QwenImage30InputImages"
          },
          "size": {
            "$ref": "#/components/schemas/QwenImage30Size"
          },
          "n": {
            "$ref": "#/components/schemas/QwenImage30Count"
          },
          "seed": {
            "$ref": "#/components/schemas/QwenImage30Seed"
          },
          "negative_prompt": {
            "type": "string",
            "description": "反向提示词，描述不希望在画面中出现的内容。"
          },
          "watermark": {
            "$ref": "#/components/schemas/QwenImage30Watermark"
          },
          "prompt_extend": {
            "$ref": "#/components/schemas/QwenImage30PromptExtend"
          },
          "prompt_extend_mode": {
            "$ref": "#/components/schemas/QwenImage30PromptExtendMode"
          },
          "enable_thinking": {
            "$ref": "#/components/schemas/QwenImage30EnableThinking"
          }
        }
      },
      "QwenImage30TaskSubmitRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/QwenImage30Model"
          },
          "input": {
            "$ref": "#/components/schemas/QwenImage30TaskInput"
          },
          "parameters": {
            "$ref": "#/components/schemas/QwenImage30TaskParameters"
          }
        }
      },
      "QwenImage30TaskInput": {
        "type": "object",
        "additionalProperties": false,
        "anyOf": [
          {
            "required": [
              "prompt"
            ]
          },
          {
            "required": [
              "images"
            ]
          },
          {
            "required": [
              "img_url"
            ]
          }
        ],
        "properties": {
          "prompt": {
            "type": "string",
            "minLength": 1,
            "description": "正向提示词，描述期望生成或编辑的图像内容、风格和构图。支持中英文，推荐不超过 4500 Token。"
          },
          "negative_prompt": {
            "type": "string",
            "description": "反向提示词，描述不希望在画面中出现的内容。"
          },
          "images": {
            "$ref": "#/components/schemas/QwenImage30InputImages"
          },
          "img_url": {
            "$ref": "#/components/schemas/QwenImage30InputImage"
          }
        }
      },
      "QwenImage30TaskParameters": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "size": {
            "$ref": "#/components/schemas/QwenImage30Size"
          },
          "n": {
            "$ref": "#/components/schemas/QwenImage30Count"
          },
          "seed": {
            "$ref": "#/components/schemas/QwenImage30Seed"
          },
          "watermark": {
            "$ref": "#/components/schemas/QwenImage30Watermark"
          },
          "prompt_extend": {
            "$ref": "#/components/schemas/QwenImage30PromptExtend"
          },
          "prompt_extend_mode": {
            "$ref": "#/components/schemas/QwenImage30PromptExtendMode"
          },
          "enable_thinking": {
            "$ref": "#/components/schemas/QwenImage30EnableThinking"
          }
        }
      },
      "QwenImage30InputImage": {
        "type": "string",
        "minLength": 1,
        "description": "输入图像，可为公网 URL（HTTP/HTTPS）或 Base64 Data URL（格式为 `data:{MIME_type};base64,{base64_data}`）。\n图像格式支持 JPG、JPEG、PNG、BMP、TIFF、WEBP 和 GIF；建议宽高均在 384 至 2048 像素之间，单张图像不超过 10MB。\n图生图（I2I）场景支持 1-3 张参考图。\n",
        "examples": [
          "https://example.com/reference.png"
        ]
      },
      "QwenImage30InputImages": {
        "type": "array",
        "minItems": 1,
        "maxItems": 3,
        "description": "多张参考图，图生图（I2I）场景支持传入 1-3 张图像，多图输入时按数组顺序定义图像顺序。\n",
        "items": {
          "$ref": "#/components/schemas/QwenImage30InputImage"
        }
      },
      "QwenImage30Size": {
        "type": "string",
        "description": "输出图像分辨率，格式为 `宽*高`，例如 `\"1024*1024\"`。未指定时由模型根据提示词自动推荐分辨率。\n总像素面积需在 `512*512` 至 `2048*2048` 之间，宽高比限制在 `1:8` 至 `8:1` 之间。\n",
        "pattern": "^[1-9][0-9]*\\*[1-9][0-9]*$",
        "examples": [
          "1024*1024",
          "1536*1024",
          "2048*2048"
        ]
      },
      "QwenImage30Count": {
        "type": "integer",
        "minimum": 1,
        "maximum": 6,
        "default": 1,
        "description": "输出图像数量，支持 1-6 张，默认值为 1。"
      },
      "QwenImage30Seed": {
        "type": "integer",
        "minimum": 0,
        "maximum": 2147483647,
        "description": "随机数种子，取值范围 `[0, 2147483647]`。未传入时由服务随机选择，固定种子可使生成结果相对稳定。"
      },
      "QwenImage30Watermark": {
        "type": "boolean",
        "default": false,
        "description": "是否在生成图片中添加水印，默认值为 `false`。"
      },
      "QwenImage30PromptExtend": {
        "type": "boolean",
        "default": true,
        "description": "是否开启提示词智能改写，默认值为 `true`（建议开启）。开启后模型会按 `prompt_extend_mode` 指定的方式优化正向提示词。"
      },
      "QwenImage30PromptExtendMode": {
        "type": "string",
        "default": "direct",
        "enum": [
          "direct",
          "agent"
        ],
        "description": "提示词改写方式，默认值为 `direct`。\n- `direct`：直接提示词增强（DPE），适用于大多数场景，文生图（T2I）与图生图（I2I）均支持。\n- `agent`：智能体提示词增强（APE），提供更精细的改写效果，仅支持文生图（T2I）。图生图（I2I）场景传入 `agent` 将返回 400 错误。\n"
      },
      "QwenImage30EnableThinking": {
        "type": "boolean",
        "default": true,
        "description": "是否开启思考模式，默认值为 `true`。开启时模型将增强推理能力以提升出图质量，但会增加生成耗时。\n仅在 `prompt_extend=true` 时生效，适用于 Direct T2I、Direct I2I 与 Agent T2I，I2I Agent 暂不支持。\n"
      },
      "QwenImage30GenerationResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "created",
          "data"
        ],
        "properties": {
          "created": {
            "type": "integer",
            "description": "请求创建的 Unix 时间戳（秒）。"
          },
          "data": {
            "type": "array",
            "description": "生成图像 URL 列表。",
            "items": {
              "$ref": "#/components/schemas/QwenImage30UrlData"
            }
          }
        }
      },
      "QwenImage30UrlData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "生成图像的下载 URL，格式为 PNG，链接有效期为 24 小时。"
          }
        }
      },
      "QwenImage30TaskSubmitResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "task_id"
            ],
            "properties": {
              "task_id": {
                "type": "string",
                "description": "异步任务标识，用于后续状态查询。"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "请求标识。"
          }
        }
      },
      "QwenImage30TaskStatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "$ref": "#/components/schemas/QwenImage30TaskStatusOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/QwenImage30Usage"
          },
          "request_id": {
            "type": "string",
            "description": "请求标识。"
          }
        }
      },
      "QwenImage30TaskStatusOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task_id",
          "task_status"
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "异步任务标识。"
          },
          "task_status": {
            "type": "string",
            "enum": [
              "Pending",
              "Running",
              "Success",
              "Failure",
              "Cancelled"
            ],
            "description": "任务状态。"
          },
          "urls": {
            "type": "array",
            "description": "生成图像结果 URL 列表，链接有效期为 24 小时。",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "submit_time": {
            "type": "integer",
            "description": "任务提交时间戳。"
          },
          "finish_time": {
            "type": "integer",
            "description": "任务完成时间戳。"
          },
          "error_message": {
            "type": "string",
            "description": "任务失败时返回的错误信息。"
          }
        }
      },
      "QwenImage30Usage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "image_count": {
            "type": "integer",
            "description": "实际生成的输出图片数量。"
          },
          "input_image_count": {
            "type": "integer",
            "description": "请求中输入图片的数量，文生图（T2I）时为 0，图生图（I2I）按实际输入图片数返回。"
          },
          "pixel_count": {
            "type": "integer",
            "description": "输出图片像素值（宽×高），用于按像素分档计费。"
          }
        }
      },
      "QwenImage30ErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": true,
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "错误码。",
                "examples": [
                  "InvalidParameter"
                ]
              },
              "message": {
                "type": "string",
                "description": "错误信息。",
                "examples": [
                  "invalid image url"
                ]
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "可选的请求标识。"
          }
        }
      }
    },
    "examples": {
      "QwenImage30InvalidParameterError": {
        "summary": "无效参数",
        "value": {
          "error": {
            "code": "InvalidParameter",
            "message": "invalid image url"
          },
          "request_id": "req_202604021530000001"
        }
      },
      "QwenImage30InvalidTaskIdError": {
        "summary": "无效任务 ID",
        "value": {
          "error": {
            "code": "InvalidParameter",
            "message": "invalid task_id"
          },
          "request_id": "req_202604021530000001"
        }
      }
    }
  }
}
```