O modelo de reference-to-video do HappyHorse permite fornecer várias imagens de referência e um prompt de texto para gerar um vídeo que combina os elementos das imagens em uma cena baseada no prompt.
Observações de uso
Para garantir chamadas de API bem-sucedidas, use um modelo, uma URL de endpoint e uma chave de API pertencentes à mesma região. Chamadas entre regiões falharão.
- Selecione um modelo: Confirme a região onde seu modelo está localizado.
- Selecione uma URL: Escolha a URL de endpoint correspondente. URLs HTTP e DashScope SDK são suportadas.
- Configure uma chave de API: Selecione uma região, obtenha uma chave de API e, em seguida, configure a chave de API como variável de ambiente.
O código de exemplo neste tópico aplica-se à região Singapore.
Chamadas HTTP
Como as tarefas de reference-to-video consomem tempo (geralmente de 1 a 5 minutos), a API utiliza chamada assíncrona. O fluxo de trabalho consiste em duas etapas principais: "Crie uma tarefa -> Consulte 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{WorkspaceId} pelo seu workspace ID real.
- Após criar a tarefa, use o
task_idretornado para consultar o resultado. Otask_idé válido por 24 horas. Não crie tarefas duplicadas. Em vez disso, utilize polling para recuperar o resultado. - Para orientações destinadas a iniciantes, consulte Chamar APIs com Postman ou cURL.
Parâmetros da solicitação |
| |||||||||
Cabeçalhos da solicitação | ||||||||||
Content-Type string (Obrigatório)O 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 suportam apenas chamadas assíncronas. Deve ser enable. | ||||||||||
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-r2v. | ||||||||||
input object (Obrigatório)Entrada do modelo, incluindo as imagens de referência e o prompt de texto.
Propriedades prompt string (Obrigatório)Descrição dos elementos desejados e do estilo visual para o vídeo gerado.Entrada em qualquer idioma é suportada. O limite é de 5.000 caracteres não chineses ou 2.500 caracteres chineses. Conteúdo excedente será truncado automaticamente.Referência de imagem: No prompt, use "[Image 1]" e "[Image 2]" para referenciar a imagem correspondente no array media. A ordem deve corresponder à ordem no array media. Ao usar uma referência, especifique o objeto na imagem, como "a mulher de qipao vermelho em [Image 1]".media array (Obrigatório)Lista de imagens de referência.Cada elemento no array é um objeto de mídia contendo os campos type e url.
Propriedades do elemento type string (Obrigatório)Tipo de ativo de mídia. Defina como:
string (Obrigatório)URL ou dados codificados em Base64 de uma imagem de referência.Requisitos da imagem:
| ||||||||||
parameters object (Opcional)Parâmetros para geração de vídeo, como resolução, proporção de tela e duração.
Propriedades resolution string (Opcional)Categoria de resolução do vídeo gerado.Valores válidos:
string (Opcional)Proporção de tela do vídeo gerado.Valores válidos:
integer (Opcional)Duração do vídeo gerado, em segundos.Intervalo de valores: Número inteiro de 3 a 15.Valor padrão: 5.watermark boolean (Opcional)Define se uma marca d'água será adicionada ao vídeo gerado. A marca d'água fica posicionada no canto inferior direito com o texto fixo "Happy Horse".
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 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 da resposta |
Salve o task_id para consultar o status e o resultado da tarefa. |
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
| |
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 Códigos de erro. | |
message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro. |
Etapa 2: Obter o resultado 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 pode levar vários minutos. Implemente um mecanismo de polling com intervalo de consulta razoável (por exemplo, 15 segundos) para recuperar o resultado.
- Fluxo de status da tarefa: PENDING (Na fila) → RUNNING (Processando) → SUCCEEDED (Bem-sucedido) ou FAILED (Falhou).
- Validade do ID da tarefa: O ID da tarefa é válido por 24 horas. Após esse período, não é mais possível consultar o resultado, e a API retorna status de tarefa
UNKNOWN.
Parâmetros da solicitação |
Substitua {task_id} pelo valor 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. |
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 da URL | |
task_id string (Obrigatório)ID da tarefa. |
Parâmetros da resposta |
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. |
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
stringHorá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 stringHorá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 stringHorá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 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 Códigos de erro.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro. | |
usage objectEstatísticas de uso da tarefa. A cobrança ocorre apenas para tarefas bem-sucedidas.
Propriedades duration integerDuração faturável do vídeo gerado, em segundos.input_video_duration integerDuração total do vídeo de entrada, em segundos. Este valor é sempre 0 para tarefas de reference-to-video.output_video_duration integerDuração total do vídeo de saída, em segundos.ratio stringProporção de tela do vídeo gerado.SR integerCategoria de resolução do vídeo gerado.video_count integerNúmero de vídeos gerados. Este valor é sempre 1. | |
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas. |