VideoRetalk Video Generate

Authorizations

Authorization

string

header

required

##All endpoints require Bearer Token authentication##

Get your API Key:

Visit the API Key management page to obtain your API Key

Add the following header to every request:

Authorization: Bearer YOUR_API_KEY

Body

application/json

model

enum<string>

default:videoretalk

required

Model name

Available options:

videoretalk

Example:

"videoretalk"

video_url

string<uri>

required

Input video URL containing the person whose lip movements will be replaced

Requirements:

Publicly accessible video URL
Formats: MP4, MOV, and other common formats
The video must contain a clearly visible human face
Recommended duration: 2 ~ 300 seconds

Example:

"https://example.com/speaker.mp4"

audio_url

string<uri>

required

Target audio URL — the person in the video will lip-sync to this audio

Requirements:

Publicly accessible audio URL
Formats: WAV, MP3, M4A, and other common formats
Recommended to use human speech content

Example:

"https://example.com/target-speech.wav"

ref_image_url

string<uri>

Reference face image URL

When the video contains multiple faces, use this image to specify the target face whose lip movements should be replaced

Requirements:

The image should show a clear frontal view of the target person's face
Only required when the video contains multiple faces

Example:

"https://example.com/target-person-face.jpg"

video_extension

boolean

default:false

Whether to automatically extend the video to match the audio length when the audio is longer than the video

true: output duration = audio duration (video extended automatically)
false: output duration = min(video duration, audio duration)

Example:

false

query_face_threshold

integer

default:170

Face matching confidence threshold

Range: 120 ~ 200
Lower values match more easily (may cause false matches)
Higher values are stricter (may fail to match)
If "no matching face found" is reported, try lowering the value (e.g. 140)
If the wrong face is matched, try raising the value (e.g. 190)

Required range: 120 <= x <= 200

Example:

170

callback_url

string<uri>

HTTPS callback URL invoked when the task completes

Trigger conditions:

Triggered when the task is completed, failed, or cancelled
Sent after billing confirmation

Security restrictions:

HTTPS only
Internal IP addresses are blocked (127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, etc.)
URL length must not exceed 2048 characters

Callback behavior:

Timeout: 10 seconds
Up to 3 retries after failure (at 1s / 2s / 4s intervals)
Response body format matches the task query API response
A 2xx status code is considered success; other codes trigger a retry

Example:

"https://your-domain.com/webhooks/video-task-completed"

Response

Lip-sync video generation task created successfully

created

integer

Task creation timestamp

Example:

1775200000

string

Task ID

Example:

"task-unified-1775200000-xyz12345"

model

string

Actual model name used

Example:

"videoretalk"

object

enum<string>

Specific task type

Available options:

video.generation.task

progress

integer

Task progress percentage (0-100)

Required range: 0 <= x <= 100

Example:

0

status

enum<string>

Task status

Status	progress	Description
`pending`	0~10	Waiting to be processed
`processing`	10~80	Processing
`completed`	100	Completed
`failed`	0	Failed

Available options:

pending,

processing,

completed,

failed

Example:

"pending"

task_info

object

Video task details

Show child attributes

type

enum<string>

Task output type

Available options:

video

Example:

"video"

usage

object

Usage and billing information

Show child attributes