Crie vídeos curtos com o Kling 3.0 image-to-video via API HiAPI

Vídeos curtos são o formato que toda pipeline de conteúdo acaba precisando suportar, e a forma mais barata de produzi-los em lote com confiabilidade é o image-to-video: pegue um frame estático que você já controla — uma foto de produto, um design de personagem, um keyframe gerado — e deixe um modelo de vídeo dar movimento a ele. O endpoint de image-to-video do Kling 3.0 no HiAPI se destaca nisso, e tem um recurso que a maioria dos modelos i2v ignora: você pode fornecer tanto o primeiro quanto o último frame, de modo que o modelo anima entre os dois estados, em vez de apenas extrapolar movimento a partir de um único frame.

Este tutorial constrói um fluxo de trabalho completo e scriptável: gerar o primeiro frame, enviá-lo para a API de tarefas assíncronas do Kling 3.0, fazer polling até a conclusão e baixar um clipe finalizado com áudio sincronizado nativo — tudo por meio de chamadas HTTP simples que podem ir direto para tarefas de processamento em lote.

Por que image-to-video em vez de text-to-video

Text-to-video te dá uma surpresa a cada vez. Image-to-video te dá um ponto de partida que você já aprovou — o que importa quando esse frame é uma foto de produto, um personagem de marca ou qualquer coisa que precise parecer específica antes de se mover. O modelo image-to-video do Kling 3.0 leva isso adiante com o controle de primeiro frame + último frame: passe uma imagem de referência e o modelo a trata apenas como ponto de partida; passe duas e a segunda se torna o estado final alvo, com o modelo interpolando o movimento entre elas. Na prática, é animação de keyframes programável por meio de uma única chamada de API, sem precisar de nenhum editor de linha do tempo.

Estrutura da requisição

O Kling 3.0 image-to-video roda no endpoint unificado de tarefas assíncronas do HiAPI — POST /v1/tasks, e então polling em GET /v1/tasks/{id} até concluir. O schema de entrada do modelo é deliberadamente enxuto:

{
  "model": "kling-3.0/image-to-video",
  "input": {
    "prompt": "a lantern slowly lighting up as the camera pushes in, warm cinematic glow",
    "image_urls": ["https://static.hiapi.ai/blog/kling-3-0-image-to-video-short-form-workflow/first-frame-v2.jpg"],
    "duration": 3,
    "resolution": "720p",
    "sound": true
  }
}

Antes de construir em cima disso, algumas coisas valem saber:

• image_urls aceita 1 ou 2 entradas. Uma imagem significa “anime a partir deste frame”. Duas imagens significam “anime da primeira em direção à segunda” — esse é o controle de primeiro frame + último frame mencionado acima. Não há um campo separado tail_image_url; tudo é expresso pela posição no array.
• duration é um inteiro de 3 a 15 segundos. Plataformas de vídeo curto em geral querem clipes na faixa de 3–8 segundos, então para uma cena única você normalmente quer a parte mais baixa dessa faixa.
• resolution pode chegar a 4K, acima do modelo irmão kling-3.0-turbo (limite de 1080p). O custo é o preço — veja os preços abaixo — então 720p ou 1080p cobrem a maioria dos casos de vídeo curto sem pagar por uma resolução que ninguém vai notar na tela do celular.
• sound é booleano, e é geração real de áudio sincronizado, não um clipe silencioso com música adicionada depois. Ative quando o movimento da sua cena razoavelmente produziria som (uma porta batendo, vento, passos), e o resultado será visivelmente mais crível do que um render silencioso.
• Não há campo aspect_ratio — a saída corresponde à proporção da imagem que você enviou.

Script de ponta a ponta

Este é o fluxo completo em Python: criar a tarefa, fazer polling até concluir, baixar o resultado.

import requests
import time

