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'.
Proses citra input menggunakan API deteksi citra EMO untuk mendapatkan nilai koordinat wilayah wajah (face_bbox) dan wilayah dinamis (ext_bbox). Nilai-nilai ini digunakan sebagai parameter permintaan.
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_idberlaku selama 24 jam setelah dibuat.
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-Asyncstring(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-Typestring(Wajib)
Tipe konten permintaan. Atur parameter ini ke application/json.
Badan Permintaan
modelstring(Wajib)
Nama model. Contoh: emo-v1.
inputobject(Wajib)
Menentukan informasi input dasar.
Properti
image_urlstring(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.
Anda dapat mengunggah file menggunakan tautan HTTP atau HTTPS. Jalur file lokal tidak didukung.
face_bboxarray(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_bboxarray(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]`.
parametersobject (Opsional)
Properti
style_levelstring (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`.
ID tugas asinkron yang dikirimkan. Hasil tugas aktual harus diambil menggunakan API kueri tugas asinkron. Contoh: a8532587-fa8c-4ef8-82be-xxxxxx.
task_statusstring
Status tugas setelah dikirimkan. Contoh: "PENDING".
request_idstring
ID permintaan unik. Anda dapat menggunakan ID ini untuk melacak dan memecahkan masalah.
codestring
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_idstring(Wajib)
`task_id` dari tugas yang ingin ditanyakan. Contoh: a8532587-fa8c-4ef8-82be-xxxxxx.
{
"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_idstring
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_statusstring
Status tugas.
Enumerasi
PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Tugas tidak ada atau statusnya tidak dapat ditentukan.
submit_timestring
Waktu saat tugas dikirimkan. Zona waktu adalah UTC+8. Contoh: 2025-09-11 14:33:38.716.
scheduled_timestring
Waktu saat tugas dijadwalkan untuk dimulai. Zona waktu adalah UTC+8. Contoh: 2025-09-11 14:33:53.089.
end_timestring
Waktu saat tugas selesai. Zona waktu adalah UTC+8. Contoh: 2025-09-11 14:35:51.541.
resultsobject
Hasil eksekusi tugas.
Properti
video_urlstring
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.
codestring
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.
usageobject
Properti
video_durationfloat
Durasi video yang dihasilkan oleh permintaan ini, dalam detik. Contoh: 13,93.
video_ratiostring
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: