Saltar al contenido

Imágenes con Kling

Genere y expanda imágenes con Kling de forma asíncrona: parámetros, respuesta y advertencias.

ElementoValor
Base URLhttps://api.hop-base.com/v1
Enviar una tarea de imagenPOST /v1/images/generations
Consultar una tareaGET /v1/video/tasks/{task_id}
GrupoKling 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

ModeloID de modeloNiveles de qualityImágenes de referenciaPrecio oficial
Kling Imagen 3.0kling-image-v31k / 2k0–1$0,0294/ imagen
Kling Imagen 3.0 Omnikling-image-v3-omni1k / 2k / 4k0–10$0,0294desde/ imagen
Kling Imagen O1kling-image-o11k / 2k / 4k0–10$0,0294desde/ imagen
Kling Imagen 2.1 (texto a imagen)kling-image-v2-11k / 2kNinguna$0,0147/ imagen
Kling Imagen 2.1 (imagen a imagen)kling-image-v2-1-i2i1k / 2kExactamente 1$0,0294/ imagen
Kling Imagen 2.1 (varias referencias)kling-image-v2-1-multi-ref1k / 2k2–4$0,0588desde/ imagen
Kling expansión de imagenkling-image-expand1kExactamente 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ámetroObligatorioTipo y límitesPredeterminadoDescripción
modelObligatoriocadena—Un ID de modelo de imagen de la tabla anterior
promptObligatorio sin imágenescadena—Envíelo, un images no vacío, o ambos
qualityOpcional1k / 2k / 4k1kNivel de calidad; los valores varían por modelo
nOpcionalentero 1–91Número de imágenes
imagesSegún el modeloarreglo de elementos url / file_id—Imágenes de referencia, o la imagen a expandir
extraSolo expansiónobjeto con las cuatro proporciones—Vea Expansión de imagen
  • 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, "cost": 0.17, "cost_usd": 0.025, "currency": "CNY" }
}
CampoTipoDescripción
idstringID de tarea de HopBase, igual en el envío y la consulta
objectstringimage.generation.task al enviar, video.generation.task al consultar
statusstringqueued → processing → completed o failed
progressintegerPorcentaje de avance; solo en la consulta
requested_imagesintegerImágenes solicitadas; solo en el envío
billing_bucketstringNivel de facturación de la calidad; solo en el envío
outputsstring[]URL de las imágenes; solo con completed
usage.billed_imagesintegerImágenes facturadas, igual a las producidas
usage.costnumberEl cargo de esta tarea en CNY (el mismo cargo que usage.cost_usd)
usage.cost_usdnumberEl importe en USD realmente descontado de su saldo por esta tarea, el mismo que su registro de consumo
usage.currencystringLa moneda de usage.cost, siempre CNY
error.code / error.messagestringSolo 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.com y 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.

Errores comunes

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

ErrorSolució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 emptyAñada un prompt o imágenes de referencia
images[0] must provide exactly one of url or file_idDeje solo url o file_id en cada elemento
images[0].url must be a publicly accessible absolute http(s) URLUse 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 imagesAjuste las imágenes de referencia al modelo
model "<model ID>" is not an image model in this catalogVerifique el ID con GET /v1/models (404)

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.

Casoerror.code
Prompt o imagen de referencia rechazados por la moderacióninput_sensitive
Resultado bloqueado por la moderaciónsafety_rejected
Techo de concurrencia alcanzadorate_limited
Versión del modelo retiradaunsupported_model
Prompt demasiado largo, o parámetros o medios rechazadosinvalid_request
Imagen de referencia ilegiblereference_input_invalid
La generación falló o se detuvo antes de terminargeneration_failed
Sin terminar 2 horas después de crearsetimeout
La tarea terminó sin salidano_output

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