> ## Documentation Index > Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Qwen Image 2.1 图像编辑 > Qwen Image 2.1 图像编辑 API 通过文字指令和参考图编辑一张图像。 > [!TIP] > > 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。 > 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。 ## 可选参数 * `size` (string)：输出宽高比。auto 跟随参考图。提供 mask\_url 时忽略。可选值：`1:1`、`4:3`、`3:4`、`3:2`、`2:3`、`16:9`、`9:16`、`21:9`、`9:21`、`auto`。默认：`auto`。 * `resolution` (string)：输出分辨率档位。可选值：`1K`、`2K`。默认：`1K`。 * `output_format` (string)：输出图像格式。透明输出需要 PNG 或 WebP。可选值：`png`、`jpeg`、`webp`。默认：`png`。 * `enable_safety_checker` (boolean)：开启内容安全检查。默认：`true`。 * `background` (string)：背景模式。透明输出需要 PNG 或 WebP。可选值：`opaque`、`transparent`。默认：`opaque`。 * `mask_url` (string)：可选的局部编辑蒙版。需要恰好一张参考图，且背景不透明。白色区域会被修改，黑色区域保持不变。与参考图的宽高比一致；蒙版会缩放到参考图尺寸。size 和 prompt\_extend 会被忽略。 * `prompt_extend` (boolean)：生成前增强提示词。提供 mask\_url 时忽略。默认：`true`。 * `seed` (integer)：可选的随机种子。省略时使用随机种子。 ## 使用指南 使用 Qwen Image 2.1，通过文字指令和参考图编辑一张图像。 * 将 `model` 设为 `alibaba/qwen-image-2.1/edit`。 * `model` 和可选的 `callback_url` 放在请求根级；工作流参数放在 `input` 内。 * 每次请求生成一张图像。 * 如只需根据提示词生成，请使用[文生图](https://docs.vidgo.ai/zh/api-manual/image-series/qwen-image-2-1-text-to-image.md)，并设置 `model=alibaba/qwen-image-2.1/text-to-image`。 ## 参数详情 * `prompt` 必填。提供非空文本，最多 5,000 个字符。 * `image_urls` 必填，接受 1 到 10 个参考图 URL。使用公开可访问的 HTTP(S) URL，顺序与提示词中引用参考图的顺序一致。 * `size` 默认 `auto`。`auto` 跟随参考图的宽高比。 * 透明背景需要 `output_format=png` 或 `webp`。 * `mask_url` 需要恰好一张参考图，且 `background=opaque`。白色区域会被修改；黑色区域保持不变。与参考图的宽高比一致；蒙版会缩放到参考图尺寸。 * 使用蒙版时，输出跟随参考图的宽高比；`size` 和 `prompt_extend` 会被忽略。 * 参考图支持 JPEG、PNG 和 WebP，每张最大 30 MB、2500 万像素。媒体限制在生成时检查。 ## 计费 按输出图像计费，取决于 `resolution`。在每个档位上，文生图和图像编辑的计费标准相同。 积分在提交时扣除，任务失败会退还。 ## OpenAPI ````yaml zh/api-manual/image-series/qwen-image-2-1-edit.json POST /api/generate/submit openapi: 3.0.0 info: title: Vidgo API - Qwen Image 2.1 图像编辑 description: 使用 Qwen Image 2.1，通过文字指令和参考图编辑一张图像。 version: 1.0.0 servers: - url: https://api.vidgo.ai description: 生产环境服务器 security: - BearerAuth: [] paths: /api/generate/submit: post: tags: - Qwen Image 2.1 Image Edit summary: 提交 Qwen Image 2.1 图像编辑任务 operationId: submitQwenImage21ImageEditTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRequest' examples: reference-edit: summary: 使用参考图编辑 value: model: alibaba/qwen-image-2.1/edit input: prompt: >- Preserve the product and replace the background with a warm modern studio. image_urls: - https://cdn.vidgo.ai/temp/reference-product.png size: auto resolution: 1K mask-edit: summary: 编辑蒙版区域 value: model: alibaba/qwen-image-2.1/edit input: prompt: Replace the masked area with a small vase of flowers. image_urls: - https://cdn.vidgo.ai/temp/reference-product.png mask_url: https://cdn.vidgo.ai/temp/edit-mask.png background: opaque size: auto prompt_extend: false transparent-background: summary: 编辑并输出透明背景图像 value: model: alibaba/qwen-image-2.1/edit input: prompt: Keep the silver robot and remove its background. background: transparent output_format: webp resolution: 2K seed: 20261009 image_urls: - https://cdn.vidgo.ai/temp/reference-product.png responses: '200': description: 任务提交结果。任务 ID 标识一项异步任务；生成可能仍在进行中。 content: application/json: schema: $ref: '#/components/schemas/SubmitResponse' '400': description: 请求参数无效 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 未授权 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SubmitRequest: type: object required: - model - input additionalProperties: false properties: model: type: string example: alibaba/qwen-image-2.1/edit callback_url: type: string format: uri description: 可选的 Webhook URL，用于接收完成或失败通知。 example: https://your-domain.com/callback input: type: object required: - prompt - image_urls additionalProperties: false properties: prompt: type: string minLength: 1 maxLength: 5000 description: |- 描述编辑内容的文字指令。 至少包含一个非空白字符。 size: type: string description: |- 输出宽高比。 auto 跟随参考图。 提供 mask_url 时忽略。 enum: - '1:1' - '4:3' - '3:4' - '3:2' - '2:3' - '16:9' - '9:16' - '21:9' - '9:21' - auto default: auto resolution: type: string enum: - 1K - 2K default: 1K description: 输出分辨率档位。 image_urls: type: array maxItems: 10 items: type: string format: uri description: 使用公开可访问的 HTTP(S) 下载 URL。 description: 编辑所需的参考图，按提示词中的顺序排列。 minItems: 1 output_format: type: string enum: - png - jpeg - webp default: png description: |- 输出图像格式。 透明输出需要 PNG 或 WebP。 enable_safety_checker: type: boolean default: true description: 开启内容安全检查。 background: type: string enum: - opaque - transparent default: opaque description: |- 背景模式。 透明输出需要 PNG 或 WebP。 mask_url: type: string format: uri description: |- 可选的局部编辑蒙版。 需要恰好一张参考图，且蒙版背景不透明。 白色区域会被修改，黑色区域保持不变。 与参考图的宽高比一致；蒙版会缩放到参考图尺寸。 size 和 prompt_extend 会被忽略。 使用公开可访问的 HTTP(S) 下载 URL。 prompt_extend: type: boolean default: true description: |- 生成前增强提示词。 提供 mask_url 时忽略。 seed: type: integer description: |- 可选的随机种子。 省略时使用随机种子。 SubmitResponse: type: object required: - code - data properties: code: type: integer example: 200 data: type: object required: - task_id - status - created_time properties: task_id: type: string example: task-example-001 status: type: string example: running created_time: type: string format: date-time example: '2026-10-09T10:30:00' ErrorResponse: type: object required: - code - error properties: code: type: integer example: 400 error: type: object properties: message: type: string example: Invalid request parameters type: type: string example: invalid_request_error securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: '使用 `Authorization: Bearer VIDGO_API_KEY`。' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.