Usar o Kling AI para vídeos curtos via API: fluxo de trabalho ponta a ponta de texto para vídeo com o kling-3.0-omni

Vídeos curtos são um jogo de volume: o feed recompensa contas que publicam todos os dias, e ninguém consegue filmar, editar e fazer o design de som de um clipe manualmente todos os dias. O kling-3.0-omni/text-to-video é um dos poucos modelos capazes de cobrir a checklist completa de vídeos curtos em uma única chamada de API — saída vertical 9:16, movimento cinematográfico, sequências multi-plano e áudio sincronizado nativo — de modo que todo o pipeline pode ser reduzido a "escrever um prompt, consultar uma tarefa, baixar um .mp4 pronto para publicar".

Este guia percorre o fluxo de trabalho de ponta a ponta na API hiapi: enviar uma tarefa assíncrona, projetar prompts que retenham espectadores durante a rolagem do feed, ativar áudio nativo, escalar para narrativas multi-plano e gerar variantes em lote. Cada clipe incorporado abaixo é uma saída real, não editada e de primeira tentativa, da API em produção — gerada para este artigo, com o prompt exato e as configurações mostrados ao lado.

As ferramentas que você vai usar

O kling-3.0-omni/text-to-video (Kling 3.0 Omni da Kuaishou, endpoint de texto para vídeo) roda na interface de tarefas assíncronas da hiapi. A cobrança é por segundo de saída, dependendo da resolução e se o áudio nativo está ativado. As tarifas abaixo são da página de preços da hiapi no momento em que este artigo foi escrito:

Nível	Preço por segundo	Clipe de 5 segundos	Clipe de 10 segundos
720p	$0.10	$0.50	$1.00
720p + áudio	$0.143	$0.72	$1.43
1080p	$0.129	$0.65	$1.29
1080p + áudio	$0.193	$0.97	$1.93
4K	$0.479	$2.40	$4.79

Para vídeos verticais destinados ao feed, 720p é a escolha honesta: TikTok e Reels recompressionam tudo de qualquer forma, e é a maneira mais barata de iterar prompts. Reserve 1080p/4K para clipes que você vai cortar em outros formatos.

O schema de entrada que validamos de fato neste artigo: prompt (string), duration (inteiro em segundos — executamos 5 s e 10 s), resolution (720p / 1080p / 4K), aspect_ratio (9:16 para vertical) e sound (booleano, desativado por padrão). Um comportamento que vale conhecer antes de construir em cima disso: quando você omite sound, o .mp4 retornado não tem nenhuma faixa de áudio — não uma faixa silenciosa, mas nenhuma faixa. Se o seu pipeline de edição downstream espera um stream de áudio em todo arquivo, defina sempre sound: true ou trate explicitamente arquivos sem faixa.

Enviar → consultar → baixar: o ciclo de vida da tarefa

Tudo passa por POST /v1/tasks. Envie a tarefa, receba imediatamente um ID de tarefa, consulte até a conclusão e baixe a saída. Um clipe de 5 segundos em 720p geralmente é renderizado em poucos minutos.

Envio com curl:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/text-to-video",
    "input": {
      "prompt": "Vídeo vertical de formato curto. Um barista em um café especializado iluminado pelo sol despeja uma arte latte rosetta perfeita em um movimento fluido, vapor subindo, luz da manhã pela janela, profundidade de campo rasa, detalhe fotorrealista nítido, leve movimento lento de aproximação.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "9:16"
    }
  }'

A resposta retorna imediatamente:

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

Em seguida, consulte GET /v1/tasks/{taskId} até que status seja success (ou fail) e baixe output[0].url. Abaixo está um script auxiliar completo em Python — este é o padrão real que usamos para gerar cada clipe deste guia:

import json, subprocess, time, os

API = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

