kling-official

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kling Official Direct API

Kling官方直接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="kling_official"

的OpenMontage工具。这并非fal.ai Kling网关。官方Kling使用

KLING_API_KEY

、可选的

KLING_API_BASE_URL

，以及

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.

```
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
```
功能。

切勿在这些路径间静默切换。若所选提供者不可用，需明确告知阻碍，并在替换前征得用户同意。

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>

默认基础URL：

text

https://api-singapore.klingai.com

用户可通过

KLING_API_BASE_URL

覆盖默认值，例如使用区域端点。所有请求均发送JSON数据，并附带：

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

经典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 References

Omni参考

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

end_frame

video_list[]

with

video_url

, official

refer_type

values such as

feature

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.

Video Omni和Image Omni通过

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。

Image Omni接受包含官方

image

值的

image_list[]

。提示占位符（如

<<<image_1>>>

）必须稳定映射到提供的图像顺序。若提示已包含占位符，需验证引用的图像是否存在，且不得插入重复内容。

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.

TTS、虚拟形象和唇形同步是对现有OpenMontage能力的提供者扩展。音频特效和视频特效是官方Kling端点，但在流水线拥有稳定能力插槽前，它们不会注册为默认OpenMontage工具。

请勿在提供者实现内添加
```
sound_effects
```
或
```
video_effects
```
能力。
请勿让视频特效进入常规
```
video_generation
```
选择器路径。
除非流水线明确支持该形式且工具的
```
best_for
```
/
```
not_good_for
```
有相关说明，否则请勿将短音效伪装成长背景音乐。

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.

使用

operation

来适配OpenMontage语义：

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

使用

api_family

来选择官方协议：

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

重要约束：

官方视频提供者输入模式不得暴露顶层
```
image_url
```
；请使用
```
reference_image_url
```
或
```
reference_image_path
```
。
经典图生视频接受
```
reference_image_url
```
或转换为原始base64的本地路径（对应官方字段
```
image
```
）。
Turbo图生视频要求提供第一帧的URL。请勿通过fal.ai上传本地文件作为 fallback。
仅在当前模式支持的场景下发送
```
aspect_ratio
```
：经典文生视频、Turbo文生视频和Video Omni。
默认付费路径应避免
```
4k
```
、原生音效或批量行为，除非用户明确选择。

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.

使用

api_family="generation"

对应

/v1/images/generations

，使用

api_family="omni"

对应

/v1/images/omni-image

。

生成/编辑路径：

```
prompt
```
为必填项，且长度应控制在官方限制的2500字符以内。
```
image_url
```
直接作为官方
```
image
```
字段传递。
```
image_path
```
转换为原始base64后作为官方
```
image
```
字段发送。
```
image_reference
```
可选值为
```
subject
```
或
```
face
```
。

Omni路径：

将参考内容放入包含官方
```
image
```
值的
```
image_list[]
```
中。
仅当提示需要绑定特定参考图像时，才使用
```
<<<image_1>>>
```
这类提示占位符。

TTS Parameters

TTS参数

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

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 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.

kling_avatar

使用

/v1/videos/avatar/image2video

，接受以下参数：

通过URL或转换为原始base64的本地路径提供的虚拟形象图像
```
audio_id
```
或
```
sound_file
```
可选的
```
prompt
```
```
mode
```
，如
```
std
```
或
```
pro
```

请将其与本地

talking_head

功能区分开。需要Kling虚拟形象输出的流水线必须明确列出并选择该功能。

Lip Sync Parameters

唇形同步参数

kling_lip_sync

has two steps:

POST /v1/videos/identify-face

with

video_id

video_url

; read faces from

data.face_data[]

POST /v1/videos/advanced-lip-sync

with

session_id

and one

face_choose[]

item containing

face_id

audio_id

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

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.

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或其他提供者静默上传。若返回多个人脸且用户未传递

face_id

或

face_choose

，需停止操作并返回人脸列表供用户确认，除非明确设置了

auto_select_face=True

。若启用自动选择，需在结果/工件中记录选择原因和选中的人脸。

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.

官方Kling音频特效（

/v1/audio/text-to-audio

、

/v1/audio/video-to-audio

）和视频特效（

/v1/videos/effects

）并非默认OpenMontage选择器工具。请在文档/测试中记录未映射的原因，而非注册当前流水线可能误用的工具。

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.

元素是Kling官方内部助手，并非新的OpenMontage工具能力。请使用

tools/_kling/elements.py

来标准化

element_list[].element_id

，可选择性查询只读元素端点，并在查询时记录元素元数据。请勿在默认提供者路径中创建或删除元素。

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

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

账户使用情况仅用于诊断。请使用

tools/_kling/account.py

进行低频率的

/account/costs

检查，并提供本地缓存和限流保护。请勿在每次生成前调用该接口，也请勿将其放入选择器或生产流水线阶段。

若遇到

或

错误，需告知用户账户或资源包已耗尽，并提供账户使用情况的诊断提示。

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.

提供者可接受

callback_url

，但轮询仍是默认执行模式。

经典和Omni路径在顶层传递
```
callback_url
```
。
Turbo路径通过
```
options.callback_url
```
传递。

成功结果应记录

callback_requested=true

、

polling_used=true

、

callback_url

和

task_id

。

发送前需验证回调URL；仅允许绝对
```
http
```
或
```
https
```
URL通过。

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

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

只要可用，就需展示官方

code

、

message

和

request_id

。

以下情况请勿重试：

认证失败：
```
1000
```
-
```
1004
```
余额/资源包耗尽：
```
1101
```
、
```
1102
```
权限/模型访问：
```
1103
```
参数错误：
```
1200
```
、
```
1201
```
安全策略：
```
1301
```

以下情况可进行有限次数的重试：

```
1302
```
请求过快
```
1303
```
并发/资源包插槽限制
```
5000
```
、
```
5001
```
、
```
5002
```
服务器/维护/积压错误

若遇到

错误，需向用户说明账户已达到并发或资源包插槽限制。

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.

官方Kling是付费远程API。提供者工具必须从

estimate_cost()

返回非零的保守估算值，并在成功的付费结果中包含

cost_usd

。在实现账户使用对账前，估算值视为低可信度。高成本Omni输入（如多参考、元素ID、

result_type="series"

、

mode="4k"

、

sound="on"

）必须提高或标记成本估算。

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.

对于视频生成，请从通用OpenMontage视频提示框架入手：主体、主体动作、场景、空间构图和镜头。Kling对清晰的时间动作顺序、镜头移动动词和简洁的负面提示响应较好。对于参考工作流，请说明参考内容中应保持一致的部分和需要更改的部分。