Gere vídeos com rostos animados a partir de imagens de retrato e áudio de voz. Envie uma imagem e um arquivo de áudio para receber um vídeo com o rosto animado em sincronia com a fala.
Esta API aplica-se apenas à região China (Beijing). Use uma chave de API da região China (Beijing).
Como funciona
A API EMO utiliza um fluxo de trabalho assíncrono em duas etapas:
Crie uma tarefa -- Envie uma imagem de retrato e um arquivo de áudio. Você recebe um
task_idimediatamente.Consulte o resultado -- Verifique o status da tarefa usando o
task_id. Quando o status forSUCCEEDED, baixe o vídeo gerado.
A geração do vídeo leva alguns minutos. Os IDs de tarefa permanecem válidos por 24 horas após a criação.
Demonstração de desempenho
|
Entrada de exemplo |
Saída de exemplo |
|
Retrato: |
Vídeo de saída de exemplo Intensidade do estilo de ação: |
Para mais exemplos, consulte Demonstração de desempenho.
Certifique-se de que as imagens e os arquivos de áudio enviados estejam em conformidade legal e que você possua as permissões necessárias para seu uso.
Pré-requisitos
Ative o serviço de modelo e crie uma chave de API, e depois exporte-a como uma variável de ambiente.
Processe a imagem de entrada com a API de detecção de imagem EMO para obter as coordenadas da **área do rosto (
face_bbox) e da área dinâmica (ext_bbox)**. Ambos são parâmetros obrigatórios.
Etapa 1: Crie uma tarefa
Envie a imagem de retrato e o arquivo de áudio para criar uma tarefa de geração de vídeo. Você receberá um task_id para usar na Etapa 2.
Endpoint
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis
Os IDs de tarefa permanecem válidos por 24 horas após a criação.
Cabeçalhos da solicitação
|
Cabeçalho |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Obrigatório |
Modo de processamento assíncrono. Defina como |
|
|
string |
Obrigatório |
Credencial de autenticação no formato |
|
|
string |
Obrigatório |
Tipo de conteúdo da solicitação. Defina como |
Corpo da solicitação
|
Parâmetro |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Obrigatório |
Nome do modelo. Defina como |
|
|
object |
Obrigatório |
Dados de entrada contendo a imagem, o áudio e as coordenadas da caixa delimitadora. Consulte Parâmetros de entrada. |
|
|
object |
Opcional |
Configurações de geração. Consulte Objeto parameters. |
Parâmetros de entrada
|
Parâmetro |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Obrigatório |
URL da imagem de retrato. O modelo recorta a imagem usando |
|
|
string |
Obrigatório |
URL do arquivo de áudio de voz para inferência do modelo EMO. Consulte Requisitos de áudio. |
|
|
array |
Obrigatório |
Coordenadas da caixa delimitadora da área do rosto no formato |
|
|
array |
Obrigatório |
Coordenadas da caixa delimitadora da área dinâmica no formato |
A origem das coordenadas (0,0) está no canto superior esquerdo da imagem. O eixo x se estende para a direita e o eixo y se estende para baixo.
Objeto parameters
|
Parâmetro |
Tipo |
Obrigatório |
Padrão |
Descrição |
|
|
string |
Opcional |
|
Controla a amplitude de movimento do personagem. Valores permitidos: |
Requisitos de imagem
-
A proporção de
ext_bboxdefine as dimensões do vídeo de saída:A proporção 1:1 gera um vídeo de foto de perfil com 512 x 512 pixels.
A proporção 3:4 gera um vídeo de retrato de meio corpo com 512 x 704 pixels.
Comprimento mínimo do lado: 400 pixels.
Comprimento máximo do lado: 7.000 pixels.
Formatos suportados: JPG, JPEG, PNG, BMP e WebP.
A imagem deve ser uma URL HTTP ou HTTPS. Caminhos de arquivos locais não são suportados.
Requisitos de áudio
O áudio deve conter uma voz humana clara. Para obter melhores resultados, remova ruídos de fundo e música.
Tamanho máximo do arquivo: 15 MB.
Duração máxima: 60 segundos.
Formatos suportados: WAV e MP3.
O áudio deve ser uma URL HTTP ou HTTPS. Caminhos de arquivos locais não são suportados.
Exemplos de solicitação
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. Get the API key from an environment variable.
api_key = os.getenv("DASHSCOPE_API_KEY")
# 2. Prepare the request.
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. Send the POST request.
response = requests.post(url, headers=headers, json=payload)
# 4. Print the response.
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;
/**
* Requirements:
* - Java 8 or later.
* - The DASHSCOPE_API_KEY environment variable must be set at runtime.
**/
public class DashScopeApiDemo {
public static void main(String[] args) throws IOException {
// 1. Get the API key from an environment variable.
String apiKey = System.getenv("DASHSCOPE_API_KEY");
// 2. Prepare the request.
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. Send the POST request.
URL url = new URL(urlString);
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);
try (OutputStream os = connection.getOutputStream()) {
byte[] input = payload.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
}
// 4. Get and print the server response.
int statusCode = connection.getResponseCode();
System.out.println("Status Code: " + 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("Response Body: " + responseBody);
connection.disconnect();
}
}
// The node-fetch package is required.
// npm install node-fetch@2
const fetch = require('node-fetch');
// 1. Get the API key from an environment variable.
const apiKey = process.env.DASHSCOPE_API_KEY;
// 2. Prepare the request.
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'
};
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. Send a POST request and process the response.
fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => {
// 4. Print the JSON data returned by the server.
console.log(data);
});
Parâmetros de resposta
|
Parâmetro |
Tipo |
Descrição |
|
|
object |
Informações de saída da tarefa. |
|
|
string |
ID da tarefa assíncrona. Use este ID na Etapa 2 para consultar o resultado. Exemplo: |
|
|
string |
Status da tarefa após o envio. Valor: |
|
|
string |
ID exclusivo da solicitação para rastreamento e solução de problemas. |
|
|
string |
Código de erro. Retornado apenas quando a solicitação falha. Consulte Códigos de erro. |
|
|
string |
Mensagem de erro. Retornada apenas quando a solicitação falha. Consulte Códigos de erro. |
Exemplos de resposta
Exemplo de resposta de sucesso
{
"output": {
"task_id": "a8532587-fa8c-4ef8-82be-xxxxxx",
"task_status": "PENDING"
},
"request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}
Exemplo de resposta de erro
{
"code": "InvalidParameter",
"message": "The specified parameter is not valid.",
"request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}
Etapa 2: Consulte o resultado
Use o task_id da Etapa 1 para verificar o status da tarefa e recuperar o vídeo gerado.
Endpoint
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
Substitua {task_id} pelo ID da tarefa obtido na Etapa 1.
Observações importantes
**Validade do
task_id:** Os IDs de tarefa permanecem válidos por 24 horas após a criação. Após a expiração, a API retorna o statusUNKNOWN.Fluxo de status da tarefa:
PENDING→RUNNING→SUCCEEDEDouFAILED.Consulta periódica: A geração do vídeo leva alguns minutos. Limite da API de consulta: 20 QPS. Faça consultas a cada 15 segundos ou mais.
**Validade da
video_url:** As URLs de vídeo permanecem válidas por 24 horas após o sucesso da tarefa. Baixe e transfira para um armazenamento permanente (por exemplo, O que é o OSS?) imediatamente.
Cabeçalhos da solicitação
|
Cabeçalho |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Obrigatório |
Credencial de autenticação no formato |
Parâmetros de caminho da URL
|
Parâmetro |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Obrigatório |
ID da tarefa da Etapa 1. Exemplo: |
Exemplos de solicitação
curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
import requests
import os
# 1. Get the API key from the environment variable.
api_key = os.getenv("DASHSCOPE_API_KEY")
# 2. Replace this with the actual task ID.
task_id = "a8532587-fa8c-4ef8-82be-xxxxxx"
# 3. Prepare the request.
url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
headers = {
'Authorization': f'Bearer {api_key}'
}
# 4. Send a GET request.
response = requests.get(url, headers=headers)
# 5. Print the response.
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;
/**
* Requirements:
* - Java 8 or later.
* - The DASHSCOPE_API_KEY environment variable must be set at runtime.
**/
public class TaskStatusChecker {
public static void main(String[] args) throws IOException {
// 1. Get the API key from the environment variable.
String apiKey = System.getenv("DASHSCOPE_API_KEY");
// 2. Replace this with the actual task ID.
String taskId = "a8532587-fa8c-4ef8-82be-xxxxxx";
// 3. Prepare the request.
String urlString = "https://dashscope.aliyuncs.com/api/v1/tasks/" + taskId;
// 4. Create a connection and send a GET request.
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
connection.setRequestProperty("Authorization", "Bearer " + apiKey);
// 5. Get and print the server response.
int statusCode = connection.getResponseCode();
System.out.println("Status Code: " + 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("Response Body: " + responseBody);
connection.disconnect();
}
}
// The node-fetch package is required.
// npm install node-fetch@2
const fetch = require('node-fetch');
// 1. Get the API key from the environment variable.
const apiKey = process.env.DASHSCOPE_API_KEY;
// 2. Replace this with the actual task ID.
const taskId = "a8532587-fa8c-4ef8-82be-xxxxxx";
// 3. Prepare the request.
const url = `https://dashscope.aliyuncs.com/api/v1/tasks/${taskId}`;
const headers = {
'Authorization': `Bearer ${apiKey}`
};
// 4. Send a GET request.
fetch(url, {
headers: headers
})
.then(response => response.json())
.then(data => {
// 5. Print the response.
console.log(data);
});
Parâmetros de resposta
|
Parâmetro |
Tipo |
Descrição |
|
|
string |
ID exclusivo da solicitação para rastreamento e solução de problemas. |
|
|
object |
Informações de saída da tarefa. |
|
|
string |
ID da tarefa consultada. Exemplo: |
|
|
string |
Status atual da tarefa. Consulte Exemplos de resposta. |
|
|
string |
Horário em que a tarefa foi enviada (UTC+8). Exemplo: |
|
|
string |
Horário em que a tarefa foi agendada para iniciar (UTC+8). Exemplo: |
|
|
string |
Horário em que a tarefa foi concluída (UTC+8). Exemplo: |
|
|
object |
Resultado da execução da tarefa. Presente quando |
|
|
string |
URL do vídeo gerado, válida por 24 horas após a conclusão da tarefa. Baixe e salve prontamente. Exemplo: |
|
|
string |
Código de erro. Presente quando |
|
|
string |
Mensagem de erro. Presente quando |
|
|
object |
Informações de uso de recursos. Presente quando |
|
|
float |
Duração do vídeo gerado, em segundos. Exemplo: |
|
|
string |
Proporção do vídeo gerado. Valor: |
Valores de status da tarefa
|
Status |
Descrição |
|
|
A tarefa está na fila, aguardando processamento. |
|
|
A tarefa está sendo processada. |
|
|
Tarefa concluída com sucesso. A |
|
|
Falha na tarefa. Verifique |
|
|
A tarefa foi cancelada. |
|
|
A tarefa não existe ou o status não pode ser determinado. Retornado quando o |
Exemplos de resposta
Exemplo de resposta de sucesso
{
"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"
}
}
Exemplo de resposta de erro
{
"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"
}
Faturamento e limites de taxa
Preços
O modelo emo-v1 utiliza faturamento conforme o uso, baseado na duração do vídeo gerado.
|
Proporção |
Resolução |
Preço unitário |
|
1:1 |
512 x 512 |
USD 0,011469 por segundo |
|
3:4 |
512 x 704 |
USD 0,022937 por segundo |
Exemplos de custo:
Um vídeo de 10 segundos com proporção 1:1 custa aproximadamente USD 0,11.
Um vídeo de 30 segundos com proporção 3:4 custa aproximadamente USD 0,69.
Limites de taxa
|
Tipo de limite |
Valor |
|
QPS para envio de tarefas |
5 |
|
Tarefas simultâneas |
1 (tarefas excedentes entram na fila) |
|
QPS para consulta de tarefas |
20 |
Códigos de erro
Para códigos de erro comuns e códigos de status, consulte Mensagens de erro.
Áudio de voz: (áudio de exemplo)