how-tos

Guia da Kling Image 4.0 API: primeiro pedido com cURL e Python

Poyo.ai Team
10 min read
Share:

Guia da Kling Image 4.0 API: primeiro pedido com cURL e Python

Este guia da Kling Image 4.0 API leva-o de uma chave de API a uma imagem concluída: uma chamada cURL, um ciclo 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. Experimente qualquer um deles primeiro no playground do Kling Image 4.0; todos os corpos de pedido abaixo seguem a documentação da PoYo.

O seu primeiro pedido à 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 submeta 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 tem code: 200 e data.task_id, com status: "not_started". Uma tarefa submetida não é uma imagem concluída. Verifique-a com:

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

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

Um ciclo de polling em Python com limite

Isto corre no seu backend com requests. Verifica tanto o estado HTTP como o campo code no corpo (os erros de validação podem chegar como HTTP 200 com code: 400), para em failed e deixa de esperar ao fim de 20 minutos sem voltar a submeter, porque uma segunda submissão é uma segunda fatura.

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, acrescente antes 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 invólucro 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úblicos em image_urls. O primeiro é @Image1, o segundo @Image2, pela ordem do array. Dê a cada um uma função no prompt e diga o que tem de 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 tem de 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.

Sujeitos consistentes com kling_elements

Um elemento é uma 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 pode passar até 7; imagens mais elementos estão limitados a 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"
  }
}

Este pedido 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 (predefinição 4) e o modelo planeia as imagens como uma série com os mesmos sujeitos e estilo, devolvidas por ordem. Com a opção desligada, n de 1 a 9 devolve 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 devolveu quatro imagens de 2720×1536 com o mesmo motociclista, mota e roupa ao longo da madrugada, do meio-dia, do pôr do sol e da noite. Custa 52 créditos e demorou cerca de 4.9 minutos da submissão ao resultado.

Páginas web longas e páginas de ecommerce

Mude o ID de modelo para kling-4.0-long-image e escolha um skill. Um design de página web, opcionalmente a seguir 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 detalhe de ecommerce a partir de uma fotografia 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: indique o idioma da página. No nosso teste, um prompt de página web em inglês que não dizia em que idioma devia estar o texto devolveu texto em chinês na página. Acrescentar "All text on the page is in English." ao prompt resolveu, e é por isso que ambos os corpos acima terminam com essa linha. O nosso teste de página web em 1K devolveu 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.

Guardar os resultados

Cada files[].file_url aponta para um PNG. Copie-o para o seu próprio armazenamento em vez de o ligar diretamente a partir da sua app. Três aspetos do nosso teste do dia do lançamento a prever:

  • Tamanho. Uma imagem 16:9 em 8K foi um PNG de 10880×6144 com cerca de 128 MB. Escreva-o em disco por streaming em vez de o carregar em memória, e aumente o timeout de leitura do seu cliente.
  • Canal alfa. As transferências foram PNG RGBA mesmo para imagens opacas. Se o seu pipeline, CDN ou fluxo de impressão espera RGB ou JPEG, converta após a transferência.
  • Ordem. Uma série de imagens é devolvida por ordem, por isso o índice em files é o número do fotograma do seu storyboard ou conjunto de diapositivos.

Regras de validação a verificar antes de submeter

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 extra (output_format, seed, negative_prompt são rejeitados)ambos

Erros a tratar

codeSignificadoO que fazer
400Parâmetros inválidosCorrija o corpo; não repita sem alterações
401Chave de API em falta ou inválidaVerifique o cabeçalho
402Créditos insuficientesCarregue créditos e volte a submeter
429Limite de pedidosAbrande e tente mais tarde
500 / 502 / 503Erro do servidor ou do fornecedorRepita a submissão com backoff

Uma tarefa failed não é cobrada, por isso voltar a submeter após uma falha é seguro. Voltar a submeter após um timeout do seu lado não é: consulte primeiro o mesmo task_id.

Como é calculada a sua primeira fatura

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 pedido. Com 1 crédito = $0.005:

PedidoCré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 ecommerce medium em 1K, 1 fotografia 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 ciclo acima faz isto 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 ecommerce. kling-4-0-image é apenas o slug da página.

A Kling Image 4.0 API suporta webhooks? Sim. Acrescente callback_url no nível superior do pedido. 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. As nossas transferências foram PNG RGBA mesmo para imagens opacas, por isso converta do seu lado se precisar de JPEG.

Porque é que a minha página web longa do Kling Image 4.0 veio noutro idioma? Se o prompt não indicar o idioma do texto da página, o modelo pode escolher um. Indique-o, por exemplo "All text on the page is in English."

Share: