API de video e imagen de Kling

Essevin expone Kling a través del gateway AIGC de Tencent Cloud VOD. Es una API asíncrona: envíe una tarea y luego consulte el ID de tarea de Essevin. Use una clave que tenga habilitada la cuenta VOD de Kling y confirme los IDs exactos de modelo con GET /v1/models antes de enviar trabajo de pago.

Cuenta de Tencent VOD

La cuenta de Kling debe configurarse con el SecretId, SecretKey de Tencent Cloud VOD y el SubAppId numérico de la aplicación VOD. region es opcional para VOD y normalmente puede dejarse en blanco. Mantenga estas credenciales en la configuración de cuenta de Essevin; nunca las incluya en solicitudes de cliente, ejemplos o control de versiones. Los clientes siguen usando la Base URL https://api.essevin.com/v1 de Essevin, no un endpoint de Tencent VOD o TokenHub.

Endpoints

Todas las solicitudes usan Authorization: Bearer sk-tu-clave y Content-Type: application/json. El cuerpo se decodifica de forma estricta. Los campos desconocidos, un segundo valor JSON, image_url/video_url de nivel superior y los campos anidados no verificados se rechazan antes de llamar a Tencent.

Matriz de modelos

Los IDs de imagen de Kling son kling-image-v3, kling-image-v3-omni, kling-image-o1, kling-image-v2-1, kling-image-v2-1-i2i, kling-image-v2-1-multi-ref y kling-image-expand. Usan el endpoint de imágenes, aceptan n de 1 a 9 y se facturan por imagen de salida. Use el catálogo de modelos para conocer los niveles de calidad exactos disponibles para la clave actual.

Contrato de solicitud

Localizadores de medios

Cada elemento de images[] o videos[] debe contener exactamente uno de:

{ "url": "https://cdn.example.com/file.png" }

o

{ "file_id": "vod-file-id" }

url debe ser una URL http:// o https:// absoluta y accesible públicamente. Las cadenas vacías, las rutas relativas, file://, ftp://, las direcciones privadas / loopback / link-local, las URLs con credenciales incrustadas y ambos campos a la vez se rechazan de forma síncrona en el envío. La misma regla aplica al endpoint de imágenes, la detección de rostros y el extra.sound_file del avatar.

Generación de video ordinaria

Use images[] para fotogramas o referencias de imagen y videos[] para un video de referencia/edición. No use los campos image_url o video_url de OpenAI en el nivel superior.

{
  "model": "kling-v3-omni",
  "prompt": "<<<element_1>>> y <<<element_2>>> giran lentamente sobre una mesa de estudio limpia",
  "duration": 5,
  "resolution": "1080p",
  "audio": false,
  "images": [
    { "url": "https://cdn.example.com/first.png", "usage": "first_frame" },
    { "file_id": "vod-last-frame", "usage": "last_frame" },
    { "url": "https://cdn.example.com/reference-a.png", "usage": "reference" },
    { "file_id": "vod-reference-b", "usage": "reference" }
  ],
  "videos": [
    {
      "url": "https://cdn.example.com/character-motion.mp4",
      "reference_type": "feature",
      "keep_original_sound": false
    }
  ],
  "subjects": [
    { "id": "subject-92951593344", "name": "gato" },
    { "id": "subject-92951593345", "name": "perro" }
  ]
}

Para la generación ordinaria, images[].usage es obligatorio y es uno de first_frame, last_frame o reference. Puede haber como máximo un primer fotograma y un último fotograma; un último fotograma requiere un primer fotograma. Cuando hay más de dos imágenes reference, no se admite un último fotograma. Con kling-v2-1, proporcionar tanto el primer como el último fotograma restringe resolution a 1080p. Hay como máximo un elemento en videos[], y su reference_type es obligatorio. Un video feature solo lo acepta kling-v3-omni y kling-o1. Un video base solo lo acepta kling-v1-6; debe ser la única entrada de medios y no puede combinarse con imágenes o sujetos.

También aplican los límites de acoplamiento de Tencent: con un video de referencia, el número de imágenes reference más el número de sujetos es como máximo 4; sin video de referencia es como máximo 7. Los prompts vacíos solo se permiten cuando una entrada de medios provee la solicitud. Si se omiten duration, resolution y audio, se normalizan a 5 segundos, 720P y salida silenciosa.

Sujetos y tomas

