Referensi API pembuatan video LivePortrait - Alibaba Cloud Model Studio

Buat video potret dinamis dari gambar potret yang telah diproses oleh LivePortrait-detect dan file audio suara manusia. Dokumen ini menjelaskan API untuk pembuatan video tersebut.

PentingDokumen ini hanya berlaku untuk wilayah China (Beijing). Untuk menggunakan model ini, Anda harus menggunakan API key untuk wilayah China (Beijing).

Ikhtisar model

Model	Description
liveportrait	Menghasilkan video potret dinamis yang ringan dari gambar potret dan audio suara manusia.

HTTP

Prasyarat

Aktifkan Model Studio dan buat API key: Dapatkan API key.
Gambar input telah melewati deteksi gambar LivePortrait.

Batas input

Format gambar: JPEG, JPG, PNG, BMP, atau WebP.
Resolusi gambar: Maksimal 10 MB, rasio aspek ≤ 2, panjang sisi maksimal 4.096 piksel.
Format audio: WAV atau MP3.
Batas audio: Maksimal 15 MB, durasi antara 1 detik hingga 3 menit.
Konten audio: Harus berupa suara manusia yang jelas. Tidak boleh mengandung kebisingan lingkungan, musik latar, atau gangguan lainnya.
Unggah gambar dan file audio menggunakan URL HTTP atau HTTPS. Jalur file lokal tidak didukung.

Kirim tugas

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

Catatan

Tugas dikirim secara asinkron karena waktu pemrosesan yang lama.
Setelah pengiriman, sistem mengembalikan ID tugas. Gunakan API "Query task status and retrieve results" untuk memeriksa status dan mengambil hasil.

Parameter permintaan

Field	Type	Location	Required	Description	Example
Content-Type	String	Header	Yes	Format body permintaan. Atur ke application/json.	application/json
Authorization	String	Header	Yes	API key dengan awalan Bearer.	Bearer d1**2a
X-DashScope-Async	String	Header	Yes	Atur ke enable untuk pengiriman asinkron.	enable
model	String	Body	Yes	Nama model. Atur ke liveportrait.	liveportrait
input.image_url	String	Body	Yes	URL gambar yang diunggah (harus diproses terlebih dahulu oleh API deteksi gambar LivePortrait). Maksimal 10 MB, rasio aspek ≤ 2, panjang sisi maksimal 4096 piksel. Format yang didukung: JPEG, JPG, PNG, BMP, dan WebP. Pengunggahan file hanya mendukung tautan HTTP atau HTTPS. Jalur file lokal tidak didukung.	"image_url": "http://a/a.jpg"
input.audio_url	String	Body	Yes	URL file audio yang diunggah. Maksimal 15 MB, durasi antara 1 detik hingga 3 menit. Format yang didukung: WAV dan MP3. Pengunggahan file hanya mendukung tautan HTTP atau HTTPS. Jalur file lokal tidak didukung.	http://aaa/bbb.wav
parameters.template_id	String	Body	No	Mengatur postur dan rentang gerakan kepala. Opsi: normal (default), calm, active.	"normal"
parameters.eye_move_freq	Float	Body	No	Jumlah kedipan per detik (0–1). Nilai lebih tinggi = frekuensi kedipan lebih sering. Default: 0.5.	0.5
parameters.video_fps	Integer	Body	No	Laju bingkai video output (15–30). Default: 24.	24
parameters.mouth_move_strength	Float	Body	No	Besarnya gerakan mulut (0–1.5). Nilai lebih tinggi = bentuk mulut lebih besar. Atur ke 0 untuk menonaktifkan gerakan. Default: 1.	1
parameters.paste_back	Boolean	Body	No	Tempel wajah yang dihasilkan kembali ke gambar asli. Jika false, hanya mengembalikan wajah (bagian tubuh diabaikan). Default: true.	true
parameters.head_move_strength	Float	Body	No	Besarnya gerakan kepala (0–1). Nilai lebih tinggi = rentang gerakan lebih besar. Default: 0.7.	0.7

Parameter respons

Field	Type	Description	Example
output.task_id	String	ID tugas yang dikirim. Gunakan API kueri untuk mengambil hasil.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Status tugas setelah pengiriman.	"PENDING"
request_id	String	ID permintaan unik.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Templat aksi

template_id	Effect description
normal	Templat default dengan rentang gerakan kepala moderat. Cocok untuk berbagai skenario.
calm	Karakter tampak tenang dengan gerakan kepala minimal. Direkomendasikan untuk skenario penyiaran.
active	Karakter tampak hidup dengan rentang gerakan kepala besar. Direkomendasikan untuk skenario bernyanyi.

Contoh permintaan

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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 tugas dan ambil hasil

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Parameter permintaan

Field	Type	Location	Required	Description	Example
Authorization	String	Header	Yes	API key dengan awalan Bearer.	Bearer d1**2a
task_id	String	Url Path	Yes	ID tugas yang akan dikueri.	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 RUNNING SUCCEEDED FAILED UNKNOWN: Tugas tidak ada atau status tidak diketahui.
output.results.video_url	String	Jika tugas berhasil, bidang ini berisi URL video yang dihasilkan. Berlaku selama 24 jam setelah tugas selesai.	https://xxx/1.mp4
usage.video_duration	Float	Durasi video yang dihasilkan (dalam detik).	10.23
usage.video_ratio	String	Jenis bingkai video yang dihasilkan. Nilai: standard.	"video_ratio": "standard"
request_id	String	ID permintaan unik.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Contoh permintaan

Ganti 86ecf553-d340-4e21-xxxxxxxxx dengan ID tugas Anda.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.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 error

Untuk informasi tentang kode status umum, lihat Kode error.