# Kling Official

> Guía oficial de la API directa de Kling para los proveedores de OpenMontage. Úsala antes de llamar a kling_official_video, kling_official_image, kling_tts, kling_avatar o kling_lip_sync.

Fuente: https://skillsagentes.com/skills/calesthio/openmontage/kling-official
Markdown: https://skillsagentes.com/skills/calesthio/openmontage/kling-official.md

Repositorio: https://github.com/calesthio/OpenMontage
Autor: calesthio
Licencia: AGPL-3.0
Actualizado: el mes pasado
Coste de contexto: 45 tok instalada, 2.4k tok al activarse, 2.4k tok con todos los archivos del bundle
Bundle: 1 archivo, 9 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add calesthio/OpenMontage --skill kling-official --agent claude-code
# Cursor
npx -y skills add calesthio/OpenMontage --skill kling-official --agent cursor
# Codex
npx -y skills add calesthio/OpenMontage --skill kling-official --agent codex
# Gemini CLI
npx -y skills add calesthio/OpenMontage --skill kling-official --agent gemini
# Windsurf
npx -y skills add calesthio/OpenMontage --skill kling-official --agent windsurf
# Cline
npx -y skills add calesthio/OpenMontage --skill kling-official --agent cline
```

## Qué hace

- Documenta la API directa oficial de Kling para los proveedores de OpenMontage: autenticación, endpoint y protocolos de tarea
- Cubre parámetros de vídeo, imagen, TTS, avatar y lip sync, además de efectos de audio y de vídeo
- Explica el reparto entre proveedores, las referencias Omni y los límites de capacidad
- Detalla las notas de callback: `callback_url` va arriba en las rutas clásica y Omni, y dentro de `options` en las turbo, pero el polling sigue siendo el modo por defecto
- Impone gobierno de coste y manejo de errores antes de lanzar

## Cuándo usarla

- Antes de llamar a `kling_official_video`, `kling_official_image`, `kling_tts`, `kling_avatar` o `kling_lip_sync`

## Qué la activa

- "Genera este vídeo con la API oficial de Kling"
- "Haz lip sync de este clip con Kling"
- "Usa el avatar de Kling para esta locución"

## Antes de instalar

- Necesita `KLING_API_KEY`; valida las URLs de callback antes de enviarlas y acepta solo `http` o `https` absolutas.
- makes network requests

## Archivos

- SKILL.md — 9 KB

## SKILL.md

Reproducido tal cual desde calesthio/OpenMontage bajo AGPL-3.0. Esta sección es el documento original y está en inglés.

# Kling Official Direct API

Use this skill for OpenMontage tools with `provider="kling_official"`. This is not the fal.ai Kling gateway. Official Kling uses `KLING_API_KEY`, optional `KLING_API_BASE_URL`, and `Authorization: Bearer <KLING_API_KEY>`.

## Provider Split

- `kling_video` uses fal.ai, `FAL_KEY`, fal.ai queue URLs, and `provider="kling"`.
- `kling_official_video` uses Kling official API, `KLING_API_KEY`, official task protocols, and `provider="kling_official"`.
- `kling_official_image` uses the same official auth and task protocol for image generation.
- `kling_tts` uses the official audio TTS endpoint and stays in the existing `tts` capability.
- `kling_avatar` and `kling_lip_sync` use official avatar/lip-sync endpoints and stay in the existing `avatar` capability. They do not replace local `talking_head` or `lip_sync`.

Never silently switch between these paths. If the selected provider is unavailable, surface the blocker and ask before substituting.

## Auth And Endpoint

Default base URL:

```text
https://api-singapore.klingai.com
```

Users may override it with `KLING_API_BASE_URL`, for example for a regional endpoint. All requests send JSON and:

```text
Authorization: Bearer <KLING_API_KEY>
```

## Task Protocols

Classic APIs:

- Create ID path: `data.task_id`
- Statuses: `submitted`, `processing`, `succeed`, `failed`
- Result paths: `data.task_result.videos[]`, `data.task_result.images[]`, `data.task_result.audios[]`

Turbo APIs:

- Create ID path: `data.id`
- Poll path: `GET /tasks?task_ids=<id>`
- Statuses: `submitted`, `processing`, `succeeded`, `failed`
- Result path: `data[0].outputs[]`

Keep the parsers separate. Do not write a fuzzy parser that guesses between `task_id` and `id` or between `succeed` and `succeeded`.

## Omni References

Video Omni and Image Omni stay inside the existing provider tools through `api_family="omni"`.
Do not create selector-level Omni operations.

Video Omni accepts official reference structures:

- `image_list[]` with `image_url` and optional `type` such as `first_frame` or `end_frame`.
- `video_list[]` with `video_url`, official `refer_type` values such as `feature` or `base`, and optional `keep_original_sound`.
- `element_list[]` with official `element_id` values.
- Structured `multi_prompt[]`; do not split natural language into shots automatically.

Local image references may be normalized through `tools/_kling/media.py`. Local video paths must not be silently uploaded through fal.ai; ask for or require a reachable URL.

Image Omni accepts `image_list[]` with official `image` values. Prompt placeholders such as `<<<image_1>>>` must map stably to the provided image order. If the prompt already contains placeholders, validate that the referenced images exist and do not insert duplicates.

## Capability Boundaries

TTS, avatar, and lip sync are provider additions to existing OpenMontage capabilities. Audio effects and video effects are official Kling endpoints, but they are not registered as default OpenMontage tools until a pipeline has a stable capability slot for them.

- Do not add `sound_effects` or `video_effects` capabilities from inside a provider implementation.
- Do not let video effects enter the ordinary `video_generation` selector path.
- Do not disguise short sound effects as long background music unless a pipeline explicitly consumes that shape and the tool's `best_for` / `not_good_for` says so.

## Video Parameters

Use `operation` for OpenMontage semantics:

- `text_to_video`
- `image_to_video`
- `reference_to_video`

Use `api_family` for official protocol choice:

- `classic`
- `turbo`
- `omni`

Important constraints:

- Official video provider input schema must not expose top-level `image_url`; use `reference_image_url` or `reference_image_path`.
- Classic image-to-video accepts `reference_image_url` or a local path converted to raw base64 in official field `image`.
- Turbo image-to-video requires a URL first frame. Do not upload local files through fal.ai as a fallback.
- Send `aspect_ratio` only where the current schema supports it: Classic text-to-video, Turbo text-to-video, and Video Omni.
- Default paid path should avoid `4k`, native sound, or batch behavior unless explicitly selected.

## Image Parameters

Use `api_family="generation"` for `/v1/images/generations` and `api_family="omni"` for `/v1/images/omni-image`.

Generation/edit path:

- `prompt` is required and should stay under the official 2500 character limit.
- `image_url` passes through as official `image`.
- `image_path` is converted to raw base64 and sent as official `image`.
- `image_reference` can be `subject` or `face`.

Omni path:

- Put references in `image_list[]` using official `image` values.
- Use prompt placeholders such as `<<<image_1>>>` only when the prompt needs to bind a specific reference image.

## TTS Parameters

`kling_tts` uses:

- `text`
- `voice_id`
- `voice_language`, currently `zh` or `en`
- `voice_speed`

Require an explicit `voice_id` unless an official account-specific default has been verified. Do not hard-code a made-up voice. Download every returned audio item, set `data.output_path` to the first local file, and include `voice_id`, `voice_language`, `voice_speed`, `task_id`, and non-zero `cost_usd`.

## Avatar Parameters

`kling_avatar` uses `/v1/videos/avatar/image2video` and accepts:

- avatar image via URL or local path converted to raw base64
- `audio_id` or `sound_file`
- optional `prompt`
- `mode`, such as `std` or `pro`

Keep it separate from local `talking_head`. Pipelines that want Kling avatar output must list and choose it explicitly.

## Lip Sync Parameters

`kling_lip_sync` has two steps:

1. `POST /v1/videos/identify-face` with `video_id` or `video_url`; read faces from `data.face_data[]`
2. `POST /v1/videos/advanced-lip-sync` with `session_id` and one `face_choose[]` item containing `face_id`, `audio_id` or `sound_file`, and the sound start/end/insert times

Local video paths must not be silently uploaded through fal.ai or any other provider. If multiple faces are returned and the user did not pass `face_id` or `face_choose`, stop and return the face list for confirmation unless `auto_select_face=True` was explicitly set. If auto-selecting, record the selection reason and selected face in the result/artifact.

## Audio Effects And Video Effects

Official Kling audio effects (`/v1/audio/text-to-audio`, `/v1/audio/video-to-audio`) and video effects (`/v1/videos/effects`) are intentionally not default OpenMontage selector tools. Record the non-mapping reason in docs/tests instead of registering tools that current pipelines might misuse.

## Elements Helper

Elements are an internal Kling Official helper, not a new OpenMontage tool capability.
Use `tools/_kling/elements.py` to normalize `element_list[].element_id`, optionally query read-only element endpoints, and record element metadata when queried. Do not create or delete elements from the default provider path.

## Account Usage Helper

Account Usage is diagnostic only. Use `tools/_kling/account.py` for low-frequency `/account/costs` checks, with local cache and throttle protection. Do not call it before every generation and do not put it in selectors or production pipeline stages.

For `1101` or `1102`, surface that the account or resource pack is exhausted and include an account-usage diagnostic hint.

## Callback Notes

Providers may accept `callback_url`, but polling remains the default execution mode.

- Classic and Omni paths pass `callback_url` at the top level.
- Turbo paths pass it as `options.callback_url`.
- Successful results should record `callback_requested=true`, `polling_used=true`, the `callback_url`, and `task_id`.
- Validate callback URLs before sending; only absolute `http` or `https` URLs should pass.

## Error Handling

Surface official `code`, `message`, and `request_id` whenever available.

Do not retry:

- Auth failures: `1000`-`1004`
- Balance/resource-pack exhaustion: `1101`, `1102`
- Permission/model access: `1103`
- Parameter errors: `1200`, `1201`
- Safety policy: `1301`

Limited retry is acceptable for:

- `1302` request too fast
- `1303` concurrency/resource-pack slot limit
- `5000`, `5001`, `5002` server/maintenance/backlog errors

For `1303`, explain that the account hit a concurrency or resource-pack slot limit.

## Cost Governance

Official Kling is a paid remote API. Provider tools must return non-zero conservative estimates from `estimate_cost()` and include `cost_usd` on successful paid results. Treat estimates as low-confidence until account usage reconciliation is implemented.
High-cost Omni inputs such as multiple references, element IDs, `result_type="series"`, `mode="4k"`, and `sound="on"` must increase or flag the cost estimate.

## Prompt Notes

For video, start from the universal OpenMontage video prompt skeleton: subject, subject motion, scene, spatial framing, and camera. Kling tends to respond well to clear temporal action order, camera movement verbs, and concise negative prompts. For reference workflows, state what should stay consistent from the reference and what should change.

## Dónde encaja

- Categoría: [Desarrollo de APIs](https://skillsagentes.com/categorias/desarrollo-apis.md) — Diseña, prueba y documenta APIs HTTP y GraphQL.
- Creador: [calesthio](https://skillsagentes.com/creators/calesthio.md) — 0 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Seedance 2 5](https://skillsagentes.com/skills/calesthio/openmontage/seedance-2-5.md): Genera vídeo cinematográfico de 4-30 s con ByteDance Seedance 2.5 por fal.ai, Volcengine Ark, Runway o ComfyUI. Cubre el contrato de prompt 2.5, cortes duros, locks de continuidad y voz.
- [Comfyui](https://skillsagentes.com/skills/calesthio/openmontage/comfyui.md): Úsalo al trabajar con workflows de ComfyUI en OpenMontage: comfyui_image/video/music, workflows propios, selección de output_node, modelos que faltan, LoRAs, poca VRAM e importación de workflows de la comunidad.
- [Fish Audio Tts](https://skillsagentes.com/skills/calesthio/openmontage/fish-audio-tts.md): Genera narración expresiva y multilingüe con fish.audio (modelos S1 / S2) y reutiliza voces clonadas mediante reference_id.
- [Minimax H3](https://skillsagentes.com/skills/calesthio/openmontage/minimax-h3.md): Genera vídeo con MiniMax H3 (Hailuo 3.0) por la API oficial v2, fal.ai, Runway, nodos partner de ComfyUI o pesos abiertos locales. Clips de 4-15s a 2K con animación de primer/último fotograma.
- [Gemini Omni](https://skillsagentes.com/skills/calesthio/openmontage/gemini-omni.md): Genera y edita conversacionalmente vídeos cortos con Google Gemini Omni Flash: itera con ediciones en lenguaje natural, clips de 3-10s a 720p con audio y texto en pantalla, e imágenes de referencia por etiquetas.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)