Imágenes con Kling

Todos los modelos de imagen de Kling funcionan como tareas asíncronas: el envío devuelve 202 con un id de tarea, usted consulta el endpoint de tareas y una tarea terminada lista las URL de las imágenes en outputs[].

Modelos disponibles

Cómo elegir: use 2.1 (texto a imagen) para prompts de solo texto, 3.0 Omni u O1 para 4k o muchas imágenes de referencia, y la expansión de imagen para extender una imagen existente hacia fuera.

Parámetros de la solicitud

• Solo se aceptan estos campos; otros como size, aspect_ratio o response_format devuelven 400.
• Un ID de modelo de video en model devuelve 400.
• quality no distingue mayúsculas; se rechazan valores de OpenAI como high o standard.
• n se factura por imagen de salida.
• Un extra no vacío en cualquier otro modelo de imagen devuelve 400.

Imágenes de referencia

Cada elemento de images[] lleva exactamente uno de url o file_id, y ningún usage:

{
  "model": "kling-image-v3-omni",
  "prompt": "Coloca las tazas de ambas imágenes sobre una mesa de madera",
  "quality": "2k",
  "images": [
    { "url": "https://cdn.example.com/cup-a.png" },
    { "file_id": "your-file-id" }
  ]
}

• url debe ser una URL http:// o https:// absoluta y accesible públicamente.
• Se rechazan de forma síncrona las cadenas vacías, las rutas relativas, los esquemas que no son HTTP(S) como file://, las direcciones privadas o loopback y las URL con credenciales.
• Un file_id debe ser un recurso de Kling disponible para su clave, no un ID de recurso de Seedance.
• El número de imágenes de referencia está limitado por modelo; vea Modelos disponibles.

Expansión de imagen

kling-image-expand extiende una imagen hacia fuera; las proporciones van en extra:

{
  "model": "kling-image-expand",
  "images": [{ "url": "https://example.com/input.png" }],
  "extra": {
    "left_expansion_ratio": 0.5,
    "right_expansion_ratio": 0.5,
    "up_expansion_ratio": 0,
    "down_expansion_ratio": 0
  }
}

• Cada una de las 4 proporciones es un número de 0–2; una proporción omitida vale 0.
• Las cuatro proporciones no pueden valer 0 a la vez.
• El área expandida no puede superar 3 veces la original: (1+izquierda+derecha) × (1+arriba+abajo) ≤ 3.

Respuesta

Un envío exitoso devuelve HTTP 202 con el ID de tarea en el id de la raíz, con la forma kt57x<task-id>:

{
  "id": "ktEXAMPLE",
  "object": "image.generation.task",
  "model": "kling-image-v3",
  "status": "queued",
  "created": 1790000000,
  "billing_bucket": "img_1k",
  "requested_images": 1
}

Consulte GET /v1/video/tasks/{task_id} con ese id. Una tarea terminada tiene este aspecto:

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "kling-image-v3",
  "status": "completed",
  "progress": 100,
  "created": 1790000000,
  "outputs": [
    "https://api.hop-base.com/example-signed-image.png"
  ],
  "usage": { "bucket": "img_1k", "billed_images": 1 }
}

Solo completed y failed son terminales, así que trate cualquier otro valor como en curso.

Cuando la tarea termina, el objeto usage de la raíz de la consulta también incluye cost —el importe realmente descontado de su saldo por esta tarea, 0 si falló sin cargo— y la moneda en currency.

Ejemplos

Envíe una tarea de texto a imagen, consulte hasta que termine y descargue la primera imagen:

# 1. Enviar
curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-su-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-image-v3",
    "prompt": "Una tetera de cerámica sobre una mesa de madera al sol",
    "quality": "1k",
    "n": 1
  }'

# 2. Consultar con el id devuelto hasta que status sea completed o failed
curl https://api.hop-base.com/v1/video/tasks/ktYOUR_TASK_ID \
  -H "Authorization: Bearer sk-su-clave"

Advertencias

• Las URL de las imágenes se sirven desde api.hop-base.com y son válidas por 6 horas desde que la tarea se completa, así que descárguelas pronto.
• Consultar de nuevo devuelve la misma URL sin extenderla, y un enlace vencido devuelve 410.
• Una tarea sin terminar 2 horas después de crearse se marca como fallida y no se factura, y las tareas no se pueden cancelar.
• La generación de imágenes de Kling no reserva saldo y solo se bloquea cuando su saldo es cero o negativo.
• Antes de enviar trabajo de pago, confirme los IDs exactos de modelo que devuelve su clave con GET /v1/models.

