Como chamar kling-4.0/image-to-video na HiAPI: curl, Python e polling

O que o endpoint kling-4.0/image-to-video faz

kling-4.0/image-to-video converte uma única imagem estática em um clipe de vídeo gerado relativamente curto. Na HiAPI, ele é oferecido como um endpoint baseado em tarefas: você envia uma imagem e uma descrição no estilo de prompt que indica como deseja que a cena se mova, e a API retorna imediatamente um identificador de tarefa, em vez do vídeo finalizado.

No nível da requisição, o chamador deve fornecer:

• o identificador do modelo (kling-4.0/image-to-video),
• a imagem de origem (normalmente uma URL de imagem acessível publicamente),
• uma descrição em texto que oriente como a imagem deve se mover ou o que deve acontecer na cena,
• quaisquer opções adicionais de geração documentadas para esse modelo nesse endpoint.

O que é retornado não é o vídeo em si. A resposta de submissão traz um identificador de tarefa e um estado inicial. O clipe em si só fica disponível depois que a tarefa de geração é concluída, e então você o obtém referenciando esse identificador.

Essa separação é o modelo mental completo desse endpoint: enviar → obter o id da tarefa → consultar o estado (polling) → baixar o resultado. Cada seção abaixo é uma variação desse ciclo.

Como o endpoint é assíncrono, seu código de integração tem duas responsabilidades, não uma: ele deve enviar uma requisição de submissão bem formada e gerenciar o fluxo seguinte até a tarefa atingir um estado terminal. Se você cuidar bem desses dois pontos, o resto é apenas conexão rotineira.

Pré-requisitos e autenticação

Antes de qualquer chamada, você precisa de duas coisas: uma conta na HiAPI com acesso a esse modelo e uma chave de API emitida no console.

A autenticação é feita por requisição. Toda chamada à API inclui sua chave em um cabeçalho HTTP — o padrão é um cabeçalho de autorização no estilo bearer:

Authorization: Bearer <YOUR_HIAPI_API_KEY>

Não deixe a chave entrar no controle de versão. As práticas usuais são:

• Armazená-la em uma variável de ambiente (por exemplo, HIAPI_API_KEY) e lê-la em tempo de execução.
• Nunca colá-la no código do cliente nem em comandos curl que você depois vai commitar no repositório.
• Se a chave vazar, rotacioná-la pelo console.

Exporte-a no shell para que os exemplos curl e Python abaixo possam lê-la:

export HIAPI_API_KEY="your-key-here"

Você também precisa de uma URL de imagem acessível. O endpoint usa imagens por referência, portanto um caminho de arquivo local no seu notebook não serve — hospede a imagem em um local com URL HTTPS estável ou, se a plataforma oferecer um mecanismo de recursos, faça upload da imagem e use a referência retornada.

Com a chave exportada e a imagem acessível, você já pode enviar a tarefa.

Desmembrando a requisição curl passo a passo

Uma requisição de submissão completa tem esta aparência:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "image": "https://example.com/your-image.jpg",
      "prompt": "A slow camera push-in as the subject turns toward the light; soft afternoon shadows"
    }
  }'

Parte por parte:

• -X POST — a criação de tarefa é POST, não GET. A requisição carrega um corpo que descreve o trabalho.
• URL — o endpoint unificado de tarefas da HiAPI. Para modelos baseados em tarefas, esta é a mesma rota; o modelo é escolhido no corpo, não no caminho.
• Authorization — sua chave, conforme descrito na seção anterior.
• Content-Type: application/json — o corpo é JSON; omitir ou errar esse cabeçalho normalmente faz o servidor rejeitar a requisição antes mesmo de chegar ao modelo.
• model — a string literal kling-4.0/image-to-video. Trate-a como exata e sensível a maiúsculas e minúsculas; erros de digitação geram erro de modelo não encontrado, não uma dica útil.
• input.image — a imagem estática de origem, fornecida como URL. Este é o quadro que o modelo vai animar, então escolha uma imagem nítida e bem enquadrada.
• input.prompt — orientação em linguagem natural. Descreva o movimento e o comportamento da câmera (aproximação, panorâmica, movimento do sujeito) e a atmosfera geral. Prompts vagos produzem movimentos vagos.

