全部产品
Search
文档中心

Alibaba Cloud Model Studio:Referensi API pembuatan video EMO

更新时间:Dec 27, 2025

Model EMO menghasilkan video animasi wajah menggunakan citra potret dan audio suara.

Penting

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

Tampilan performa

Contoh input

Contoh output

Portret:

上春山

Audio suara:

Kekuatan gaya aksi: Parameter style_level diatur ke 'active'.

Untuk contoh lainnya, lihat Tampilan performa.

Catatan

Pastikan semua citra dan file audio yang diunggah berasal dari sumber yang mematuhi hukum dan Anda memiliki izin yang diperlukan untuk penggunaannya.

Prasyarat

HTTP

Langkah 1: Buat tugas dan dapatkan ID tugas

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis
Catatan
  • Setelah tugas dibuat, sistem segera mengembalikan task_id. Anda dapat menggunakan ID ini pada Langkah 2 untuk menanyakan hasil tugas. task_id berlaku selama 24 jam setelah dibuat.

Parameter 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": "emo-v1",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251225/onmomb/emo.png",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250825/aejgyj/input_audio.mp3",
        "face_bbox":[302,286,610,593],
        "ext_bbox":[71,9,840,778]
        },
    "parameters": {
        "style_level": "normal"
        }
    }'
import requests
import os

# 1. Dapatkan kunci API dari variabel lingkungan.
api_key = os.getenv("DASHSCOPE_API_KEY")

# 2. Siapkan permintaan.
url = 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis'

headers = {
    'X-DashScope-Async': 'enable',
    'Authorization': f'Bearer {api_key}',
}

payload = {
    "model": "emo-v1",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251225/onmomb/emo.png",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250825/aejgyj/input_audio.mp3",
        "face_bbox": [302, 286, 610, 593],
        "ext_bbox": [71, 9, 840, 778]
    },
    "parameters": {
        "style_level": "normal"
    }
}

# 3. Kirim permintaan POST.
#    Dengan parameter 'json', requests secara otomatis menangani serialisasi JSON dan header 'Content-Type'.
response = requests.post(url, headers=headers, json=payload)

# 4. Cetak respons JSON asli dari server.
#    Jika permintaan berhasil, ID tugas dan informasi lainnya akan dicetak.
#    Jika permintaan gagal, pesan kesalahan dari server akan dicetak.
print(response.json())
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.stream.Collectors;
/**
 * Persyaratan:
 * - Java 8 atau versi lebih baru.
 * - Variabel lingkungan DASHSCOPE_API_KEY harus diatur saat runtime.
 **/
public class DashScopeApiDemo {

    public static void main(String[] args) throws IOException {
        // 1. Dapatkan kunci API dari variabel lingkungan.
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        // 2. Siapkan permintaan.
        String urlString = "https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis";
        String payload = "{"
                + "\"model\": \"emo-v1\","
                + "\"input\": {"
                +     "\"image_url\": \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251225/onmomb/emo.png\","
                +     "\"audio_url\": \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250825/aejgyj/input_audio.mp3\","
                +     "\"face_bbox\": [302, 286, 610, 593],"
                +     "\"ext_bbox\": [71, 9, 840, 778]"
                + "},"
                + "\"parameters\": {"
                +     "\"style_level\": \"normal\""
                + "}"
                + "}";
        // 3. Kirim permintaan POST.
        URL url = new URL(urlString);
        // noinspection StartSSRFNetHookCheckingInspection
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("POST");
        connection.setRequestProperty("Authorization", "Bearer " + apiKey);
        connection.setRequestProperty("X-DashScope-Async", "enable");
        connection.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
        connection.setRequestProperty("Accept", "application/json");
        connection.setDoOutput(true);
        // Dapatkan aliran output dan tulis data badan permintaan.
        try (OutputStream os = connection.getOutputStream()) {
            byte[] input = payload.getBytes(StandardCharsets.UTF_8);
            os.write(input, 0, input.length);
        }
        // 4. Dapatkan dan cetak respons server.
        int statusCode = connection.getResponseCode();
        System.out.println("Kode Status: " + statusCode);
        // Pilih aliran input (normal atau aliran kesalahan) berdasarkan kode status.
        InputStream inputStream = (statusCode >= 200 && statusCode < 300)
                ? connection.getInputStream()
                : connection.getErrorStream();
        String responseBody;
        try (BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8))) {
            responseBody = reader.lines().collect(Collectors.joining("\n"));
        }
        System.out.println("Badan Respons: " + responseBody);
        connection.disconnect();
    }
}
// Paket node-fetch diperlukan.
// npm install node-fetch@2