API_KEY = "YOUR_HIAPI_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_i2v(image_url, prompt, duration=3, resolution="720p", sound=True):
    payload = {
        "model": "kling-3.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "duration": duration,
            "resolution": resolution,
            "sound": sound,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_result(task_id, poll_interval=5, timeout_s=600):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = submit_i2v(
    image_url="https://static.hiapi.ai/blog/kling-3-0-image-to-video-short-form-workflow/first-frame-v2.jpg",
    prompt="a lantern slowly lighting up as the camera pushes in, warm cinematic glow",
)
video_url = wait_for_result(task_id)
print(video_url)  # temporary signed URL — download immediately, don't store it as a permanent link

Há um detalhe que costuma derrubar as pessoas ao conectar isso a uma pipeline real: o output[0].url que você recebe é um link temporário que expira. Baixe os bytes imediatamente e mova-os para o seu próprio armazenamento, em vez de guardar a URL de saída da tarefa em qualquer lugar como se fosse permanente.

Este é o primeiro frame usado no exemplo, e o clipe que o Kling 3.0 gerou a partir dele com sound: true:

Um clipe de 3 segundos, 720p, com áudio como o acima custa pouco mais de US$ 0,40 — barato o suficiente para iterar várias vezes no prompt antes de definir a versão que você quer entregar.

Preços: resolução e áudio afetam o custo

O Kling 3.0 image-to-video cobra por segundo de duração de saída, e tanto a resolução quanto a opção de áudio afetam a tarifa:

Resolução	Sem áudio	Com áudio
720p	$0.10/s	$0.143/s
1080p	$0.129/s	$0.193/s
4K	$0.479/s	—

Exemplos de cálculo: um clipe de 3 segundos, 720p, com som custa cerca de US$ 0,43. Um clipe de 5 segundos, 1080p, sem áudio custa US$ 0,645; o mesmo clipe com áudio custa US$ 0,965. Para conteúdo de vídeo curto cujos clipes finais ficam na faixa de 3–8 segundos, 720p ou 1080p quase sempre é a escolha certa — o preço de 4K só faz sentido se você for compor em algo downstream que realmente se beneficie da resolução extra. Antes de rodar qualquer coisa em escala, consulte os preços atuais, pois detalhes como tarifas por segundo merecem confirmação na página ao vivo, não em cache de memória.

Transforme isso em um fluxo de trabalho real com processamento em lote

Para conteúdo de vídeo curto em qualquer escala, você não quer enviar uma tarefa e ficar olhando para ela — quer disparar um lote de tarefas e coletar os resultados conforme chegam. Como cada tarefa é independente e identificada pelo seu próprio taskId, o padrão é simples: envie primeiro todas as requisições de image-to-video, armazene os IDs de tarefa retornados e então faça polling em loop sobre elas, agindo apenas quando cada tarefa se tornar success ou fail. Assim sua pipeline roda na taxa de transferência real da plataforma, em vez de ser serializada na geração mais lenta individual.

Alguns hábitos que vale cultivar desde o início:

• Valide que a imagem de origem está acessível antes de enviar. A API de tarefas aceita alegremente uma URL e depois a tarefa falha mais tarde se a imagem não puder ser buscada — uma verificação prévia com uma requisição HEAD evita uma geração desperdiçada.
• Trate o status fail como resultado normal, não como exceção. A saída do modelo ocasionalmente rejeita uma combinação específica de prompt/imagem; registre a falha e siga para o próximo item, em vez de abortar o lote inteiro.
• Reutilize clipes entre variantes sempre que possível. Se você está testando várias legendas ou trilhas sonoras sobre a mesma animação gerada, não há necessidade de gerar o vídeo de novo — isso é puramente uma etapa de edição downstream.

Se for a primeira vez que você configura chave de API e autenticação, o guia de início rápido do HiAPI cobre o básico para obter uma chave e fazer sua primeira chamada autenticada, e depois disso você pode construir a pipeline de lote completa em cima disso.

Resumo

O modelo image-to-video do Kling 3.0 transforma um único frame estático — ou dois, se você quiser controle de primeiro frame + último frame — em um clipe curto com áudio sincronizado por meio de uma única chamada HTTP, com preços que escalam de forma previsível por duração, resolução e necessidade de som. Para pipelines de vídeo curto, a combinação desse controle, do baixo custo por clipe em 720p/1080p e de uma API de tarefas assíncronas direta torna fácil passar de “uma imagem estática” para “um lote de clipes finalizados” sem tocar em um editor de vídeo.