Skip to main content
HappyHorse

Referência da API de edição de vídeo HappyHorse

O modelo de edição de vídeo HappyHorse recebe um vídeo e uma imagem de referência como entrada e executa tarefas de edição, como transferência de estilo e substituição local, com base em instruções de texto.

Disponibilidade

Certifique-se de que o modelo, a URL do endpoint e a chave da API pertençam à mesma região. Chamadas entre regiões falharão.
  • Selecione um modelo: Verifique a qual região o modelo pertence.
  • Selecione uma URL: Use a URL do endpoint correspondente à região. URLs HTTP são suportadas.
  • Configure uma chave de API: Selecione uma região e Crie uma chave de API e, em seguida, Exporte a chave de API como variável de ambiente.
Os códigos de exemplo neste tópico aplicam-se à região Singapore.
O Alibaba Cloud Model Studio lançou domínios específicos para workspaces nas 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 edição de vídeo consomem tempo (geralmente de 1 a 5 minutos); portanto, a API utiliza chamadas assíncronas. O fluxo de trabalho possui duas etapas: "Criar uma tarefa -> Consultar o resultado", conforme descrito abaixo:

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

  • Singapore
  • US (Virginia)
  • China (Beijing)
  • Germany (Frankfurt)
  • 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 consultas periódicas (polling) para recuperar o resultado.
  • Para orientações destinadas a iniciantes, consulte Chame APIs com Postman ou cURL.

Parâmetros da solicitação

  • Edição de vídeo (instrução + imagem de referência)
# 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.0-video-edit",
    "input": {
        "prompt": "Make the horse-headed humanoid character in the video wear the striped sweater from the image",
        "media": [
            {
                "type": "video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260415/hynnff/wan-video-edit-clothes.webp"
            }
        ]
    },
    "parameters": {
        "resolution": "720P"
    }
}'
Headers
Content-Type string (Required)O tipo de conteúdo da solicitação. Deve ser application/json.
Authorization string (Required)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
X-DashScope-Async string (Required)Ativa o processamento assíncrono. Solicitações HTTP suportam apenas chamadas assíncronas. Deve ser enable.
Se este header de solicitação estiver ausente, a API retornará o erro "current user api does not support synchronous calls".
Corpo da solicitação
model string (Required)Nome do modelo.Valor fixo: happyhorse-1.0-video-edit.
input object (Required)Informações de entrada, incluindo o vídeo a editar, imagens de referência e o prompt.

Propriedades

prompt string (Required)Prompt de texto que descreve a edição desejada, como transferência de estilo ou substituição local.Suporta qualquer idioma. Máximo de 5.000 caracteres não chineses ou 2.500 caracteres chineses. O conteúdo excedente será truncado automaticamente.media array (Required)Lista de ativos de mídia, incluindo o vídeo a editar e imagens de referência opcionais.O array deve conter exatamente 1 elemento video e pode conter opcionalmente de 0 a 5 elementos reference_image.

Propriedades do elemento

type string (Required)Tipo de ativo de mídia. Deve ser um dos seguintes:
  • video: Obrigatório. O vídeo a editar.
  • reference_image: Opcional. Uma imagem de referência.
Limites de ativos:
  • Vídeos: exatamente 1.
  • Imagens de referência: 0–5.
url string (Required)URL do ativo de mídia.

Entrada de vídeo (type=video)

URL publicamente acessível do vídeo a editar.Requisitos do vídeo:
  • Formato: MP4, MOV (codificação H.264 recomendada).
  • Duração: 3–60 segundos.
  • Resolução: o lado maior não deve exceder 4.096 px; o lado menor deve ter pelo menos 360 px.
  • Proporção: 1:2,5–2,5:1.
  • Tamanho do arquivo: até 100 MB.
  • Taxa de quadros: superior a 8 fps.
Duração do vídeo de saída: 3–15 segundos.
  • Se o vídeo de entrada tiver 15 segundos ou menos, o vídeo de saída terá a mesma duração da entrada.
  • Caso o vídeo de entrada tenha mais de 15 segundos, o sistema usará automaticamente apenas os primeiros 15 segundos, limitando a duração máxima de saída a 15 segundos.

Entrada de imagem (type=reference_image)

URL ou dados codificados em Base64 da imagem de referência.Requisitos da imagem:
  • Formato: JPEG, JPG, PNG, WEBP.
  • Resolução: largura e altura devem ter pelo menos 300 px.
  • Proporção: 1:2,5–2,5:1.
  • Tamanho do arquivo: até 20 MB.
Formatos de entrada suportados:
  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 demonstração).

      Formato de dados 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 (Optional)Parâmetros de edição de vídeo, como resolução.

Propriedades

resolution string (Optional)Resolução do vídeo gerado.Valores válidos:
  • 1080P (padrão)
  • 720P
watermark boolean (Optional)Define se uma marca d'água será adicionada ao vídeo gerado. A marca d'água aparece no canto inferior direito com o texto "Happy Horse". O padrão é true.
  • true (padrão)
  • false
audio_setting string (Optional)Controle de áudio.
  • auto (padrão): Determinado pelo modelo.
  • origin: Preserva o áudio original do vídeo de entrada.
seed integer (Optional)A semente de número aleatório deve ser um inteiro no intervalo [0, 2147483647].Se não especificada, uma semente aleatória será 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 de 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 resultados pelo ID da tarefa

  • Singapore
  • US (Virginia)
  • China (Beijing)
  • Germany (Frankfurt)
  • Japan (Tokyo)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Consulta periódica (Polling): A edição de vídeo leva vários minutos. Use um mecanismo de polling com um intervalo razoável (por exemplo, 15 segundos) para verificar os resultados.
  • Fluxo de status da tarefa: PENDING (na fila) → RUNNING (processando) → SUCCEEDED / FAILED.
  • Expiração do task_id: O task_id expira após 24 horas. Após a expiração, não é mais possível recuperar os resultados e a API retorna o status de tarefa 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"
Headers
Authorization string (Required)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
Parâmetros de caminho
task_id string (Required)ID da tarefa.

Parâmetros de resposta

  • Tarefa bem-sucedida
  • Falha na tarefa
  • 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": "c11018a8-3f83-9591-a636-xxxxxx",
    "output": {
        "task_id": "051c7b40-b2c5-4341-aee4-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-26 14:13:14.373",
        "scheduled_time": "2026-04-26 14:13:14.419",
        "end_time": "2026-04-26 14:14:13.679",
        "orig_prompt": "Dress the horse-headed humanoid character in the video in the striped sweater from the image",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4"
    },
    "usage": {
        "duration": 13,24,
        "input_video_duration": 6,62,
        "output_video_duration": 6,62,
        "video_count": 1,
        "SR": 720
    }
}
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 stringHorário de envio da tarefa. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringHorário de execução da tarefa. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.end_time stringHorário de conclusão da tarefa. 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 uso. Conta apenas resultados bem-sucedidos.

Propriedades

duration floatDuração total do vídeo gerado, usada para faturamento.SR integerNível de resolução do vídeo gerado.output_video_duration floatDuração do vídeo de saída, em segundos.input_video_duration floatDuração do vídeo de entrada, em segundos.video_count integerNúmero de vídeos gerados. Sempre 1.
request_id stringIdentificador único da solicitação para rastreamento e solução de problemas.

Códigos de erro

Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Error codes para resolução.
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