Referensi API Pembuatan Video Emoji - Alibaba Cloud Model Studio

Dokumen ini hanya berlaku untuk wilayah Cina (Beijing). Untuk menggunakan model, Anda harus menggunakan Kunci API dari wilayah Cina (Beijing).

Ikhtisar Model

Model	Deskripsi
emoji-v1	Menghasilkan video wajah dari gambar potret yang terdeteksi, koordinat area wajah dan area ekspresi dinamis, serta ID template.

Prasyarat

Anda harus memperoleh Kunci API dan atur Kunci API sebagai Variabel lingkungan.
Proses gambar input menggunakan Deteksi Gambar Emoji untuk mendapatkan koordinat area wajah dan area ekspresi dinamis. Koordinat ini diperlukan sebagai parameter input.

HTTP

Karena pembuatan video memakan waktu (biasanya 1 hingga 5 menit), API menggunakan pemanggilan asinkron. Proses ini melibatkan dua langkah inti: Buat tugas lalu Polling hasilnya. Langkah-langkahnya adalah sebagai berikut:

Waktu yang dibutuhkan bergantung pada jumlah tugas dalam antrian dan status eksekusi layanan. Harap tunggu hingga tugas selesai.

Langkah 1: Buat tugas dan dapatkan ID tugas

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

Parameter Permintaan

Header

Tipe Konten string (Diperlukan)Tipe konten dari permintaan. Atur parameter ini ke application/json.Otorisasi string (Diperlukan)Kredensial otentikasi identitas untuk permintaan. API ini menggunakan Kunci API Model Studio untuk otentikasi identitas. Contoh: Bearer sk-xxxx.X-DashScope-Async string (Diperlukan)Parameter konfigurasi pemrosesan asinkron. Permintaan HTTP hanya mendukung pemrosesan asinkron. Anda harus mengatur parameter ini ke enable.

Jika header permintaan ini tidak ada, pesan kesalahan "current user api does not support synchronous calls" akan dikembalikan.

Body Permintaan

model string (Diperlukan)Nama model. Atur parameter ini ke emoji-v1.input objek (Diperlukan)Informasi input dasar, seperti gambar wajah, area wajah, dan area emoji.

Properti

image_url string (Diperlukan)URL publik gambar wajah depan. Protokol HTTP dan HTTPS didukung.Persyaratan gambar:

Format: JPEG, JPG, PNG, BMP, atau WEBP.
Resolusi: Lebar dan tinggi harus antara 400 dan 7.000 piksel.
Ukuran file: Tidak lebih besar dari 10 MB.
Gambar harus lolos Deteksi Gambar Emoji.

Contoh: https://help-static-aliyun-doc.aliyuncs.com/xxx.png.face_bbox array of integer (Diperlukan)Koordinat area wajah dalam gambar. Formatnya adalah [x1, y1, x2, y2] dalam piksel, sesuai dengan titik kiri atas dan kanan bawah.Atur parameter ini ke nilai dari bidang output.bbox_face dari respons API Deteksi Gambar Emoji.Contoh: [212,194,460,441].ext_bbox array of integer (Diperlukan)Koordinat area ekspresi dinamis. Rasio aspek area ini sekitar 1:1. Formatnya adalah [x1, y1, x2, y2] dalam piksel, sesuai dengan titik kiri atas dan kanan bawah.Atur parameter ini ke nilai dari bidang output.ext_bbox_face dalam respons API Deteksi Gambar Emoji.Contoh: [63,30,609,575].

Catatan: Area ekspresi dinamis adalah area persegi yang menjadi fokus model selama pembuatan video. Biasanya sedikit lebih besar daripada area wajah, termasuk beberapa latar belakang dan bahu, untuk memastikan efek animasi yang alami.

driven_id string (Diperlukan)ID template preset. Untuk daftar nilai valid, lihat Lampiran: Daftar ID Template.Contoh: mengwa_kaixin.

Hasilkan Video Emoji

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--data '{
    "model": "emoji-v1",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20250912/uopnly/emoji-image-detection.png",
        "driven_id": "mengwa_kaixin",
        "face_bbox": [212,194,460,441],
        "ext_bbox": [63,30,609,575]
    }
}'

Parameter Respons

output objekInformasi keluaran tugas.

Properti

task_id stringID tugas. Query valid selama 24 jam.task_status stringStatus tugas.

Enumerasi

PENDING
Berjalan
SUCCEEDED
GAGAL
DIBATALKAN
TIDAK DIKETAHUI

request_id stringID permintaan unik. Anda dapat menggunakan ID ini untuk melacak dan memecahkan masalah.code stringKode kesalahan untuk permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi lebih lanjut, lihat Pesan Kesalahan.message stringInformasi rinci tentang permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi lebih lanjut, lihat Pesan Kesalahan.

Respons Sukses
Respons Kesalahan

Simpan task_id untuk menanyakan status dan hasil tugas.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Pembuatan tugas gagal. Untuk informasi lebih lanjut, lihat Pesan Kesalahan untuk menyelesaikan masalah.

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxx"
}

Langkah 2: Tanyakan hasil berdasarkan ID tugas

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

