Skip to main content
HappyHorse

Referência da API de texto para vídeo do HappyHorse

Gere vídeos fisicamente realistas e com movimentos suaves a partir de prompts de texto usando o modelo HappyHorse.

Disponibilidade

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: Use a URL do endpoint correspondente à região. Há suporte para HTTP.
  • Configure uma chave de API: Obtenha uma API key para a região e, em seguida, Export API key as environment variable.
Os códigos de exemplo neste tópico aplicam-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.

Solicitação HTTP

As tarefas de texto para vídeo geralmente levam de 1 a 5 minutos. A API usa chamadas assíncronas em duas etapas: "Crie uma tarefa → Consultar resultados".

Etapa 1: Crie uma tarefa e obter o ID da 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, use polling para recuperar o resultado.
  • Para orientações destinadas a iniciantes, consulte Call APIs with Postman or cURL.

Parâmetros da solicitação

  • Texto para vídeo
# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual 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-t2v",
        "input": {
            "prompt": "A miniature city built from cardboard and bottle caps comes to life at night. A cardboard train slowly passes through, with small lights dotting the scene and illuminating the way ahead."
        },
        "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "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-t2v.
input object (Obrigatório)Entrada do modelo.

Propriedades

prompt string (Obrigatório)Descrição textual do vídeo a gerar.Aceita qualquer idioma. Máximo de 5.000 caracteres não chineses ou 2.500 caracteres chineses. O excesso é truncado.
parameters object (Opcional)Configurações de saída do vídeo (resolução, proporção, duração).

Propriedades

resolution string (Opcional)Resolução do vídeo de saída.Valores válidos:
  • 480P
  • 720P
  • 1080P (padrão)
ratio string (Opcional)Proporção de aspecto do vídeo de saída.Valores válidos:
  • 16:9 (padrão)
  • 9:16
  • 1:1
  • 4:3
  • 3:4
  • 4:5
  • 5:4
  • 9:21
  • 21:9
duration integer (Opcional)Duração do vídeo de saída em segundos.
  • happyhorse-1.0-t2v: 3–15. Padrão: 5.
watermark boolean (Opcional)Define se uma marca d'água deve ser adicionada. Exibe "HappyHorse" 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 objectInformações de saí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 único 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 pelo ID da tarefa

  • 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 polling: A geração de vídeo leva vários minutos. Use um mecanismo de consulta periódica 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 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
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 com falha
  • Consulta de tarefa expirada
As URLs de vídeo são válidas apenas por 24 horas e depois removidas automaticamente. Salve os vídeos gerados imediatamente.
{
    "request_id": "99243b47-ec5f-9413-9993-xxxxxx",
    "output": {
        "task_id": "4673458e-28be-4a05-bf2a-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-20 17:55:17.075",
        "scheduled_time": "2026-04-20 17:55:17.129",
        "end_time": "2026-04-20 17:56:36.658",
        "orig_prompt": "A miniature city built from cardboard and bottle caps comes to life at night. A cardboard train slowly passes through, with small lights dotting the scene and illuminating the way ahead.",
        "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,
        "ratio": "16:9"
    }
}
outputobjectInformações de saí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 o polling:
  • 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 stringMomento 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 stringMomento 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 stringMomento 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 stringURL 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.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 saída. Apenas tarefas bem-sucedidas são contabilizadas.

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 para faturamento.SR integerResolução do vídeo de saída.ratio stringProporção de aspecto do vídeo de saída.video_count integerNúmero de vídeos de saída. Sempre 1.
request_id stringIdentificador único da solicitação para rastreamento e solução de problemas.

Códigos de erro

Chamadas de API com falha retornam códigos de erro documentados em Error messages.
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