subjects[] usa IDs de sujeto fijos de Tencent. Cada elemento requiere un id no vacío; name es opcional. Los sujetos solo son compatibles con kling-v3-turbo, kling-v3 y kling-v3-omni. Para kling-v3, Tencent VOD también requiere al menos un elemento de images[] con usage: "reference" cuando hay sujetos presentes. Los elementos son posicionales: subjects[0] es <<<element_1>>>, subjects[1] es <<<element_2>>>, y así sucesivamente. Todo sujeto proporcionado debe referenciarse en el prompt, y un prompt no debe referenciar <<<element_N>>> a menos que ese sujeto exista.

Las tomas solo son compatibles con kling-v3 y kling-v3-omni:

{
  "model": "kling-v3-omni",
  "prompt": "Una breve historia de producto en dos tomas",
  "duration": 5,
  "shots": {
    "mode": "customize",
    "segments": [
      { "index": 1, "prompt": "La caja se abre", "duration": 2 },
      { "index": 2, "prompt": "El producto se revela", "duration": 3 }
    ]
  }
}

mode es intelligence o customize. El modo intelligence debe omitir segments; el modo customize los requiere. Los segmentos personalizados se numeran consecutivamente desde 1, tienen prompts no vacíos de como máximo 512 caracteres, duran al menos un segundo, y sus duraciones deben sumar exactamente la duración de la solicitud. Use shots estructurado; extra.multi_shot, extra.shot_type y extra.multi_prompt en bruto se rechazan.

Control de movimiento

Las tareas de control de movimiento requieren exactamente un video seguido de exactamente una imagen de persona. La escena determina su significado, por lo que no debe enviar usage en la imagen ni reference_type en el video. videos[].keep_original_sound es un booleano y se mapea al indicador keep_original_sound de Tencent. El único parámetro adicional actualmente verificado es extra.character_orientation (image o video). La duración del control de movimiento proviene del video de entrada y debe omitirse; la salida es temporal.

{
  "model": "kling-v3-motion-control",
  "prompt": "Sigue el movimiento del bailarín",
  "resolution": "1080p",
  "images": [{ "file_id": "vod-person-image" }],
  "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
  "extra": { "character_orientation": "video" }
}

Avatar y sincronización labial

Avatar (kling-avatar) requiere de 1 a 5 imágenes de persona, ningún video, y exactamente uno de extra.sound_file (una URL de audio HTTP(S)) o extra.audio_id. La duración se deriva de la entrada de audio; omita duration.

La sincronización labial (kling-lip-sync) no acepta imágenes ni videos. Primero llame a la detección de rostros con uno o más localizadores de medios:

curl https://api.essevin.com/v1/kling/faces \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{"videos":[{"file_id":"vod-source-video"}]}'

Luego envíe un elemento face_choose para la sesión devuelta:

{
  "model": "kling-lip-sync",
  "extra": {
    "session_id": "face-session-id",
    "face_choose": [
      { "face_id": "face-1", "sound_file": "https://cdn.example.com/voice.mp3" }
    ]
  }
}

face_choose debe contener exactamente un elemento con un face_id y un sound_file no vacíos. El audio/video de origen determina la duración. La facturación de la sincronización labial es por segundo con un mínimo de cinco segundos, por lo que un resultado de cuatro segundos se factura como cinco segundos. extra.voice_list y voice_ids en bruto están deliberadamente no disponibles hasta que Tencent confirme un SKU correspondiente.

Enviar y consultar

  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-v3","prompt":"Una pelota roja rueda sobre una mesa blanca","duration":5,"resolution":"720p"}'

La respuesta 202 contiene un ID como kt57x<upstream-task-id>. Consúltelo sin un encabezado de facturación:

  -H "Authorization: Bearer sk-tu-clave"

Los estados son queued, processing, completed y failed. Los outputs completados son URLs de relay de Essevin; el plugin no almacena la fuente de forma permanente. El relay valida el token de archivo de la tarea antes de obtener la URL de Tencent. La facturación se produce una sola vez, por el poller interno fijado, únicamente después de una respuesta FINISH exitosa de Tencent con ErrCode=0, una salida válida y una duración facturable. Un FINISH con ErrCode o ErrCodeExt distinto de cero es un fallo y nunca se factura.

Unidades de precio y buckets

El catálogo de modelos publica price.unit: el video es second, las imágenes son image y la detección de rostros es call. Los precios base de video son el precio en CNY de Tencent dividido entre la tasa fija del sitio de 6.8 CNY/USD; Core aplica el multiplicador de grupo por separado.

Los buckets faltantes o no confirmados no están disponibles en lugar de mapearse silenciosamente a un precio cercano. En particular, el precio de video feature silencioso en 4K de kling-v3-omni se retiene en espera de una segunda confirmación de Tencent. Las voces seleccionadas por el llamador también se retienen: no envíe voice_ids ni extra.voice_list.