Tutorial
Chamar muse-video-1.0/text-to-video pela API HiAPI: guia com curl e Python
Campos da requisição, consulta assíncrona e exemplos de requisição executáveis
Nesta página
Antes de enviar: autenticação, endpoint e identificador do modelo
muse-video-1.0/text-to-video converte prompts de texto em clipes de vídeo gerados. Você envia um prompt e alguns parâmetros de controle, o serviço renderiza o clipe e então retorna uma URL ou referência para download.
O detalhe arquitetural crítico: esta chamada é assíncrona. A renderização de vídeo leva tempo, e a API não mantém a sua conexão HTTP aberta até o arquivo ficar pronto. Por isso o fluxo se divide em duas fases:
- Envio — você faz POST do prompt e dos parâmetros. A resposta volta rapidamente, com um identificador de tarefa e o estado inicial da tarefa.
- Consulta periódica — você faz GET da tarefa pelo identificador em intervalos regulares, até o estado mudar para um estado terminal (sucesso ou falha), e então obtém o resultado.
Esse formato de "enviar primeiro, consultar depois" é o ponto mais importante a internalizar antes de escrever código. Ele muda a estrutura da aplicação: o vídeo não aparece na resposta do envio, e qualquer erro que você encontre pertence a uma fase específica — envio, validação, renderização ou obtenção. Separar essas fases no seu próprio código (com funções distintas e logs separados) tornará o restante deste guia mais fácil de aplicar.
A string do modelo enviada deve ser exata: muse-video-1.0/text-to-video. O formato vendor/model é a convenção comum dos endpoints de modelos da HiAPI, e é com base nele que o roteamento da API determina qual gerador será chamado.
Montar a requisição: prompt, duração e campos de áudio
Antes da primeira requisição, três coisas precisam estar prontas.
Chave de API
Toda requisição precisa ser autenticada por bearer token. Guarde-o em uma variável de ambiente, e não no código-fonte, para evitar vazamentos em commits:
export HIAPI_API_KEY="your_key_here"
Envie-o no cabeçalho Authorization: Bearer $HIAPI_API_KEY. Se a requisição falhar com erro de autenticação, verifique primeiro esse cabeçalho — erros de digitação no nome da variável, espaços no final ou valor não definido no shell atual são as causas mais comuns.
URL base
Todas as chamadas compartilham uma única URL base da plataforma HiAPI. Use o valor atual do painel da sua conta ou da referência da API, e não copie de trechos de código antigos; guarde-o em uma variável para precisar alterar em apenas um lugar.
Identificador do modelo
A string do modelo é muse-video-1.0/text-to-video. Trate-a como um literal sensível a maiúsculas e minúsculas. Não monte nem adivinhe variantes, como diferenças de caixa ou sufixos ausentes — um identificador de modelo desconhecido gera erro de validação, não um fallback.
Com esses três elementos prontos, você pode montar o corpo da requisição.
Uma requisição curl funcional
O corpo da requisição é JSON. Conceitualmente, ele contém três grupos de campos.
Prompt
O prompt é a instrução criativa e determina a maior parte da qualidade da saída. Um prompt eficaz descreve especificamente o sujeito, a ação, o comportamento de câmera, a iluminação e o estilo, em vez de acumular apenas adjetivos. É um campo de string comum.
Duração
Modelos de texto para vídeo precisam saber quanto tempo o clipe deve durar. A duração é um campo da requisição e também afeta o custo: a geração é cobrada por segundos de saída. Como a faixa aceitável e o valor padrão são definidos pelo modelo em determinado momento, leia da referência ao vivo da API de muse-video-1.0/text-to-video os nomes exatos dos campos e valores permitidos, sem adivinhar. Enviar uma duração fora da faixa causa falha de validação.
Áudio
muse-video-1.0/text-to-video também oferece controles relacionados a áudio além da geração visual. Estes também são campos da requisição — normalmente chaves de ativação ou entradas no estilo de prompt de áudio — cujos nomes exatos e valores aceitáveis estão documentados na mesma referência da API. Na primeira integração, a abordagem conservadora é omitir completamente os campos opcionais de áudio, confirmar que o vídeo é retornado com sucesso e só então adicionar as opções de áudio uma a uma.
Assim, o corpo mínimo da requisição é aproximadamente este (nomes de campos apenas ilustrativos — confirme na referência):
{
"model": "muse-video-1.0/text-to-video",
"prompt": "Ao amanhecer, um movimento aéreo lento avança sobre uma floresta de pinheiros enevoada, luz volumétrica suave, cinematográfico",
"duration": 5
}
Como o conjunto de parâmetros pode evoluir, o hábito confiável é: obter a documentação de referência do modelo, copiar os nomes dos campos literalmente e validar localmente antes de enviar.
A mesma requisição em Python
A chamada de envio é um HTTP POST comum. O caminho exato do recurso é definido pela referência da API HiAPI; o exemplo abaixo usa o endpoint habitual de tarefas, com o modelo no corpo da requisição.
curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video-1.0/text-to-video",
"prompt": "Um robô de papelão atravessa um beco neon chuvoso, reflexos no asfalto molhado, textura de filme 35mm",
"duration": 5
}'
A resposta é pequena e volta rápido. O que importa nela são o identificador da tarefa e o estado. A estrutura típica é esta:
{
"id": "job_abc123",
"status": "queued"
}
Registre o id — é o handle para todas as suas chamadas seguintes. status igual a queued ou processing é normal e indica que a requisição foi aceita, não que algo deu errado.
Consulta manual no shell:
curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Execute algumas vezes em intervalos para observar o status mudar em direção ao estado terminal. Na prática, você quer esse laço no código, não no histórico do terminal.
Tratar resultados assíncronos e consultar sem sobrecarregar a API
A versão em Python faz as mesmas duas coisas — enviar e depois consultar —, mas acrescenta tratamento de timeout, retries limitados e salvamento do resultado, para poder rodar sem supervisão com segurança.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
MODEL = "muse-video-1.0/text-to-video"
def submit(prompt: str, duration: int) -> str:
resp = requests.post(
f"{BASE}/v1/video/generations",
headers={**HEADERS, "Content-Type": "application/json"},
json={"model": MODEL, "prompt": prompt, "duration": duration},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for(job_id: str, max_wait: int = 900) -> dict:
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/video/generations/{job_id}",
headers=HEADERS,
timeout=30,
)
if r.status_code >= 500 or r.status_code == 429:
time.sleep(interval)
interval = min(interval * 2, 30)
continue
r.raise_for_status()
job = r.json()
if job["status"] == "succeeded":
return job
if job["status"] == "failed":
raise RuntimeError(job.get("error") or "generation failed")
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in time")
def save(job: dict, path: str) -> None:
url = job["result"]["video_url"]
with requests.get(url, stream=True, timeout=120) as r:
r.raise_for_status()
with open(path, "wb") as f:
for chunk in r.iter_content(8192):
f.write(chunk)
if __name__ == "__main__":
job_id = submit(
"Um terrário de vidro em miniatura sobre uma mesa de madeira, luz da manhã, partículas de poeira flutuando, macro",
5,
)
job = wait_for(job_id)
save(job, "output.mp4")
print("saved output.mp4")
Há três escolhas deliberadas aqui. Os retries são limitados por um prazo final, e não por um número de iterações, para nunca ficarem pendurados indefinidamente. O backoff cresce em falhas transitórias e cresce lentamente durante a consulta no caminho de sucesso. O download é uma requisição separada em streaming, evitando que arquivos grandes passem pelo caminho JSON.
Erros comuns e como diagnosticá-los
A frequência de consulta é uma decisão de projeto real. Consultar a cada 200 ms gera carga desnecessária; consultar a cada cinco minutos desperdiça tempo real depois que a renderização termina.
Estratégia prática:
- Comece com um intervalo moderado (alguns segundos) e aumente gradualmente — multiplicar por 1,5 a cada consulta, com limite de cerca de meio minuto, funciona bem.
- Para respostas
429e5xx, aumente mais o backoff: dobre o intervalo e tente novamente, tratando isso como sinal de capacidade e não de estado da tarefa. - Defina um tempo máximo total de espera e lance um erro ao ultrapassá-lo, em vez de consultar para sempre. Renderizações de duração maior realmente demoram mais, então o limite deve ser definido conforme a sua carga de trabalho.
- Registre uma transição apenas quando o estado mudar, e não a cada consulta — logs ruidosos tornam falhas reais difíceis de perceber.
A resposta de uma tarefa concluída normalmente contém o status terminal, o id da tarefa e um payload de resultado com a URL do vídeo para download, às vezes com metadados e expiração da URL. Obtenha o arquivo logo após o sucesso. Se a tarefa reportar failed, leia a mensagem de erro da resposta antes de tentar novamente — falhas de validação nunca terão sucesso ao repetir, enquanto erros internos de renderização podem.
Próximos passos
Comece com o corpo mínimo da requisição, confirme uma execução bem-sucedida de ponta a ponta e depois adicione controles de duração e áudio conforme a documentação de referência atual de muse-video-1.0/text-to-video. O mesmo padrão de "enviar primeiro, consultar depois" é transferível para outros endpoints de modelos da HiAPI, então o código de cliente que você escrever aqui é reutilizável.
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