Como chamar a API de texto para vídeo do Kling 2.5 Turbo: guia com curl e Python

O que o endpoint kling-2.5-turbo/text-to-video oferece

kling-2.5-turbo/text-to-video é o modelo de texto para vídeo disponibilizado publicamente no HiAPI. Você envia um prompt de texto e ele devolve um vídeo gerado. O "turbo" no nome indica a direção da otimização: uma velocidade de entrega maior do que a do nível de qualidade padrão, ao custo de perder alguns detalhes. Para renderizações de rascunho, pré-visualização de storyboards, edições para redes sociais e iteração criativa, essa troca geralmente é a correta.

Antes de escrever a primeira linha de código, o ponto mais importante a internalizar é este: trata-se de um endpoint assíncrono. A geração de vídeo leva de segundos a minutos, muito além de qualquer timeout HTTP razoável. Por isso a API é dividida em duas operações:

1. Submissão — você faz um POST do prompt e dos parâmetros e recebe imediatamente um identificador de tarefa.
2. Polling — você consulta repetidamente a tarefa com esse identificador via GET até que ela atinja um estado terminal, e então lê o resultado do vídeo no payload da resposta concluída.

Se você tentar modelar isso como uma chamada bloqueante, vai encontrar timeouts, gerações duplicadas em cada retry e conexões resetadas sob carga alta. O padrão submeter-e-depois-consultar não é um incômodo a ser contornado; é o modelo mental correto. Todos os exemplos de código abaixo são construídos em torno dele, e, uma vez internalizado, o restante da integração se torna direto.

Também é preciso estabelecer uma expectativa: o endpoint tem estado, mas o estado fica no servidor, não do seu lado. A tarefa existe independentemente da sua conexão HTTP. Seu script pode cair no meio do polling, reiniciar e reconectar à mesma tarefa usando o ID — desde que você tenha persistido esse ID em algum lugar. Projete desde o início com essa premissa.

Estrutura da requisição: prompt, predefinição rápida e duração flexível

Você controla apenas alguns campos, mas cada um deles causa impacto real na tarefa. A seguir está o que realmente importa.

Prompt

O prompt é a principal entrada criativa. Trate-o como a descrição de uma tomada, não como uma consulta de busca. Um bom prompt para este modelo normalmente inclui:

• Assunto — quem ou o que está na tela.
• Ação — o que o assunto faz durante o clipe.
• Câmera — enquadramento e movimento, como slow dolly in, static wide shot, handheld follow.
• Ambiente e iluminação — cenário, horário, atmosfera.
• Estilo — se quiser orientar a aparência visual, escreva coisas como cinematic, anime, product photography.

Seja específico e coloque o assunto no início. Prompts vagos produzem movimento vago, e o nível turbo amplifica isso, pois deixa menos espaço para interpretação.

Predefinição fast/turbo

A família de modelos suporta uma predefinição rápida que troca parte do refinamento por menor latência. Ao ativá-la, você diz ao backend para priorizar velocidade — o movimento continua coerente, mas texturas finas, rostos pequenos e fundos complexos degradam mais cedo do que no caminho de qualidade. Use-a no ciclo de iteração em que você testa variações de prompt; quando for renderizar a tomada final, considere se o caminho de qualidade não é o melhor último passo. A predefinição é um campo da requisição, portanto é uma decisão por tarefa, não uma configuração global da conta.

Duração flexível

A duração é flexível dentro do intervalo suportado pelo modelo, em vez de fixa em um único comprimento. Durações maiores significam mais quadros a gerar e, portanto, mais tempo de conclusão e custo mais alto — a cobrança é feita por segundos de saída. Escolha a menor duração que atenda à tomada. Um loop de cinco segundos para uma postagem em rede social não precisa do mesmo comprimento de uma batida narrativa.

Disciplina nos campos

Defina apenas os campos de que você precisa. Chaves desconhecidas ou com erro de digitação são uma fonte comum de configuração silenciosamente equivocada, então mantenha o corpo JSON pequeno, explícito e versionado junto com o restante da configuração do pipeline.

Fazendo a requisição com curl

Toda chamada ao HiAPI usa o mesmo padrão de autenticação: um token bearer no cabeçalho Authorization. Mantenha a chave em uma variável de ambiente, para que ela não apareça no histórico do shell nem em scripts versionados.

export HIAPI_API_KEY="your_api_key_here"

Em seguida, submeta a tarefa. Os nomes exatos dos campos e o caminho do endpoint devem ser obtidos na referência do modelo; a forma abaixo é a canônica:

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/text-to-video",
    "prompt": "A slow dolly-in on a ceramic coffee cup on a wooden table, morning light raking across the surface, steam rising, shallow depth of field, cinematic",
    "duration": 5,
    "fast": true
  }'

