全部产品
Search

搜索本产品

    Alibaba Cloud Model Studio：Referensi API Pembuatan Video Emoji

    文档中心

    Alibaba Cloud Model Studio：Referensi API Pembuatan Video Emoji

    更新时间：Oct 25, 2025

    Model emoji-v1 menghasilkan video Emoji wajah dari gambar potret dan ID template preset.

    Penting

    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

    1. Anda harus memperoleh Kunci API dan atur Kunci API sebagai Variabel lingkungan.

    2. 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

    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]
    }
}'
    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.

    Penting

    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.

    Parameter Respons

    Respons Sukses

    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"
}

    Respons Kesalahan

    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"
}

    output objek

    Informasi keluaran tugas.

    Properti

    task_id string

    ID tugas. Query valid selama 24 jam.

    task_status string

    Status tugas.

    Enumerasi

    • PENDING

    • Berjalan

    • SUCCEEDED

    • GAGAL

    • DIBATALKAN

    • TIDAK DIKETAHUI

    request_id string

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

    code string

    Kode kesalahan untuk permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi lebih lanjut, lihat Pesan Kesalahan.

    message string

    Informasi rinci tentang permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi lebih lanjut, lihat Pesan Kesalahan.

    Langkah 2: Tanyakan hasil berdasarkan ID tugas

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

    Catatan

    • 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

    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"
    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.

    Parameter Respons

    Tugas berhasil

    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"
    }
}

    Tugas gagal

    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"
    }
}

    Query tugas kedaluwarsa

    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"
    }
}

    output objek

    Informasi keluaran tugas.

    Properti

    task_id string

    ID tugas. Query valid selama 24 jam.

    task_status string

    Status 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 string

    Waktu ketika tugas dikirim. Formatnya adalah YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    Waktu ketika tugas mulai berjalan. Formatnya adalah YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    Waktu ketika tugas selesai. Formatnya adalah YYYY-MM-DD HH:mm:ss.SSS.

    video_url string

    URL 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 string

    Kode kesalahan untuk permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi lebih lanjut, lihat Pesan Kesalahan.

    message string

    Informasi rinci tentang permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi lebih lanjut, lihat Pesan Kesalahan.

    usage objek

    Statistik penggunaan untuk keluaran. Hanya tugas yang berhasil yang dihitung.

    Properti

    video_duration integer

    Durasi video yang dihasilkan dalam detik.

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

    video_ratio string

    Rasio aspek video yang dihasilkan. Tetap pada `standard`, yang menunjukkan rasio aspek 1:1.

    request_id string

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

    Penagihan dan 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" } }.

    Catatan

    • 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

    1_mengwa_kaixin

    dagong_zhuakuang

    10_dagong_zhuakuang

    mengwa_dengyan

    7_mengwa_dengyan

    dagong_wunai

    15_dagong_wunai

    mengwa_gandong

    16_mengwan_gandong

    dagong_weixiao

    17_dagong_weixiao

    mengwa_renzhen_1

    18_mengwa_renzhen_1

    dagong_ganji

    20_dagong_ganji

    mengwa_jidong

    8_mengwa_jidong

    jingdian_tiaopi

    4_jingdian_tiaopi

    mengwa_kun_1

    11_mengwa_kun_1

    jingdian_deyi_1

    5_jingdian_deyi_1

    mengwa_jiaoxie

    19_mengwa_renzhen_1

    jingdian_qidai

    6_jingdian_qidai

    dagong_kaixin

    2_dagong_kaixin

    jingdian_landuo_1

    12_jingdian_landuo_1

    dagong_yangwang

    3_dagong_yangwang

    jingdian_xianqi

    13_jingdian_xianqi

    dagong_kunhuo

    9_dagong_kunhuo

    jingdian_lei

    14_jingdian_lei