用途
该技能面向 OpenMontage 中 provider 为 kling_official 的工具调用场景，提供 Kling 官方直连 API 的指引。它并非 fal.ai 的 Kling 网关，两者是不同路径，不能静默互换。若所选 provider 不可用，应显式暴露阻塞点并在替换前先询问。
与 fal.ai 路径的区分
- kling_video：使用 fal.ai，凭 FAL_KEY，走 fal.ai 队列 URL，provider 为 kling。
- kling_official_video：使用 Kling 官方 API，凭 KLING_API_KEY，走官方任务协议，provider 为 kling_official。
- kling_official_image：图像生成，使用同样的官方认证与任务协议。
- kling_tts：官方音频 TTS 端点，归入现有 tts 能力。
- kling_avatar 与 kling_lip_sync：官方 avatar / 口型同步端点，归入现有 avatar 能力，不替代本地的 talking_head 或 lip_sync。
认证与端点
默认 base URL 为 https://api-singapore.klingai.com，可通过 KLING_API_BASE_URL 覆盖（例如区域端点）。所有请求发送 JSON，并带有 Authorization: Bearer <KLING_API_KEY>。
任务协议
Classic API：创建后从 data.task_id 取值；状态为 submitted、processing、succeed、failed；结果路径为 data.task_result.videos[]、data.task_result.images[]、data.task_result.audios[]。
Turbo API：创建后从 data.id 取值；轮询用 GET /tasks?task_ids=<id>；状态为 submitted、processing、succeeded、failed；结果路径为 data[0].outputs[]。
两类解析器必须分离，不能写模糊解析在 task_id 与 id，或 succeed 与 succeeded 之间猜测。
Omni 引用
Video Omni 与 Image Omni 通过 api_family="omni" 留在现有 provider 工具内，不创建 selector 级 Omni 操作。
Video Omni 接受官方引用结构：image_list[]（含 image_url 与可选类型如 first_frame、end_frame）；video_list[]（含 video_url、官方 refer_type 值如 feature 或 base，以及可选 keep_original_sound）；element_list[]（含官方 element_id）；结构化 multi_prompt[]，不自动将自然语言拆分为镜头。本地图像引用可经 tools/_kling/media.py 规范化；本地视频路径不得静默经由 fal.ai 上传，需提供可访问 URL。
Image Omni 接受 image_list[] 官方图像值。提示占位符如 <<<image_1>>> 须稳定映射到所提供图像顺序；若提示已含占位符，需校验被引用图像存在且不重复插入。
能力边界
TTS、avatar、lip sync 是 provider 对现有 OpenMontage 能力的补充。音频特效与视频特效属于官方 Kling 端点，但在 pipeline 有稳定能力槽之前不注册为默认 OpenMontage 工具。不得在 provider 实现内新增 sound_effects 或 video_effects 能力，不得让视频特效进入普通 video_generation selector 路径，也不得在未明确支持的情况下把短音效伪装成长背景音乐。
视频参数
- operation 用于 OpenMontage 语义：text_to_video、image_to_video、reference_to_video。
- api_family 用于官方协议选择：classic、turbo、omni。
约束：官方视频 provider 输入 schema 不得暴露顶层 image_url，应使用 reference_image_url 或 reference_image_path；Classic 图生视频接受 reference_image_url 或转为 raw base64 的本地路径（官方字段 image）；Turbo 图生视频需要 URL 首帧，不得回退为经 fal.ai 上传本地文件；仅在当前 schema 支持处发送 aspect_ratio（Classic 文生视频、Turbo 文生视频、Video Omni）；默认付费路径应避免 4k、原生声音或批量行为，除非显式选择。
图像参数
api_family="generation" 用于 /v1/images/generations，api_family="omni" 用于 /v1/images/omni-image。
生成/编辑路径：prompt 必填，应保持在官方 2500 字符限制内；image_url 作为官方 image 传递；image_path 转为 raw base64 作为官方 image 发送；image_reference 可为 subject 或 face。
Omni 路径：将引用放入 image_list[]，使用官方 image 值；仅在需要绑定特定引用图时使用 <<<image_1>>> 之类占位符。
TTS 参数
kling_tts 使用 text、voice_id、voice_language（当前为 zh 或 en）、voice_speed。除非已验证账号特定默认值，否则要求显式 voice_id，不得硬编码虚构音色。需下载每个返回音频项，将 data.output_path 设为第一个本地文件，并包含 voice_id、voice_language、voice_speed、task_id 与非零 cost_usd。
Avatar 参数
kling_avatar 使用 /v1/videos/avatar/image2video，接受 avatar 图像（URL 或转为 raw base64 的本地路径）、audio_id 或 sound_file、可选 prompt、mode（如 std 或 pro）。与本地 talking_head 保持分离；需要 Kling avatar 输出的 pipeline 须显式列出并选择。
Lip Sync 参数
kling_lip_sync 分两步：先 POST /v1/videos/identify-face（video_id 或 video_url），从 data.face_data[] 读取人脸；再 POST /v1/videos/advanced-lip-sync，传 session_id 与一个 face_choose[] 项，含 face_id、audio_id 或 sound_file，以及声音起始/结束/插入时间。本地视频路径不得静默经 fal.ai 或其他 provider 上传。若返回多张人脸且未传 face_id 或 face_choose，除非显式设置 auto_select_face=True，否则应停止并返回人脸列表等待确认；自动选择时需在结果/产物中记录选择理由与选中人脸。
音视频特效
官方 Kling 音频特效（/v1/audio/text-to-audio、/v1/audio/video-to-audio）与视频特效（/v1/videos/effects）有意不作为默认 OpenMontage selector 工具；应在 docs/tests 记录未映射原因，而非注册可能被现有 pipeline 误用的工具。
Elements 辅助
Elements 是 Kling Official 的内部辅助，不是新的 OpenMontage 工具能力。使用 tools/_kling/elements.py 规范化 element_list[].element_id，可选只读查询 element 端点，并在查询时记录 element 元数据；默认 provider 路径不创建或删除 element。
账号用量辅助
账号用量仅供诊断。使用 tools/_kling/account.py 进行低频 /account/costs 检查，带本地缓存与限流保护；不得在每次生成前调用，也不放入 selector 或生产 pipeline 阶段。遇到 1101 或 1102 时，应说明账号或资源包已耗尽并给出账号用量诊断提示。
回调注意
Provider 可接受 callback_url，但轮询仍是默认执行模式。Classic 与 Omni 路径在顶层传 callback_url，Turbo 路径通过 options.callback_url 传递。成功结果应记录 callback_requested=true、polling_used=true、callback_url 与 task_id。发送前校验回调 URL，仅允许绝对的 http 或 https URL。
错误处理
应尽可能暴露官方 code、message 与 request_id。不重试：认证失败 1000-1004；余额/资源包耗尽 1101、1102；权限/模型访问 1103；参数错误 1200、1201；安全策略 1301。有限重试可接受：1302 请求过快、1303 并发/资源包槽位限制、5000/5001/5002 服务器/维护/积压错误。对 1303，应说明账号触及并发或资源包槽位限制。
成本治理
官方 Kling 是付费远程 API。Provider 工具须从 estimate_cost() 返回非零保守估算，并在成功付费结果中包含 cost_usd；在实现账号用量对账前，估算视为低置信度。高成本 Omni 输入（如多个引用、element ID、result_type="series"、mode="4k"、sound="on"）必须提高或标记成本估算。
提示词说明
视频方面，从通用 OpenMontage 视频提示骨架开始：主体、主体运动、场景、空间取景与镜头。Kling 通常对清晰的时间动作顺序、镜头运动动词与简洁负向提示反应良好。参考工作流中，应说明哪些内容需与参考保持一致、哪些需要改变。