Referensi API VideoRetalk - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

VideoRetalk adalah model yang menghasilkan video baru dari seseorang yang berbicara dengan menyinkronkan gerakan bibirnya sesuai trek audio yang diberikan. Dokumen ini menjelaskan cara menggunakan API untuk menghasilkan video.

Penting

Dokumen ini hanya berlaku untuk wilayah China (Beijing). Untuk menggunakan model ini, gunakan API key dari wilayah China (Beijing).

HTTP

API VideoRetalk hanya mendukung panggilan HTTP dan menggunakan proses asinkron untuk mengurangi waktu tunggu serta mencegah timeout permintaan. Oleh karena itu, Anda perlu membuat dua permintaan terpisah untuk menghasilkan video:

Kirim task: Kirim permintaan untuk membuat task pembuatan video. API akan mengembalikan ID task.
Kueri status task dan ambil hasil: Gunakan ID task yang dikembalikan untuk mengecek status task dan mengambil video yang dihasilkan.

Prasyarat

Anda telah membuat API key dan menyetel API key sebagai environment variable.

Batasan input

Persyaratan video:
- File: Format MP4, AVI, dan MOV didukung. Ukuran file maksimal 300 MB dengan durasi antara 2 hingga 120 detik.
- Properti: Laju frame video harus antara 15 fps hingga 60 fps. Video harus dikodekan dalam H.264 atau H.265. Panjang setiap sisi harus antara 640 hingga 2.048 piksel.
- Konten: Video harus berupa bidikan close-up wajah seseorang yang menghadap ke depan. Hindari sudut samping ekstrem atau wajah yang sangat kecil.
Persyaratan audio:
- File: Format WAV, MP3, dan AAC didukung. Ukuran file maksimal 30 MB dengan durasi antara 2 hingga 120 detik.
- Konten: Audio harus berisi suara manusia yang jelas dan keras. Hilangkan gangguan seperti kebisingan latar atau musik latar.
Persyaratan gambar referensi karakter:
- File: Format JPEG, JPG, PNG, BMP, dan WebP didukung. Ukuran file maksimal 10 MB.
- Konten: Gambar harus berisi tampilan frontal wajah seseorang yang jelas, dan orang tersebut harus muncul dalam video. Anda juga dapat menggunakan tangkapan layar dari video tersebut.
Persyaratan URL file:
- File video, audio, dan gambar yang diunggah harus dapat diakses melalui tautan HTTP. Jalur lokal tidak didukung. Anda juga dapat menggunakan temporary storage space yang disediakan oleh platform untuk mengunggah file lokal dan membuat tautan.

Kirim task

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/

Parameter permintaan

