API de imagem para vídeo do Kling 4.0: referência de requisição e uma execução real

O Kling 4.0 imagem para vídeo transforma uma imagem de primeiro quadro em um clipe de 3–30 segundos com áudio sincronizado. Este guia apresenta exemplos de requisição prontos para uso no hiapi, os campos que a API aceita e rejeita, e o resultado de uma execução real. Você precisa obter uma chave de API no console do hiapi; o ID do modelo é kling-4.0/image-to-video, e a página do modelo lista as especificações atuais.

Se você ainda usa o Kling 3.0, a visão geral da API do Kling 4.0 foi escrita antes do lançamento e descreve o anúncio de lançamento; esta página é a referência atualmente disponível.

Requisição mínima (curl)

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": {
      "prompt": "ela vira levemente a cabeça para a câmera, o cabelo balança com o vento, a câmera avança lentamente, som ambiente de ondas do mar",
      "image_urls": ["https://example.com/first-frame.jpg"],
      "duration": 3,
      "resolution": "720p"
    }
  }'

A resposta retorna imediatamente um ID de tarefa:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Faça polling em GET /v1/tasks/<taskId> até que data.status seja success, depois leia data.output[0].url.

Python: envio e polling

import os, time, requests

BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def kling4_i2v(image_url, prompt, duration=5, resolution="720p"):
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, json={
        "model": "kling-4.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # exatamente uma imagem de primeiro quadro
            "duration": duration,        # inteiro, 3-30
            "resolution": resolution,    # "720p" ou "1080p"
        },
    })
    body = r.json()
    if body["code"] != 200:
        raise RuntimeError(body["message"])
    task_id = body["data"]["taskId"]

    while True:
        d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)

Baixe o arquivo MP4 retornado imediatamente. A URL de saída tem um carimbo de data/hora expireAt (em nossa execução, cerca de sete dias depois) e está hospedada em um domínio temporário, então copie-a para o seu próprio armazenamento em vez de fazer hotlink direto.

Campos que a API aceita

Testamos o endpoint com valores deliberadamente inválidos (esses valores retornam HTTP 400 INVALID_REQUEST e não criam tarefa):

Campo	Regra observada
image_urls	Array obrigatório, exatamente um item (dois itens → maxItems: got 2, want 1)
duration	Inteiro, mínimo 3, máximo 30. Strings como "5" são rejeitadas (got string, want integer)
resolution	720p ou 1080p
aspect_ratio	Opcional: 16:9, 9:16, 1:1, 21:9. A página do modelo afirma que, quando omitido, a composição segue a imagem de origem
prompt	Descrição do movimento; só enviamos requisições sem esse campo nas sondagens do validador, então trate-o como campo recomendado

Ao migrar código de outros modelos de vídeo, duas coisas costumam dar errado:

• O campo é image_urls, não image_url. Enviar image_url gera simultaneamente "campo obrigatório ausente image_urls" e "propriedade extra não permitida image_url".
• Não há chave de áudio. audio, generate_audio e sound são todos rejeitados como propriedades extras. O áudio sempre é gerado junto com a imagem; oriente o áudio no prompt (o exemplo acima pede som ambiente de ondas do mar).

Campos desconhecidos são rejeitados, não ignorados, então erros de digitação aparecem como 400 em vez de serem silenciosamente ignorados.

Considerações para produção

• Prefira callbacks ao polling. A geração do clipe leva minutos, então passe callback (contendo url e when: "final") ao criar a tarefa e trate o resultado no webhook; use o polling apenas como fallback.
• Valide antes de pagar. Como entradas inválidas retornam 400 e não criam tarefa, verifique duração e resolução no seu próprio código primeiro; requisições erradas não custam nada, mas requisições corretas são cobradas por cada segundo solicitado.
• A cobrança é por segundo e depende da resolução. Clipes mais longos e 1080p custam mais; consulte a tabela de preços para as tarifas atuais em vez de confiar em números de artigos.
• Salve o ID da tarefa. Se o polling falhar por um erro de rede temporário, faça polling novamente do mesmo ID em vez de reenviar, caso contrário um segundo clipe será criado e cobrado.

Execução medida

Enviamos a requisição acima: uma imagem de primeiro quadro em retrato, duration: 3, resolution: "720p", sem aspect_ratio.

• Sequência de estados observada com polling a cada ~10 segundos: handling → archiving → success.
• Tempo total real: cerca de 274 segundos para um clipe de 3 segundos. handling ocupa cerca de 255 segundos; planeje em minutos, não em segundos, e projete em torno de callbacks.
• Arquivo de saída (verificado com ffprobe): vídeo H.264, 1280×720, 3,04 segundos, mais uma faixa de áudio AAC com a mesma duração. Portanto, o áudio está realmente embutido no MP4, e a composição segue a imagem de origem 16:9.

Não testamos: 1080p, durações acima de 3 segundos, e valores de aspect_ratio diferentes do padrão. Esses limites vêm das mensagens de validação da API e da página do modelo, não das saídas geradas.

Páginas relacionadas

• Página do modelo Kling 4.0 imagem para vídeo
• Página do modelo Kling 4.0 texto para vídeo, para casos sem imagem de origem
• Página do modelo Kling 3.0 imagem para vídeo
• Como usar o Kling 3.0 Turbo imagem para vídeo
• Preços do hiapi
• Documentação do hiapi

Perguntas frequentes

Posso desativar o áudio no Kling 4.0 imagem para vídeo?

Não por meio de campos da requisição. audio, generate_audio e sound são todos rejeitados pelo validador. Descreva no prompt o som que você quer (ou não quer).

Quantas imagens de entrada posso enviar?

Uma. image_urls deve conter exatamente uma imagem de primeiro quadro.

Quanto tempo leva uma requisição?

Nosso clipe de 3 segundos em 720p levou cerca de 274 segundos de ponta a ponta. Para cargas de produção, use callbacks.

Qual é a duração máxima do clipe?

A API aceita duration até 30 (segundos inteiros) e rejeita valores maiores; nós mesmos só geramos clipes de 3 segundos.