Referensi API pembuatan video VideoRetalk - Alibaba Cloud Model Studio

VideoRetalk adalah model pembuatan video karakter. Anda dapat menggunakan video karakter dan file audio untuk menghasilkan video baru di mana gerakan bibir karakter disinkronkan dengan audio input. Dokumen ini menjelaskan cara memanggil API untuk fitur pembuatan video yang disediakan oleh model ini.

Penting

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

HTTP

API pembuatan video VideoRetalk hanya dapat dipanggil melalui HTTP. Untuk mengurangi waktu tunggu dan menghindari timeout permintaan, API ini menggunakan metode pemrosesan asinkron. Oleh karena itu, Anda harus melakukan dua permintaan untuk menghasilkan video.

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

Prasyarat

Anda telah mendapatkan API key dan mengonfigurasi API key sebagai environment variable.

Batasan input

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

Pengiriman tugas

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

Parameter permintaan

Field	Type	Method	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 tugas 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 berupa alamat yang dapat diakses publik dan mendukung protokol HTTP atau HTTPS. Persyaratan file video: Ukuran: Ukuran file harus 300 MB atau kurang. Format: MP4, AVI, atau MOV. Durasi: Durasi harus lebih dari 2 detik dan kurang dari 120 detik. Frame rate: Laju frame harus antara 15 fps dan 60 fps. Encoding: Kami merekomendasikan penggunaan encoding H.264 atau H.265. Panjang sisi: Panjang sisi harus antara 640 hingga 2048 piksel. Konten: Video harus berupa bidikan close-up seseorang yang menghadap ke depan. Hindari sudut samping ekstrem atau wajah yang sangat kecil. Jika wajah dalam video tidak lengkap atau tidak ada orang, lihat FAQ untuk penanganannya.	http://aaa/bbb.mp4
input.audio_url	String	Body	Yes	URL file audio yang Anda unggah. URL harus berupa alamat yang dapat diakses publik dan mendukung protokol HTTP atau HTTPS. Persyaratan file audio: Ukuran: Ukuran file harus 30 MB atau kurang. Format: WAV, MP3, atau AAC. Durasi: Durasi harus lebih dari 2 detik dan kurang dari 120 detik. Jika durasi video dan audio berbeda, lihat FAQ untuk penanganannya. Konten: Audio harus berisi suara manusia yang jelas dan keras. Gangguan seperti kebisingan lingkungan dan musik latar harus dihilangkan.	http://aaa/bbb.wav
input.ref_image_url	String	Body	No	URL citra wajah referensi yang Anda unggah. URL harus berupa alamat yang dapat diakses publik dan mendukung protokol HTTP atau HTTPS. Saat terdapat beberapa wajah dalam video input, Anda dapat menggunakan parameter ini untuk menentukan wajah yang akan disinkronkan gerakan bibirnya. Jika hanya terdapat satu wajah dalam video, Anda tidak perlu menentukannya. Jika Anda tidak menyediakan citra wajah referensi, orang dengan wajah terbesar pada frame pertama yang berisi wajah akan dipilih secara default. Persyaratan file citra: Konten: Citra harus berisi tampilan depan yang jelas dari wajah seseorang, dan orang tersebut harus muncul dalam video. Ukuran file: Ukuran file harus 10 MB atau kurang. Ukuran citra: Rasio aspek harus 2 atau kurang. Panjang sisi maksimum harus 4096 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. Nilai default adalah `false`. Anda dapat mengaturnya ke `true` atau `false`. Jika Anda mengatur parameter ini ke `true`, frame video asli diperpanjang dengan pola "reverse-playback" bergantian hingga durasi video sesuai dengan durasi audio. Jika Anda mengatur parameter ini ke `false`, durasi video tidak diperpanjang. Video yang dihasilkan akan memiliki durasi yang sama dengan video asli, dan audio akan dipotong.	false

Parameter respons

