Imágenes con Kling
Genere y expanda imágenes con Kling de forma asíncrona: parámetros, respuesta y advertencias.
| Elemento | Valor |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| Enviar una tarea de imagen | POST /v1/images/generations |
| Consultar una tarea | GET /v1/video/tasks/{task_id} |
| Grupo | Kling oficial |
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
| Modelo | ID de modelo | Niveles de quality | Imágenes de referencia | Precio oficial |
|---|---|---|---|---|
| Kling Imagen 3.0 | kling-image-v3 | 1k / 2k | 0–1 | $0,0294/ imagen |
| Kling Imagen 3.0 Omni | kling-image-v3-omni | 1k / 2k / 4k | 0–10 | $0,0294desde/ imagen |
| Kling Imagen O1 | kling-image-o1 | 1k / 2k / 4k | 0–10 | $0,0294desde/ imagen |
| Kling Imagen 2.1 (texto a imagen) | kling-image-v2-1 | 1k / 2k | Ninguna | $0,0147/ imagen |
| Kling Imagen 2.1 (imagen a imagen) | kling-image-v2-1-i2i | 1k / 2k | Exactamente 1 | $0,0294/ imagen |
| Kling Imagen 2.1 (varias referencias) | kling-image-v2-1-multi-ref | 1k / 2k | 2–4 | $0,0588desde/ imagen |
| Kling expansión de imagen | kling-image-expand | 1k | Exactamente 1 | $0,0294/ imagen |
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
| Parámetro | Obligatorio | Tipo y límites | Predeterminado | Descripción |
|---|---|---|---|---|
model | Obligatorio | cadena | — | Un ID de modelo de imagen de la tabla anterior |
prompt | Obligatorio sin imágenes | cadena | — | Envíelo, un images no vacío, o ambos |
quality | Opcional | 1k / 2k / 4k | 1k | Nivel de calidad; los valores varían por modelo |
n | Opcional | entero 1–9 | 1 | Número de imágenes |
images | Según el modelo | arreglo de elementos url / file_id | — | Imágenes de referencia, o la imagen a expandir |
extra | Solo expansión | objeto con las cuatro proporciones | — | Vea Expansión de imagen |
- Solo se aceptan estos campos; otros como
size,aspect_ratiooresponse_formatdevuelven 400. - Un ID de modelo de video en
modeldevuelve 400. qualityno distingue mayúsculas; se rechazan valores de OpenAI comohighostandard.nse factura por imagen de salida.- Un
extrano 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" }
]
}urldebe ser una URLhttp://ohttps://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_iddebe 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, "cost": 0.17, "cost_usd": 0.025, "currency": "CNY" }
}| Campo | Tipo | Descripción |
|---|---|---|
id | string | ID de tarea de HopBase, igual en el envío y la consulta |
object | string | image.generation.task al enviar, video.generation.task al consultar |
status | string | queued → processing → completed o failed |
progress | integer | Porcentaje de avance; solo en la consulta |
requested_images | integer | Imágenes solicitadas; solo en el envío |
billing_bucket | string | Nivel de facturación de la calidad; solo en el envío |
outputs | string[] | URL de las imágenes; solo con completed |
usage.billed_images | integer | Imágenes facturadas, igual a las producidas |
usage.cost | number | El cargo de esta tarea en CNY (el mismo cargo que usage.cost_usd) |
usage.cost_usd | number | El importe en USD realmente descontado de su saldo por esta tarea, el mismo que su registro de consumo |
usage.currency | string | La moneda de usage.cost, siempre CNY |
error.code / error.message | string | Solo con failed; vea Tareas fallidas |
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_usd —el importe en USD realmente descontado de su saldo por esta tarea, 0 si falló sin cargo—, cost (el mismo cargo en CNY) y currency, la moneda de cost (siempre CNY). En la lista de tareas (GET /v1/video/tasks), cada tarea finalizada lleva los mismos cost, cost_usd y currency en su usage.
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.comy son válidas por 24 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.
- El gateway valida solo la estructura de la solicitud y el número de imágenes; la resolución, el formato y el tamaño se verifican oficialmente durante la tarea, así que un recurso no conforme falla minutos después del envío.
- El cuerpo se decodifica de forma estricta: un campo desconocido dentro de un objeto anidado o un segundo valor JSON tras el cuerpo también devuelve 400, sin cargo.
- Las tareas de imagen comparten con las de video de Kling el endpoint de consulta y la lista de tareas
GET /v1/video/tasks. - Los modelos de imagen de Kling solo se envían por
POST /v1/images/generations; enviarlos al endpoint de video devuelve 400.
Errores comunes
Un error en el envío no crea ninguna tarea ni factura nada; error.message explica el motivo:
| Error | Solución |
|---|---|
request body does not match the JSON contract: json: unknown field "size" | Quite el campo sobrante; fije el nivel con quality |
prompt and input images cannot both be empty | Añada un prompt o imágenes de referencia |
images[0] must provide exactly one of url or file_id | Deje solo url o file_id en cada elemento |
images[0].url must be a publicly accessible absolute http(s) URL | Use una URL HTTP(S) pública |
model "kling-image-v3" does not support quality tier "4k" | Elija un nivel que admita el modelo |
model "kling-image-v2-1-multi-ref" requires 2 to 4 input images | Ajuste las imágenes de referencia al modelo |
model "<model ID>" is not an image model in this catalog | Verifique el ID con GET /v1/models (404) |
Cada línea que empieza por # es el caso y la siguiente es el error.message literal:
# 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 catalogTareas 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.
| Caso | error.code |
|---|---|
| Prompt o imagen de referencia rechazados por la moderación | input_sensitive |
| Resultado bloqueado por la moderación | safety_rejected |
| Techo de concurrencia alcanzado | rate_limited |
| Versión del modelo retirada | unsupported_model |
| Prompt demasiado largo, o parámetros o medios rechazados | invalid_request |
| Imagen de referencia ilegible | reference_input_invalid |
| La generación falló o se detuvo antes de terminar | generation_failed |
| Sin terminar 2 horas después de crearse | timeout |
| La tarea terminó sin salida | no_output |
# 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 failingFacturació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