Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Referência da API de geração de vídeo EMO

Última atualização: Jun 29, 2026

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.

Importante

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:

  1. Crie uma tarefa -- Envie uma imagem de retrato e um arquivo de áudio. Você recebe um task_id imediatamente.

  2. Consulte o resultado -- Verifique o status da tarefa usando o task_id. Quando o status for SUCCEEDED, 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: Portrait sample Áudio de voz: (áudio de exemplo)

Vídeo de saída de exemplo Intensidade do estilo de ação: style_level definido como active.

Para mais exemplos, consulte Demonstração de desempenho.

Nota

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

  1. Ative o serviço de modelo e crie uma chave de API, e depois exporte-a como uma variável de ambiente.

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

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

X-DashScope-Async

string

Obrigatório

Modo de processamento assíncrono. Defina como enable. As solicitações HTTP suportam apenas processamento assíncrono. Sem este cabeçalho, as solicitações falham com a mensagem "current user api does not support synchronous calls".

Authorization

string

Obrigatório

Credencial de autenticação no formato Bearer {API_KEY}, usando uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.

Content-Type

string

Obrigatório

Tipo de conteúdo da solicitação. Defina como application/json.

Corpo da solicitação

Parâmetro

Tipo

Obrigatório

Descrição

model

string

Obrigatório

Nome do modelo. Defina como emo-v1.

input

object

Obrigatório

Dados de entrada contendo a imagem, o áudio e as coordenadas da caixa delimitadora. Consulte Parâmetros de entrada.

parameters

object

Opcional

Configurações de geração. Consulte Objeto parameters.

Parâmetros de entrada

Parâmetro

Tipo

Obrigatório

Descrição

image_url

string

Obrigatório

URL da imagem de retrato. O modelo recorta a imagem usando ext_bbox. A proporção da área recortada determina a resolução do vídeo de saída. Consulte Requisitos de imagem.

audio_url

string

Obrigatório

URL do arquivo de áudio de voz para inferência do modelo EMO. Consulte Requisitos de áudio.

face_bbox

array

Obrigatório

Coordenadas da caixa delimitadora da área do rosto no formato [x1, y1, x2, y2] (cantos superior esquerdo e inferior direito). Obtenha esses valores do campo face_bbox na resposta da API de detecção de imagem EMO. Exemplo: [302, 286, 610, 593].

ext_bbox

array

Obrigatório

Coordenadas da caixa delimitadora da área dinâmica no formato [x1, y1, x2, y2] (cantos superior esquerdo e inferior direito). A proporção deve ser 1:1 ou 3:4. Obtenha esses valores do campo ext_bbox na resposta da API de detecção de imagem EMO. Exemplo: [71, 9, 840, 778].

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

style_level

string

Opcional

normal

Controla a amplitude de movimento do personagem. Valores permitidos: normal (movimento moderado), calm (movimento calmo), active (movimento ativo).

Requisitos de imagem

  • A proporção de ext_bbox define 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

output

object

Informações de saída da tarefa.

output.task_id

string

ID da tarefa assíncrona. Use este ID na Etapa 2 para consultar o resultado. Exemplo: a8532587-fa8c-4ef8-82be-xxxxxx.

output.task_status

string

Status da tarefa após o envio. Valor: PENDING.

request_id

string

ID exclusivo da solicitação para rastreamento e solução de problemas.

code

string

Código de erro. Retornado apenas quando a solicitação falha. Consulte Códigos de erro.

message

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 status UNKNOWN.

  • Fluxo de status da tarefa: PENDINGRUNNINGSUCCEEDED ou FAILED.

  • 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

Authorization

string

Obrigatório

Credencial de autenticação no formato Bearer {API_KEY}, usando uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.

Parâmetros de caminho da URL

Parâmetro

Tipo

Obrigatório

Descrição

task_id

string

Obrigatório

ID da tarefa da Etapa 1. Exemplo: a8532587-fa8c-4ef8-82be-xxxxxx.

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

request_id

string

ID exclusivo da solicitação para rastreamento e solução de problemas.

output

object

Informações de saída da tarefa.

output.task_id

string

ID da tarefa consultada. Exemplo: a8532587-fa8c-4ef8-82be-xxxxxx.

output.task_status

string

Status atual da tarefa. Consulte Exemplos de resposta.

output.submit_time

string

Horário em que a tarefa foi enviada (UTC+8). Exemplo: 2025-09-11 14:33:38.716.

output.scheduled_time

string

Horário em que a tarefa foi agendada para iniciar (UTC+8). Exemplo: 2025-09-11 14:33:53.089.

output.end_time

string

Horário em que a tarefa foi concluída (UTC+8). Exemplo: 2025-09-11 14:35:51.541.

output.results

object

Resultado da execução da tarefa. Presente quando task_status é SUCCEEDED.

output.results.video_url

string

URL do vídeo gerado, válida por 24 horas após a conclusão da tarefa. Baixe e salve prontamente. Exemplo: http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxxx.

output.code

string

Código de erro. Presente quando task_status é FAILED. Consulte Códigos de erro.

output.message

string

Mensagem de erro. Presente quando task_status é FAILED. Consulte Códigos de erro.

usage

object

Informações de uso de recursos. Presente quando task_status é SUCCEEDED.

usage.video_duration

float

Duração do vídeo gerado, em segundos. Exemplo: 13.93.

usage.video_ratio

string

Proporção do vídeo gerado. Valor: 1:1 ou 3:4.

Valores de status da tarefa

Status

Descrição

PENDING

A tarefa está na fila, aguardando processamento.

RUNNING

A tarefa está sendo processada.

SUCCEEDED

Tarefa concluída com sucesso. A video_url está disponível na resposta.

FAILED

Falha na tarefa. Verifique output.code e output.message para obter detalhes.

CANCELED

A tarefa foi cancelada.

UNKNOWN

A tarefa não existe ou o status não pode ser determinado. Retornado quando o task_id expirou (após 24 horas).

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.