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

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.

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

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

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

Cabeçalhos da solicitação

Corpo da solicitação

Parâmetros de entrada

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

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

Exemplos de resposta

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

{
    "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: PENDING → RUNNING → SUCCEEDED 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

Parâmetros de caminho da URL

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

Valores de status da tarefa

Exemplos de resposta

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

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

• 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

Códigos de erro

Para códigos de erro comuns e códigos de status, consulte Mensagens de erro.