O que você deve esperar receber não é o vídeo. É uma confirmação com o identificador da tarefa e seu estado inicial — normalmente o estado queued ou processing, além de um campo id. Guarde esse ID; é o handle de todas as operações seguintes.

A resposta mínima é mais ou menos assim:

{
  "id": "job_abc123",
  "status": "queued",
  "model": "kling-2.5-turbo/text-to-video"
}

A chamada de submissão deve retornar rápido — bem abaixo de um segundo em condições normais. Se ela travar, o problema está na conectividade ou na autenticação, não no modelo. Se retornar 401, verifique o formato do cabeçalho (o prefixo Bearer é importante). Se retornar 422, seu corpo JSON está malformado ou falta um campo obrigatório.

Não adicione -L, retries ou timeouts longos a esta chamada. A etapa de submissão ou tem sucesso rápido, ou falha rápido. Toda a espera acontece no loop de polling, que é o assunto a seguir.

A mesma requisição em Python

A versão em Python é um envoltório fino sobre o mesmo contrato HTTP. Use requests com um Session compartilhado, para que o pool de conexões seja aproveitado entre a submissão e cada polling. Envolva tudo em funções, para que o restante do seu código nunca toque em HTTP bruto.

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

session = requests.Session()

def submit_video(prompt: str, duration: int = 5, fast: bool = True) -> str:
    body = {
        "model": "kling-2.5-turbo/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "fast": fast,
    }
    resp = session.post(f"{BASE}/video/generations", json=body, headers=HEADERS, timeout=15)
    resp.raise_for_status()
    return resp.json()["id"]

def poll_video(job_id: str, timeout_s: int = 600, interval_s: float = 3.0) -> dict:
    deadline = time.monotonic() + timeout_s
    delay = interval_s
    while time.monotonic() < deadline:
        resp = session.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS, timeout=15)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("succeeded", "failed", "cancelled"):
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    job = submit_video("A slow dolly-in on a ceramic coffee cup, morning light, steam rising, cinematic")
    result = poll_video(job)
    print(result)

Há alguns detalhes que vale manter em vez de enxugar: o timeout em cada requisição, para que um socket travado não pendure seu worker; o backoff exponencial com um teto razoável; e um TimeoutError separado, para que o chamador consiga distinguir "ainda em execução" de "quebrado".

Se você preferir httpx, a conversão é direta — mesmos métodos, URL e corpo JSON. A camada de transporte não é a parte interessante; o contrato é. Antes de iniciar o polling, guarde o job_id em um lugar persistente, para que um reinício não deixe gerações em andamento órfãs.

Consultando a tarefa e lendo a resposta

O loop de polling é onde mora a maioria dos bugs de integração. Três regras o mantêm confiável.

Regra 1: só estados terminais encerram o loop

Você verá estados transitórios — queued, processing — e estados terminais, como succeeded, failed e cancelled. Apenas estados terminais saem do loop. Não trate uma string de estado desconhecida como sucesso, nem interrompa em processing. Registre o estado a cada iteração; quando algo der errado às duas da manhã, esse log é sua única evidência.

Regra 2: faça backoff, não gire em falso

Para uma tarefa que leva um minuto, polling fixo de um segundo é desperdício; e, ao executar tarefas em lote, polling agressivo pode esbarrar no limite de requisições. Comece com cerca de dois a três segundos, multiplique por cerca de 1,5 a cada rodada e limite a dez ou quinze segundos. O total de requisições de uma tarefa de um minuto cai de sessenta para menos de quinze, e a latência de detecção no pior caso ainda fica no valor do teto.

Regra 3: separe o ativo dos metadados

O payload da resposta concluída contém as duas coisas. O vídeo em si é entregue como URL (e normalmente com prazo de expiração), enquanto todo o resto — ID da tarefa, modelo, duração, estado, tempo de execução — são metadados sobre como você chegou ali. Leia a URL, baixe logo e armazene por conta própria. URLs de ativos gerados não são CDN permanente; trate-as como uma entrega, não como uma casa. Persista o ID da tarefa junto com sua própria cópia, para que você possa rastrear qualquer clipe de volta até a requisição exata que o produziu.

Uma nota sobre failed

O estado failed é um resultado no nível da tarefa, não um erro de transporte. A chamada HTTP teve sucesso; a geração não. Leia o payload de erro — ele pode indicar rejeição por política de conteúdo, combinação de parâmetros não suportada ou falha interna. Repetir tal e qual um retry em uma rejeição de política só vai falhar de novo, então ramifique por causa antes de considerar um retry.

