kling-official

Kling 官方 Direct API

在 OpenMontage 工具中使用 provider="kling_official" 时，请使用此技能。这不是 fal.ai Kling 网关。官方 Kling 使用 KLING_API_KEY、可选的 KLING_API_BASE_URL，以及 Authorization: Bearer <KLING_API_KEY>。

Provider 区分

• 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 功能中。它们不会取代本地的 talking_head 或 lip_sync。

绝不要在不提示的情况下切换这些路径。如果所选 provider 不可用，请说明阻碍并在替换前征求确认。

身份验证与端点

默认基础 URL：

https://api-singapore.klingai.com

用户可以通过 KLING_API_BASE_URL 覆盖此设置，例如使用区域端点。所有请求均以 JSON 格式发送，并包含：

Authorization: Bearer <KLING_API_KEY>

任务协议

经典 API：

• 创建 ID 的路径：data.task_id
• 状态：submitted、processing、succeed、failed
• 结果路径：data.task_result.videos[]、data.task_result.images[]、data.task_result.audios[]

Turbo API：

• 创建 ID 的路径：data.id
• 轮询路径：GET /tasks?task_ids=<id>
• 状态：submitted、processing、succeeded、failed
• 结果路径：data[0].outputs[]

请将解析器分开。不要编写会猜测 task_id 与 id、或 succeed 与 succeeded 之间区别的模糊解析器。

Omni 参考

Video Omni 和 Image Omni 均保留在现有 provider 工具中，通过 api_family="omni" 使用。 不要创建选择器级别的 Omni 操作。

Video Omni 接受以下官方参考结构：

• image_list[]，包含 image_url 和可选的 type，例如 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，或要求使用此类 URL。

Image Omni 接受包含官方 image 值的 image_list[]。提示词中的 <<<image_1>>> 等占位符必须稳定映射到所提供图像的顺序。如果提示词已经包含占位符，请验证所引用的图像确实存在，并且不要插入重复项。

功能边界

TTS、头像和口型同步是对现有 OpenMontage 功能的 provider 扩展。音频效果和视频效果是 Kling 官方端点，但在流水线具备稳定的功能槽位之前，不会注册为默认的 OpenMontage 工具。

• 不要在 provider 实现中添加 sound_effects 或 video_effects 功能。
• 不要让视频效果进入常规的 video_generation 选择器路径。
• 不要将短音效伪装成长背景音乐，除非某个流水线明确使用此类音频形式，且该工具的 best_for / not_good_for 也对此作出说明。

视频参数

使用 operation 表示 OpenMontage 语义：

• text_to_video
• image_to_video
• reference_to_video

使用 api_family 选择官方协议：

• classic
• turbo
• omni

重要约束：

• 官方视频提供商的输入架构不得公开顶层 image_url；应使用 reference_image_url 或 reference_image_path。
• Classic 图生视频接受 reference_image_url，或转换为原始 base64 并填入官方字段 image 的本地路径。
• Turbo 图生视频要求首帧为 URL。不得将本地文件上传到 fal.ai 作为回退方案。
• 仅在当前架构支持时发送 aspect_ratio：Classic 文生视频、Turbo 文生视频和 Video Omni。
• 默认的付费路径应避免使用 4k、原生声音或批量行为，除非用户明确选择。

图像参数

/v1/images/generations 使用 api_family="generation"，/v1/images/omni-image 使用 api_family="omni"。

生成／编辑路径：

• 必须提供 prompt，且长度应低于官方的 2500 字符限制。
• image_url 会原样传递为官方字段 image。
• image_path 会转换为原始 base64，并作为官方字段 image 发送。
• image_reference 可以是 subject 或 face。

Omni 路径：

• 使用官方字段 image，将参考图放入 image_list[]。
• 仅当提示词需要绑定特定参考图时，才使用 <<<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，并接受：

• 通过 URL 提供的头像图像，或转换为原始 base64 的本地路径
• audio_id 或 sound_file
• 可选的 prompt
• mode，例如 std 或 pro

将其与本地 talking_head 分开。需要 Kling avatar 输出的流水线必须明确列出并选择该功能。

唇形同步参数

kling_lip_sync 分为两个步骤：

1. 使用 video_id 或 video_url 调用 POST /v1/videos/identify-face；从 data.face_data[] 读取人脸
2. 调用 POST /v1/videos/advanced-lip-sync，传入 session_id 和一个 face_choose[] 项，其中包含 face_id、audio_id 或 sound_file，以及声音的开始、结束和插入时间

不得通过 fal.ai 或任何其他提供商静默上传本地视频路径。如果返回多张人脸，且用户未传入 face_id 或 face_choose，则停止并返回人脸列表以供确认，除非明确设置了 auto_select_face=True。如果自动选择人脸，应在结果／产物中记录选择理由和所选人脸。

音频特效和视频特效

官方 Kling 音频特效（/v1/audio/text-to-audio、/v1/audio/video-to-audio）和视频特效（/v1/videos/effects）有意不作为默认 OpenMontage 选择器工具。应在文档／测试中记录不映射的原因，而不是注册当前流水线可能误用的工具。

Elements 辅助工具

Elements 是 Kling Official 的内部辅助工具，并非新的 OpenMontage 工具能力。 使用 tools/_kling/elements.py 规范化 element_list[].element_id，可选择查询只读元素端点，并在查询时记录元素元数据。不得通过默认提供商路径创建或删除元素。

账号用量辅助工具

账号用量仅用于诊断。使用 tools/_kling/account.py 低频检查 /account/costs，并启用本地缓存和节流保护。不得在每次生成前调用，也不得将其加入选择器或生产流水线阶段。

对于 1101 或 1102，应说明账号或资源包已耗尽，并提供账号用量诊断提示。

回调说明

服务提供方可能接受 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。服务提供方工具必须在 estimate_cost() 中返回非零的保守估算值，并在成功的付费结果中包含 cost_usd。在实现账号用量核对之前，应将估算视为低置信度。 多个参考图、元素 ID、result_type="series"、mode="4k" 和 sound="on" 等高成本 Omni 输入必须提高成本估算，或对其进行标记。

提示词说明

对于视频，请从通用的 OpenMontage 视频提示词骨架开始：主体、主体动作、场景、空间构图和摄像机。Kling 通常对清晰的动作时间顺序、摄像机运动动词和简洁的负面提示词响应良好。对于参考工作流，请说明哪些内容应与参考保持一致，哪些内容应发生变化。