Crear un sujeto personalizado

Crea un sujeto personalizado de Kling a partir de imágenes o de un video; el ID de sujeto obtenido va en `subjects[].id` de la solicitud de video.

POST/v1/kling/subjects

image_refer requiere una imagen frontal más 1–3 imágenes de referencia auxiliares; video_refer requiere un video y opcionalmente puede vincular un voice_id. Los campos de ambos modos no se pueden mezclar. Todas las direcciones deben ser direcciones HTTP(S) públicas y absolutas, con las mismas reglas que en Localizadores de medios.

La creación es una tarea asíncrona y por ahora no se factura. El envío devuelve 202 y el id de la tarea (object es kling.subject.task); consulte con Consultar una tarea de video. Al terminar, el resultado incluye element_ids (array de ID de sujetos) y elements (cada elemento con id y posiblemente info).

El cuerpo de la solicitud es un contrato JSON estricto: los campos fuera de la tabla devuelven 400 antes de crear la tarea. Toda la validación de campos se hace antes del envío; si algo no es válido, no se crea la tarea.

Crear un sujeto personalizado

curl https://api.hop-base.com/v1/kling/subjects \
  -H "Authorization: Bearer $HOPBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gato naranja",
    "description": "Gato naranja de pelo corto y ojos verdes",
    "reference_type": "image_refer",
    "frontal_image_url": "https://cdn.example.com/cat-front.png",
    "reference_image_urls": [
      "https://cdn.example.com/cat-side.png",
      "https://cdn.example.com/cat-back.png"
    ]
  }'

202application/json

{
  "id": "ktEXAMPLE",
  "object": "kling.subject.task",
  "status": "queued",
  "created": 1790000000
}

Encabezados

Authorization:obligatoriostring

Bearer sk-…: una clave de API creada en la consola; su grupo debe incluir el modelo solicitado

Parámetros del cuerpoJSON

name:obligatoriostring

Nombre del sujeto; se eliminan los espacios al inicio y al final

Longitud1–20 caracteres

description:opcionalstring

Descripción del sujeto

Longitud≤ 100 caracteres

reference_type:obligatoriostring

image_refer crea a partir de imágenes; video_refer, a partir de un video

Valoresimage_refervideo_refer

frontal_image_url:opcionalstring

Dirección de la imagen frontal; obligatoria con image_refer y no permitida con video_refer; debe ser una dirección HTTP(S) absoluta accesible públicamente

Longitud≥ 1 caracteres

reference_image_urls:opcionalarray of string

Direcciones de las imágenes de referencia auxiliares; obligatorias con image_refer, de 1 a 3, sin repetir la imagen frontal ni repetirse entre sí; no permitidas con video_refer

Elementos1–3

video_url:opcionalstring

Dirección del video; obligatoria con video_refer y no permitida con image_refer; debe ser una dirección HTTP(S) absoluta accesible públicamente

Longitud≥ 1 caracteres

voice_id:opcionalstring

Voz vinculada al sujeto; solo disponible con video_refer

tag_ids:opcionalarray of string

ID de etiquetas para clasificar el sujeto; cada uno no vacío y sin repetir

Respuesta

202Aceptado; devuelve la tarea de creación del sujeto

id:opcionalstring

ID de tarea; consúltelo periódicamente con GET /v1/video/tasks/{task_id}

object:opcionalstring

Siempre kling.subject.task

status:opcionalstring

Siempre queued

created:opcionalinteger

Hora de creación, en segundos Unix

Errores

400La validación previa al envío falló; no se crea la tarea. Mensajes originales, por ejemplo: request body does not match the JSON contract: …: JSON no válido, campos fuera de la tabla o un segundo valor JSON después del cuerpo name is required, name cannot exceed 20 characters, description cannot exceed 100 characters reference_type must be image_refer or video_refer reference_type=image_refer does not accept video_url, voice_id is only supported with reference_type=video_refer, reference_type=video_refer does not accept image references reference_image_urls must contain 1 to 3 reference images different from the frontal image, reference_image_urls[<índice>] duplicates the frontal image or another reference image <campo> is required, <campo>.url must be a publicly accessible absolute http(s) URL tag_ids[<índice>] cannot be empty, tag_ids[<índice>] is duplicated

401Falta la clave, la clave no es válida o ha caducado (missing_api_key / invalid_api_key / api_key_expired)

Encabezados

Parámetros del cuerpoJSON

Respuesta

Errores

Páginas relacionadas