A resposta imediata é um objeto de tarefa, não o vídeo. Ele contém o identificador do trabalho e um campo de estado — normalmente algo como enfileirado ou pendente logo após o envio. Guarde esse identificador; é a única informação de que você precisará para verificar o trabalho depois.

Nesse momento o clipe ainda não existe. Isso é o comportamento esperado, e a próxima seção mostra como lidar com isso.

A mesma chamada em Python

A versão em Python faz exatamente a mesma coisa — mesmo endpoint, mesmos cabeçalhos, mesmo corpo — portanto a ferramenta que você escolher não muda o protocolo.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "kling-4.0/image-to-video",
    "input": {
        "image": "https://example.com/your-image.jpg",
        "prompt": "A slow camera push-in as the subject turns toward the light; "
                  "soft afternoon shadows",
    },
}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

resp.raise_for_status()
task = resp.json()
task_id = task["id"]
print("submitted:", task_id, task.get("status"))

Alguns pontos de atenção na prática:

• Use json=payload, não uma string serializada à mão. Ele define o tipo de conteúdo para você e evita erros de aspas.
• Mantenha o envio e as operações seguintes na mesma função ou classe, para que o id da tarefa não se perca entre as etapas.
• Defina timeouts explícitos. A chamada de submissão deve retornar rápido; ela apenas cria o trabalho, não espera o vídeo.
• Não chame raise_for_status() e depois presuma que a tarefa existe — uma resposta fora da faixa 2xx significa que nenhuma tarefa foi criada, e o corpo do erro geralmente indica qual campo está errado.

Se você estiver construindo um serviço, envolva essa chamada em um cliente pequeno, com um método para enviar e outro para verificar o estado. Isso centraliza repetições, registro de logs e tratamento de chaves em um só lugar, em vez de espalhá-los pelos pontos de chamada.

Consultando a tarefa assíncrona até a conclusão

A geração de vídeo a partir de imagem leva consideravelmente mais tempo do que uma conclusão de chat — o modelo precisa sintetizar muitos quadros, codificá-los e armazenar o resultado. Não seria viável retornar o clipe mantendo a conexão aberta por muito tempo na resposta de submissão, por isso o endpoint é assíncrono por concepção.

Como verificar o estado

Consulte a tarefa pelo identificador com uma requisição GET:

curl "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

A resposta descreve o trabalho: seu estado e, quando concluído, a saída. O estado normalmente passa de enfileirado para em execução até um estado terminal — por exemplo, sucesso, ou falha com uma mensagem de erro.

Loop de polling simples em Python

import time

def wait_for_task(session, base_url, task_id, timeout=900):
    deadline = time.time() + timeout
    delay = 2.0
    while time.time() < deadline:
        r = session.get(f"{base_url}/tasks/{task_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")

        if status in ("succeeded", "failed"):
            return data

        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)  # gentle backoff, capped

    raise TimeoutError(f"task {task_id} did not finish in time")

Orientações sobre backoff

• Comece com intervalos curtos e aumente gradualmente. A geração não termina no primeiro segundo, então consultar o endpoint com frequência só desperdiça cota e dispara limites de taxa.
• Limite o intervalo para ainda perceber trabalhos concluídos em tempo hábil — alguns segundos em regime estável é suficiente.
• Sempre defina um prazo limite rígido. Sem definir um limite, uma tarefa que nunca termina é indistinguível de uma tarefa excepcionalmente longa.
• Faça polling a partir de um processo em segundo plano ou de um job agendado, em vez de bloquear a requisição web. Se o usuário estiver esperando na interface, faça o frontend consultar o seu próprio endpoint de estado.
• Repita tentativas em erros de rede transitórios nas chamadas de estado, mas não repita uma tarefa que já reportou failed — nesse caso, a ação correta é enviar uma nova tarefa.