Field	Type	Location	Required	Description	Example
Content-Type	String	Header	Yes	Jenis permintaan: application/json	application/json
Authorization	String	Header	Yes	API key. Contoh: Bearer d1**2a	Bearer d1**2a
X-DashScope-Async	String	Header	Yes	Atur ke `enable` untuk menunjukkan bahwa task dibuat secara asinkron.	enable
model	String	Body	Yes	Menentukan model yang akan dipanggil.	videoretalk
input.video_url	String	Body	Yes	URL file video yang Anda unggah. URL harus dapat diakses publik dan menggunakan protokol HTTP atau HTTPS. Persyaratan file video: Ukuran: Ukuran file harus 300 MB atau kurang. Format: MP4, AVI, atau MOV. Durasi: Antara 2 hingga 120 detik. Laju frame: Antara 15 hingga 60 fps. Pengkodean: Disarankan H.264 atau H.265. Panjang sisi: Antara 640 hingga 2048 piksel. Konten: Bidikan close-up wajah seseorang yang menghadap ke depan. Hindari sudut samping ekstrem atau wajah yang sangat kecil. Jika video tidak berisi wajah penuh atau sama sekali tidak ada wajah, lihat FAQ untuk solusinya.	http://aaa/bbb.mp4
input.audio_url	String	Body	Yes	URL file audio yang Anda unggah. URL harus dapat diakses publik dan menggunakan protokol HTTP atau HTTPS. Persyaratan file audio: Ukuran: Ukuran file harus 30 MB atau kurang. Format: WAV, MP3, atau AAC. Durasi: Antara 2 hingga 120 detik. Jika durasi video dan audio berbeda, lihat FAQ untuk solusinya. Konten: Harus berisi ucapan manusia yang jelas dan keras. Hilangkan kebisingan latar atau musik.	http://aaa/bbb.wav
input.ref_image_url	String	Body	No	URL gambar wajah referensi. URL harus dapat diakses publik dan menggunakan protokol HTTP atau HTTPS. Gunakan parameter ini untuk menentukan wajah mana yang akan digunakan untuk lip-syncing ketika terdapat beberapa wajah dalam video input. Jika video hanya berisi satu wajah, parameter ini tidak diperlukan. Jika Anda mengabaikan parameter ini, sistem akan menggunakan wajah terbesar yang terdeteksi pada frame pertama yang berisi wajah. Persyaratan file gambar: Konten: Harus berupa gambar jelas wajah seseorang yang menghadap ke depan dan muncul dalam video. Ukuran file: 10 MB atau kurang. Ukuran gambar: Rasio aspek harus 2 atau kurang. Panjang sisi maksimum harus 4.096 piksel atau kurang. Format: JPEG, JPG, PNG, BMP, atau WebP.	http://aaa/bbb.jpg
parameters.video_extension	Boolean	Body	No	Menentukan apakah durasi video diperpanjang ketika audio input lebih panjang daripada video. Default: `false`. `true`: Memperpanjang durasi video agar sesuai dengan panjang audio dengan mengulang video dalam pola "putar mundur, putar maju". `false`: Tidak memperpanjang video. Video yang dihasilkan akan memiliki durasi yang sama dengan video asli, dan audio akan dipotong.	false
parameters.query_face_threshold	Integer	Body	No	Menyesuaikan tingkat kepercayaan pencocokan wajah saat gambar wajah referensi diberikan. Nilainya berkisar antara 120 hingga 200. Nilai yang lebih kecil menghasilkan pencocokan yang lebih longgar, sedangkan nilai yang lebih besar menghasilkan pencocokan yang lebih ketat. Nilai default adalah 170. Catatan: Parameter ini diabaikan jika input.ref_image_url kosong.	170

Parameter respons

Field	Type	Description	Example
output.task_id	String	ID task asinkron yang dikirimkan. Gunakan ID ini untuk mengambil hasil sebenarnya melalui API kueri status task.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Status task setelah dikirimkan.	"PENDING"
request_id	String	ID permintaan.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Contoh permintaan

curl --location 'https://dashscope.aliyuncs.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://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/pvegot/input_video_01.mp4",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/aumwir/stella2-%E6%9C%89%E5%A3%B0%E4%B9%A67.wav",
        "ref_image_url": ""
     },
    "parameters": {
        "video_extension": false
    }
  }'

Contoh respons

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

Kueri status task dan ambil hasil

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Parameter permintaan

Field	Type	Location	Required	Description	Example
Authorization	String	Header	Yes	API key. Contoh: Bearer d1**2a.	Bearer d1**2a
task_id	String	Url Path	Yes	ID task yang akan dikueri. Ini adalah nilai yang dikembalikan oleh API pengiriman task.	a8532587-fa8c-4ef8-82be-0c46b17950d1

Parameter respons

Field	Type	Description	Example
output.task_id	String	ID task yang dikueri.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Status task yang dikueri.	Status task: PENDING PRE-PROCESSING RUNNING POST-PROCESSING SUCCEEDED FAILED UNKNOWN: Task tidak ada atau statusnya tidak diketahui.
output.video_url	String	Video yang dihasilkan. video_url berlaku selama 24 jam setelah task selesai.	https://xxx/1.mp4"
usage.video_duration	Float	Durasi video yang dihasilkan, dalam detik.	"video_duration": 10.23
usage.video_ratio	String	Jenis rasio aspek video yang dihasilkan. Nilainya adalah standard, artinya video output memiliki rasio aspek yang sama dengan video asli secara default.	"video_ratio": "standard"
usage.size	String	Resolusi video yang dihasilkan, resolusi yang sama dengan video input.	"size": "1080*1920"
usage.fps	Integer	Laju frame video yang dihasilkan, resolusi yang sama dengan video input.	"fps": 25
request_id	String	ID permintaan.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Contoh permintaan

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/<YOUR_TASK_ID>' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Contoh respons

