Model LivePortrait secara cepat menghasilkan video potret dinamis yang ringan dari citra potret yang telah diproses oleh model LivePortrait-detect dan file audio berisi suara manusia. Dokumen ini menjelaskan cara memanggil API untuk menggunakan fitur pembuatan video dari model ini.
Dokumen ini hanya berlaku untuk wilayah China (Beijing). Untuk menggunakan model ini, Anda harus menggunakan API key untuk wilayah China (Beijing).
Ikhtisar model
Model | Deskripsi |
liveportrait | Liveportrait adalah model pembuatan video potret. Model ini menghasilkan video potret dinamis yang ringan dari citra potret dan file audio suara manusia. |
HTTP API
Deskripsi fitur
Menghasilkan video potret dinamis.
Prasyarat
Aktifkan Alibaba Cloud Model Studio dan peroleh API key. Untuk informasi selengkapnya, lihat Buat dan konfigurasikan API key.
Citra input telah melalui deteksi citra LivePortrait.
Batasan input
Format citra: JPEG, JPG, PNG, BMP, atau WebP.
Resolusi citra: Ukuran file citra harus kurang dari 10 MB. Rasio aspek tidak boleh melebihi 2. Panjang sisi maksimum tidak boleh lebih dari 4.096 piksel.
Format audio: WAV atau MP3.
Batasan audio: Ukuran file audio harus kurang dari 15 MB. Durasi harus antara 1 detik hingga 3 menit.
Konten audio: Audio harus berisi suara manusia yang jelas dan keras tanpa kebisingan lingkungan, musik latar, atau gangguan suara lainnya.
Unggah citra dan file audio menggunakan URL HTTP atau HTTPS. Jalur file lokal tidak didukung.
Kirim pekerjaan
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/Karena ini merupakan pemanggilan algoritma yang memakan waktu, pekerjaan dikirim menggunakan pemanggilan asinkron.
Setelah pekerjaan dikirim, sistem akan mengembalikan ID pekerjaan. Gunakan API "Kueri status pekerjaan dan ambil hasil" untuk memeriksa status dan mengambil hasil pekerjaan tersebut.
Parameter permintaan
Field | Type | Passing parameters | Required | Deskripsi | Contoh |
Content-Type | String | Header | Ya | Jenis permintaan. Tetapkan nilai ini ke application/json. | application/json |
Authorization | String | Header | Ya | API key. Contoh: Bearer d1**2a. | Bearer d1**2a |
X-DashScope-Async | String | Header | Ya | Tetapkan ke enable untuk mengirim pekerjaan secara asinkron. | enable |
model | String | Body | Ya | Model yang dipanggil. Tetapkan nilai ini ke liveportrait. | liveportrait |
input.image_url | String | Body | Ya | URL citra yang diunggah. Citra tersebut harus terlebih dahulu diproses oleh API deteksi citra LivePortrait.
Catatan Unggahan file hanya mendukung tautan HTTP atau HTTPS, bukan jalur file lokal. | "image_url": "http://a/a.jpg" |
input.audio_url | String | Body | Ya | URL file audio yang diunggah.
Catatan Unggahan file hanya mendukung tautan HTTP atau HTTPS, bukan jalur file lokal. | http://aaa/bbb.wav |
parameters.template_id | String | Body | Tidak | Mengontrol postur dan rentang gerakan kepala berdasarkan templat. Templat yang didukung: normal, calm, dan active. Nilai default: normal. | "normal" |
parameters.eye_move_freq | Float | Body | Tidak | Jumlah kedipan per detik. Nilai valid: 0 hingga 1. Nilai yang lebih besar menunjukkan frekuensi kedipan yang lebih tinggi. Nilai default: 0.5. | 0.5 |
parameters.video_fps | Integer | Body | Tidak | Laju frame video output. Nilai valid: 15 hingga 30. Nilai default: 24. | 24 |
parameters.mouth_move_strength | Float | Body | Tidak | Besarnya gerakan mulut. Nilai valid: 0 hingga 1.5. Nilai yang lebih besar menunjukkan bentuk mulut yang lebih besar. Jika Anda menetapkan nilai ini ke 0, mulut tidak bergerak. Nilai default: 1. | 1 |
parameters.paste_back | Boolean | Body | Tidak | Menentukan apakah wajah yang dihasilkan ditempelkan kembali ke citra asli. Nilai valid: true atau false. Jika Anda menetapkan nilai ini ke false, hanya wajah yang dihasilkan yang dikembalikan dan tubuh diabaikan. Nilai default: true. | true |
parameters.head_move_strength | Float | Body | Tidak | Besarnya gerakan kepala. Nilai valid: 0 hingga 1. Nilai yang lebih besar menunjukkan rentang gerakan kepala yang lebih besar. Nilai default: 0.7. | 0.7 |
Parameter respons
Field | Type | Deskripsi | Contoh |
output.task_id | String | ID pekerjaan asinkron yang dikirim. Hasil pekerjaan sebenarnya harus diperoleh menggunakan API kueri pekerjaan asinkron. | a8532587-fa8c-4ef8-82be-0c46b17950d1 |
output.task_status | String | Status pekerjaan setelah pekerjaan asinkron dikirim. | "PENDING" |
request_id | String | ID unik permintaan. | 7574ee8f-38a3-4b1e-9280-11c33ab46e51 |
Templat aksi
template_id | Deskripsi efek |
normal | Templat aksi default. Rentang gerakan kepala moderat. Templat ini cocok untuk berbagai skenario. |
calm | Karakter tampak tenang, dan rentang gerakan kepala kecil. Templat ini direkomendasikan untuk skenario seperti siaran. |
active | Karakter tampak hidup, dan rentang gerakan kepala besar. Templat ini direkomendasikan untuk skenario seperti bernyanyi. |
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": "liveportrait",
"input": {
"image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/ynhjrg/p874909.png",
"audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251226/fwnqyq/liveportrait_boy.mp3"
},
"parameters": {
"template_id": "normal",
"eye_move_freq": 0.5,
"video_fps":30,
"mouth_move_strength":1,
"paste_back": true,
"head_move_strength":0.7
}
}'Contoh respons
{
"output": {
"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
"task_status": "PENDING"
},
"request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}Kueri status pekerjaan dan ambil hasil
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}Parameter permintaan
Field | Type | Passing parameters | Required | Deskripsi | Contoh |
Authorization | String | Header | Ya | API key. Contoh: Bearer d1**2a. | Bearer d1**2a |
task_id | String | Url Path | Ya | ID pekerjaan yang akan dikueri. | a8532587-fa8c-4ef8-82be-0c46b17950d1 |
Parameter respons
Field | Type | Deskripsi | Contoh |
output.task_id | String | ID pekerjaan yang dikueri. | a8532587-fa8c-4ef8-82be-0c46b17950d1 |
output.task_status | String | Status pekerjaan yang dikueri. | Status pekerjaan: PENDING: Pekerjaan sedang dalam antrian. RUNNING: Pekerjaan sedang berlangsung. SUCCEEDED: Pekerjaan berhasil. FAILED UNKNOWN: Pekerjaan tidak ada atau statusnya tidak diketahui. |
output.results.video_url | String | Jika pekerjaan berhasil, parameter ini berisi objek hasil yang dihasilkan oleh model. Setiap objek berisi URL hasil yang dihasilkan. video_url berlaku selama 24 jam setelah pekerjaan selesai. | https://xxx/1.mp4 |
usage.video_duration | Float | Durasi video yang dihasilkan untuk permintaan ini, dalam satuan detik. | 10.23 |
usage.video_ratio | String | Jenis frame video yang dihasilkan untuk permintaan ini. Nilainya adalah standard. | "video_ratio": "standard" |
request_id | String | ID unik permintaan. | 7574ee8f-38a3-4b1e-9280-11c33ab46e51 |
Contoh permintaan
Ganti 86ecf553-d340-4e21-xxxxxxxxx dengan ID task Anda yang sebenarnya.
curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"Contoh respons (berhasil)
{
"request_id": "b64e9c68-3923-462d-b25a-xxxxxx",
"output": {
"task_id": "a1c69ca5-810b-49ae-8b20-xxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2025-12-26 11:33:03.146",
"scheduled_time": "2025-12-26 11:33:13.312",
"end_time": "2025-12-26 11:33:22.455",
"results": {
"video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
}
},
"usage": {
"video_duration": 2.79,
"video_ratio": "standard"
}
}Contoh respons (gagal)
{
"request_id": "7574ee8f-38a3-4b1e-9280-xxxxxx",
"output": {
"task_id": "a8532587-fa8c-4ef8-82be-xxxxxx",
"task_status": "FAILED",
"code": "xxx",
"message": "xxxxxx"
}
}Kode status
Untuk informasi tentang kode status umum, lihat Pesan error.