Recuperando e armazenando o clipe retornado

Quando o polling retorna um estado terminal de sucesso, o objeto de tarefa contém a referência de saída do vídeo gerado — uma URL de recurso ou referência equivalente que aponta para o vídeo concluído.

result = wait_for_task(session, "https://api.hiapi.ai/v1", task_id)
if result["status"] != "succeeded":
    raise RuntimeError(result.get("error") or "generation failed")

video_url = result["output"]["video_url"]

with session.get(video_url, stream=True, timeout=120) as r:
    r.raise_for_status()
    with open(f"{task_id}.mp4", "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 16):
            f.write(chunk)

Duas decisões de projeto costumam surgir aqui.

Baixe imediatamente. As URLs de saída costumam ter validade limitada. Se você pretende guardar o clipe, copie-o para o seu próprio armazenamento, em vez de entregar a URL bruta ao usuário e torcer para que continue válida.

Armazene os metadados junto com o arquivo. Persista o id da tarefa, o prompt, a referência da imagem de origem e o horário de criação junto com o vídeo. Quando alguém perguntar mais tarde por que o clipe ficou daquele jeito, esse registro é a resposta.

Para oferecer um serviço, o padrão comum é: gerar no backend, armazenar o arquivo em object storage e devolver ao cliente a sua própria URL estável. Assim, sua aplicação controla acesso, expiração e cache, em vez de depender do ciclo de vida dos recursos gerados.

Se quiser gerar novamente com outro movimento, envie uma nova tarefa com o prompt ajustado — cada tarefa é independente, e não é necessário modificar uma tarefa já concluída.

Solução de problemas em requisições que falham

Quando algo dá errado, investigue de dentro para fora a partir da estrutura da requisição. A maioria das falhas se reduz a poucas causas.

A chamada de submissão retorna erro

• String do modelo errada. kling-4.0/image-to-video precisa corresponder exatamente, inclusive maiúsculas e minúsculas e a barra. Imprima a string que você realmente está enviando, em vez de confiar no arquivo-fonte.
• Autenticação rejeitada. Confirme que o cabeçalho é Authorization: Bearer <key> — não a chave nua, não um parâmetro de query — e que a variável de ambiente está definida no mesmo shell ou processo que executa a requisição.
• Imagem inacessível. A imagem precisa ser buscável pela plataforma via HTTPS. URLs de localhost, buckets privados ou hosts com proteção contra hotlink vão falhar. Abra a URL em uma janela anônima para verificar se ela resolve sem autenticação.
• Campo ausente ou com nome errado. O corpo aninha as entradas do modelo em input. Colocar prompt ou image no nível superior em vez de dentro de input é um erro comum, e os erros de validação geralmente apontam o nome do campo.
• Tipo de conteúdo. Enviar um corpo JSON sem Content-Type: application/json faz a requisição ser rejeitada antes de envolver o modelo.

A tarefa foi criada mas nunca teve sucesso

• Pouco polling ou nenhum. Verifique se o seu loop está realmente em execução e se ele compara os valores de estado que a API retorna. Um erro de digitação na verificação do estado terminal causa um loop infinito.
• A tarefa virou failed. Leia a mensagem de erro no objeto de tarefa; normalmente ela aponta para a entrada — por exemplo, uma imagem que não pôde ser decodificada.
• Você atingiu o prazo limite. Se o trabalho ainda está em execução perto do timeout, aumente o limite em vez de reenviar repetidamente, o que só aumenta a carga e o custo.
• O link de saída expirou. Se a tarefa teve sucesso mas o download retorna 404, passou tempo demais entre a conclusão e a recuperação. Baixe imediatamente após o sucesso.

Um hábito de diagnóstico rápido: nas primeiras integrações, registre literalmente o corpo da resposta de submissão. Ele informa o id da tarefa, o estado inicial e os nomes exatos dos campos que o endpoint retorna, eliminando adivinhações em cada falha posterior.