Field	Type	Description	Example
output.task_id	String	ID tugas asinkron yang dikirimkan. Gunakan ID ini untuk mengambil hasil tugas sebenarnya menggunakan API kueri status tugas.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Status tugas setelah tugas asinkron 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/en-US/20250717/pvegot/input_video_01.mp4",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20250717/aumwir/stella2-audiobook7.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 tugas dan pengambilan hasil

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

Parameter permintaan

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

Parameter respons

Field	Type	Description	Example
output.task_id	String	ID tugas yang dikueri.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Status tugas yang dikueri.	Status tugas: PENDING: Tugas sedang dalam antrian. PRE-PROCESSING: Tugas sedang dalam tahap pra-pemrosesan. RUNNING: Tugas sedang berjalan. POST-PROCESSING: Tugas sedang dalam tahap pasca-pemrosesan. SUCCEEDED: Tugas berhasil. FAILED: Tugas gagal. UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
output.video_url	String	Video yang dihasilkan. video_url berlaku selama 24 jam setelah tugas selesai.	https://xxx/1.mp4"
usage.video_duration	Float	Durasi video yang dihasilkan untuk permintaan ini, dalam satuan detik.	"video_duration": 10.23
usage.video_ratio	String	Jenis rasio aspek video yang dihasilkan untuk permintaan ini. Nilainya adalah standard, yang berarti video output memiliki rasio aspek yang sama dengan video asli secara default.	"video_ratio": "standard"
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.16,
        "video_ratio": "standard"
    }
}

Contoh respons kesalahan

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

Kode status

Untuk informasi tentang kode status umum layanan model, lihat Pesan kesalahan.

Model ini juga memiliki kode kesalahan spesifik berikut:

Kode Pengembalian HTTP	Error code	Pesan kesalahan	Deskripsi
400	InvalidParameter	Field required: xxx	Parameter permintaan tidak lengkap 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. Batas waktu adalah 60 detik.
400	InvalidFile.Size	Invalid file size. The video/audio/image file size must be less than **MB.	File video, audio, atau citra 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. Citra 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 detik hingga 120 detik.
400	InvalidFile.ImageSize	The size of image is beyond limit.	Ukuran citra melebihi batas. Rasio aspek citra harus 2 atau kurang, dan sisi terpanjang harus 4096 piksel atau kurang.
400	InvalidFile.Openerror	Invalid file, cannot open file as video/audio/image.	File video, audio, atau citra tidak dapat dibuka.
400	InvalidFile.Content	The input image has no human body or multi human bodies. Please upload other image with single person.	Citra 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 citra referensi tidak cocok dengan wajah apa pun dalam video.

FAQ

Bagaimana ketidakkonsistenan antara durasi audio dan video input ditangani?
Secara default, file yang lebih panjang dipotong agar sesuai dengan durasi file yang lebih pendek.
Jika audio input lebih panjang daripada video dan Anda ingin menghasilkan video berdasarkan durasi audio, Anda dapat mengatur parameter video_extension ke true. Algoritma memperpanjang durasi video menggunakan pola "reverse-playback" bergantian dengan frame video asli hingga durasi video sesuai dengan durasi audio.
Bagaimana periode diam dalam audio input ditangani?
Selama periode diam dalam audio, karakter dalam video tetap menutup mulutnya.
Bagaimana situasi ditangani jika tidak ada orang atau wajah tidak lengkap dalam video input?
Jika audio berisi suara manusia tetapi orang atau mulutnya tidak terlihat dalam frame video, frame video asli dipertahankan, dan audio diputar secara normal.
Bagaimana situasi ditangani jika terdapat beberapa orang dalam video input?
Hanya wajah satu orang yang dapat diganti. Algoritma mendeteksi wajah yang ditentukan menggunakan citra referensi input (input.ref_image_url). Jika citra referensi tidak disediakan, algoritma secara default memilih wajah terbesar dalam frame pertama yang berisi wajah.