how-tos

Guia da Kling Image 4.0 API: primeira requisição com cURL e Python

Poyo.ai Team
9 min read
Share:

Guia da Kling Image 4.0 API: primeira requisição com cURL e Python

Este guia da Kling Image 4.0 API leva você de uma chave de API até uma imagem pronta: uma chamada cURL, um loop de polling em Python com limite de tempo e, depois, um corpo JSON funcional para cada modo de entrada de kling-4.0-image e kling-4.0-long-image. Teste qualquer um deles primeiro no playground do Kling Image 4.0; todos os corpos de requisição abaixo seguem a documentação da PoYo.

Sua primeira requisição à Kling Image 4.0 API com cURL

Crie uma chave no painel da PoYo e guarde-a no seu servidor como POYO_API_KEY. Depois envie uma tarefa de texto para imagem em 2K:

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-image",
    "input": {
      "prompt": "High fashion model wearing a dress made of living moss, standing in an abandoned greenhouse, shafts of light, editorial photography",
      "size": "16:9",
      "resolution": "2K"
    }
  }'

A resposta traz code: 200 e data.task_id, com status: "not_started". Uma tarefa enviada não é uma imagem pronta. Verifique-a com:

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

Os status são not_started, running, finished e failed. Com finished, data.files traz uma entrada por imagem com file_url e file_type: "image", e data.credits_amount mostra quanto a tarefa custou. Com failed, leia data.error_message.

Um loop de polling em Python com limite

Este código roda no seu backend com requests. Ele verifica tanto o status HTTP quanto o campo code no corpo (erros de validação podem chegar como HTTP 200 com code: 400), para em failed e desiste de esperar depois de 20 minutos sem reenviar, porque um segundo envio é uma segunda cobrança.

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(resp):
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 200:
        raise RuntimeError(f"PoYo error {body.get('code')}: {body.get('error')}")
    return body["data"]

def run(payload, max_wait=1200, every=10):
    task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
    task_id = task["task_id"]
    deadline = time.monotonic() + max_wait
    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":
            return [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
        time.sleep(every)
    raise TimeoutError("still running, poll task " + task_id + " again later")

urls = run({
    "model": "kling-4.0-image",
    "input": {
        "prompt": "A ceramic pour-over kettle on a walnut counter, morning window light",
        "size": "1:1",
        "resolution": "2K",
    },
})
print(urls)

Para trabalhos longos, adicione em vez disso um "callback_url": "https://your-domain.com/poyo-hook" no nível superior do payload. A PoYo envia por POST os mesmos dados da tarefa (sem o envelope code/data) quando a tarefa termina ou falha, assinados com HMAC-SHA256 em X-Webhook-Signature; a documentação de webhooks mostra como verificar.

Imagem para imagem com image_urls

Passe de 1 a 10 URLs HTTP(S) públicas em image_urls. A primeira é @Image1, a segunda @Image2, na ordem do array. Dê a cada uma um papel no prompt e diga o que precisa ficar inalterado.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Turn @Image1 into a late-evening scene with warm window light. Keep the furniture, layout and camera angle of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "resolution": "2K"
  }
}

image_urls precisa ser um array mesmo para uma única imagem. Cada imagem deve ter no máximo 30 MB, pelo menos 300 px de largura e de altura, e uma proporção largura/altura entre 0.4 e 2.5.

Objetos consistentes com kling_elements

Um elemento é um personagem ou objeto mostrado de 2 a 4 ângulos, com a vista frontal primeiro. Os elementos precisam de pelo menos uma entrada em image_urls, e você pode passar até 7; imagens mais elementos têm limite de 10.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Place @Element1 sitting on the sofa in @Image1, reading a book in warm evening light. Keep the room layout of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "kling_elements": [
      {
        "element_input_urls": [
          "https://example.com/character-front.png",
          "https://example.com/character-side.png",
          "https://example.com/character-back.png"
        ]
      }
    ],
    "resolution": "2K"
  }
}

Esta requisição custa 13 créditos pela imagem 2K mais 1 pela imagem de referência e 1 pelo elemento: 15 créditos ($0.075).

Séries de imagens com enable_sequential

Com enable_sequential: true, n vai de 2 a 10 (padrão 4) e o modelo planeja as imagens como uma série com os mesmos objetos e estilo, retornadas em ordem. Com a opção desligada, n de 1 a 9 retorna imagens independentes.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "A four-panel story of a paper boat drifting from a rainy city gutter to a calm sunny lake, same boat in every panel, watercolor style",
    "size": "3:2",
    "enable_sequential": true,
    "n": 4
  }
}

No nosso teste do dia do lançamento (API de produção da PoYo, 19 de novembro de 2026), uma série 16:9 em 2K com n: 4 retornou quatro imagens de 2720×1536 com o mesmo piloto, moto e roupa ao longo do amanhecer, do meio-dia, do pôr do sol e da noite. Custa 52 créditos e levou cerca de 4.9 minutos do envio ao resultado.

Páginas web longas e páginas de e-commerce

