how-tos

Guía de la Kling Image 4.0 API: primera petición con cURL y Python

Poyo.ai Team
10 min read
Share:

Guía de la Kling Image 4.0 API: primera petición con cURL y Python

Esta guía de la Kling Image 4.0 API te lleva de una clave de API a una imagen terminada: una llamada con cURL, un bucle de sondeo en Python con límite de tiempo y, después, un cuerpo JSON funcional para cada modo de entrada de kling-4.0-image y kling-4.0-long-image. Prueba cualquiera de ellos primero en el playground de Kling Image 4.0; todos los cuerpos de petición de abajo siguen la documentación de PoYo.

Tu primera petición a la Kling Image 4.0 API con cURL

Crea una clave en el panel de PoYo y guárdala en tu servidor como POYO_API_KEY. Después envía una tarea de texto a imagen en 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"
    }
  }'

La respuesta tiene code: 200 y data.task_id, con status: "not_started". Una tarea enviada no es una imagen terminada. Compruébala con:

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

Los estados son not_started, running, finished y failed. Con finished, data.files contiene una entrada por imagen con file_url y file_type: "image", y data.credits_amount muestra lo que costó la tarea. Con failed, lee data.error_message.

Un bucle de sondeo en Python con límite

Esto se ejecuta en tu backend con requests. Comprueba tanto el estado HTTP como el campo code del cuerpo (los errores de validación pueden llegar como HTTP 200 con code: 400), se detiene ante failed y deja de esperar tras 20 minutos sin volver a enviar, porque un segundo envío es una segunda factura.

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 trabajos largos, añade en su lugar un "callback_url": "https://your-domain.com/poyo-hook" en el nivel superior del payload. PoYo envía por POST los mismos datos de la tarea (sin el envoltorio code/data) cuando la tarea termina o falla, firmados con HMAC-SHA256 en X-Webhook-Signature; la documentación de webhooks explica cómo verificarlo.

Imagen a imagen con image_urls

Pasa de 1 a 10 URLs HTTP(S) públicas en image_urls. La primera es @Image1, la segunda @Image2, en el orden del array. Da a cada una un papel en el prompt e indica qué debe quedar sin cambios.

{
  "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 debe ser un array incluso para una sola imagen. Cada imagen debe pesar como máximo 30 MB, medir al menos 300 px de ancho y de alto, y tener una relación ancho/alto entre 0.4 y 2.5.

Sujetos coherentes con kling_elements

Un elemento es un personaje u objeto mostrado desde 2 a 4 ángulos, con la vista frontal primero. Los elementos necesitan al menos una entrada en image_urls, y puedes pasar hasta 7; imágenes más elementos tienen un máximo 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 petición cuesta 13 créditos por la imagen en 2K más 1 por la imagen de referencia y 1 por el elemento: 15 créditos ($0.075).

Series de imágenes con enable_sequential

Con enable_sequential: true, n va de 2 a 10 (por defecto 4) y el modelo planifica las imágenes como una serie con los mismos sujetos y estilo, devueltas en orden. Con la opción desactivada, n de 1 a 9 devuelve imágenes independientes.

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

En nuestra prueba del día del lanzamiento (API de producción de PoYo, 19 de noviembre de 2026), una serie 16:9 en 2K con n: 4 devolvió cuatro imágenes de 2720×1536 con el mismo piloto, moto y atuendo a lo largo del amanecer, el mediodía, el atardecer y la noche. Cuesta 52 créditos y tardó unos 4.9 minutos del envío al resultado.

Páginas web largas y páginas de ecommerce

Cambia el ID de modelo a kling-4.0-long-image y elige un skill. Un diseño de página web, opcionalmente siguiendo una referencia 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"
  }
}

Una página de detalle de ecommerce a partir de una foto de producto:

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

Consejo: indica el idioma de la página. En nuestra prueba, un prompt de página web en inglés que no decía en qué idioma debía estar el texto devolvió texto en chino en la página. Añadir "All text on the page is in English." al prompt lo solucionó, y por eso ambos cuerpos de arriba terminan con esa línea. Nuestra prueba de página web en 1K devolvió una imagen de 1024×4257 por 110 créditos en unos 1.7–2.2 minutos.

