BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Wan 2.7 -- Recuperar resultado de referência ao vídeo
Verifique Wan 2.7 status da tarefa de vídeo
Verifique o status da tarefa e recupere o URL do vídeo gerado. A resposta inclui carimbos de data/hora e a solicitação original para rastreamento.
Estratégia de votação
- Crie uma tarefa para receber um
task_id. - Pesquise este endpoint a cada 15 segundos até
task_statuséSUCCEEDEDouFAILED. - Se tiver sucesso, baixe o vídeo de
video_url.
Notas importantes
- Expiração de URL: URLs de vídeo expiram após 24 horas. Baixe imediatamente.
- Fluxo de status da tarefa:
PENDING->RUNNING->SUCCEEDEDouFAILED. - Metadados aprimorados: a resposta inclui
submit_time,scheduled_time,end_timeeorig_prompt(o prompt original antes de qualquer extensão de prompt). - Detalhes de uso: o faturamento é baseado em
duration(=input_video_duration+output_video_duration). A resposta também retornaSR(resolução) eratio.
OpenAPI
openapi: 3.1.0
info:
title: Wan 2.7 Reference-to-Video API
description: Wan 2.7 reference-to-video API. Generates performance videos from reference images or videos with multimodal input (text, image, video). Uses the new protocol with media array input, resolution+ratio parameters, and enhanced response metadata.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com/api/v1
description: Singapore
security:
- BearerAuth: []
paths:
/tasks/{task_id}:
get:
operationId: getWan27RefToVideoTaskStatus
summary: Query Wan 2.7 task result
description: Query the status and result of the Wan 2.7 video generation task.
parameters:
- name: task_id
in: path
required: true
description: Task identifier returned by the video creation endpoint.
schema:
type: string
responses:
"200":
description: Task status retrieved successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/TaskStatusResponse"
examples:
SUCCEEDED:
summary: Task succeeded
value:
request_id: 52cade0d-905e-9b7d-a01e-xxxxxx
output:
task_id: 18814247-f944-4102-aa4a-xxxxxx
task_status: SUCCEEDED
submit_time: 2026-04-02 22:53:19.537
scheduled_time: 2026-04-02 22:53:30.427
end_time: 2026-04-02 23:00:39.287
orig_prompt: Video 2 holds Image 3 and plays a soothing American country ballad in a coffee shop, while Video 1 smiles, watches Video 2, and slowly walks towards him
video_url: https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?xxxx
usage:
duration: 15
input_video_duration: 5
output_video_duration: 10
video_count: 1
SR: 720
ratio: 16:9
FAILED:
summary: Task failed
value:
request_id: e5d70b02-ebd3-98ce-9fe8-759d7d7b107d
output:
task_id: 86ecf553-d340-4e21-af6e-a0c6a421c010
task_status: FAILED
code: InvalidParameter
message: The size does not match xxxxxx
RUNNING:
summary: Task running
value:
request_id: c1209113-8437-424f-a386-xxxxxx
output:
task_id: 966cebcd-dedc-4962-af88-xxxxxx
task_status: RUNNING
submit_time: 2025-09-29 14:18:52.331
scheduled_time: 2025-09-29 14:18:59.290
UNKNOWN:
summary: Task query expired
value:
request_id: a4de7c32-7057-9f82-8581-xxxxxx
output:
task_id: 502a00b1-19d9-4839-a82f-xxxxxx
task_status: UNKNOWN
"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 actual task ID from the submit response
curl -X GET 'https://maas.qwencloudapi.com/api/v1/tasks/{task_id}' \
-H "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:
Wan27RefToVideoRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: Model name.
enum:
- wan2.7-r2v
- wan2.7-r2v-2026-06-12
example: wan2.7-r2v
input:
$ref: "#/components/schemas/Wan27RefToVideoInput"
parameters:
$ref: "#/components/schemas/Wan27RefToVideoParameters"
Wan27RefToVideoInput:
type: object
required:
- prompt
- media
description: Input data for Wan 2.7 reference-to-video generation.
properties:
prompt:
type: string
maxLength: 5000
description: |-
Text prompt describing the desired video content. Supports Chinese and English. Each Chinese character, letter, and punctuation mark counts as one character. Text that exceeds the limit is automatically truncated.
**Reference identifiers**: Use `Image 1`, `Image 2`, etc. to reference characters from reference images, and `Video 1`, `Video 2`, etc. to reference characters from reference videos. The numbering matches the order in the `media` array. Images and videos are counted separately — `Image 1` and `Video 1` can coexist. If there is only one reference image or video, you can use `the reference image` or `the reference video` instead.
**Scene description**: Two approaches — (1) Use identifiers directly: "Image 1 is playing in Image 2"; (2) Supplement with subject/scene context: "The cat from Image 1 is playing in the room from Image 2".
**Multi-panel storyboard**: Describe multi-shot narratives with time segments (e.g., `Scene 1 [0-3s]: ...`). You do not need to describe every panel — provide key shots, and the model automatically recognizes the panel logic.
example: Video 2 holds Image 3 and plays a soothing American country ballad in a coffee shop
negative_prompt:
type: string
maxLength: 500
description: "Content to exclude from the generated video. Supports Chinese and English. Maximum 500 characters. Text that exceeds the limit is automatically truncated. Example values: `low resolution, error, worst quality, low quality, disfigured, extra fingers, bad proportions`."
media:
type: array
description: |-
Array of reference media objects. Each object has a `type` and `url`. Supports image and video input for visual reference. Images support multiple views, commonly for referencing characters, props, and scenes.
**Ordering**: The first `reference_video` in the array is `Video 1`, the second is `Video 2`, and so on. The first `reference_image` is `Image 1`, the second is `Image 2`. Images and videos are counted separately.
**Limits**: At least 1 reference image or video is required. Total images + videos must not exceed 5. At most 1 `first_frame` is allowed. Each reference image or video should contain a single character when used for main character portrayal.
items:
$ref: "#/components/schemas/MediaItem"
minItems: 1
maxItems: 5
reference_voice:
type: string
format: uri
description: |-
URL of a reference audio file for voice timbre. Used with `reference_image` or `reference_video` to specify the voice timbre for the main character. This audio is used only for voice timbre reference and is not related to the spoken content.
Supported formats: WAV, MP3. Duration: 1-10 seconds. Max file size: 15 MB.
**Default behavior**: If `reference_video` has audio and `reference_voice` is not specified, the original video audio is used as the voice timbre.
**Priority**: If both `reference_video` audio and `reference_voice` are provided, `reference_voice` takes priority.
For best results, the language of the reference audio should match the language of the prompt.
MediaItem:
type: object
required:
- type
- url
description: A reference media item (image, video, or first frame).
properties:
type:
type: string
description: |-
Type of reference media.
- `reference_image`: Reference image containing a single character or object. Supported formats: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP. Resolution: 240-8000 px per side. Aspect ratio: 1:8 to 8:1. Max file size: 20 MB.
- `reference_video`: Reference video containing a single character. Supported formats: MP4, MOV. Duration: 1-30 seconds. Resolution: 240-4096 px per side. Aspect ratio: 1:8 to 8:1. Max file size: 100 MB.
- `first_frame`: First frame image for the generated video. At most 1 allowed. Supported formats and constraints same as `reference_image`. When used with subject references, two modes apply: (1) Subject already in the first frame — use subject reference to enhance character consistency or reference voice timbre. (2) Subject not in the first frame — use subject reference to define features of a new character appearing during the video.
enum:
- reference_image
- reference_video
- first_frame
url:
type: string
format: uri
description: URL of the reference media file.
Wan27RefToVideoParameters:
type: object
description: Generation parameters for Wan 2.7 reference-to-video.
properties:
resolution:
type: string
description: |-
Video clarity tier. Higher resolution costs more.
Actual output dimensions depend on `ratio`:
- **720P**: 16:9=1280x720, 9:16=720x1280, 1:1=960x960, 4:3=1104x832, 3:4=832x1104
- **1080P**: 16:9=1920x1080, 9:16=1080x1920, 1:1=1440x1440, 4:3=1648x1248, 3:4=1248x1648
enum:
- 720P
- 1080P
default: 1080P
ratio:
type: string
description: Aspect ratio of the output video. When a `first_frame` image is provided, `ratio` is ignored and the video uses the image's aspect ratio.
enum:
- 16:9
- 9:16
- 1:1
- 4:3
- 3:4
default: 16:9
duration:
type: integer
description: "Video duration in seconds. Longer videos cost more -- billing is per second. Conditional range: if reference material includes a video, the range is 2-10; if reference material does not include a video (images only), the range is 2-15."
minimum: 2
maximum: 15
default: 5
prompt_extend:
type: boolean
description: Whether to rewrite the prompt using a large language model. Improves results for shorter prompts but increases processing time.
default: true
seed:
type: integer
description: Random seed for reproducible generation. If not specified, a random seed is generated. A fixed seed improves reproducibility, but because model generation is probabilistic, the same seed does not guarantee identical results.
minimum: 0
maximum: 2147483647
watermark:
type: boolean
description: Whether to add an "AI Generated" watermark to the lower-right corner of the output video.
default: false
AsyncTaskSubmitResponse:
type: object
description: Response returned when an asynchronous task is created successfully.
properties:
request_id:
type: string
description: Unique request identifier.
output:
type: object
properties:
task_id:
type: string
description: Task identifier. Use this with `GET /tasks/{task_id}` to poll for results.
task_status:
type: string
description: Initial task status, typically `PENDING`.
enum:
- PENDING
TaskStatusResponse:
type: object
description: Response containing the current status and results of a Wan 2.7 reference-to-video task.
properties:
request_id:
type: string
description: Unique request identifier.
output:
type: object
properties:
task_id:
type: string
description: Task identifier.
task_status:
type: string
description: Current task status.
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: Task submission time in UTC+8 format (e.g., `2026-04-02 22:53:19.537`).
scheduled_time:
type: string
description: Task scheduling time in UTC+8 format.
end_time:
type: string
description: Task completion time in UTC+8 format.
orig_prompt:
type: string
description: The original prompt before any prompt extension was applied.
video_url:
type: string
format: uri
description: Generated video URL (MP4, H.264 codec). Only present when `task_status` is `SUCCEEDED`. Valid for 24 hours — download promptly.
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 succeeds).
properties:
duration:
type: integer
description: Total billable duration in seconds (equals `input_video_duration` + `output_video_duration`).
input_video_duration:
type: integer
description: Duration of the input reference video(s) in seconds.
output_video_duration:
type: integer
description: Duration of the generated output video in seconds.
video_count:
type: integer
description: Number of videos generated (always 1).
SR:
type: integer
description: Resolution of the generated video (e.g., 720 or 1080).
ratio:
type: string
description: Aspect ratio of the generated video (e.g., `16:9`).
DashScopeErrorResponse:
type: object
description: DashScope API error response.
properties:
request_id:
type: string
description: Unique request identifier.
code:
type: string
description: Error code (e.g., `InvalidParameter`, `Throttling`, `Unauthorized`).
example: InvalidParameter
message:
type: string
description: Human-readable error message.
example: "Invalid parameter: resolution"