Saran Polling: Pembuatan video membutuhkan beberapa menit. Gunakan mekanisme polling dan atur interval query yang wajar, seperti 15 detik, untuk mengambil hasilnya.
Transisi Status Tugas: PENDING (Dalam antrian) → RUNNING (Sedang diproses) → SUCCEEDED (Berhasil) atau FAILED (Gagal).
Tautan Hasil: Setelah tugas berhasil, tautan video akan dikembalikan. Tautan tersebut valid selama 24 jam. Setelah Anda mengambil tautan, segera unduh dan simpan videonya ke layanan penyimpanan permanen, seperti Alibaba Cloud OSS.
Validitas task_id: 24 jam. Setelah periode ini, Anda tidak dapat menanyakan hasilnya, dan API mengembalikan status tugas UNKNOWN.

Parameter Permintaan

Header

Otorisasi string (Diperlukan)Kredensial otentikasi identitas untuk permintaan. API ini menggunakan Kunci API Model Studio untuk otentikasi identitas. Contoh: Bearer sk-xxxx.

Parameter jalur URL

task_id string (Diperlukan)ID tugas.

Mengkueri hasil tugas

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

Kunci API untuk wilayah Singapura dan Beijing berbeda. Peroleh Kunci API.

Kode berikut memberikan base_url untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti base_url dengan https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parameter Respons

outputobjekInformasi keluaran tugas.

Properti

task_id stringID tugas. Query valid selama 24 jam.task_status stringStatus tugas.

Enumerasi

PENDING
Berjalan
SUCCEEDED
GAGAL
DIBATALKAN
TIDAK DIKETAHUI

Transisi status selama polling:

PENDING (Dalam antrian) → RUNNING (Sedang diproses) → SUCCEEDED (Berhasil) atau FAILED (Gagal).
Status query pertama biasanya PENDING (Dalam antrian) atau RUNNING (Sedang diproses).
Jika status berubah menjadi SUCCEEDED, respons berisi URL video yang dihasilkan.
Jika statusnya FAILED, periksa pesan kesalahan dan coba lagi.

submit_time stringWaktu ketika tugas dikirim. Formatnya adalah YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu ketika tugas mulai berjalan. Formatnya adalah YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu ketika tugas selesai. Formatnya adalah YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL video. Parameter ini hanya dikembalikan jika task_status adalah SUCCEEDED.Tautan valid selama 24 jam. Anda dapat menggunakan URL ini untuk mengunduh video. Video dalam format MP4 dengan pengkodean H.264.code stringKode kesalahan untuk permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi lebih lanjut, lihat Pesan Kesalahan.message stringInformasi rinci tentang permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi lebih lanjut, lihat Pesan Kesalahan.

usage objekStatistik penggunaan untuk keluaran. Hanya tugas yang berhasil yang dihitung.

Properti

video_duration integerDurasi video yang dihasilkan dalam detik.

Rumus penagihan: Biaya = Durasi video dalam detik × Harga satuan.

video_ratio stringRasio aspek video yang dihasilkan. Tetap pada standard, yang menunjukkan rasio aspek 1:1.

request_id stringID permintaan unik. Anda dapat menggunakan ID ini untuk melacak dan memecahkan masalah.

Tugas berhasil
Tugas gagal
Query tugas kedaluwarsa

Tautan video disimpan hanya selama 24 jam dan secara otomatis dihapus setelah periode ini. Anda harus menyimpan video yang dihasilkan segera.

{
    "request_id": "ad225054-6c94-47e5-9356-xxxxxxx",
    "output": {
        "task_id": "b56f509a-3ea9-4cfe-848d-xxxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-10-14 11:28:04.372",
        "scheduled_time": "2025-10-14 11:28:04.400",
        "end_time": "2025-10-14 11:29:03.924",
        "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xx.mp4?Expires=xxx"
    },
    "usage": {
        "video_duration": 2,
        "video_ratio": "standard"
    }
}

Jika tugas gagal, task_status diatur ke FAILED, dan kode kesalahan serta pesan disediakan. Untuk informasi lebih lanjut, lihat Pesan Kesalahan untuk menyelesaikan masalah.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

task_id valid selama 24 jam. Setelah periode ini, query gagal dan pesan kesalahan berikut dikembalikan.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

Penagihan dan pembatasan laju

Untuk kuota gratis dan harga satuan, lihat Model dan Penagihan.
Untuk batas laju, lihat Pembatasan Laju.

Kode kesalahan

Jika pemanggilan model gagal dan pesan kesalahan dikembalikan, lihat Pesan Kesalahan untuk informasi tentang cara menyelesaikan masalah tersebut.

Lampiran: Daftar ID Template

Contoh pengaturan parameter: { "input": { "driven_id": "mengwa_kaixin" } }.

Efek berikut dihasilkan oleh aplikasi Tongyi, yang mengintegrasikan model Emoji.
Model Emoji menghasilkan video potret yang tidak termasuk stiker atau teks.

ID Template (driven_id)	Pratinjau Efek	ID Template (driven_id)	Pratinjau Efek
mengwa_kaixin		dagong_zhuakuang
mengwa_dengyan		dagong_wunai
mengwa_gandong		dagong_weixiao
mengwa_renzhen_1		dagong_ganji
mengwa_jidong		jingdian_tiaopi
mengwa_kun_1		jingdian_deyi_1
mengwa_jiaoxie		jingdian_qidai
dagong_kaixin		jingdian_landuo_1
dagong_yangwang		jingdian_xianqi
dagong_kunhuo		jingdian_lei