Tutorial
Tutorial da API muse-video-1.0 de imagem para vídeo: curl e Python Requests
Nesta página
O que o endpoint muse-video-1.0 de imagem para vídeo exige
O endpoint muse-video-1.0/image-to-video converte uma única imagem estática em um vídeo curto. Antes de escrever a primeira linha de código, entender a estrutura da requisição ajuda você a montar o payload correto de primeira.
Em alto nível, uma chamada envolve quatro aspectos:
- Roteamento do modelo — você especifica o modelo como
muse-video-1.0/image-to-videopela API unificada da HiAPI. - Imagem de entrada — o quadro estático que serve de ponto de partida para a animação. Esta é a entrada criativa obrigatória.
- Opções de geração — o comportamento do áudio e o nível de duração, que moldam as características da saída, não o material de origem.
- Execução assíncrona — a geração não retorna o vídeo final de forma inline. Você envia a tarefa e depois faz polling para obter o resultado.
O último ponto é o que os desenvolvedores mais costumam ignorar. Como a renderização leva tempo, o endpoint funciona com base em tarefas: a chamada inicial confirma sua requisição e retorna um handle, e depois você acompanha com consultas de status até o vídeo ficar pronto. Projete seu cliente em torno desse fluxo de duas fases desde o início, em vez de adicionar o polling depois.
O corpo da requisição é JSON. Os campos são agrupados: a imagem fica em um bloco input separado, e o áudio e a duração ficam ao lado dele como configurações de geração. Mantenha esse modelo mental — entrada, opções e ciclo de vida da tarefa separados — e o restante do tutorial será direto.
Autenticação
Cada requisição é autenticada com sua chave de API da HiAPI, na forma de credencial bearer no cabeçalho Authorization. Trate a chave como confidencial: carregue-a de uma variável de ambiente, em vez de codificá-la em um script que você possa compartilhar.
export HIAPI_API_KEY="your_api_key_here"
Depois de exportar a chave, você tem tudo o que precisa para entender a requisição. As próximas seções montam o payload passo a passo.
Prepare e envie sua imagem do primeiro quadro
A imagem do primeiro quadro é a âncora criativa de toda a tarefa. O que você fornecer se tornará o quadro zero, e o modelo anima a partir dali. Acertar isso evita desperdício de gerações.
Dicas práticas para o quadro de origem
- Use uma imagem estática nítida e de alta qualidade. O que funciona bem como quadro único oferece ao modelo o melhor ponto de partida.
- Escolha uma proporção que corresponda à saída desejada. Imagens panorâmicas largas e imagens verticais altas geram composições muito diferentes, então defina a orientação antes de enviar de fato.
- Evite desfoque de movimento severo ou sujeito ambíguo. Imagens estáticas já visualmente estáveis geram animações mais previsíveis.
- Garanta que o arquivo esteja acessível no momento da requisição. Seja enviando uma URL ou um payload codificado, certifique-se de que a referência seja alcançável no instante do envio da tarefa.
Como a imagem entra na requisição
A imagem é fornecida no bloco input do corpo JSON. Uma entrada mínima de imagem fica assim:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
}
}
Se sua imagem de origem estiver armazenada localmente, hospede-a em um local acessível à requisição ou passe-a na forma codificada aceita pelo endpoint. A regra principal é: o valor em input.image deve resolver para conteúdo de imagem real no momento da criação da tarefa — links quebrados ou expirados falham no envio, não no polling, o que na prática é um sinal útil e precoce.
Valide antes de gerar
Uma verificação rápida de sanidade vale a pena: abra a URL da imagem no navegador, confirme que carrega e depois confirme que as dimensões se adequam à saída pretendida. Dois segundos de verificação aqui evitam uma depuração confusa mais tarde.
Com o primeiro quadro pronto e acessível, você pode seguir para as opções de geração.
Configure os parâmetros de áudio e o nível de duração
Além da imagem, muse-video-1.0/image-to-video oferece duas categorias de opções que alteram as características da saída: comportamento do áudio e duração.
Parâmetros de áudio
O áudio é representado por um campo no corpo da requisição, ao lado do seu input. Defina a intenção antes de chamar:
- Saída silenciosa — mantenha o áudio desativado se você planeja adicionar sua própria trilha na pós-produção ou precisa de uma faixa de vídeo limpa.
- Áudio ativado — ative o áudio se o clipe deve ter som próprio. Verifique explicitamente essa opção no payload, em vez de assumir o valor padrão.
Como o processamento de áudio é uma propriedade da própria requisição, e não uma etapa de pós-processamento, vale defini-lo antes de escalar. Se seu pipeline mistura clipes silenciosos e com áudio, modele essa escolha como um parâmetro explícito no seu próprio código de cliente, para que não aconteça por acidente.
Níveis de duração
O endpoint permite escolher um nível de duração para o clipe. Trate a duração como uma decisão consciente de criatividade e custo:
- Níveis mais curtos são adequados para prévias rápidas, clipes sociais e testes de storyboard, em que você quer feedback rápido sobre muitas imagens de origem.
- Níveis mais longos dão mais espaço para a animação se desenvolver, sendo melhores para planos principais ou sequências que precisam de respiro.
A duração é cobrada por segundos de saída, então o nível escolhido afeta diretamente o consumo. Não há vantagem em renderizar clipes longos só para uma verificação visual rápida — use níveis curtos ao iterar sobre o primeiro quadro e depois eleve as configurações vencedoras para níveis mais longos.
Monte essas opções juntas
Em JSON, as configurações de áudio e duração ficam ao lado do bloco input:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}
Use os identificadores exatos de nível fornecidos na documentação do endpoint, em vez de adivinhar valores. A próxima seção transforma isso em uma requisição executável.
Uma requisição curl funcional
Com o payload montado, aqui está o comando curl para o envio inicial. Ele cria a tarefa; não retorna o vídeo final.
curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}'
Algumas observações sobre o comando:
- A URL especifica o modelo pelo nome. Você não precisa de um cliente separado por modelo; o caminho já identifica
muse-video-1.0/image-to-video. - O cabeçalho carrega sua chave.
$HIAPI_API_KEYé expandida a partir da variável de ambiente que você exportou antes, então a chave nunca aparece no próprio script. - O corpo é o payload que você acabou de montar. A URL da imagem, o sinalizador de áudio e o nível de duração são enviados juntos.
A resposta é uma confirmação de tarefa: ela contém o identificador da tarefa que você acabou de criar. Copie esse identificador — ele será usado na etapa de polling. Se você estiver apenas explorando, pode formatar a resposta com uma ferramenta JSON para localizar o job ID mais facilmente.
Se o envio falhar, os erros costumam ser imediatos e específicos: corpo JSON malformado, referência de imagem ausente ou valores de opção não reconhecidos. Esse ciclo de feedback rápido é justamente o motivo para testar o envio isoladamente antes de conectar o polling.
A mesma requisição em Python
A maioria das integrações acaba em Python, então aqui está o envio equivalente usando a biblioteca padrão — sem SDK de terceiros.
import json
import os
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"
payload = {
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": True,
"duration": "<duration_tier>",
}
request = urllib.request.Request(
ENDPOINT,
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
result = json.loads(response.read().decode("utf-8"))
job_id = result["id"]
print("Submitted job:", job_id)
O script corresponde campo a campo à chamada curl. Alguns hábitos que vale cultivar:
- Mantenha o payload em um dicionário. Construí-lo como um dicionário Python significa que você pode alimentar a mesma estrutura a qualquer biblioteca HTTP —
urllib,requestsou um cliente assíncrono — sem reescrever a lógica. - Leia a chave do ambiente.
os.environmantém as credenciais fora do controle de versão. - Analise a resposta como JSON de imediato. Extrair o job ID para uma variável nomeada deixa a etapa de polling mais legível.
Se você preferir a biblioteca requests, a única mudança é a camada de transporte: construa o mesmo dicionário payload e envie com seu conjunto de cabeçalhos, depois chame .json() na resposta. O endpoint, os cabeçalhos e o corpo permanecem exatamente iguais.
Com a tarefa enviada e seu identificador capturado, o trabalho restante é esperar pelo resultado da maneira correta.
Faça polling da tarefa assíncrona e obtenha o vídeo
A geração de vídeo não é instantânea, então o endpoint é assíncrono. Após o envio, você consulta o status da tarefa para saber quando a renderização termina e então obtém a saída.
O loop de polling
Um loop robusto faz três coisas: espera entre verificações, define um limite para não rodar indefinidamente e distingue “ainda processando”, “concluído” e “falhou”.
import time
import urllib.request
STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"
def wait_for_video(job_id, max_attempts=60, interval=5):
for attempt in range(max_attempts):
url = STATUS_ENDPOINT.format(job_id=job_id)
request = urllib.request.Request(
url,
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(request) as response:
status = json.loads(response.read().decode("utf-8"))
state = status.get("status")
if state == "succeeded":
return status.get("output")
if state == "failed":
raise RuntimeError(f"Job {job_id} failed: {status}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} did not finish in time")
Pontos de design para produção
- Use um intervalo razoável. Cinco segundos é um bom ponto de partida; não martele o endpoint de status.
- Sempre limite o número de tentativas. O limite
max_attemptstransforma uma espera infinita em um erro claro que pode ser registrado e alertado. - Trate estados de falha explicitamente. Tarefas com falha trazem informações de diagnóstico — exponha-as, em vez de repetir silenciosamente a mesma entrada.
- Persista o job ID. Se seu processo reiniciar, você pode retomar o polling sem pagar por uma nova geração.
Obtenha a saída
Quando a tarefa é bem-sucedida, a resposta de status contém a referência de saída para o vídeo final. Baixe-o prontamente para seu próprio armazenamento, em vez de depender de um link válido por muito tempo. Depois de ter o arquivo localmente ou em um bucket, a geração está concluída do ponto de vista do pipeline.
Esse é todo o ciclo de vida: enviar, consultar, obter. Mantenha as duas fases separadas no código e cada uma permanecerá simples.
Armadilhas comuns e dicas de depuração
A maioria dos problemas de integração com muse-video-1.0/image-to-video se enquadra em algumas categorias. Aqui está o que verificar quando algo der errado.
Problemas com a entrada de imagem
- Referência de imagem inacessível. Se a URL exigir autenticação ou estiver expirada, a tarefa falhará no envio. Hospede o quadro em um local publicamente legível durante a requisição.
- Proporção incompatível. Forçar uma imagem estática vertical em uma saída horizontal causa cortes estranhos ou tarjas pretas. Defina a orientação da origem para corresponder ao destino.
- Conteúdo errado. É fácil apontar para uma miniatura ou imagem de placeholder em vez do quadro real. Verifique se a URL abre a imagem esperada.
Erros de parâmetros
- Adivinhar valores de duração. Use os identificadores exatos de nível fornecidos na documentação do endpoint. Valores não reconhecidos são uma causa comum de rejeição.
- Esquecer o sinalizador de áudio. Se você omitir a configuração de áudio mas esperar som, poderá obter um clipe silencioso. Seja explícito sobre precisar ou não de áudio.
- Confundir campos de nível superior com campos de input. A imagem fica dentro de
input; áudio e duração são irmãos deinput, não filhos. Aninhamento errado produz mensagens de validação confusas.
Erros de polling
- Tratar o envio como conclusão. A primeira resposta é apenas uma confirmação, não o vídeo. Sempre acompanhe com uma verificação de status.
- Polling ilimitado. Um loop sem limite travará seu worker se a tarefa estagnar. Adicione limites e erros de timeout.
- Ignorar falhas. Tarefas que terminam com estado de falha nunca produzirão vídeo; capture isso e inspecione o diagnóstico, em vez de continuar esperando.
- Esperar muito com entrada errada. Se a renderização continua falhando, pare de gerar novamente. Corrija primeiro o quadro de origem ou os parâmetros e depois reenvie.
Uma ordem de depuração eficaz
- Confirme que a URL da imagem carrega no navegador.
- Envie um payload mínimo com apenas a imagem, para isolar problemas de parâmetros.
- Verifique se o job ID retorna de forma limpa.
- Faça polling manual primeiro, observando as transições de estado.
- Só depois automatize o loop, adicionando novas tentativas para erros de rede transitórios.
Tratar essas etapas em ordem reduz rapidamente o problema a uma camada — imagem, opções ou ciclo de vida — e mantém a integração avançando. Entendendo a estrutura da requisição, as opções e o fluxo de polling, você está pronto para construir para esse endpoint.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio