Tutorial
Como chamar o kling-4.0-flash Reference-to-Video pela API HiAPI: práticas com curl e Python
Práticas executáveis de chamada com múltiplas imagens de referência, polling assíncrono e guia de diagnóstico
- Modelo
- kling-4.0-flash
Nesta página
Quando usar referência de imagem para vídeo em vez de texto para vídeo
Texto para vídeo é a ferramenta do roteirista: você descreve uma cena e o modelo cria tudo do zero. Referência de imagem para vídeo é a ferramenta do diretor: você entrega ao modelo uma ou mais imagens e pede que ele gere um movimento no qual esses sujeitos, estilos ou composições permaneçam reconhecíveis. Na HiAPI, essa diferença se manifesta no nível do endpoint — kling-4.0-flash/reference-to-video é uma rota separada das chamadas comuns de texto para vídeo; escolher o endpoint certo desde o início evita cair em engenharia de prompt que nunca conseguirá reproduzir fielmente uma aparência específica.
Escolha referência de imagem para vídeo quando qualquer uma destas condições for verdadeira:
- A consistência de identidade ou de produto é essencial. Você tem uma folha de personagem, uma foto de produto ou um mascote, e a saída não pode se degradar em uma figura genérica parecida.
- Você precisa combinar várias fontes. Uma cena pode exigir uma imagem para definir o personagem e outra para definir o ambiente ou o figurino. Várias imagens de referência permitem expressar essa composição de forma explícita, em vez de depender de descrições em prosa.
- A transferência de estilo é o objetivo. Você quer levar a paleta, a iluminação ou o estilo de renderização da imagem fornecida para o vídeo em movimento.
- Você está iterando sobre um plano. As imagens de referência tornam execuções repetidas comparáveis, pois a âncora visual é fixa e você só ajusta parâmetros ligados ao movimento.
Continue usando texto para vídeo quando estiver explorando conceitos, quando não tiver imagens com direitos claros para usar como âncora, ou quando a necessidade for abstrata ("uma tomada aérea lenta atravessando a névoa ao amanhecer") e qualquer interpretação razoável for aceitável. Imagens de referência restringem o modelo, e restrições só são benéficas quando você realmente precisa delas.
Uma regra prática: se você se pegar escrevendo um parágrafo inteiro descrevendo a aparência exata de um objeto específico, esse é o sinal para trocar de endpoint e fornecer a imagem diretamente. Descrições consomem tokens e ainda assim se degradam; imagens de referência ancoram.
Estrutura da requisição: imagens de referência e parâmetros essenciais
O endpoint aceita um corpo JSON. As partes que você realmente vai tocar se dividem em três categorias: imagens de referência, prompt e parâmetros que moldam a saída.
Imagens de referência
As imagens de referência são enviadas como array, então o mesmo campo naturalmente escala de uma imagem para várias. Cada entrada é uma URL que o serviço precisa conseguir buscar. Restrições práticas a considerar no design:
- Use URLs HTTPS publicamente acessíveis, ou URLs às quais sua conta tenha acesso. Caminhos de arquivo locais e URIs
file://não podem ser buscados por um serviço remoto. - Prefira hospedagem estável a links assinados que expiram em poucos minutos — tarefas de longa duração podem buscar a imagem em um momento além do que você espera.
- Mantenha cada imagem focada. Uma imagem limpa do sujeito ajuda mais do que uma colagem confusa, porque o modelo precisa discernir o que está vendo.
- A ordem pode influenciar como as referências são interpretadas, então mantenha a ordem do array determinística no código, em vez de depender da ordem de iteração de um dicionário.
Prompt
Com as imagens de referência fornecidas, o prompt deve descrever movimento, câmera e atmosfera, não aparência. Explique como o sujeito se move, como a câmera se move e qual é a sensação de ritmo. Redescrever a imagem de referência desperdiça orçamento de prompt e pode conflitar com a âncora que você acabou de fornecer.
Parâmetros que moldam a saída
Além de prompt e do array de imagens de referência, o corpo da requisição geralmente traz campos que controlam o formato da saída e o comportamento da geração. Trate-os como os últimos botões a ajustar: primeiro faça a chamada funcionar com os valores padrão, confirme que as referências estão sendo respeitadas e só então ajuste as configurações de saída. Os nomes dos campos e os valores permitidos estão definidos na documentação de referência do endpoint; enviar campos não reconhecidos é uma causa comum de rejeição do corpo, então valide conforme o schema da documentação em vez de adivinhar.
O modelo mental é simples: as imagens de referência dizem o quê, o prompt diz como se move, os parâmetros dizem o que você recebe de volta.
Requisição curl funcional
Antes de escrever código de cliente, a forma mais confiável de validar o corpo da requisição é uma chamada curl. Defina credenciais e entradas como variáveis de shell, mantenha o JSON legível e envie a requisição.
API_KEY="$HIAPI_API_KEY"
BASE_URL="https://api.hiapi.ai" # use a URL base exibida no seu console
curl -sS -X POST "$BASE_URL/v1/kling-4.0-flash/reference-to-video" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "O personagem se vira para a janela, a câmera avança lentamente; luz suave da manhã, ritmo calmo.",
"reference_images": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/location-window.jpg"
]
}'
Verifique três coisas antes de executar:
- Caminho e prefixo de versão. Confirme a rota exata na documentação do endpoint da sua conta; o caminho inclui número de versão, e um prefixo desatualizado retorna não encontrado em vez de erro de validação.
- Cabeçalho de autenticação. A chave vai como bearer token no cabeçalho
Authorization. Nunca a coloque no corpo da requisição ou na query string, pois ela vazará para os logs. - Placeholders. Todo valor que precisa ser substituído é claramente um placeholder — o comentário da URL base, as duas URLs de CDN, o prompt. Antes de declarar pronto para produção, procure por
example.comna requisição.
Um envio bem-sucedido retorna um identificador de tarefa, não o vídeo pronto. Capture esse identificador do corpo da resposta; a próxima etapa, o polling, vai usá-lo. Passar a resposta por um formatador JSON (| jq .) deixa o ID da tarefa evidente, e vale criar esse hábito.
Versão Python da mesma chamada
A principal diferença na versão Python está na forma de construir o corpo: monte um dict, serialize uma vez e separe a função de requisição da lógica de polling, para que cada uma possa ser testada independentemente.
import os
import requests
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
API_KEY = os.environ["HIAPI_API_KEY"]
REFERENCE_IMAGES = [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/location-window.jpg",
]
def submit_reference_video(prompt: str) -> str:
payload = {
"prompt": prompt,
"reference_images": REFERENCE_IMAGES,
}
response = requests.post(
f"{BASE_URL}/v1/kling-4.0-flash/reference-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()["task_id"]
if __name__ == "__main__":
task_id = submit_reference_video(
"O personagem se vira para a janela, a câmera avança lentamente."
)
print("submitted:", task_id)
As observações a seguir evitam sofrimento desnecessário:
- Leia a chave de variáveis de ambiente. Chaves hardcoded acabam no histórico do git e em capturas de tela.
- Use
json=em vez dedata=, para que o cliente defina corretamente o content type e faça o escape do corpo. - Defina um
timeoutexplícito. A espera infinita padrão transforma conexões travadas em workers pendurados. - Chame
raise_for_status()antes de fazer o parse, para que respostas 4xx sejam reportadas como erro HTTP e não causem umKeyErrorconfuso ao ler o JSON da resposta. - Confirme na documentação o nome do campo de resposta que traz o identificador da tarefa, em vez de assumir
task_id; ajuste a linha de extração conforme necessário.
Faça submit_reference_video retornar apenas o ID. O polling é uma preocupação separada e deve ficar em sua própria função.
Lidar com o ciclo de vida de tarefas assíncronas
A geração de vídeo leva tempo, então o endpoint é assíncrono por design. A chamada de envio retorna rapidamente um identificador de tarefa; o trabalho real acontece depois. Sua integração precisa modelar isso, e o modelo correto mais simples tem três estados: pending ou processing (continue esperando), succeeded (busque a saída), failed (leia o erro e pare).
Faça polling do endpoint de tarefa em intervalos, com um limite total de espera:
import time
def wait_for_task(task_id: str, interval: float = 5.0, max_wait: float = 600.0) -> dict:
deadline = time.monotonic() + max_wait
url = f"{BASE_URL}/v1/tasks/{task_id}"
while time.monotonic() < deadline:
r = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")
Ajuste as strings de status e o caminho da tarefa conforme a documentação — a estrutura acima é apenas o padrão, e a maioria das falhas nesse domínio vem de assumir um rótulo de status que não existe.
Etiqueta de polling que vale adotar desde cedo:
- Backoff gradual. Um intervalo curto e fixo martela a API sem benefício. Comece com um valor moderado e aumente o tempo de espera entre tentativas.
- Sempre limite o loop. Um
while Trueem torno de uma tarefa remota é uma espera por falha. O deadline acima lança uma exceção em vez de pendurar. - Persista o ID da tarefa. Se seu processo cair após o envio, esse ID é a única forma de recuperar o resultado sem pagar por uma segunda geração.
- Trate
failedcomo terminal. Não repita uma tarefa falha fazendo polling de novo; leia o erro e reenvie um corpo corrigido quando fizer sentido. - Trate expiração explicitamente. Resultados de tarefas podem não ficar disponíveis para sempre, então baixe e armazene a saída assim que a tarefa tiver sucesso.
Erros comuns e como corrigi-los
A maioria das falhas de primeira integração se encaixa em poucas categorias. Antes de mudar o código, associe o sintoma à causa.
Falhas de autenticação e autorização
401 ou 403 quase sempre significa credencial errada, ausente ou com escopo incorreto. Verifique se o cabeçalho é exatamente Authorization: Bearer <key>, se a variável de ambiente está de fato preenchida no processo que faz a chamada (exportações de shell não chegam a units do systemd) e se a chave foi rotacionada ou revogada.
Problemas com imagens de referência
Se a requisição for rejeitada por causa de uma imagem, ou se a geração ignorar alguma referência, a suspeita está na URL. Confirme que o link resolve de fora da sua máquina — nomes de host internos ou endereços localhost são inalcançáveis para o serviço. Verifique a expiração de URLs assinadas, confirme que o arquivo é realmente uma imagem e não uma página de erro HTML retornada com status 200, e verifique limites de tamanho e formato. Uma entrada ruim em um array com várias imagens pode derrubar a requisição inteira, então teste as referências uma a uma ao depurar.
Corpo de requisição inválido
Um 400 com mensagem de validação geralmente significa corpo malformado: um array no nível superior em vez de um objeto, campo obrigatório ausente, reference_images enviado como string entre aspas em vez de array, ou nome de parâmetro não reconhecido. Compare seu corpo campo a campo com o schema da documentação e registre o corpo exato que você enviou — o defeito costuma ser uma diferença de serialização entre o caminho de teste e o de produção.
Erros de rota ou de método
404 geralmente significa caminho errado, não modelo indisponível. Reconfira o prefixo de versão e o nome do endpoint na documentação, e confirme que o envio usa POST e que a consulta de status da tarefa usa GET.
Timeouts e erros de polling
Se o próprio envio der timeout, aumente moderadamente o timeout do cliente e tente de novo — mas, se a tarefa já tiver sido aceita, não reenvie às cegas, ou você pagará por uma geração duplicada. Se o polling nunca termina, sua verificação de status provavelmente compara com a string errada; registre o valor bruto de status nas primeiras consultas para ver o que realmente volta.
Limite de taxa
429 significa que você precisa desacelerar. Respeite o intervalo indicado em vez de tentar imediatamente, e aplique backoff exponencial com jitter para que workers paralelos não tentem de novo em sincronia.
Lista de verificação de produção antes do lançamento
Código que roda em um notebook não é o mesmo que uma integração confiável. Antes de expor esse endpoint aos usuários, reforce os limites operacionais.
- Configuração. Mantenha URL base e chave de API em variáveis de ambiente ou em um gerenciador de segredos, nunca no código-fonte. Defina o caminho do endpoint como constante, para que uma atualização de versão exija mudar uma única linha.
- Retries com backoff. Para falhas transitórias — reset de conexão, 429, 5xx — use backoff exponencial com jitter. Não repita erros de validação 4xx; eles falharão da mesma forma.
- Disciplina de idempotência. Registre cada ID de tarefa enviado e sua entrada. Ao reiniciar, retome o polling das tarefas existentes em vez de enviar novas.
- Espera limitada. Defina timeouts explícitos tanto no cliente HTTP quanto no loop de polling, e encaminhe timeouts para uma fila de mensagens mortas inspecionável por humanos, em vez de descartá-los silenciosamente.
- Logs estruturados. Registre IDs de tarefa, transições de status com timestamp, tempos de envio e conclusão, e o corpo de erro em caso de falha. Mascare segredos e trunque o prompt quando ele contiver dados de usuário.
- Tratamento de saída. Baixe a mídia gerada para seu próprio armazenamento assim que a tarefa tiver sucesso, e valide o resultado antes de exibi-lo ao usuário.
- Visibilidade de custo. A cobrança varia com o uso, então acompanhe quantas tarefas foram enviadas por funcionalidade e por usuário. Loops de retry que reenviam sob incerteza são a causa mais comum de gastos inesperados.
- Higiene de entrada. Valide as URLs de referência e o comprimento do prompt do seu lado primeiro. Capturar URLs ruins localmente é mais rápido e mais barato do que uma ida e volta à API.
Feito isso, a integração é uma camada leve e previsível: monte o corpo, envie, faça polling, armazene. Comece pela documentação de referência do endpoint, execute o exemplo curl uma vez e então leve o mesmo corpo para o Python — uma requisição que funciona no shell também funcionará no seu serviço.
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