Todos os produtos
Search

Este produto

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

    Central de documentação

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

    Última atualização: Jun 29, 2026

    O modelo emoji-v1 gera vídeos de emojis faciais a partir de imagens de retrato e IDs de modelo predefinidos.

    Importante

    Este documento se aplica apenas à região China (Beijing). Para utilizar o modelo, é necessário usar uma chave de API da região China (Beijing).

    Visão geral do modelo

    Modelo

    Descrição

    emoji-v1

    Gera vídeos faciais a partir de imagens de retrato utilizando coordenadas faciais, coordenadas da área de expressão dinâmica e IDs de modelo.

    Pré-requisitos

    1. Obtenha uma chave de API e exporte a chave de API como uma variável de ambiente.

    2. Processe a imagem de entrada usando a Detecção de imagem Emoji para obter as coordenadas da área facial e da área de expressão dinâmica. Essas coordenadas são obrigatórias como parâmetros de entrada.

    HTTP

    A geração de vídeo geralmente leva de 1 a 5 minutos, portanto a API utiliza invocação assíncrona. Crie uma tarefa e, em seguida, consulte os resultados periodicamente.

    O tempo de processamento varia conforme o tamanho da fila e o status do serviço. Aguarde a conclusão da tarefa.

    Etapa 1: Crie uma tarefa e obter o ID da tarefa

    POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

    Parâmetros da requisição

    Gerar um vídeo Emoji

    curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--data '{
    "model": "emoji-v1",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250912/uopnly/emoji-%E5%9B%BE%E5%83%8F%E6%A3%80%E6%B5%8B.png",
        "driven_id": "mengwa_kaixin",
        "face_bbox": [212.194.460.441],
        "ext_bbox": [63.30.609.575]
    }
}'
    Headers

    Content-Type string (Required)

    O tipo de conteúdo da requisição. Deve ser application/json.

    Authorization string (Required)

    Autentica a requisição com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.

    X-DashScope-Async string (Required)

    Ative o processamento assíncrono. Requisições HTTP suportam apenas chamadas assíncronas. O valor deve ser enable.

    Importante

    Se este header de requisição estiver ausente, o erro "current user api does not support synchronous calls" será retornado.
    Request body

    model string (Required)

    Nome do modelo. Defina este parâmetro como emoji-v1.

    input object (Required)

    Informações básicas de entrada, como imagem facial, área facial e área do emoji.

    Properties

    image_url string (Required)

    URL pública de uma imagem facial frontal. Protocolos HTTP e HTTPS são suportados.

    Requisitos da imagem:

    • Formato: JPEG, JPG, PNG, BMP ou WEBP.

    • Resolução: A largura e a altura devem estar entre 400 e 7.000 pixels.

    • Tamanho do arquivo: Não superior a 10 MB.

    • A imagem deve passar na Detecção de imagem Emoji.

    Exemplo: https://help-static-aliyun-doc.aliyuncs.com/xxx.png.

    face_bbox array of integer (Required)

    Coordenadas da área facial na imagem. O formato é [x1, y1, x2, y2] em pixels (pontos superior esquerdo e inferior direito).

    Defina este parâmetro com o valor do campo output.bbox_face obtido na resposta da API de Detecção de Imagem Emoji.

    Exemplo: [212.194.460.441].

    ext_bbox array of integer (Required)

    Coordenadas da área de expressão dinâmica. A proporção é de aproximadamente 1:1. O formato é [x1, y1, x2, y2] em pixels (pontos superior esquerdo e inferior direito).

    Defina este parâmetro com o valor do campo output.ext_bbox_face na resposta da API de Detecção de imagem Emoji.

    Exemplo: [63.30.609.575].

    Nota: A área de expressão dinâmica é a região quadrada em que o modelo se concentra durante a geração do vídeo. Geralmente é ligeiramente maior que a área facial, incluindo fundo e ombros para garantir uma animação natural.

    driven_id string (Required)

    ID do modelo predefinido. Para consultar a lista de valores válidos, veja Apêndice: Lista de IDs de modelos.

    Exemplo: mengwa_kaixin.

    Parâmetros de resposta

    Resposta bem-sucedida

    Salve o task_id para consultar o status e o resultado da tarefa.

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

    Resposta de erro

    Falha na criação da tarefa. Consulte Códigos de erro.

    {
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

    output object

    Status e resultados da tarefa.

    Properties

    task_id string

    ID da tarefa. Válido para consultas por 24 horas.

    task_status string

    Status atual da tarefa.

    Enumeration values

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: A tarefa não existe ou seu status é desconhecido.

    request_id string

    Identificador único da requisição para rastreamento e solução de problemas.

    code string

    Código de erro. Retornado apenas para requisições com falha. Consulte Códigos de erro.

    message string

    Mensagem de erro detalhada. Retornada apenas para requisições com falha. Consulte Códigos de erro.

    Etapa 2: Consultar o resultado pelo ID da tarefa

    GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

    Nota

    • Recomendação de consulta periódica: A geração de vídeo leva vários minutos. Utilize um mecanismo de consulta com intervalo razoável, como 15 segundos.

    • Transição de estado da tarefa: PENDING → RUNNING → SUCCEEDED ou FAILED.

    • Link do resultado: Após o sucesso da tarefa, uma URL de vídeo válida por 24 horas é retornada. Baixe e salve o vídeo em armazenamento permanente, como o OSS.

    • Validade do task_id: 24 horas**. Após esse período, as consultas retornam o status da tarefa como UNKNOWN.

    Parâmetros da requisição

    Consultar resultados da tarefa

    Substitua 86ecf553-d340-4e21-xxxxxxxxx pelo seu task_id real.

    As chaves de API são diferentes para cada região. Para mais informações, consulte Obter uma chave de API.
    Se você usar um modelo na região China (Beijing), substitua base_url por https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx, onde WorkspaceId é o ID real do seu workspace.
    curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"
    Headers

    Authorization string (Required)

    Autentica a requisição com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
    Parâmetros de caminho da URL

    task_id string (Required)

    ID da tarefa.

    Parâmetros de resposta

    Tarefa bem-sucedida

    As URLs de vídeo são válidas apenas por 24 horas e depois são removidas automaticamente. Salve os vídeos gerados prontamente.

    {
    "request_id": "ad225054-6c94-47e5-9356-xxxxxxx",
    "output": {
        "task_id": "b56f509a-3ea9-4cfe-848d-xxxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-10-14 11:28:04.372",
        "scheduled_time": "2025-10-14 11:28:04.400",
        "end_time": "2025-10-14 11:29:03.924",
        "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xx.mp4?Expires=xxx"
    },
    "usage": {
        "video_duration": 2,
        "video_ratio": "standard"
    }
}

    Falha na tarefa

    Quando uma tarefa falha, task_status é FAILED com um código e mensagem de erro. Consulte Códigos de erro.

    {
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

    Consulta de tarefa expirada

    O task_id é válido por 24 horas. Após esse período, as consultas retornam o seguinte erro.

    {
        "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
        "output": {
            "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
            "task_status": "UNKNOWN"
        }
    }

    output object

    Status e resultados da tarefa.

    Properties

    task_id string

    ID da tarefa. Válido para consultas por 24 horas.

    task_status string

    Status atual da tarefa.

    Enumeration values

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: A tarefa não existe ou seu status é desconhecido.

    Transições de estado durante a consulta periódica:

    • PENDING → RUNNING → SUCCEEDED ou FAILED.

    • O status inicial da consulta geralmente é PENDING ou RUNNING.

    • Quando o status muda para SUCCEEDED, a resposta contém a URL do vídeo gerado.

    • Se o status for FAILED, verifique a mensagem de erro e tente executar a tarefa novamente.

    submit_time string

    Horário em que a tarefa foi enviada. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    Horário em que a tarefa foi executada. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    Horário em que a tarefa foi concluída. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.

    video_url string

    URL do vídeo gerado. Retornada apenas quando task_status é SUCCEEDED.

    Válida por 24 horas. O vídeo está no formato MP4 com codificação H.264.

    code string

    Código de erro. Retornado apenas para requisições com falha. Consulte Códigos de erro.

    message string

    Mensagem de erro detalhada. Retornada apenas para requisições com falha. Consulte Códigos de erro.

    usage object

    Estatísticas de uso de saída (apenas tarefas bem-sucedidas).

    Properties

    video_duration integer

    Duração do vídeo gerado em segundos.

    Faturamento: Custo = Duração do vídeo (segundos) × Preço unitário.

    video_ratio string

    Proporção do vídeo. Fixa em standard (1:1).

    request_id string

    Identificador único da requisição para rastreamento e solução de problemas.

    Faturamento e limitação de taxa

    Códigos de erro

    Se uma chamada de modelo falhar, consulte Códigos de erro para resolver o problema.

    Apêndice: Lista de IDs de modelos

    Exemplo: { "input": { "driven_id": "mengwa_kaixin" } }.

    Nota

    • Pré-visualização dos efeitos gerados pelo aplicativo Tongyi (integra o modelo Emoji).

    • Os vídeos gerados não incluem adesivos ou sobreposições de texto.

    ID do Modelo (driven_id)

    Prévia do efeito

    ID do Modelo (driven_id)

    Prévia do efeito

    mengwa_kaixin

    1_mengwa_kaixin

    dagong_zhuakuang

    10_dagong_zhuakuang

    mengwa_dengyan

    7_mengwa_dengyan

    dagong_wunai

    15_dagong_wunai

    mengwa_gandong

    16_mengwan_gandong

    dagong_weixiao

    17_dagong_weixiao

    mengwa_renzhen_1

    18_mengwa_renzhen_1

    dagong_ganji

    20_dagong_ganji

    mengwa_jidong

    8_mengwa_jidong

    jingdian_tiaopi

    4_jingdian_tiaopi

    mengwa_kun_1

    11_mengwa_kun_1

    jingdian_deyi_1

    5_jingdian_deyi_1

    mengwa_jiaoxie

    19_mengwa_renzhen_1

    jingdian_qidai

    6_jingdian_qidai

    dagong_kaixin

    2_dagong_kaixin

    jingdian_landuo_1

    12_jingdian_landuo_1

    dagong_yangwang

    3_dagong_yangwang

    jingdian_xianqi

    13_jingdian_xianqi

    dagong_kunhuo

    9_dagong_kunhuo

    jingdian_lei

    14_jingdian_lei