image_urls y length pertenecen a ecommerce; style_image_url y subject_image_url pertenecen a webpage. Más sobre longitudes de página y salida en 8K en 8K e imágenes largas con la Kling Image 4.0 API.

Guardar los resultados

Cada files[].file_url apunta a un PNG. Cópialo a tu propio almacenamiento en lugar de enlazarlo directamente desde tu app. Tres cosas de nuestra prueba del día del lanzamiento que conviene prever:

  • Tamaño. Una imagen 16:9 en 8K fue un PNG de 10880×6144 de unos 128 MB. Escríbelo en disco por streaming en lugar de cargarlo en memoria, y aumenta el timeout de lectura de tu cliente.
  • Canal alfa. Las descargas fueron PNG RGBA incluso para imágenes opacas. Si tu pipeline, CDN o flujo de impresión espera RGB o JPEG, convierte tras la descarga.
  • Orden. Una serie de imágenes se devuelve en orden, así que el índice en files es el número de fotograma de tu storyboard o presentación.

Reglas de validación que conviene revisar antes de enviar

ReglaModelo
prompt de 1–50,000 caracteres, no solo espacios en blancoambos
image_urls de 1–10 elementos; 30 MB, ≥300 px, relación 0.4–2.5 cada unokling-4.0-image
kling_elements ≤ 7, cada uno con 2–4 URLs, solo con image_urls; imágenes + elementos ≤ 10kling-4.0-image
n 1–9 sin serie, 2–10 con enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" necesita 1–3 image_urls; resolution 1K / 2Kkling-4.0-long-image
Sin campos adicionales (output_format, seed, negative_prompt se rechazan)ambos

Errores que conviene gestionar

codeSignificadoQué hacer
400Parámetros no válidosCorrige el cuerpo; no reintentes sin cambios
401Clave de API ausente o no válidaRevisa la cabecera
402Créditos insuficientesRecarga y vuelve a enviar
429Límite de tasaEspera y reintenta más tarde
500 / 502 / 503Error del servidor o del proveedorReintenta el envío con backoff

Una tarea failed no se cobra, así que volver a enviar tras un fallo es seguro. Volver a enviar tras un timeout en tu lado no lo es: consulta primero la misma task_id.

Cómo se calcula tu primera factura

kling-4.0-image cuesta el precio por imagen multiplicado por el número de imágenes, más 1 crédito por cada elemento de image_urls y cada elemento de kling_elements, una vez por petición. Con 1 crédito = $0.005:

PeticiónCréditosUSD
Primera llamada cURL de arriba (2K, una imagen)13$0.065
El mismo prompt en 8K32$0.16
Edición con elemento de arriba (2K, 1 imagen + 1 elemento)15$0.075
Serie de cuatro imágenes en 2K52$0.26
Página web en 1K, sin referencias110$0.55
Página de ecommerce medium en 1K, 1 foto de producto95$0.475

Las tablas completas y más ejemplos están en precios de la Kling Image 4.0 API. Para una visión general de ambos IDs de modelo, consulta qué es Kling Image 4.0.

Preguntas frecuentes

¿Cómo llamo a la Kling Image 4.0 API con Python? Envía por POST el cuerpo JSON a https://api.poyo.ai/api/generate/submit con requests, lee data.task_id y después consulta /api/generate/status/{task_id} hasta que esté finished y lee files[].file_url. El bucle de arriba lo hace con un plazo límite y comprobación de errores.

¿Cuál es el ID de modelo de la Kling Image 4.0 API? kling-4.0-image para texto a imagen, ediciones y series de imágenes, y kling-4.0-long-image para páginas web largas y páginas de ecommerce. kling-4-0-image es solo el slug de la página.

¿La Kling Image 4.0 API admite webhooks? Sí. Añade callback_url en el nivel superior de la petición. PoYo envía un POST firmado cuando la tarea termina o falla.

¿Puedo obtener JPEG de la Kling Image 4.0 API? No existe un campo de formato de salida; los resultados son PNG. Nuestras descargas fueron PNG RGBA incluso para imágenes opacas, así que convierte en tu lado si necesitas JPEG.

¿Por qué mi página web larga de Kling Image 4.0 salió en otro idioma? Si el prompt no indica el idioma del texto de la página, el modelo puede elegir uno. Indícalo, por ejemplo "All text on the page is in English."

Share: