Tutorial
Como usar kling-4.0-flash de imagem para vídeo via API HiAPI: curl e Python
Passo a passo prático de requisição: entrada de imagem do primeiro quadro, consulta de tarefas assíncronas, áudio síncrono e resolução de erros
- Modelo
- kling-4.0-flash
Nesta página
O que o endpoint kling-4.0-flash de imagem para vídeo faz
kling-4.0-flash/image-to-video é um modelo de geração de vídeo condicionado por imagem. Você fornece uma imagem — o primeiro quadro — mais um prompt de texto, e ele retorna um vídeo gerado que começa nesse quadro e evolui conforme sua descrição.
A coisa mais importante a internalizar antes de escrever código: esta não é uma chamada de requisição/resposta que devolve os bytes do vídeo na mesma troca HTTP. A geração leva tempo, então o endpoint segue o modelo de tarefa assíncrona. Sua primeira requisição envia uma tarefa; depois você consulta o status da tarefa repetidamente até que ela atinja um estado terminal.
Mantenha estes três conceitos distintos em mente, pois correspondem a três partes diferentes do cliente:
- Envio — o payload que você manda: a imagem do primeiro quadro, o prompt e as opções de geração.
- Referência da tarefa — o identificador retornado no envio, usado depois para consultar essa tarefa.
- Obtenção do resultado — verificar o status repetidamente e, por fim, receber o vídeo concluído (ou a falha).
Quando você trata o endpoint como uma fila de tarefas em vez de um RPC, o restante da integração — intervalo de consulta, timeout, novas tentativas — passa a ser um pipeline assíncrono comum, e não um caso especial. Se quiser consultar a documentação mais completa do endpoint além deste passo a passo, abra-a em outra aba e acompanhe enquanto executa.
Antes de enviar a requisição
Três coisas precisam estar prontas antes da primeira chamada.
1. Credenciais da API
Você precisa de uma chave da API HiAPI. Toda requisição a envia como token bearer no cabeçalho Authorization. Não a coloque no controle de versão — leia-a de uma variável de ambiente em vez de colá-la no script.
export HIAPI_API_KEY="your-api-key-here"
2. Caminho do endpoint
Todas as chamadas passam pela interface unificada da HiAPI. O identificador de modelo que você usa é kling-4.0-flash/image-to-video. Sua requisição de envio e as consultas de status subsequentes apontam para o mesmo namespace de modelo, então mantenha esse identificador em uma constante no código em vez de espalhar literais de string por toda parte.
3. A imagem do primeiro quadro pronta
Você precisa de uma imagem para servir como quadro de abertura. Antes de enviar, defina duas coisas:
- Como passá-la — como URL publicamente acessível ou como dados de imagem codificados, dependendo de qual forma o endpoint aceita no seu caso de uso.
- Se ela está bem formatada — formato correto, legível e não tão grande a ponto de inchar o corpo da requisição.
Uma regra prática: mantenha o corpo da requisição pequeno e explícito. Se passar uma URL, garanta que ela seja acessível sem autenticação pelo chamador. Se passar dados codificados, confirme que a codificação é exatamente a que o endpoint espera.
Prepare também um prompt curto e específico. Prompts de imagem para vídeo funcionam melhor quando descrevem movimento e mudança (o que se move, como a câmera se move) em vez de repetir o que já é visível no quadro.
Requisição curl funcional
Abaixo está uma chamada de envio completa. Substitua os placeholders pela sua chave, imagem e prompt.
curl -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Slow dolly-in on the subject as light shifts across the scene",
"image": "https://your-host.example/first-frame.jpg"
}'
Item a item:
-X POST— o envio é uma operação de escrita, não de consulta.- URL — o identificador do modelo faz parte do caminho do endpoint unificado. É o único lugar onde você especifica o modelo.
Authorization: Bearer $HIAPI_API_KEY— cabeçalho expandido pelo shell a partir da sua variável de ambiente. As aspas duplas permitem a expansão da variável mantendo seu valor como um único argumento.Content-Type: application/json— o corpo é JSON; sem este cabeçalho, alguns gateways rejeitam ou interpretam mal o payload.-d '{ ... }'— o corpo JSON.promptdescreve o movimento;imagefornece o primeiro quadro. Cada campo é explícito — nada depende de posição ou de padrões invisíveis para você.
Um envio bem-sucedido retorna um corpo JSON contendo o identificador da tarefa. Capture-o — esse valor é o seu handle para operar a tarefa. Se estiver explorando interativamente, pode passar a resposta por um formatador JSON para copiar o identificador:
curl -s -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Slow dolly-in as light shifts","image":"https://your-host.example/first-frame.jpg"}' | python -m json.tool
Não presuma que o vídeo está nesta resposta. Não está — esta resposta apenas informa que a tarefa foi aceita.
A mesma requisição em Python
O cliente Python corresponde exatamente ao payload curl. Trocar de linguagem não muda a semântica, apenas o mecanismo de envio dos bytes. Use requests e leia a chave da variável de ambiente:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-4.0-flash/image-to-video"
BASE_URL = "https://api.hiapi.ai/v1/models"
def submit_job(prompt: str, image: str) -> dict:
response = requests.post(
f"{BASE_URL}/{MODEL}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={
"prompt": prompt,
"image": image,
},
timeout=30,
)
response.raise_for_status()
return response.json()
job = submit_job(
prompt="Slow dolly-in on the subject as light shifts across the scene",
image="https://your-host.example/first-frame.jpg",
)
print(job)
Pontos de portabilidade:
- Use
json=em vez de-d— passar um dict faz orequestsserializar o corpo e definir o tipo de conteúdo. Você obtém o mesmo formato de transmissão do exemplo curl sem escrever JSON à mão. raise_for_status()— converte respostas não 2xx em exceções, para você não confundir um corpo de erro com uma referência de tarefa.timeout=30— o envio deve ser rápido. Um timeout folgado evita conexões penduradas sem mascarar chamadas realmente lentas.- Modelo em uma única constante — se trocar de modelo no futuro, basta alterar uma linha.
O dict retornado contém o identificador da tarefa, que a próxima seção utiliza.
Tratando o ciclo de vida da tarefa assíncrona
O padrão de integração é enviar, depois consultar. Duas fases, bem delimitadas.
Fase 1: enviar e capturar a referência
A chamada submit_job da seção anterior retorna um corpo JSON contendo o identificador da tarefa. Guarde-o. Toda verificação de status posterior precisa dele; perdê-lo significa perder a tarefa.
Fase 2: consultar até o término
A verificação de status é uma requisição de leitura para a mesma tarefa. Repita em intervalos fixos até a tarefa atingir um estado terminal — concluída ou falhou. Um laço simples com limite de tentativas:
import time
def wait_for_job(task_id: str, attempts: int = 60, interval: float = 5.0) -> dict:
for _ in range(attempts):
response = requests.get(
f"{BASE_URL}/{MODEL}",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"task_id": task_id},
timeout=30,
)
response.raise_for_status()
status = response.json()
state = status.get("status")
if state in ("succeeded", "failed"):
return status
time.sleep(interval)
raise TimeoutError(f"Job {task_id} did not finish in time")
Decisões de projeto que vale a pena tomar deliberadamente:
- Limite o número de iterações. Nunca consulte indefinidamente. Um número máximo de tentativas com intervalo fixo dá um tempo máximo de espera previsível.
- Durma entre as verificações, não dentro da requisição. Consultar com muita frequência desperdiça cota e pode acionar limites de taxa.
- Trate a falha como estado terminal. Uma tarefa com falha não vira sucesso na próxima consulta — pare e exponha o erro.
- Distinga espera de conclusão. Só estados terminais encerram o laço; qualquer outro estado significa continuar esperando.
- Persista o ID da tarefa. Se o processo cair no meio da consulta, você quer poder retomar em vez de gerar de novo.
Em produção, mova a consulta para fora da thread da requisição — para um worker em segundo plano ou consumidor de fila — para que gerações longas não mantenham uma requisição web aberta.
Usando a opção de áudio síncrono
O endpoint oferece uma opção de áudio síncrono. Na prática, isso significa uma coisa para o cliente: se ativada, a chamada bloqueia até a geração terminar, em vez de retornar uma referência de tarefa para você consultar.
Isso muda seu design de forma concreta:
- O orçamento de timeout precisa aumentar. Uma chamada de geração bloqueante pode levar muito mais tempo que uma requisição de API típica. Defina o timeout do cliente para cobrir toda a duração esperada, não a duração do envio.
- Não há ponto de verificação no meio. Com consulta, você pode cair e retomar usando o ID da tarefa. Com uma chamada bloqueante, perder a conexão significa refazer o trabalho.
- Pressão sobre threads e pool de conexões. Uma chamada bloqueante ocupa um worker por toda a sua duração. Em um servidor web, isso rapidamente limita sua capacidade de concorrência.
Quando uma chamada bloqueante é aceitável? Quando você executa um script pontual, ferramenta CLI ou tarefa em lote, onde nada mais espera o resultado e a simplicidade supera a vazão. Nesses cenários, a chamada síncrona elimina completamente o mecanismo de consulta, e o código fica mais curto.
Quando evitar? Em qualquer caminho de requisição voltado ao usuário, em serviços de alta concorrência, ou em qualquer lugar onde o cliente possa dar timeout e tentar de novo — uma chamada bloqueante repetida pode dobrar sua carga de trabalho. Nesses cenários, mantenha o padrão de envio assíncrono e consulta da seção anterior, desativando a opção síncrona.
Diagnosticando falhas comuns
Trate falhas em camadas. O primeiro erro que você vê costuma ser o mais superficial, então corrija-o e execute de novo, em vez de adivinhar vários problemas de uma vez.
Erros de autenticação
401 ou 403 significa credenciais ausentes, mal formatadas ou rejeitadas. Verifique se HIAPI_API_KEY está realmente definida no ambiente que o processo enxerga — uma variável exportada em um shell não passa para outro shell ou contêiner. Confirme que o cabeçalho Authorization é Bearer <key>, com um único espaço e sem aspas extras vindas de copiar e colar.
Erros de formato do payload
400 normalmente significa que o corpo não pôde ser interpretado ou faltam campos obrigatórios. Verifique novamente se você enviou Content-Type: application/json, se o JSON é válido (vírgulas finais causam falha) e se prompt e image existem e são strings não vazias. Ao depurar, imprima o corpo que você realmente enviou — não o dict que pretendia enviar.
Problemas com a entrada de imagem
Esses problemas costumam aparecer como erros de validação, não como erros óbvios de imagem. Verifique em ordem:
- Acessibilidade — se passar uma URL, busque-a a partir do mesmo ambiente de rede de onde a requisição é feita. Uma URL que funciona no navegador pode estar bloqueada por firewall ou protegida por autenticação para a API.
- Formato — confirme que a imagem é um arquivo suportado e não corrompido. Em caso de dúvida, reexporte.
- Tamanho — imagens muito grandes podem causar falha de validação ou inflar o corpo além do limite.
- Codificação — se enviar dados codificados, confirme exatamente que a codificação corresponde à esperada pelo endpoint; prefixos incompatíveis ou espaços em branco extras causam falha.
Falhas no nível da tarefa
Se o envio foi bem-sucedido mas a tarefa termina em estado de falha, a requisição estava bem formatada, mas a geração não foi concluída. Releia o prompt, verifique se há ambiguidade ou movimento fisicamente implausível, e confirme que a imagem do primeiro quadro realmente serve como ponto de partida. Tente de novo com um prompt simplificado antes de presumir um problema sistêmico — e registre o ID da tarefa e a mensagem de falha para correlacionar depois.
Timeout do laço de consulta
O TimeoutError lançado por wait_for_job significa que seus limites são apertados demais, não que a tarefa morreu. Aumente o número de tentativas ou o intervalo, e verifique se você está consultando o ID de uma execução anterior já encerrada.
Comece pela requisição mínima — uma imagem, um prompt curto, sem campos opcionais — e só aumente a complexidade depois que a linha de base funcionar. Quando o payload é pequeno e explícito, a maioria dos problemas de integração desaparece.
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