{
    "request_id": "87b9dce5-7f36-4305-a347-xxxxxx",
    "output": {
        "task_id": "3afd65eb-9604-48ea-8a91-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-11 20:15:29.887",
        "scheduled_time": "2025-09-11 20:15:36.741",
        "end_time": "2025-09-11 20:16:40.577",
        "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "video_duration": 7.2,
        "size": "1080*1920",
        "video_ratio": "standard",
        "fps": 25
    }
}

Contoh respons error

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

Kode kesalahan

Untuk kode status umum, lihat Pesan kesalahan.

Model ini juga memiliki kode kesalahan spesifik berikut:

Kode Status HTTP	Kode kesalahan	Pesan kesalahan	Deskripsi
400	InvalidParameter	Field required: xxx	Parameter permintaan hilang atau formatnya salah.
400	InvalidURL.ConnectionRefused	Connection to ${url} refused, please provide avaiable URL	Unduhan ditolak. Berikan URL yang tersedia.
400	InvalidURL.Timeout	Download ${url} timeout, please check network connection.	Waktu unduhan habis. Periode timeout adalah 60 detik.
400	InvalidFile.Size	Invalid file size. The video/audio/image file size must be less than **MB.	File video, audio, atau gambar harus lebih kecil dari ** MB.
400	InvalidFile.Format	Invalid file format，the request file format is one of the following types: MP4, AVI, MOV, MP3, WAV, AAC, JPEG, JPG, PNG, BMP, and WEBP.	Format file tidak valid. Video dalam format MP4, AVI, atau MOV didukung. Audio dalam format MP3, WAV, atau AAC didukung. Gambar dalam format JPG, JPEG, PNG, BMP, atau WebP didukung.
400	InvalidFile.Resolution	Invalid video resolution. The height or width of video must be 640 ~ 2048.	Panjang sisi video harus antara 640 hingga 2048 piksel.
400	InvalidFile.FPS	Invalid video FPS. The video FPS must be 15 ~ 60.	Laju frame video harus antara 15 hingga 60 fps.
400	InvalidFile.Duration	Invalid file duration. The video/audio file duration must be 2s ~ 120s.	Durasi file video atau audio harus antara 2 hingga 120 detik.
400	InvalidFile.ImageSize	The size of image is beyond limit.	Ukuran gambar melebihi batas. Rasio aspek gambar harus 2 atau kurang, dan sisi terpanjang harus 4.096 piksel atau kurang.
400	InvalidFile.Openerror	Invalid file, cannot open file as video/audio/image.	File video, audio, atau gambar tidak dapat dibuka.
400	InvalidFile.Content	The input image has no human body or multi human bodies. Please upload other image with single person.	Gambar input tidak berisi orang atau berisi beberapa orang.
400	InvalidFile.FaceNotMatch	There are no matched face in the video with the provided reference image.	Wajah dalam gambar referensi tidak cocok dengan wajah apa pun dalam video.

FAQ

Bagaimana cara menangani video dan audio input dengan durasi berbeda?
Secara default, file yang lebih panjang akan dipotong agar sesuai dengan durasi file yang lebih pendek.
Jika audio input lebih panjang daripada video dan Anda ingin menghasilkan video berdasarkan durasi audio, atur parameter video_extension ke true. Ini akan memperpanjang video dengan mengulangnya dalam pola "putar mundur, putar maju" hingga durasinya sesuai dengan panjang audio.
Bagaimana API menangani segmen diam dalam audio input?
Model menghasilkan frame di mana mulut orang tersebut tertutup untuk menyesuaikan dengan segmen diam dalam audio input.
Apa yang terjadi ketika frame video tidak berisi wajah, tetapi audio yang sesuai berisi ucapan?
Frame video asli dipertahankan, dan audio tetap diputar di atasnya. Lip-syncing hanya diterapkan pada frame yang berisi wajah yang dapat dideteksi.
Bagaimana cara memilih orang tertentu untuk lip-syncing dalam video yang berisi beberapa orang?
API hanya dapat menyinkronkan bibir satu orang dalam video. Algoritma mendeteksi wajah yang ditentukan menggunakan gambar referensi input (input.ref_image_url). Jika tidak diberikan, algoritma secara default menggunakan wajah terbesar dalam frame pertama yang berisi wajah.