Kling 3.0 API: código da requisição de texto para vídeo e clipes reais

Uma tarefa de texto para vídeo do Kling 3.0 é um POST para https://api.omniakey.com/v1/media/tasks com o id de modelo kling-3.0, a operação text_to_video e dois parâmetros obrigatórios: duration (5, 10 ou 15 segundos) e mode (std ou pro). A resposta traz um id de tarefa; consulte até ela concluir e baixe o MP4. Em 29 de outubro de 2026 fizemos dois clipes de 5 segundos no modo std em 1280×720 e medimos os arquivos e os quadros.

O que uma requisição do Kling 3.0 leva

O corpo da requisição tem sete campos. Dois deles, duration e mode, são obrigatórios no Kling e definem o tamanho do clipe e a faixa de qualidade.

O exemplo da própria página do modelo envia duration 6 e um campo resolution com 720p, e nenhum dos dois serve aqui: a página aceita apenas 5, 10 ou 15 segundos e diz que não existe campo de resolução separado (página do modelo, consultada em 29 de outubro de 2026). As perguntas frequentes da página associam a saída standard a 720P e a pro a 1080P.

O áudio vem por padrão e a página não lista nenhum botão para desligar (consultada em 29 de outubro de 2026). A proporção se aplica a texto para vídeo; imagem para vídeo tira o formato do primeiro quadro e recusa uma proporção explícita. As duas execuções abaixo usaram std, 5 segundos e 16:9, e ficaram de fora o modo pro, 10 s e 15 s, 9:16 e 1:1, imagem para vídeo e um último quadro.

O texto do prompt define a cena, a ação e a câmera. O guia de prompts do Kling 3.0 cobre as partes de um prompt e a linguagem de câmera.

O código da requisição

Um arquivo Python envia o corpo, consulta a tarefa e baixa o MP4. Ele lê a chave de OMNIAKEY_API_KEY, coloca um Idempotency-Key aleatório na requisição de criação e espera 5 segundos entre as consultas, por até 180 tentativas. O corpo leva os mesmos campos e valores dos dois clipes da próxima seção: modelo kling-3.0, type video, operation text_to_video, duration 5, mode std, proporção 16:9.

import json
import os
import time
import urllib.error
import urllib.request
import uuid

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]