// Impor pustaka node-fetch.
const fetch = require('node-fetch');
// 1. Dapatkan kunci API dari variabel lingkungan.
const apiKey = process.env.DASHSCOPE_API_KEY;
// 2. Siapkan permintaan.
const url = 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis';

const headers = {
    'X-DashScope-Async': 'enable',
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json' // Ini harus ditentukan saat menggunakan fetch.
};

const payload = {
    "model": "emo-v1",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251225/onmomb/emo.png",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250825/aejgyj/input_audio.mp3",
        "face_bbox": [302, 286, 610, 593],
        "ext_bbox": [71, 9, 840, 778]
    },
    "parameters": {
        "style_level": "normal"
    }
};

// 3. Kirim permintaan POST dan proses respons.
fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload) // Objek JavaScript harus dikonversi menjadi string JSON.
})
.then(response => response.json()) // Uraikan badan respons sebagai JSON.
.then(data => {
    // 4. Cetak data JSON yang dikembalikan oleh server.
    console.log(data);
});
Header

X-DashScope-Async string (Wajib)

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.

Authorization string (Wajib)

Header ini digunakan untuk otentikasi identitas. API melakukan autentikasi permintaan menggunakan Kunci API Model Studio. Contoh: Bearer sk-xxxx.

Content-Type string (Wajib)

Tipe konten permintaan. Atur parameter ini ke application/json.

Badan Permintaan

model string (Wajib)

Nama model. Contoh: emo-v1.

input object (Wajib)

Menentukan informasi input dasar.

Properti

image_url string (Wajib)

URL citra yang diunggah. Model memotong citra asli berdasarkan parameter ext_bbox yang dikembalikan oleh API deteksi citra EMO. Rasio aspek area yang dipotong secara langsung menentukan rasio aspek dan resolusi video output.

  • Jika rasio aspek `ext_bbox` adalah 1:1, video potret profil 512 × 512 dihasilkan. Jika rasio aspeknya 3:4, video potret setengah badan 512 × 704 dihasilkan.

  • Panjang sisi minimum citra harus setidaknya 400 piksel. Panjang sisi maksimum tidak boleh melebihi 7.000 piksel.

  • Format yang didukung: JPG, JPEG, PNG, BMP, dan WebP.

  • Contoh: `https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/yhdvfg/emo.png`.

  • Anda dapat mengunggah file menggunakan tautan HTTP atau HTTPS. Jalur file lokal tidak didukung.

audio_url string (Wajib)

URL file audio yang diunggah. File audio ini digunakan sebagai input untuk inferensi model EMO.

  • Audio harus berisi suara manusia yang jelas. Untuk hasil terbaik, hapus kebisingan latar belakang, musik latar, dan gangguan lainnya.

  • Ukuran file harus 15 MB atau kurang. Durasi harus 60 detik atau kurang.

  • Format yang didukung: WAV dan MP3.

  • Contoh: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250825/aejgyj/input_audio.mp3.

  • Anda dapat mengunggah file menggunakan tautan HTTP atau HTTPS. Jalur file lokal tidak didukung.

face_bbox array (Wajib)

Koordinat piksel kotak pembatas (bbox) untuk wilayah wajah dalam citra. Anda dapat memperoleh nilai ini dari bidang `face_bbox` dalam respons API deteksi citra EMO. Format koordinat adalah `[x1, y1, x2, y2]`, yang merepresentasikan koordinat titik kiri atas dan kanan bawah. Contoh: `[302,286,610,593]`.

Sudut kiri atas citra adalah origin (0,0). Sumbu-x memanjang ke kanan, dan sumbu-y memanjang ke bawah.

ext_bbox array (Wajib)

Koordinat piksel kotak pembatas (bbox) untuk wilayah dinamis. Anda dapat memperoleh nilai ini dari bidang `ext_bbox` dalam respons API deteksi citra EMO. Rasio aspek area ini adalah 1:1 atau 3:4. Format koordinat adalah `[x1, y1, x2, y2]`, yang merepresentasikan koordinat titik kiri atas dan kanan bawah. Contoh: `[71, 9, 840, 778]`.

parameters object (Opsional)

Properti

style_level string (Opsional) Nilai default: normal

Mengontrol gerakan dan amplitudo karakter. Tiga gaya didukung: `normal` untuk gerakan moderat, `calm` untuk gerakan tenang, dan `active` untuk gerakan aktif. Nilai default adalah `normal`.