def submit(input_fields: dict) -> str:
    payload = {"model": "kling-3.0-omni/text-to-video", "input": input_fields}
    out = subprocess.run(
        ["curl", "-s", "-X", "POST", API,
         "-H", f"Authorization: Bearer {TOKEN}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, timeout=70).stdout
    return json.loads(out)["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 900) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        out = subprocess.run(
            ["curl", "-s", f"{API}/{task_id}",
             "-H", f"Authorization: Bearer {TOKEN}"],
            capture_output=True, text=True, timeout=40).stdout
        task = json.loads(out)["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(8)
    raise TimeoutError(task_id)

task_id = submit({
    "prompt": "...",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16",
})
task = wait(task_id)
video_url = task["output"][0]["url"]
subprocess.run(["curl", "-s", "-o", "clip.mp4", video_url], timeout=120)

Um detalhe operacional importante em produção: o output[0].url que você recebe é um link assinado com tempo limitado (com prazo de expiração). Baixe os bytes imediatamente após a tarefa ser concluída com sucesso e armazene no seu próprio bucket ou CDN — nunca salve a URL bruta da tarefa em um banco de dados ou CMS.

Projetar prompts para o gancho de 3 segundos

O sucesso de um vídeo curto depende do desempenho do primeiro segundo na tela. O padrão de prompt que funciona consistentemente para ganchos verticais: um sujet, uma ação contínua e satisfatória, luz descrita explicitamente e movimento de câmera expresso em linguagem cinematográfica. A seguir está o prompt exato do exemplo curl acima, e o clipe que ele produziu:

Vídeo vertical de formato curto. Um barista em um café especializado iluminado
pelo sol despeja uma arte latte rosetta perfeita em um movimento fluido, vapor
subindo, luz da manhã pela janela, profundidade de campo rasa, detalhe
fotorrealista nítido, leve movimento lento de aproximação.

Saída real — kling-3.0-omni/text-to-video, 5 s @ 720p, 9:16, sem áudio. Primeira geração, não editada.

O papel de cada elemento:

• "Vídeo vertical de formato curto" no início ancora as decisões de composição, não apenas a proporção de pixels — o modelo compõe para a tela do celular.
• Uma ação contínua ("despeja ... em um movimento fluido") dá ao modelo um único arco para renderizar, em vez de introduzir cortes aleatórios.
• "Leve movimento lento de aproximação" é uma instrução real de câmera. Palavras de humor vagas ("dinâmico", "envolvente") fazem o modelo improvisar; vocabulário de câmera o mantém nos trilhos.
• A luz merece uma frase inteira ("luz da manhã pela janela") — a luz é a diferença entre um "clipe de IA" e uma "filmagem real de set".

Áudio nativo: defina sound: true e descreva a paisagem sonora

O recurso de destaque do Kling 3.0 Omni é o áudio sincronizado nativo — o modelo renderiza uma trilha sonora que combina com a imagem, e para conteúdo gastronômico, ASMR e de rua, isso representa a maior parte da retenção. Duas coisas devem acontecer simultaneamente: definir "sound": true na entrada (cobrado na tarifa +áudio, $0.143/s em 720p) e descrever o áudio no prompt exatamente como você descreve a imagem:

Vídeo vertical de formato curto. Close-up do wok de um vendedor de comida de
rua à noite: alho em cubos e pimenta atingem óleo crepitante com uma explosão
de vapor, chamas lambem a borda do wok enquanto o vendedor joga o macarrão em
movimentos rítmicos, letreiros de neon brilhando em bokeh ao fundo. Sensação de
câmera na mão, apetitoso, alta energia.
Áudio nativo: crepitação alta, batidas de wok, conversas distantes na rua.

Saída real — kling-3.0-omni/text-to-video, 5 s @ 720p, 9:16, sound: true. Aumente o volume: a crepitação e o som das batidas do wok são gerados pelo modelo e sincronizados com o movimento de jogar o macarrão.

O padrão de sufixo "Áudio nativo:" — uma lista curta de dois ou três sons-chave separados por vírgulas — supera consistentemente descrições em prosa como "com efeitos sonoros realistas". Nomeie os sons e o modelo os sincronizará com os eventos visuais correspondentes.

Validamos a fronteira de cobrança na saída real com ffprobe: clipes enviados sem definir sound contêm apenas um stream de vídeo H.264, enquanto clipes com sound: true têm uma faixa de áudio AAC adicional. Você só paga o prêmio de áudio pelos clipes que o solicitam.

Narrativa multi-plano em um único prompt

Outro recurso diferenciador do Omni é a sequência multi-plano: você pode escrever cortes explícitos em uma única geração, em vez de juntar três clipes separados. Numere os planos no prompt e dê à sequência inteira uma correção de cor compartilhada, para que pareça uma edição e não um acidente:

Vídeo vertical de formato curto, sequência de três planos. Plano 1: uma jovem
com uma jaqueta de chuva amarela sai de uma saída de metrô sob uma chuva leve,
abre um guarda-chuva transparente. Plano 2: close-up das botas dela
respingando através de uma poça que reflete neon em câmera lenta. Plano 3: ela
para em um carrinho de comida, sorri enquanto vapor quente passa, luzes da
cidade em bokeh ao fundo. Correção de cor coesa em verde-azulado e âmbar,
energia cinematográfica de câmera na mão. Áudio nativo: chuva suave, ambiente
urbano, zumbido distante do trânsito.

Saída real — kling-3.0-omni/text-to-video, 10 s @ 720p, 9:16, sound: true. Três planos roteirizados, uma geração: $1.43.

Orce aproximadamente três segundos por plano — uma duração de 10 segundos funciona bem para uma história em três tempos. Âncoras recorrentes (a jaqueta de chuva amarela) são a chave para manter a consistência de identidade entre cortes; dê a cada prompt multi-plano uma constante visual marcante, caso contrário o sujeito pode variar entre planos.

Produção em lote: um template, muitas variantes

A economia fica interessante em escala. Uma semana de posts diários é um template de prompt com slots variáveis, enviado em paralelo — as tarefas renderizam em paralelo, então um lote termina em aproximadamente o tempo de um clipe. Pegamos o template do gancho de latte e trocamos o sujeito:

Vídeo vertical de formato curto. Uma tigela de cerâmica de matcha sendo batida
até virar uma espuma verde vívida com um batedor de bambu, em um bar de chá
especializado iluminado pelo sol, vapor subindo, luz da manhã pela janela,
profundidade de campo rasa, detalhe fotorrealista nítido, leve movimento
lento de aproximação.

Saída real — mesmo template do clipe de latte, apenas uma variável alterada. 5 s @ 720p, 9:16: $0.50.

O movimento de aproximação, a luz da janela e a profundidade de campo rasa foram preservados — exatamente a consistência visual de conta que você deseja. No código, o lote significa enviar antes de esperar:

TEMPLATE = ("Vídeo vertical de formato curto. {subject}, em um {venue} especializado "
            "iluminado pelo sol, vapor subindo, luz da manhã pela janela, profundidade de campo rasa, "
            "detalhe fotorrealista nítido, leve movimento lento de aproximação.")

VARIANTS = [
    {"subject": "Um barista despejando uma arte latte rosetta perfeita em um movimento fluido", "venue": "café"},
    {"subject": "Uma tigela de cerâmica de matcha sendo batida até virar uma espuma verde vívida com um batedor de bambu", "venue": "bar de chá"},
    {"subject": "Um croissant sendo aberto para revelar camadas brilhantes e fumegantes", "venue": "padaria"},
]

task_ids = [submit({
    "prompt": TEMPLATE.format(**v),
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16",
}) for v in VARIANTS]          # todos renderizando em paralelo

clips = [wait(tid) for tid in task_ids]

Planejamento de custos em 720p: 30 clipes de gancho de 5 segundos por mês custam $15; o mesmo mês com áudio nativo custa $21.45. Mesmo com um cronograma agressivo — clipes de 10 segundos com áudio todos os dias — fica em $42.90/mês, mais barato que uma hora do tempo de um editor de vídeo. Consulte os resultados conforme retornam e trate o estado fail de uma tarefa como um retry apenas daquela variante, não do lote inteiro.

Todo o conteúdo deste artigo custou $3.15 em geração de vídeo: quatro clipes, 25 segundos de material, todos gerados na primeira tentativa.

Próximos passos

Você agora tem o ciclo completo: enviar uma tarefa 9:16, consultá-la, obter o .mp4 e escalar com templates. Algumas dicas para o próximo passo:

• Obtenha a chave de API e a referência completa de endpoints na documentação da hiapi — o ciclo de vida da tarefa acima é idêntico para todos os modelos de vídeo da plataforma.
• Antes de comprometer com grandes lotes, verifique as tarifas atuais por segundo de todos os níveis na página de preços.
• Se você está escolhendo entre modelos para este caso de uso, executamos o mesmo fluxo de trabalho de vídeos curtos em um modelo econômico em Short-Form Video with seedance-2.0-mini — útil como referência de preço/qualidade para comparar com o Kling.

Comece com um clipe de teste de $0.50 do seu próprio sujeito, mantenha os elementos de prompt testados no feed e depois transforme o template em tarefas em lote na página do modelo kling-3.0-omni/text-to-video.