BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Wan 2.7 — Recuperar resultado da imagem
Verifique Wan 2.7 status da tarefa de imagem
Consulte o status e os resultados da tarefa.
Estratégia de votação
Pesquise este endpoint com o retornado task_id. Recomendamos pesquisas a cada 5 a 10 segundos.
Notas importantes
- Expiração de URL: URLs de imagem expiram em 24 horas. Baixe imediatamente.
- Fluxo de status da tarefa:
PENDING→RUNNING→SUCCEEDEDouFAILED. - Outros status:
CANCELED(tarefa cancelada),UNKNOWN(ID de tarefa inválida ou expirada). - Validade do ID da tarefa: os IDs das tarefas são válidos por 24 horas. Depois que o ID da tarefa expirar, o status e os resultados não poderão ser consultados.
- Evite tarefas duplicadas: use pesquisas para recuperar resultados. Não reenvie solicitações.
OpenAPI
openapi: 3.1.0
info:
title: Wan2.7 Image Generation and Editing API
description: Wan2.7 image generation and editing API. Supports text-to-image, multi-image editing, interactive editing with bounding boxes, and image set generation.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com/api/v1
description: Singapore
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWan27ImageTaskResult
summary: Query task result
description: Query the status and result of an async image task.
parameters:
- name: task_id
in: path
required: true
description: Task identifier returned by the async task creation endpoint.
schema:
type: string
responses:
"200":
description: Task status retrieved successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/Wan27TaskStatusResponse"
examples:
SUCCEEDED:
summary: Task succeeded
value:
request_id: 43d9e959-25bc-4dc7-9888-xxxxxx
output:
task_id: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status: SUCCEEDED
submit_time: 2026-03-31 19:57:58.840
scheduled_time: 2026-03-31 19:57:58.877
end_time: 2026-03-31 19:58:11.563
finished: true
choices:
- finish_reason: stop
message:
role: assistant
content:
- image: https://dashscope-result-intl.oss-cn-singapore.aliyuncs.com/1xxx.png?Expires=xxx
type: image
usage:
size: 2985*1405
total_tokens: 18792
image_count: 1
output_tokens: 2
input_tokens: 18790
FAILED:
summary: Task failed
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
output:
task_id: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status: FAILED
code: InvalidParameter
message: Invalid parameter value
RUNNING:
summary: Task running
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status: RUNNING
"400":
description: Invalid request parameters.
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - Query task result
source: |-
# Replace {task_id} with the task_id value returned by the previous API call.
# task_id is valid for queries within 24 hours.
curl -X GET https://maas.qwencloudapi.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: DashScope API Key. Create one in the [QwenCloud console](https://home.qwencloud.com/api-keys).
schemas:
Wan27ImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: "The model name. Valid values: wan2.7-image-pro, wan2.7-image."
enum:
- wan2.7-image-pro
- wan2.7-image
example: wan2.7-image-pro
input:
type: object
required:
- messages
description: Input data containing the messages array.
properties:
messages:
type: array
description: An array of request content. Currently, only single-turn conversations are supported. This means you can pass only one set of role and content parameters. Multi-turn conversations are not supported.
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/Wan27ImageMessage"
parameters:
$ref: "#/components/schemas/Wan27ImageParameters"
Wan27ImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: Message role. Must be `user`.
content:
type: array
description: |-
Message content array. Must contain exactly one `text` object and 0 to 9 `image` objects.
When using multiple images, include multiple `image` objects in the array. Image order is determined by array position.
items:
$ref: "#/components/schemas/Wan27ImageContentPart"
Wan27ImageContentPart:
type: object
description: Either an image or text content part.
properties:
text:
type: string
description: The user-entered prompt. Supports Chinese and English. The length cannot exceed 5,000 characters. Each Chinese character, letter, number, or symbol counts as one character. Any excess is automatically truncated. The `content` array must contain exactly one `text` object.
maxLength: 5000
example: Spray the graffiti from image 2 onto the car in image 1
image:
type: string
description: |-
Input image as a public URL (HTTP/HTTPS) or Base64-encoded string (`data:{mime_type};base64,{data}`).
**Image constraints:**
- Formats: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP.
- Resolution: Width and height each between 240 and 8,000 pixels. Aspect ratio [1:8, 8:1].
- File size: Max 20 MB.
- Quantity: 0 to 9 images per request.
example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp
Wan27ImageParameters:
type: object
description: Image processing parameters.
properties:
size:
type: string
description: |-
Output image resolution. Two specification methods are available; they cannot be used together.
**wan2.7-image-pro:**
- Method 1 (recommended): `1K`, `2K` (default), or `4K`.
- Scope: Text-to-image (no image input, not generating an image set) supports 1K, 2K, and 4K. Other scenarios support 1K and 2K only.
- Total pixels: 1K = 1024×1024, 2K = 2048×2048, 4K = 4096×4096.
- Aspect ratio: With image input, output matches the aspect ratio of the last input image scaled to the selected resolution. Without image input, output is square.
- Method 2: Specify `width*height` in pixels, aspect ratio [1:8, 8:1].
- Text-to-image: total pixels in [768×768, 4096×4096].
- Other scenarios: total pixels in [768×768, 2048×2048].
**wan2.7-image:**
- Method 1 (recommended): `1K` or `2K` (default). 4K is not supported.
- Method 2: Specify `width*height` in pixels. All scenarios: total pixels in [768×768, 2048×2048], aspect ratio [1:8, 8:1].
The pixel value of the output image may differ slightly from the specified value.
example: 2K
n:
type: integer
description: |-
Number of images to generate.
**Note:** The value of `n` directly affects the cost. Cost = Unit Price × Number of successfully generated images.
- When image set mode is disabled (`enable_sequential=false`): This value represents the number of images to generate. Range: 1–4. Default: 1.
- When image set mode is enabled (`enable_sequential=true`): This value represents the maximum number of images to generate. Range: 1–12. Default: 12. The actual number is determined by the model and will not exceed `n`.
minimum: 1
maximum: 12
default: 1
enable_sequential:
type: boolean
description: |-
Controls the image generation mode.
- `false`: Default value.
- `true`: Enables image set output mode.
default: false
thinking_mode:
type: boolean
description: Specifies whether to enable thinking mode. The default is `true` (enabled). This parameter is effective only when image set mode is disabled and there is no image input. When enabled, the model enhances its inference capabilities to improve image quality, but this increases generation time.
default: true
bbox_list:
type: array
description: |-
The selected area for interactive editing.
- Correspondence: The length of the list must match the number of input images. If an image does not require editing, pass an empty list `[]` at the corresponding position.
- Coordinate format: `[x1, y1, x2, y2]` (top-left x, top-left y, bottom-right x, bottom-right y). Use absolute pixel coordinates of the original image. The top-left coordinate is (0, 0).
- Condition: A single image supports a maximum of 2 bounding boxes.
items:
type: array
description: Bounding boxes for one input image. Empty array means no bounding box.
items:
type: array
description: A single bounding box [x1, y1, x2, y2].
items:
type: integer
minItems: 4
maxItems: 4
maxItems: 2
color_palette:
type: array
description: A custom color theme. An array of objects containing color (`hex`) and proportion (`ratio`). It must include 3 to 10 colors. We recommend setting it to 8. Available only when image set mode is disabled (`enable_sequential=false`).
minItems: 3
maxItems: 10
items:
type: object
required:
- hex
- ratio
properties:
hex:
type: string
description: "The color value in hexadecimal (HEX) format. Example: `#C2D1E6`."
ratio:
type: string
description: The percentage of the color. It must be accurate to two decimal places (for example, `"25.00%"`). The sum of all `ratio` values must be 100.00%.
example:
- hex: "#C2D1E6"
ratio: 60.00%
- hex: "#636574"
ratio: 25.00%
- hex: "#CBD4E4"
ratio: 15.00%
watermark:
type: boolean
description: Adds a watermark label in the bottom-right corner of the image with fixed text "AI Generated".
default: false
seed:
type: integer
description: "Random number seed. Valid range: [0, 2147483647]. Using the same seed yields similar outputs. If omitted, the algorithm uses a random seed. Note: Image generation is probabilistic. Even with the same seed, results may vary."
minimum: 0
maximum: 2147483647
Wan27ImageResponse:
type: object
description: Wan2.7 image generation response.
example:
output:
choices:
- finish_reason: stop
message:
content:
- image: https://dashscope-result-intl.oss-cn-singapore.aliyuncs.com/xxx.png?Expires=xxx
type: image
role: assistant
finished: true
usage:
image_count: 1
input_tokens: 18790
output_tokens: 2
size: 2985*1405
total_tokens: 18792
request_id: a3f4befe-cacd-49c9-8298-xxxxxx
properties:
output:
type: object
properties:
choices:
type: array
description: List of generated results.
items:
$ref: "#/components/schemas/Wan27ImageChoice"
finished:
type: boolean
description: Whether the generation has completed.
usage:
type: object
description: Usage statistics.
properties:
image_count:
type: integer
description: Number of images generated.
input_tokens:
type: integer
description: Number of input tokens consumed.
output_tokens:
type: integer
description: Number of output tokens consumed.
total_tokens:
type: integer
description: Total tokens consumed.
size:
type: string
description: Actual output image dimensions (width×height).
example: 2985*1405
request_id:
type: string
description: Unique request identifier.
example: a3f4befe-cacd-49c9-8298-xxxxxx
Wan27ImageChoice:
type: object
properties:
finish_reason:
type: string
description: Reason for generation completion.
example: stop
message:
type: object
properties:
role:
type: string
example: assistant
content:
type: array
items:
type: object
properties:
image:
type: string
description: URL of the generated image. **URLs expire in 24 hours.** Download and save promptly.
example: https://dashscope-result-intl.oss-cn-singapore.aliyuncs.com/xxx.png?Expires=xxx
type:
type: string
example: image
AsyncTaskSubmitResponse:
type: object
description: Response returned when an async task is successfully submitted.
example:
request_id: ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx
output:
task_id: 8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx
task_status: PENDING
properties:
request_id:
type: string
description: Unique request identifier.
example: ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx
output:
type: object
properties:
task_id:
type: string
description: Task identifier. Use this to poll the result endpoint. Valid for 24 hours.
example: 8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx
task_status:
type: string
description: Initial task status. Always `PENDING` immediately after creation.
example: PENDING
Wan27TaskStatusResponse:
type: object
description: Response from the task status query endpoint.
properties:
request_id:
type: string
description: Unique request identifier.
example: 43d9e959-25bc-4dc7-9888-xxxxxx
output:
type: object
properties:
task_id:
type: string
description: Task identifier.
example: 858cad55-4bdc-4ba3-ae6c-xxxxxx
task_status:
type: string
description: "Current task status: `PENDING` (queued), `RUNNING` (processing), `SUCCEEDED` (complete), `FAILED` (error), `CANCELED` (canceled), `UNKNOWN` (invalid or expired task ID)."
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
example: SUCCEEDED
submit_time:
type: string
description: Task submission time.
example: 2026-03-31 19:57:58.840
scheduled_time:
type: string
description: Task scheduling time.
example: 2026-03-31 19:57:58.877
end_time:
type: string
description: Task completion time.
example: 2026-03-31 19:58:11.563
finished:
type: boolean
description: Whether the task has finished.
example: true
choices:
type: array
description: Generated images. Only present when `task_status` is `SUCCEEDED`.
items:
$ref: "#/components/schemas/Wan27ImageChoice"
code:
type: string
description: Error code. Only present when `task_status` is `FAILED`.
message:
type: string
description: Error message. Only present when `task_status` is `FAILED`.
usage:
type: object
description: Usage statistics. Only present when `task_status` is `SUCCEEDED`.
properties:
image_count:
type: integer
description: Number of images generated.
input_tokens:
type: integer
description: Number of input tokens consumed.
output_tokens:
type: integer
description: Number of output tokens consumed.
total_tokens:
type: integer
description: Total tokens consumed.
size:
type: string
description: Actual output image dimensions.
example: 2985*1405
DashScopeErrorResponse:
type: object
properties:
code:
type: string
description: Error code.
example: InvalidParameter
message:
type: string
description: Error message.
example: Invalid parameter value
request_id:
type: string
description: Unique request identifier.
example: a3f4befe-cacd-49c9-8298-xxxxxx