Parameter respons

Contoh respons sukses

{
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-xxxxxx", 
        "task_status": "PENDING"
    },
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

Contoh respons kesalahan

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

output object

Berisi informasi output tugas.

Properti

task_id string

ID tugas asinkron yang dikirimkan. Hasil tugas aktual harus diambil menggunakan API kueri tugas asinkron. Contoh: a8532587-fa8c-4ef8-82be-xxxxxx.

task_status string

Status tugas setelah dikirimkan. Contoh: "PENDING".

request_id string

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

code string

Kode kesalahan yang dikembalikan ketika permintaan gagal. Untuk informasi lebih lanjut, lihat Kode kesalahan.

message string

Pesan kesalahan detail yang dikembalikan ketika permintaan gagal. Untuk informasi lebih lanjut, lihat Kode kesalahan.

Langkah 2: Tanyakan hasil berdasarkan ID tugas

Gunakan task_id dari langkah sebelumnya untuk memantau status dan hasil tugas. Ganti {task_id} dalam URL dengan ID tugas aktual Anda.

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
Catatan
  • Validitas `task_id`: ID ini berlaku selama 24 jam setelah dibuat. Setelah periode ini, Anda tidak dapat lagi menanyakan hasilnya. API akan mengembalikan status tugas UNKNOWN.

  • Alur status tugas: Tugas yang diproses secara normal akan melewati status berikut: `PENDING`, `RUNNING`, dan `SUCCEEDED` atau `FAILED`.

  • Pengambilan hasil: Pembuatan video membutuhkan waktu beberapa menit. API kueri memiliki batas default 20 QPS. Gunakan mekanisme polling dengan interval kueri yang wajar, misalnya 15 detik, untuk mengambil hasil.

  • Validitas video_url: Setelah tugas berhasil, URL tersebut berlaku selama 24 jam. Anda harus segera mengunduh video dan memindahkannya ke penyimpanan permanen setelah menerima tautan tersebut (seperti Object Storage Service (OSS)).

Parameter permintaan

curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
import requests
import os

# 1. Dapatkan kunci API dari variabel lingkungan.
api_key = os.getenv("DASHSCOPE_API_KEY")

# 2. Ganti ini dengan ID tugas aktual yang ingin Anda tanyakan.
task_id = "a8532587-fa8c-4ef8-82be-xxxxxx"

# 3. Siapkan informasi permintaan.
# Gunakan f-string untuk menambahkan task_id ke URL.
url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"

headers = {
    'Authorization': f'Bearer {api_key}'
}

# 4. Kirim permintaan GET.
response = requests.get(url, headers=headers)

# 5. Cetak respons JSON dari server.
# Ini menampilkan status tugas (seperti "RUNNING", "SUCCEEDED", atau "FAILED") dan hasilnya.
print(response.json())
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.stream.Collectors;
/**
 * Persyaratan:
 * - Java 8 atau versi lebih baru.
 * - Variabel lingkungan DASHSCOPE_API_KEY harus diatur saat runtime.
 **/
public class TaskStatusChecker {

    public static void main(String[] args) throws IOException {
        // 1. Dapatkan kunci API dari variabel lingkungan.
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        // 2. Ganti ini dengan ID tugas aktual yang ingin Anda tanyakan.
        String taskId = "a8532587-fa8c-4ef8-82be-xxxxxx"; // Ganti ini dengan ID tugas Anda.
        // 3. Siapkan informasi permintaan (bangun URL secara dinamis).
        String urlString = "https://dashscope.aliyuncs.com/api/v1/tasks/" + taskId;
        // 4. Buat koneksi dan kirim permintaan GET.
        URL url = new URL(urlString);
        // noinspection StartSSRFNetHookCheckingInspection
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("GET");
        // Atur header permintaan.
        connection.setRequestProperty("Authorization", "Bearer " + apiKey);
        // 5. Dapatkan dan cetak respons server.
        int statusCode = connection.getResponseCode();
        System.out.println("Kode Status: " + statusCode);
        InputStream inputStream = (statusCode >= 200 && statusCode < 300)
                ? connection.getInputStream()
                : connection.getErrorStream();
        String responseBody;
        try (BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8))) {
            responseBody = reader.lines().collect(Collectors.joining("\n"));
        }
        System.out.println("Badan Respons: " + responseBody);
        connection.disconnect();
    }
}
// Paket node-fetch diperlukan.
// npm install node-fetch@2

