Blogue

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

Nov 12, 2026
Imagem de capa: uma pilha de papéis em tom bege desalinhados, com bordas delineadas em preto-carvão, entre os quais se intercala uma folha de guarda em vermelho-ferrugem, projetando abaixo uma sombra uniforme.
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. prompt descreve o movimento; image fornece 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 o requests serializar 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 →

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