def request(method, url, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    headers.update(extra_headers or {})
    req = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.load(resp)

def poll(url, attempts=5):
    for attempt in range(attempts):
        try:
            return request("GET", url)
        except urllib.error.HTTPError as err:
            if err.code < 500 or attempt == attempts - 1:
                raise
        except urllib.error.URLError:
            if attempt == attempts - 1:
                raise
        time.sleep(5 * (attempt + 1))

def text_to_video(prompt, out_path, duration=5, mode="std", aspect_ratio="16:9"):
    body = {
        "model": "kling-3.0",
        "type": "video",
        "operation": "text_to_video",
        "input": {"prompt": prompt},
        "parameters": {"duration": duration, "mode": mode, "aspect_ratio": aspect_ratio},
    }
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    print("task", task, flush=True)
    for _ in range(180):
        time.sleep(5)
        state = poll(f"{API}/{task}")
        if state["status"] not in ("queued", "processing"):
            break
    if state["status"] != "succeeded":
        raise RuntimeError(state.get("error") or state["status"])
    asset_url = state["assets"][0]["url"]  # link assinado: dura pouco, então baixe agora
    req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"})
    with urllib.request.urlopen(req, timeout=300) as resp, open(out_path, "wb") as f:
        f.write(resp.read())
    return task

if __name__ == "__main__":
    task = text_to_video(
        "A paper boat drifts slowly down a rain-soaked street at dusk. Warm streetlights reflect on "
        "the wet cobblestones. The camera follows the boat at a steady pace. No people, no text.",
        "paper-boat.mp4",
    )
    print("done", task)

Cada consulta é um GET no caminho da tarefa, e o laço acompanha o status, não progress.percent, que pode ficar em 0 enquanto o clipe renderiza. Quando o status sai de queued ou processing, o código para: succeeded leva ao download de assets[0].url, e qualquer outro status lança a mensagem de erro da própria tarefa. O download sai na hora porque esse link do arquivo expira; peça a tarefa de novo para pegar um link novo quando isso acontecer. Uma consulta que esbarra em conexão caída ou em erro de servidor (5xx) é repetida até cinco vezes, com pausa maior a cada tentativa.

Rodamos esse arquivo mais uma vez em 29 de outubro de 2026, com os mesmos ajustes. A primeira tentativa perdeu a conexão durante o polling, e é por isso que a consulta agora repete. A segunda execução devolveu a tarefa task_PNB1kPopriUyfcHsXhVWY2hBOEoSUIqM, e o MP4 dela mediu 5.04 segundos em 1280×720 com uma faixa AAC estéreo. Da criação ao download foram 807 segundos, contra 82.2 e 110.7 segundos dos dois clipes abaixo, então reserve folga para esperas longas.

Dois clipes que fizemos

As duas requisições saíram em 29 de outubro de 2026 com o corpo listado acima. A tarefa do barco de papel é task_cbOtsBxO75cml3nOmVUu9YG3PkYXW2ja e a do bule é task_M2Ub1EoCaCUa1FjOZDdWDOuEOS9nRjnt. Cada prompt foi enviado exatamente como escrito.

Barco de papel

A paper boat drifts slowly down a rain-soaked street at dusk. Warm streetlights reflect on the wet cobblestones. The camera follows the boat at a steady pace. No people, no text.

Bule

A ceramic teapot sits on a wooden table by a window. Steam rises in slow curls. Soft morning light moves across the table. The camera pushes in slowly. No people, no text.

O que os arquivos mediram

Uma ferramenta de clipes mediu cada download em 29 de outubro de 2026.

• Barco de papel — Tamanho: 1280×720; Taxa de quadros: 24.0 fps; Duração: 5.04 s; Áudio: AAC, 2 canais, 44.1 kHz; Nível médio: −50.9 dB; Nível máximo: −34.0 dB; Cortes: nenhum
• Bule — Tamanho: 1280×720; Taxa de quadros: 24.0 fps; Duração: 5.04 s; Áudio: AAC, 2 canais, 44.1 kHz; Nível médio: −54.3 dB; Nível máximo: −35.9 dB; Cortes: nenhum
• Clipe do código — Tamanho: 1280×720; Taxa de quadros: 24.0 fps; Duração: 5.04 s; Áudio: AAC, 2 canais, 44.1 kHz; Nível médio: −48.4 dB; Nível máximo: −20.0 dB; Cortes: nenhum

Os dois primeiros clipes são bem baixos: níveis médios de −50.9 dB e −54.3 dB, com picos de −34.0 dB e −35.9 dB. O clipe do código é mais alto, com média de −48.4 dB e pico de −20.0 dB. Medimos só o nível; o conteúdo das faixas ficou fora da medição. O detector de mudança de plano não achou nenhum corte forte ou fraco nos três, então cada clipe roda como um plano só.

O que os quadros mostram

Os dois clipes seguem o prompt, e o bule acrescenta um pequeno movimento próprio.

No clipe do barco de papel, o barco fica perto do meio do quadro durante os 5.04 segundos enquanto a rua molhada desliza atrás dele, então a tomada lê como uma câmera que acompanha o barco. Os reflexos quentes dos postes continuam nas pedras até o último quadro (quadros conferidos em 29 de outubro de 2026). Nenhum corte interrompe o acompanhamento.

No clipe do bule, o vapor sobe em espirais lentas e some, e a luz da manhã se move pela mesa de madeira. O bule termina maior e mais para o canto inferior direito do que começou, o que lê como um push-in com um pouco de desvio lateral; o prompt pediu um push-in lento, e o desvio é algo que o prompt não pediu (quadros conferidos em 29 de outubro de 2026).

Erros e limites

Uma duração fora de 5, 10 e 15 devolve HTTP 400 model_price_error, e nenhum job é criado (documentação da API de vídeo, consultada em 29 de outubro de 2026). Envie segundos inteiros entre os três valores permitidos.

Uma requisição de criação sem Idempotency-Key devolve 400 missing_idempotency_key; a chave pode ter até 255 caracteres. A mesma chave com o mesmo corpo devolve a tarefa existente com HTTP 200 e nada novo é cobrado, enquanto um corpo alterado com essa chave devolve 409 idempotency_key_reused (visão geral da API de mídia, consultada em 29 de outubro de 2026).

Em 29 de outubro de 2026, um POST com o User-Agent padrão do urllib do Python devolveu HTTP 403 com o corpo error code: 1010 vindo da Cloudflare, e o nosso próprio cabeçalho User-Agent chegou à API. Defina um User-Agent na requisição de criação e no download.

Os links de saída duram pouco: peça a tarefa de novo para um assets[].url novo em vez de guardar um (documentação da API de vídeo, consultada em 29 de outubro de 2026). Os registros de tarefa ficam guardados por 24 horas após a criação (visão geral da API de mídia, consultada em 29 de outubro de 2026).

O Kling 3.0 é cobrado por geração, não por segundo (documentação da API de vídeo, consultada em 29 de outubro de 2026). Para os valores atuais, veja a página de preços da OmniaKey.

Perguntas frequentes

Quais durações o kling-3.0 aceita?

5, 10 e 15 segundos. Qualquer outro valor devolve HTTP 400 model_price_error e não cria job (documentação da API de vídeo, consultada em 29 de outubro de 2026).

Qual é a diferença entre std e pro?

A página do modelo chama os dois de Standard e Pro e associa a saída standard a 720P e a pro a 1080P (consultada em 29 de outubro de 2026). Rodamos só std, então não temos diferença medida entre os dois.

Os clipes têm som?

Todo clipe traz uma faixa AAC com dois canais a 44.1 kHz. Os dois primeiros são bem baixos, com níveis médios de −50.9 dB e −54.3 dB; o clipe do código é mais alto, com média de −48.4 dB e pico de −20.0 dB. Medimos só o nível e deixamos o conteúdo sem identificar.

Posso começar um clipe a partir de uma imagem?

A página do modelo lista imagem para vídeo com um primeiro quadro e um último quadro opcional (consultada em 29 de outubro de 2026). O primeiro quadro define a proporção, e uma proporção explícita é recusada nessa operação.

Quanto tempo um clipe leva para ser gerado?

Nas nossas duas execuções de 29 de outubro de 2026, o barco de papel terminou em 110.7 segundos e o bule em 82.2 segundos. Os dois eram clipes de 5 segundos, std, em 16:9.

Comece pela página do modelo Kling 3.0 e envie o mesmo corpo com o seu próprio prompt.