Blogue

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

Nov 12, 2026
Imagem de capa: dois grandes blocos de cor sólida, um lilás claro e outro preto tinta, encontram-se ao longo de uma borda reta e nítida, com uma fina costura roxa embutida na borda; a composição é contida e serena.
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:

  1. 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.
  2. 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.
  3. 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.com na 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 de data=, para que o cliente defina corretamente o content type e faça o escape do corpo.
  • Defina um timeout explí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 um KeyError confuso 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 True em 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 failed como 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 →

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