// Impor pustaka node-fetch.
const fetch = require('node-fetch');
// 1. Dapatkan kunci API dari variabel lingkungan.
const apiKey = process.env.DASHSCOPE_API_KEY;
// 2. Ganti ini dengan ID tugas aktual yang ingin Anda tanyakan.
const taskId = "a8532587-fa8c-4ef8-82be-xxxxxx"; // <-- Ganti ini dengan ID tugas Anda.
// 3. Siapkan informasi permintaan.
// Gunakan template literal untuk menambahkan taskId ke URL. Ini mirip dengan f-string di Python.
const url = `https://dashscope.aliyuncs.com/api/v1/tasks/${taskId}`;

const headers = {
    'Authorization': `Bearer ${apiKey}`
};

// 4. Kirim permintaan GET.
// Metode permintaan default untuk fetch adalah GET, sehingga Anda dapat menghilangkan method: 'GET'.
fetch(url, {
    headers: headers
})
.then(response => response.json()) // Uraikan badan respons sebagai JSON.
.then(data => {
    // 5. Cetak respons JSON dari server.
    // Ini menampilkan status tugas (seperti "RUNNING" atau "SUCCEEDED") dan hasilnya.
    console.log(data);
});

Header

Authorization string (Wajib)

Digunakan untuk otentikasi identitas permintaan. API menggunakan kunci API Model Studio untuk autentikasi. Contoh: Bearer sk-xxxx.

Parameter path URL

task_id string (Wajib)

`task_id` dari tugas yang ingin ditanyakan. Contoh: a8532587-fa8c-4ef8-82be-xxxxxx.

Parameter respons

Contoh respons sukses

{
    "request_id": "8190395f-ca1b-4703-9656-xxxxxx",
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-11 14:33:38.716",
        "scheduled_time": "2025-09-11 14:33:53.089",
        "end_time": "2025-09-11 14:35:51.541",
        "results": {
            "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxxx"
        }
    },
    "usage": {
        "video_duration": 13.93,
        "video_ratio": "1:1"
    }
}

Contoh respons kesalahan

{
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-xxxxxx", 
        "task_status": "FAILED",
        "code": "InvalidURL", 
        "message": "Required URL is missing or invalid, please check the request URL." 
    },
    "request_id": "4d687387-580a-4b49-a1f8-4691289e09a3" 
}

request_id string

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

output object

Berisi informasi output tugas.

Properti

task_id string

`task_id` dari tugas yang ditanyakan. Contoh: a8532587-fa8c-4ef8-82be-xxxxxx.

task_status string

Status tugas.

Enumerasi

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • CANCELED

  • UNKNOWN: Tugas tidak ada atau statusnya tidak dapat ditentukan.

submit_time string

Waktu saat tugas dikirimkan. Zona waktu adalah UTC+8. Contoh: 2025-09-11 14:33:38.716.

scheduled_time string

Waktu saat tugas dijadwalkan untuk dimulai. Zona waktu adalah UTC+8. Contoh: 2025-09-11 14:33:53.089.

end_time string

Waktu saat tugas selesai. Zona waktu adalah UTC+8. Contoh: 2025-09-11 14:35:51.541.

results object

Hasil eksekusi tugas.

Properti

video_url string

URL hasil video yang dihasilkan oleh platform. `video_url` berlaku selama 24 jam setelah tugas selesai. Anda harus segera mengunduh dan menyimpan file video tersebut. Contoh: http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxxx.

code string

Kode kesalahan yang dikembalikan ketika permintaan gagal. Untuk informasi lebih lanjut, lihat Kode kesalahan.

message string

Pesan kesalahan detail yang dikembalikan ketika permintaan gagal. Untuk informasi lebih lanjut, lihat Kode kesalahan.

usage object

Properti

video_duration float

Durasi video yang dihasilkan oleh permintaan ini, dalam detik. Contoh: 13,93.

video_ratio string

Rasio aspek video yang dihasilkan oleh permintaan ini. Nilainya adalah 1:1 atau 3:4.

Penagihan dan batas laju

Nama model

Harga satuan

Batas QPS pengiriman tugas

Tugas konkuren

emo-v1

Pay-as-you-go. Anda dikenai biaya berdasarkan durasi aktual video output:

  • Video rasio aspek 1:1: USD 0,011469 per detik

  • Video rasio aspek 3:4: USD 0,022937 per detik

5

1

(Tugas berlebih akan masuk antrian.)

Kode kesalahan

Untuk kode status umum, lihat Pesan kesalahan.