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

A API do Kling 4.0 na PoYo usa um único ID de modelo, kling-4.0, para texto para vídeo, geração com primeiro/último quadro, referências visuais e edição de vídeo. Envie uma requisição, guarde o ID da tarefa e faça polling até a tarefa terminar. Este guia segue o schema atual da PoYo, conferido em 24 de outubro de 2026; os nomes de campos de outros provedores não são intercambiáveis.

Abra o playground do Kling 4.0 para testar as entradas visualmente ou consulte a documentação da API.

Gere um primeiro vídeo com cURL

Defina POYO_API_KEY no ambiente do seu shell e envie esta requisição de cinco segundos. Mantenha a credencial no seu servidor, e não no código do navegador.

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"
    }
  }'

Leia data.task_id na resposta JSON; um envio bem-sucedido não é um vídeo pronto. Substitua 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 status documentados são not_started, running, finished e failed. Quando a tarefa terminar, procure em data.files o file_url do vídeo. Em caso de falha, verifique error_message e guarde o ID da tarefa para o diagnóstico. Consultar uma tarefa existente não exige enviá-la de novo.

Um loop de polling em Python com limite de tempo

Instale requests e execute isto no seu backend. O código verifica tanto erros HTTP quanto erros da aplicação, para quando a tarefa falha e limita a espera a 30 minutos. Um timeout significa que você deve consultar a mesma tarefa mais tarde; repetir o envio automaticamente pode criar um segundo job cobrá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)

Escolha o modo de entrada correto

O campo de vídeo de origem seleciona a edição mesmo que também haja imagens de referência. Em imagem para vídeo, a primeira imagem define o quadro inicial; uma segunda imagem define o quadro final. Imagens de referência orientam a identidade ou o estilo e não têm o mesmo significado que os quadros de início e fim.

Limites que vale validar antes do envio

A geração aceita durações inteiras de 3 a 30 segundos, em 720p ou 1080p. Um prompt normal é limitado a 26.000 caracteres neste schema da PoYo. Cada plano de multi_prompt aceita até 512 caracteres; se a duração do plano for omitida, o padrão é cinco segundos. A soma das durações dos planos deve ficar entre 3 e 30 segundos, e uma duração explícita no nível superior deve ser igual a esse total.

As referências permitem até 10 imagens, cinco vídeos e sete sujeitos, dentro de um limite combinado de 15 recursos. Um primeiro quadro conta tanto para o limite de imagens quanto para o limite geral. Cada vídeo de referência ou de sujeito deve ter de 3 a 30 segundos; a duração real somada não pode passar de 30 segundos. Não arredonde durações para baixo para fazer uma entrada grande demais passar na validação.

Entenda a primeira cobrança

Uma requisição de cinco segundos em 720p sem entrada de vídeo custa 142,5 créditos, ou US$ 0,7125 pela conversão listada atualmente. Uma entrada de vídeo muda tanto a tarifa quanto a duração cobrável. Veja os exemplos de preços antes de estimar um fluxo com vídeo de referência ou de edição.

O produto oficial para criadores anuncia controles adicionais, incluindo múltiplos keyframes. O schema da PoYo aqui expõe até dois quadros de início e fim e prompts por plano; não envie a este endpoint campos inventados como keyframes, seed, negative_prompt ou generate_audio. Para exemplos práticos, continue com o guia de prompts e o tutorial de 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 na requisição é kling-4.0.

Posso pedir 4K aqui? Este endpoint da PoYo aceita atualmente apenas 720p e 1080p. Consulte o schema do provedor em vez de copiar as especificações de marketing do app para criadores.

Posso usar um callback? A requisição de envio aceita um callback_url no nível superior. Consulte a documentação atual para o tratamento de callbacks; o exemplo de polling acima não depende disso.

Por onde começo? Faça primeiro uma requisição curta só com texto, guarde o ID da tarefa e o resultado e depois adicione uma modalidade de entrada por vez no playground.