Troque o ID de modelo para kling-4.0-long-image e escolha um skill. Um design de página web, opcionalmente seguindo uma referência de estilo:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a long image for a specialty coffee brand's official website, including the hero section, product showcase, roasting philosophy, store information, and footer. Follow the visual style of @StyleImage. All text on the page is in English.",
    "skill": "webpage",
    "style_image_url": "https://example.com/style-reference.png",
    "resolution": "2K"
  }
}

Uma página de detalhes de e-commerce a partir de uma foto de produto:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a product detail page for the insulated water bottle in @Image1: hero shot, key features, capacity and size, materials, and lifestyle scenes. All text on the page is in English.",
    "skill": "ecommerce",
    "image_urls": ["https://example.com/water-bottle.png"],
    "length": "medium",
    "resolution": "1K"
  }
}

Dica: informe o idioma da página. No nosso teste, um prompt de página web em inglês que não dizia em qual idioma o texto deveria estar voltou com texto em chinês na página. Adicionar "All text on the page is in English." ao prompt resolveu, e é por isso que os dois corpos acima terminam com essa linha. Nosso teste de página web em 1K retornou uma imagem de 1024×4257 por 110 créditos em cerca de 1.7–2.2 minutos.

image_urls e length pertencem a ecommerce; style_image_url e subject_image_url pertencem a webpage. Mais sobre comprimentos de página e saída em 8K em 8K e imagens longas com a Kling Image 4.0 API.

Salvando os resultados

Cada files[].file_url aponta para um PNG. Copie-o para o seu próprio armazenamento em vez de fazer hotlink a partir do seu app. Três pontos do nosso teste do dia do lançamento para planejar:

  • Tamanho. Uma imagem 16:9 em 8K foi um PNG de 10880×6144 com cerca de 128 MB. Grave-o em disco via streaming em vez de carregá-lo na memória, e aumente o timeout de leitura do seu cliente.
  • Canal alfa. Os downloads foram PNGs RGBA mesmo para imagens opacas. Se o seu pipeline, CDN ou fluxo de impressão espera RGB ou JPEG, converta depois do download.
  • Ordem. Uma série de imagens volta em ordem, então o índice em files é o número do quadro do seu storyboard ou conjunto de slides.

Regras de validação para conferir antes de enviar

RegraModelo
prompt com 1–50,000 caracteres, não só espaços em brancoambos
image_urls com 1–10 itens; 30 MB, ≥300 px, proporção 0.4–2.5 cadakling-4.0-image
kling_elements ≤ 7, cada um com 2–4 URLs, só com image_urls; imagens + elementos ≤ 10kling-4.0-image
n 1–9 sem série, 2–10 com enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" precisa de 1–3 image_urls; resolution 1K / 2Kkling-4.0-long-image
Sem campos extras (output_format, seed, negative_prompt são rejeitados)ambos

Erros que vale tratar

codeSignificadoO que fazer
400Parâmetros inválidosCorrija o corpo; não repita sem alterações
401Chave de API ausente ou inválidaVerifique o header
402Créditos insuficientesRecarregue e reenvie
429Limite de taxaEspere e tente de novo mais tarde
500 / 502 / 503Erro do servidor ou do provedorRepita o envio com backoff

Uma tarefa failed não é cobrada, então reenviar depois de uma falha é seguro. Reenviar depois de um timeout do seu lado não é: consulte primeiro o mesmo task_id.

Como sua primeira cobrança é calculada

kling-4.0-image custa o preço por imagem vezes o número de imagens, mais 1 crédito por cada item de image_urls e cada elemento, uma vez por requisição. Com 1 crédito = $0.005:

RequisiçãoCréditosUSD
Primeira chamada cURL acima (2K, uma imagem)13$0.065
O mesmo prompt em 8K32$0.16
Edição com elemento acima (2K, 1 imagem + 1 elemento)15$0.075
Série de quatro imagens em 2K52$0.26
Página web em 1K, sem referências110$0.55
Página de e-commerce medium em 1K, 1 foto de produto95$0.475

Tabelas completas e mais exemplos estão em preços da Kling Image 4.0 API. Para uma visão geral dos dois IDs de modelo, veja o que é o Kling Image 4.0.

Perguntas frequentes

Como chamo a Kling Image 4.0 API com Python? Envie por POST o corpo JSON para https://api.poyo.ai/api/generate/submit com requests, leia data.task_id, depois consulte /api/generate/status/{task_id} até finished e leia files[].file_url. O loop acima faz isso com prazo limite e verificação de erros.

Qual é o ID de modelo da Kling Image 4.0 API? kling-4.0-image para texto para imagem, edições e séries de imagens, e kling-4.0-long-image para páginas web longas e páginas de e-commerce. kling-4-0-image é só o slug da página.

A Kling Image 4.0 API suporta webhooks? Sim. Adicione callback_url no nível superior da requisição. A PoYo envia um POST assinado quando a tarefa termina ou falha.

Posso obter JPEG da Kling Image 4.0 API? Não existe campo de formato de saída; os resultados são PNG. Nossos downloads foram PNGs RGBA mesmo para imagens opacas, então converta do seu lado se precisar de JPEG.

Por que minha página web longa do Kling Image 4.0 voltou em outro idioma? Se o prompt não informar o idioma do texto da página, o modelo pode escolher um. Informe-o, por exemplo "All text on the page is in English."

Share: