Skip to main content
HappyHorse

Referência da API de imagem para vídeo (primeiro quadro) do HappyHorse

Gere vídeos realistas com movimentos fluidos a partir de uma imagem de primeiro quadro e um prompt de texto opcional usando o modelo HappyHorse.

Observações de uso

O modelo, a URL do endpoint e a chave de API devem pertencer à mesma região. Chamadas entre regiões falham.
  • Selecione um modelo: Verifique a qual região o modelo pertence.
  • Selecione uma URL: Escolha a URL do endpoint correspondente à mesma região.
  • Configure uma chave de API: Obtenha uma API key para a mesma região e configure the API key as an environment variable.
O código de exemplo neste tópico aplica-se à região Singapore.
O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Beijing): de https://dashscope.aliyuncs.com para https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de https://dashscope-intl.aliyuncs.com para https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} é o ID do seu workspace, disponível na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.

Chamadas HTTP

As tarefas de imagem para vídeo levam de 1 a 5 minutos. A API utiliza chamadas assíncronas: "Crie uma tarefa → consultar o resultado".

Etapa 1: Crie uma tarefa

  • Singapore
  • US (Virginia)
  • China (Beijing)
  • Germany (Frankfurt)
  • China (Hong Kong)
  • Japan (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Substitua {WorkspaceId} pelo seu workspace ID real.
  • Após criar a tarefa, use o task_id retornado para consultar o resultado. O task_id é válido por 24 horas. Não crie tarefas duplicadas. Em vez disso, faça consultas periódicas para obter o resultado.
  • Para orientações destinadas a iniciantes, consulte Call APIs with Postman or cURL.

Parâmetros da solicitação

  • Imagem para vídeo
# The following URLs are for the Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
    curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
        -H 'X-DashScope-Async: enable' \
        -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{
        "model": "happyhorse-1.1-i2v",
        "input": {
            "prompt": "A cat running on the grass",
            "media": [
                {
                    "type": "first_frame",
                    "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
                }
            ]
        },
        "parameters": {
            "resolution": "720P",
            "duration": 5
        }
    }'
Content-Type string (Obrigatório)Tipo de conteúdo da solicitação. Deve ser application/json.
Authorization string (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
X-DashScope-Async string (Obrigatório)Ative o processamento assíncrono. Solicitações HTTP aceitam apenas chamadas assíncronas. O valor deve ser enable.
Se este cabeçalho de solicitação estiver ausente, o erro "current user api does not support synchronous calls" será retornado.
Corpo da solicitação
model string (obrigatório)Nome do modelo. Para ver os modelos disponíveis, consulte o console do Model Studio.Exemplo: happyhorse-1.1-i2v.
input object (obrigatório)Entrada do modelo, incluindo o prompt de texto.

Propriedades

prompt string (opcional)Descreve o conteúdo do vídeo a gerar.Aceita qualquer idioma. Máximo: 5.000 caracteres não chineses ou 2.500 caracteres chineses. Entradas mais longas são truncadas.media array (obrigatório)Array de imagens de entrada.

Propriedades do elemento media[]

type string (obrigatório)Tipo de mídia. Valor permitido:
  • first_frame: Primeiro quadro.
É necessária exatamente uma imagem de primeiro quadro.url string (obrigatório)URL da mídia.

Imagem de entrada (type=first_frame)

URL ou dados codificados em Base64 da imagem do primeiro quadro.Restrições da imagem:
  • Formatos: JPEG, JPG, PNG, WEBP.
  • Resolução: Largura e altura devem ter pelo menos 300 pixels.
  • Proporção: Entre 1:2,5 e 2,5:1.
  • Tamanho do arquivo: Até 20 MB.
Formatos de entrada compatíveis:
  1. URL pública:
  2. String de imagem codificada em Base64:
    • Formato: data:{MIME_type};base64,{base64_data}.
    • Exemplo: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (truncado para exibição).

      Formato de codificação Base64

      Formato: data:{MIME_type};base64,{base64_data} .
      • {base64_data}: String codificada em Base64 do arquivo de imagem.
      • {MIME_type}: Tipo de mídia da imagem, que deve corresponder ao formato do arquivo.

      Formato da imagem

      Tipo MIME

      JPEG

      image/jpeg

      JPG

      image/jpeg

      PNG

      image/png

      WEBP

      image/webp

parameters object (opcional)Configurações de saída do vídeo, como resolução e duração.

Propriedades

resolution string (opcional)Resolução do vídeo gerado.A contagem de pixels de saída aproxima-se do nível selecionado, preservando a proporção da imagem de entrada.Valores permitidos:
  • 480P
  • 720P
  • 1080P (Padrão)
duration integer (opcional)Duração do vídeo gerado, em segundos.O valor deve ser um número inteiro no intervalo [3, 15]. Padrão: 5.watermark boolean (opcional)Adiciona uma marca d'água de texto "Happy Horse" no canto inferior direito.
  • true (Padrão)
  • false
seed integer (Opcional)A semente de número aleatório deve ser um inteiro no intervalo [0, 2147483647].Se não especificada, uma semente aleatória é gerada. Uma semente fixa melhora a reprodutibilidade.Como a geração do modelo é probabilística, a mesma semente não garante resultados idênticos.

Parâmetros da resposta

  • Resposta bem-sucedida
  • Resposta de erro
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"
    }
output objectSaída da tarefa.

Propriedades

task_id stringID da tarefa. Válido para consultas por 24 horas.task_status stringStatus da tarefa.

Valores de enumeração

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: A tarefa não existe ou seu status é desconhecido.
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas.
code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Error codes.
message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Error codes.

Etapa 2: Consultar o resultado

  • Singapore
  • US (Virginia)
  • China (Beijing)
  • Germany (Frankfurt)
  • China (Hong Kong)
  • Japan (Tokyo)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Recomendação de consulta: A geração de vídeo leva vários minutos. Use um mecanismo de consulta periódica com um 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 solicitação

  • Consultar resultado da tarefa
Substitua {task_id} pelo valor de task_id retornado pela chamada de API anterior. O task_id é válido para consultas por 24 horas. Substitua {WorkspaceId} pelo seu workspace ID real.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"
Cabeçalhos da solicitação
Authorization string (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
Parâmetros de caminho
task_id string (Obrigatório)ID da tarefa.

Parâmetros da resposta

  • Tarefa bem-sucedida
  • Tarefa falhou
  • Consulta de tarefa expirada
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": "8ae698ba-df2d-966c-abcf-xxxxxx",
    "output": {
        "task_id": "e56d806f-76f9-4037-aefa-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-20 19:33:50.425",
        "scheduled_time": "2026-04-20 19:33:50.463",
        "end_time": "2026-04-20 19:35:34.216",
        "orig_prompt": "A cat running on the grass",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720
    }
}
outputobjectSaída da tarefa.

Propriedades

task_id stringID da tarefa. Válido para consultas por 24 horas.task_status stringStatus da tarefa.

Valores de enumeração

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: A tarefa não existe ou seu status é desconhecido.
Transições de estado durante a consulta:
  • 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 stringHora em que a tarefa foi enviada. A hora está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringHora em que a tarefa foi executada. A hora está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.end_time stringHora em que a tarefa foi concluída. A hora está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.video_urlstringRetornado apenas quando task_status é SUCCEEDED.A URL é válida por 24 horas. Baixe o vídeo MP4 (24 fps, codificado em H.264) desta URL.orig_prompt stringPrompt de entrada original, correspondente ao parâmetro de solicitação prompt.code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Error codes.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Error codes.
usage objectEstatísticas de uso. Calculadas apenas para tarefas bem-sucedidas.

Propriedades

input_video_duration integerDuração do vídeo de entrada, em segundos.output_video_duration integerDuração do vídeo de saída, em segundos.duration integerDuração total do vídeo usada para faturamento.SR integerResolução do vídeo de saída.video_count integerNúmero de vídeos de saída. Este valor é sempre 1.
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas.

Códigos de erro

Se uma chamada falhar, consulte a referência de error messages.

FAQ

Proporção do vídeo

A proporção de saída corresponde à do primeiro quadro. Ao contrário do modelo HappyHorse text-to-video, a função de imagem para vídeo não aceita o parâmetro ratio.
Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais