VideoRetalk — Create a task

POST

/services/aigc/image2video/video-synthesis

cURL

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl --request POST \
  --url https://cn-beijing.maas.qwencloudapi.com/api/v1/services/aigc/image2video/video-synthesis \
  --header 'X-DashScope-Async: enable' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "videoretalk",
  "input": {
    "video_url": "https://example.com/video.mp4",
    "audio_url": "https://example.com/audio.wav"
  },
  "parameters": {
    "video_extension": false
  }
}'

{
  "output": {
    "task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
    "task_status": "PENDING"
  },
  "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

videoretalk generates a new video in which the speaker's lip movements match an input audio file, based on a person video. Supported regions: China North 2 (Beijing) only. Use an API key created in that region and the https://cn-beijing.maas.qwencloudapi.com endpoint. See Regions and endpoints. Input requirements:

Input	Requirements
Video	MP4, AVI, or MOV; up to 300 MB; 2-120 seconds; 15-60 fps; H.264 or H.265; side length 640-2,048 pixels; close-up, front-facing person
Audio	WAV, MP3, or AAC; up to 30 MB; 2-120 seconds; clear human voice without ambient noise or music
Reference image (optional)	JPEG, PNG, BMP, or WEBP; up to 10 MB; aspect ratio no more than 2; longest side no more than 4,096 pixels; clear frontal face of a person in the video
URL	Files must be publicly accessible over HTTP or HTTPS. Local paths are not supported.

Processing is asynchronous: this operation returns a task_id, and you poll Query the result until the task finishes.

Authorizations

string

header

required

QwenCloud API key. See API keys.

Header Parameters

enum<string>

required

Fixed value enable, which enables asynchronous mode.

Available options:enable

Body

application/json

enum<string>

required

Model name. Fixed to videoretalk.

Available options:videoretalk

object

required

Show child attributes

string

required

Public URL of the person video.

Video requirements:

Format: mp4, avi, mov
File size: up to 300 MB
Duration: 2 to 120 seconds
Frame rate: 15 to 60 fps
Codec: H.264 or H.265
Side length: 640 to 2,048 pixels
Content: a close-up, front-facing shot of the person. Avoid extreme angles or very small faces.
URL: publicly accessible over HTTP or HTTPS

string

required

Public URL of the voice audio that drives the lip movements.

Audio requirements:

Format: wav, mp3, aac
File size: up to 30 MB
Duration: 2 to 120 seconds
Content: clear, loud human speech with ambient noise and background music removed
URL: publicly accessible over HTTP or HTTPS

string

Public URL of the reference face image (optional). Use it to specify which face to sync when the video contains multiple faces. If omitted, the largest face in the first frame that contains a face is used.

Image requirements:

Format: jpeg, jpg, png, bmp, webp
File size: up to 10 MB
Aspect ratio: no more than 2
Longest side: no more than 4,096 pixels
Content: a clear, frontal face of a person who appears in the video
URL: publicly accessible over HTTP or HTTPS

object

Show child attributes

boolean

defaultfalse

Whether to extend the video when the audio is longer than the video. true: extends the video by alternating reverse and forward playback until it matches the audio length. false: does not extend the video and truncates the audio. Default: false.

integer

default170

Face matching confidence when a reference image is provided. Range: 120-200. Smaller values match more loosely and larger values match more strictly. Default: 170. Ignored when input.ref_image_url is empty.

Required range:120 <= x <= 200

Response

200-application/json

string

Unique ID of the request.

object

Show child attributes

string

Asynchronous task ID, used to query the task status.

enum<string>

Initial task status. The value is PENDING.

Available options:PENDING