> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Kling Videos Generation API 对接说明 > Kling video generation 集成指南 - XHuoAPI 本文将介绍一种 Kling Videos Generation API 对接说明，它是可以通过输入自定义参数来生成Kling官方的视频。 ## 申请流程 要使用 API，需要先到 [Kling Videos Generation API](https://api.xhuoapi.ai/documents/3b921a16-a411-4557-8335-53f21d3f9e46) 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示： ![](https://cdn.xhuoapi.ai/q6ytrc.png) 如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。 在首次申请时会有免费额度赠送，可以免费使用该 API。 ## 基本使用 首先先了解下基本的使用方式，就是输入提示词 `prompt`、 生成行为 `action`、首帧参考图片 `start_image_url` 以及模型 `model`，便可获得处理后的结果，首先需要简单地传递一个 `action` 字段，它的值为 `text2video`，它主要包含三种行为：文生视频（`text2video`）、图生视频（`image2video`）、扩展视频（`extend`），然后我们还需要输入模型 `model`，目前主要有 `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3`, `kling-v3-omni`, `kling-video-o1` 模型，具体的内容如下：

可以看到这里我们设置了 Request Headers，包括： * `accept`：想要接收怎样格式的响应结果，这里填写为 `application/json`，即 JSON 格式。 * `authorization`：调用 API 的密钥，申请之后可以直接下拉选择。 另外设置了 Request Body，包括： * `model`：生成视频的模型，主要有 `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3`, `kling-v3-omni`, `kling-video-o1` 模型。 * `mode`：生成视频的模式，可选值为标准模式 `std`、极速模式 `pro` 和原生 4K 模式 `4k`。其中 `4k` 仅支持 `kling-v3` 和 `kling-v3-omni`，且与 `camera_control`（运镜控制）不兼容。 * `action`：此次视频生成任务的行为，主要包含三种行为，分别为：文生视频（`text2video`）、图生视频（`image2video`）、扩展视频（`extend`）。 * `start_image_url`：当选择图生视频行为 `image2video` 就必须需要上传的首帧参考图片链接。 * `end_image_url`：图生视频时可选，指定尾帧。 * `duration`：视频时长，单位秒。对于 `kling-v3` 和 `kling-v3-omni` 模型支持灵活时长 3-15 秒（整数），其他模型支持 5 或 10 秒。 * `generate_audio`：是否同步生成音频，可选，布尔值。支持 `kling-v3`、`kling-v3-omni` 以及 `kling-v2-6`（仅 pro 模式）。默认为 `false`。 * `aspect_ratio`：视频宽高比，可选，支持 `16:9`、`9:16`、`1:1`，默认 `16:9`。 * `cfg_scale`：相关性强度，范围 \[0,1]，越大越贴合提示词。 * `camera_control`：可选，控制相机运动的对象参数，支持 type/simple 预设以及 horizontal、vertical、pan、tilt、roll、zoom 等配置。 * `negative_prompt`：可选，不希望出现的反向提示词，最多 200 字符。 * `element_list`：主体参考列表，只适用模型`kling-video-o1`，该参数的具体的使用方式参考[官网文档](https://docs.qingque.cn/d/home/eZQAyImcbaS0fz-8ANjXvU5ed?identityId=1oEG9JKKMFv#section=h.5t7wme23nn6z)。 * `video_list`：参考视频，通过URL方式获取，只适用模型`kling-video-o1`,该参数的具体的使用方式参考[官网文档](https://docs.qingque.cn/d/home/eZQAyImcbaS0fz-8ANjXvU5ed?identityId=1oEG9JKKMFv#section=h.5t7wme23nn6z)。 * `prompt`：提示词。 * `callback_url`：需要回调结果的URL。 选择之后，可以发现右侧也生成了对应代码，如图所示：

点击「Try」按钮即可进行测试，如上图所示，这里我们就得到了如下结果： ```json theme={null} { "success": true, "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4", "duration": "5.1", "state": "succeed", "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0" } ``` 返回结果一共有多个字段，介绍如下： * `success`，此时视频生成任务的状态情况。 * `task_id`，此时视频生成任务ID。 * `video_id`，此时视频生成任务的视频ID。 * `video_url`，此时视频生成任务的视频链接。 * `duration`，此时视频生成任务的视频链时长。 * `state`，此时视频生成任务的状态。 可以看到我们得到了满意的视频信息，我们只需要根据结果中 `data` 的视频链接地址获取生成的Kling视频即可。 另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下： ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-v1", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }' ``` ## 模型能力矩阵 不同模型对参数的支持情况差异较大。以下矩阵整理自 [Kling 官方 video models 文档](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels)，调用前请先核对当前 `model` / `mode` / `duration` 组合是否支持你所需的功能，否则上游会返回 `model/mode/duration(...) is not supported with image_tail` 等错误。 | 模型 | 模式 | `end_image_url`（首尾帧） | `generate_audio`（伴音） | `camera_control`（运镜） | 备注 | | ------------------- | -------------- | -------------------- | -------------------- | -------------------- | -------------------------------------------- | | `kling-v1` | std / pro | ✅ 仅 `duration=5` | ❌ | ✅ 仅 `duration=5` | `extend` 不支持 `negative_prompt` 与 `cfg_scale` | | `kling-v1-6` | std | ❌ | ❌ | ❌ | 多图生视频、`extend` 全模式可用 | | `kling-v1-6` | pro | ✅ | ❌ | ❌ | | | `kling-v2-master` | — | ❌ | ❌ | ❌ | 单一模式，仅 `duration=5/10` | | `kling-v2-1-master` | — | ❌ | ❌ | ❌ | 单一模式，仅 `duration=5/10` | | `kling-v2-5-turbo` | std | ❌ | ❌ | ❌ | | | `kling-v2-5-turbo` | pro | ✅ | ❌ | ❌ | | | `kling-v2-6` | std | ❌ | ❌ | ❌ | | | `kling-v2-6` | pro | ✅ | ✅ | ❌ | 唯一同时支持伴音的非 v3 模型 | | `kling-v3` | std / pro | ✅ | ✅ | ✅ | `duration` 范围 3–15 秒 | | `kling-v3` | 4k | ✅ | ✅ | ❌ | 4K 模式与运镜不兼容 | | `kling-v3-omni` | std / pro / 4k | ✅ | ✅ | ❌ | | | `kling-video-o1` | std / pro | ✅ | ❌ | ❌ | 仅支持 `duration=5/10` | 注意事项： * `mode=4k` 仅 `kling-v3` 与 `kling-v3-omni` 支持；并且与 `camera_control`（运镜）互斥。 * `end_image_url` 只能在 `action=image2video` 时配合 `start_image_url` 使用。仅传 `end_image_url`（无 `start_image_url`）会被拒绝。 * `kling-v3` / `kling-v3-omni` 接受任意 3–15 秒的整数 `duration`；其余模型只接受 5 或 10。 * `generate_audio` 默认 `false`。仅 `kling-v3`、`kling-v3-omni` 和 `kling-v2-6`（pro 模式）支持。 ## 扩展视频功能 如果想对已经生成的Kling视频进行继续生成的话，可以将参数 `action` 设置为 `extend` ，并且输入需要继续生成视频的 ID，视频 ID 的获取是根据基本使用来获取，如下图所示：

这时候可以看到视频的 ID 为： ``` "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c" ``` > 注意，这里的视频中 `video_id` 是生成后视频的 ID，如果你不知道如何生成视频，可以参考上文的基本使用来生成视频。 接下来我们要必须填下一步需要扩展的提示词来自定义生成视频，就可以指定如下内容： * `model`：生成视频的模型，主要有 `kling-v1` 、`kling-v1-5` 和 `kling-v1-6` 模型。 * `mode`：生成视频的模式，可选值为标准模式 `std`、极速模式 `pro` 和原生 4K 模式 `4k`（仅 `kling-v3` 和 `kling-v3-omni` 支持，与运镜控制不兼容）。 * `duration`：此次视频生成任务的视频时长，主要包含5s和10s。 * `start_image_url`：当选择图生视频行为 `image2video` 就必须需要上传的首帧参考图片链接。 * `prompt`：提示词。 填写样例如下：

填写完毕之后自动生成了代码如下：

对应的 Python 代码： ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/kling/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "action": "extend", "model": "kling-v1", "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.", "duration": 10 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 点击运行，可以发现会得到一个结果，如下： ```json theme={null} { "success": true, "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4", "duration": "9.6", "state": "succeed", "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23" } ``` 可以看出，结果内容与上文的是一致的，这也就实现视频的扩展视频功能。 ## 异步回调 由于 Kling Videos Generation API生成的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。 整体流程是：客户端发起请求的时候，额外指定一个 `callback_url` 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 `task_id` 的字段信息，代表当前的任务 ID。当任务完成之后，生成视频的结果会通过 POST JSON 的形式发送到客户端指定的 `callback_url`，其中也包括了 `task_id` 字段，这样任务结果就可以通过 ID 关联起来了。 下面我们通过示例来了解下具体怎样操作。 首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 [https://webhook.site/，打开该网站即可得到一个](https://webhook.site/，打开该网站即可得到一个) Webhook URL，如图所示： ![](https://cdn.xhuoapi.ai/tbcnai.png) 将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`。 接下来，我们可以设置字段 `callback_url` 为上述 Webhook URL，同时填入相应的参数，具体的内容如图所示：

点击运行，可以发现会立即得到一个结果，如下： ``` { "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` 稍等片刻，我们可以在 `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3` 上观察到生成视频的结果，如图所示： ![](https://cdn.xhuoapi.ai/zv5u2q.png) 内容如下： ```json theme={null} { "success": true, "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4", "duration": "5.1", "state": "succeed", "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` 可以看到结果中有一个 `task_id` 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。 ## 错误处理 在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如： * `400 token_mismatched`：Bad request, possibly due to missing or invalid parameters. * `400 api_not_implemented`：Bad request, possibly due to missing or invalid parameters. * `401 invalid_token`：Unauthorized, invalid or missing authorization token. * `429 too_many_requests`：Too many requests, you have exceeded the rate limit. * `500 api_error`：Internal server error, something went wrong on the server. ### 错误响应示例 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 结论 通过本文档，您已经了解了如何使用 Kling Videos Generation API 可通过输入提示词以及首帧参考图片来生成视频。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。