Errores comunes

Un error en el envío no crea ninguna tarea ni factura nada; error.message explica el motivo:

# Un campo fuera de la tabla
request body does not match the JSON contract: json: unknown field "<campo>"

# prompt e images vacíos a la vez
prompt and input images cannot both be empty

# Un elemento de images[] sin url / file_id o con ambos
images[<índice>] must provide exactly one of url or file_id

# url que no es una dirección http(s) absoluta y pública
images[<índice>].url must be a publicly accessible absolute http(s) URL

# usage en un elemento de images[]
images[<índice>].usage is not part of the image generation API; remove this field

# Un nivel de quality que el modelo no ofrece
model "<ID de modelo>" does not support quality tier "<valor>"

# n fuera de 1–9
n must be between 1 and 9, got <valor>

# Más imágenes de referencia de las que admite el modelo
model "<ID de modelo>" accepts at most <máximo> input images, got <cantidad>

# Imágenes enviadas a kling-image-v2-1
model "kling-image-v2-1" is a text-to-image model and does not accept input images

# kling-image-v2-1-i2i sin exactamente 1 imagen
model "kling-image-v2-1-i2i" requires exactly 1 input image

# kling-image-v2-1-multi-ref sin 2–4 imágenes
model "kling-image-v2-1-multi-ref" requires 2 to 4 input images

# extra en un modelo que no es de expansión
model "<ID de modelo>" does not accept unverified extra parameters

# Expansión sin exactamente 1 imagen
image expansion requires exactly 1 input image

# extra de expansión con una clave distinta de las cuatro proporciones
extra.<clave> is not a verified parameter of the image expansion API

# Proporción de expansión que no es un número de 0 a 2
extra.<clave> must be a number between 0 and 2

# Las cuatro proporciones valen 0
the four expansion ratios cannot all be 0

# Área expandida mayor que 3 veces la original
expanded area cannot exceed 3x the original image

# ID de modelo de imagen fuera del catálogo (404)
model "<ID de modelo>" is not an image model in this catalog

Tareas fallidas

Una tarea fallida sigue respondiendo a la consulta con HTTP 200 y status failed. Ramifique su lógica por el código estable de error.code y muestre al usuario la explicación del error. Las tareas que fallaron hace tiempo pueden no tener código.

# input_sensitive
the prompt was rejected by content moderation; rephrase it and submit again
the reference image was rejected by content moderation; replace it and submit again
the prompt or reference image was rejected by content moderation; revise it and submit again

# safety_rejected
the generated result was blocked by content moderation; adjust the prompt or reference media and submit again

# rate_limited
this model is at its concurrency limit right now; please retry shortly

# unsupported_model
this model version is no longer available; switch to another model and submit again

# invalid_request
the prompt is too long for this model (at most 2500 characters); shorten it and submit again
the request was rejected as invalid by the model; check the parameters and media against the documented limits, then submit again

# reference_input_invalid
a reference image or video is missing or could not be read; make sure every URL is publicly reachable and points to a supported file, then submit again

# generation_failed
image generation failed; please retry, and contact support with the task ID if it keeps failing
image generation was stopped before it finished; please retry, and contact support with the task ID if it keeps failing
… contact support with the task ID

# timeout
task did not reach a billable terminal state within 2 hours; polling stopped

# no_output
image generation finished without a usable output; please retry, and contact support with the task ID if it keeps failing

Facturación

Las imágenes de Kling se facturan por imagen de salida, a la tarifa del modelo y del nivel de calidad; las tareas fallidas y las consultas nunca se facturan. El precio de cada modelo está en su ficha enlazada arriba, y su tarifa es la que aparece en el catálogo de modelos con la sesión iniciada.

Próximos pasos

• API de imágenes: resumen de todas las series de imagen
• GPT Image, imágenes con Gemini, Seedream, imágenes con Grok Imagine: otras series de imagen
• Video con Kling: video, control de movimiento, avatar y sincronización labial de Kling
• Generar imágenes y Consultar una tarea de video: referencia de la API
• Solución de problemas: busque un mensaje de error