Guia da API do Kling 4.0: o teu primeiro vídeo com Python e cURL

A API do Kling 4.0 no PoYo usa um único ID de modelo, kling-4.0, para texto para vídeo, geração com primeiro e último frame, referências visuais e edição de vídeo. Submete um pedido, guarda o respetivo ID de tarefa e consulta o estado até a tarefa terminar. Este guia segue o esquema atual do PoYo, verificado a 24 de outubro de 2026; os nomes de campos de outro fornecedor não são intermutáveis.

Abre o playground do Kling 4.0 para experimentares as entradas de forma visual, ou consulta a documentação da API.

Gerar um primeiro vídeo com cURL

Define POYO_API_KEY no ambiente da tua shell e submete depois este pedido de cinco segundos. Mantém a credencial no teu servidor e não em código de browser.

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-4.0",
    "input": {
      "prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Lê data.task_id na resposta JSON; uma submissão bem-sucedida não é um vídeo concluído. Substitui YOUR_TASK_ID abaixo por esse valor:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Os estados documentados são not_started, running, finished e failed. Quando estiver finished, procura em data.files o file_url de um vídeo. Em caso de falha, inspeciona error_message e guarda o ID da tarefa para diagnóstico. Para consultar uma tarefa existente não é preciso submetê-la outra vez.

Um ciclo de consulta em Python com limite

Instala o requests e executa isto no teu backend. Verifica tanto os erros HTTP como os da aplicação, pára se a tarefa falhar e limita a espera a 30 minutos. Um tempo limite esgotado significa que deves voltar a consultar a mesma tarefa mais tarde; repetir automaticamente a submissão pode criar uma segunda tarefa faturável.

import os
import time
import requests

base = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") not in (0, 200):
        raise RuntimeError(body.get("message") or "PoYo API error")
    return body["data"]

task = checked(session.post(base + "/api/generate/submit", json={
    "model": "kling-4.0",
    "input": {
        "prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    task = checked(session.get(
        base + "/api/generate/status/" + task_id, timeout=60))
    if task["status"] == "failed":
        raise RuntimeError(task.get("error_message") or "Generation failed")
    if task["status"] == "finished":
        videos = [f["file_url"] for f in task.get("files", [])
                  if f.get("file_type") == "video"]
        if not videos:
            raise RuntimeError("Finished task returned no video")
        print(videos[0])
        break
    time.sleep(10)
else:
    raise TimeoutError("Check the saved task ID again: " + task_id)

Escolher o modo de entrada correto

O campo do vídeo de origem seleciona a edição, mesmo que também existam imagens de referência. Em imagem para vídeo, a primeira imagem estabelece o frame inicial; uma segunda imagem define o frame final. As imagens de referência orientam a identidade ou o estilo e não significam o mesmo que os frames de limite.

Limites que vale a pena validar antes de submeter

A geração suporta durações inteiras de 3 a 30 segundos, em 720p ou 1080p. Neste esquema do PoYo, um prompt normal está limitado a 26 000 carateres. Cada plano de multi_prompt aceita até 512 carateres; se a duração de um plano for omitida, é de cinco segundos por predefinição. As durações dos planos têm de somar entre 3 e 30 segundos, e uma duração explícita de nível superior tem de ser igual a essa soma.

As referências permitem até 10 imagens, cinco vídeos e sete sujeitos, dentro de um limite combinado de 15 assets. Um primeiro frame conta tanto para o limite de imagens como para o limite global. Cada vídeo de referência ou de sujeito tem de durar entre 3 e 30 segundos; a duração real combinada não pode ultrapassar os 30 segundos. Não arredondes as durações por defeito só para que uma entrada demasiado grande passe na validação.

Perceber a primeira fatura

Um pedido de cinco segundos em 720p sem entrada de vídeo custa 142,5 créditos, ou $0.7125 à conversão atualmente indicada. Uma entrada de vídeo altera tanto a tarifa como a duração faturável. Consulta os exemplos de preços antes de estimares um fluxo com vídeo de referência ou com edição.

O produto oficial para criadores anuncia controlos adicionais, incluindo vários keyframes. O esquema do PoYo aqui descrito expõe até dois frames de limite e prompts por plano; não envies para este endpoint campos inventados como keyframes, seed, negative_prompt ou generate_audio. Para exemplos práticos, continua com o guia de prompts e o tutorial do Omni Reference.

Perguntas frequentes

O ID do modelo na API é kling-4-0? Não. Esse é o slug da página. O ID do modelo no pedido é kling-4.0.

Posso pedir 4K aqui? Este endpoint do PoYo aceita atualmente apenas 720p e 1080p. Consulta o esquema do fornecedor em vez de copiares as especificações de marketing da aplicação para criadores.

Posso usar um callback? O pedido de submissão suporta um callback_url de nível superior. Consulta a documentação atual para saberes como tratar o callback; o exemplo de consulta acima não depende dele.

Por onde começo? Usa primeiro um pedido curto só com texto, guarda o ID da tarefa e o resultado, e depois acrescenta uma modalidade de entrada de cada vez no playground.