Tratando erros, timeouts e retries

Distinga dois mundos de erro e trate cada um separadamente.

Erros de nível de transporte são falhas HTTP: conexão resetada, respostas 5xx, limite de requisições 429 e timeouts do cliente. Esses não dizem se a tarefa chegou a rodar. Faça retry com backoff exponencial e jitter, e limite o número de tentativas.

Erros de nível de tarefa são estados terminais em respostas HTTP bem-sucedidas. A tarefa rodou e produziu um resultado claro. Repetir o polling não ajuda; se você for tentar de novo, será uma nova submissão, e só quando a causa da falha for transitória.

Repita a coisa certa

Esta é a parte sutil. Se a sua chamada de submissão der timeout, você não sabe se o servidor aceitou a tarefa. Reenviar às cegas pode gerar duas gerações e duas cobranças. O padrão mais seguro é tornar a submissão idempotente com uma chave de requisição gerada pelo cliente, enviada como cabeçalho ou campo do corpo, de modo que envios duplicados retornem a tarefa original em vez de iniciar uma nova. Se a superfície da API que você usa não oferecer isso, então, em caso de timeout na submissão, registre o hash do prompt e a duração, e verifique suas tarefas recentes antes de reenviar.

Timeouts em todas as camadas

Defina três timeouts distintos e não os misture:

• Timeout por requisição — curto, por exemplo de dez a quinze segundos. Isso limita a chamada HTTP individual, não a tarefa.
• Prazo total da tarefa — o orçamento de tempo de parede da geração inteira. Se estourar, marque a tarefa como órfã, dispare um alerta e siga em frente.
• Timeout voltado ao cliente — se o usuário está esperando, decida se você transmite o progresso ou devolve ao frontend o handle da tarefa.

Estratégia prática de retry

Faça retry de 429 e 5xx com backoff, com um teto pequeno. Nunca repita 400, 401, 403 ou 422 — esses são bugs na sua requisição, e repeti-los só queima quota. Registre o corpo de resposta de cada falha; os payloads de erro do HiAPI normalmente apontam o campo problemático.

Segurança em lote

Ao disparar muitas tarefas em paralelo, adicione um limite de concorrência e atrasos iniciais com jitter. Cem submissões simultâneas são um acidente de limite de requisições esperando para acontecer. Um pool de cinco a dez workers, cada um fazendo polling de forma independente, é bem mais estável e mais fácil de observar.

Checklist de produção antes de ir ao ar

Antes de isso sair do notebook, fixe estas decisões.

• Timeouts e prazos. Cada chamada tem timeout por requisição, há um prazo total da tarefa e existe uma política clara para o que acontece quando uma tarefa fica órfã. Escreva-os como constantes, não como números mágicos.
• Persistência de ID. Guarde o job_id e o hash do prompt antes de iniciar o polling. É isso que torna reinícios e auditoria possíveis.
• Armazenamento de ativos. Ao ter sucesso, baixe o vídeo concluído para o seu próprio bucket de armazenamento. Nunca envie para o frontend ou banco de dados uma URL que você não controla como referência permanente.
• Registro de logs. Registre cada transição de estado com ID da tarefa, modelo, duração, predefinição e tempo de execução. Quando surgirem problemas de custo ou qualidade, esse é o conjunto de dados para respondê-los.
• Consciência de custo. A cobrança é por segundos de saída, então a duração é sua principal alavanca de custo. A predefinição turbo mantém a latência (e, portanto, a ocupação de workers) baixa. Acompanhe os segundos gerados por funcionalidade, para que a discussão de custo se baseie em números reais, não em suposições.
• Idempotência. Use chaves de requisição geradas pelo cliente na submissão e defina regras sobre o que constitui um reenvio seguro.
• UX de falha. Decida agora o que o usuário vê quando uma tarefa falha no nível da tarefa: botão de retry, prompt alternativo ou uma mensagem de texto simples. Girar em falso silenciosamente é a pior opção.
• Versionamento de prompts. Mantenha os prompts na configuração, não embutidos no handler, para que você possa comparar saídas de variantes diferentes sem reimplantar.

O endpoint em si é pequeno — uma submissão, um polling. Quase todo o esforço de engenharia está no ciclo de vida ao redor dele, e é aí que se decide a qualidade de produção. Comece pela referência do modelo kling-2.5-turbo/text-to-video no HiAPI e construa em volta dele o andaime descrito aqui.