Blogue

Tutorial

Tutorial da API muse-video-1.0 de imagem para vídeo: curl e Python Requests

Nov 13, 2026
Arte de capa do tutorial do muse-video-1.0: corte transversal mineral facetado em plano, em verde-azulado sobre um fundo verde-petróleo profundo.
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-video pela 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, requests ou um cliente assíncrono — sem reescrever a lógica.
  • Leia a chave do ambiente. os.environ manté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_attempts transforma 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 de input, 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

  1. Confirme que a URL da imagem carrega no navegador.
  2. Envie um payload mínimo com apenas a imagem, para isolar problemas de parâmetros.
  3. Verifique se o job ID retorna de forma limpa.
  4. Faça polling manual primeiro, observando as transições de estado.
  5. 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 →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API