视频 API

Kling 3

POST https://api.beatapi.io/v1/videos/tasks

通过文字或画面帧生成 3–15 秒视频，支持多镜头和可复用元素控制，最高可输出 4K。

支持的生成方式

生成方式必填参数使用规则
文生视频model, prompt不要传入 images、multi_prompt 和 elements。
首帧驱动model, prompt, images传入一张图作为首帧，传入两张图时依次作为首帧和尾帧。
多镜头model, prompt, multi_shots, multi_prompt设置 multi_shots=true，所有镜头时长之和必须等于 duration。
可复用元素model, prompt, elements最多传入三个已命名的图片或视频参考元素。

异步任务流程

创建任务后保存 data.id，每 5–10 秒调用 GET /v1/tasks/{task_id} 查询状态。status 为 succeeded 时读取 data.output.media，为 failed 时读取 data.error_code 和 data.error_message，随后按错误与重试策略处理。

使用本地文件

请先上传本地输入，再将返回的 data.url 填入请求。

鉴权

Authorization   string   必填

在 Authorization 请求头中以 Bearer 令牌发送服务端 API 密钥，可在控制台创建。

Authorization: Bearer <BEATAPI_API_KEY>

永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 Content-Type: application/json。建议为每个逻辑创建请求设置唯一的 Idempotency-Key，只有完全相同的请求体才能安全复用原键。

请求体

字段名、类型和枚举值保留英文原样，用途和限制用中文说明。

model   string   必填

稳定的公开模型 ID，必须使用当前页面列出的值。

取值与默认值: 固定值 kling-3

prompt   string   必填

描述生成、编辑或分析目标的提示词。

取值与默认值: 长度 1–5000 字符

images   string[]   选填

按当前模型或工作流要求排序的公网 HTTPS 图片 URL 列表。

取值与默认值: 1–2 项

duration   integer   选填

请求的输出时长，单位为秒。

取值与默认值: 默认值 5；取值范围 3–15

aspect_ratio   enum<string>   选填

输出素材的宽高比。

取值与默认值: 可选值 16:9、9:16、1:1

resolution   enum<string>   选填

输出素材的分辨率或质量档位。

取值与默认值: 可选值 std、pro、4K；默认值 pro

sound   boolean   选填

是否生成与视频同步的声音。

multi_shots   boolean   选填

是否启用多镜头生成。

取值与默认值: 默认值按生成方式为 false

multi_prompt   object[]   选填

多镜头模式的分镜提示词列表，各镜头时长之和必须等于 duration。

取值与默认值: 1–5 项

multi_prompt.prompt   string   随父参数必填

描述生成、编辑或分析目标的提示词。

取值与默认值: 长度 1–500 字符

multi_prompt.duration   integer   随父参数必填

请求的输出时长，单位为秒。

取值与默认值: 取值范围 1–12

elements   object[]   选填

需要在多个镜头中保持一致的可复用参考元素。

取值与默认值: 最多 3 项

elements.name   string   随父参数必填

便于识别端点或可复用元素的名称。

取值与默认值: 最少 1 字符

elements.description   string   选填

用于说明对象、主体或端点用途的文字。

elements.element_input_urls   string[]   随父参数必填

可复用元素的公网 HTTPS 图片或视频 URL 列表。

取值与默认值: 1–4 项

elements.element_input_audio_urls   string[]   选填

可复用元素的公网 HTTPS 音频 URL 列表。

取值与默认值: 1–1 项

elements.start_time   integer   选填

该片段的开始时间。

取值与默认值: 取值范围 0–30000

elements.end_time   integer   选填

该片段的结束时间。

取值与默认值: 取值范围 0–30000

请求示例

文生视频

$curl --request POST \
>  --url https://api.beatapi.io/v1/videos/tasks \
>  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "model": "kling-3",
>  "prompt": "A dramatic product reveal with a slow orbiting camera move.",
>  "duration": 5,
>  "aspect_ratio": "16:9",
>  "resolution": "pro",
>  "sound": true
>}'

首帧驱动

$curl --request POST \
>  --url https://api.beatapi.io/v1/videos/tasks \
>  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "model": "kling-3",
>  "prompt": "Animate the product with a slow orbit and precise studio reflections.",
>  "images": [
>    "https://media.beatapi.io/samples/smart-bottle.png"
>  ],
>  "duration": 5,
>  "resolution": "pro",
>  "sound": true
>}'

多镜头

$curl --request POST \
>  --url https://api.beatapi.io/v1/videos/tasks \
>  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "model": "kling-3",
>  "prompt": "A two-shot cinematic product reveal.",
>  "duration": 6,
>  "aspect_ratio": "16:9",
>  "resolution": "pro",
>  "sound": true,
>  "multi_shots": true,
>  "multi_prompt": [
>    {
>      "prompt": "Macro detail shot with moving reflections.",
>      "duration": 3
>    },
>    {
>      "prompt": "Wide hero reveal on a dark pedestal.",
>      "duration": 3
>    }
>  ]
>}'

可复用元素

$curl --request POST \
>  --url https://api.beatapi.io/v1/videos/tasks \
>  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "model": "kling-3",
>  "prompt": "Keep @product consistent during a slow cinematic camera orbit.",
>  "duration": 5,
>  "resolution": "pro",
>  "elements": [
>    {
>      "name": "product",
>      "description": "The featured bottle",
>      "element_input_urls": [
>        "https://media.beatapi.io/samples/smart-bottle.png",
>        "https://media.beatapi.io/samples/neon-singer.png"
>      ]
>    }
>  ]
>}'

响应

成功请求返回 HTTP 201，响应体如下。

1{
2  "data": {
3    "id": "task_8K2qA",
4    "object": "task",
5    "task_kind": "video",
6    "capability_id": "kling-3",
7    "capability_version": null,
8    "media_type": "video",
9    "model": "kling-3",
10    "status": "queued",
11    "stage": "queued",
12    "created_at": 1782210000,
13    "updated_at": 1782210000,
14    "completed_at": null,
15    "output": null,
16    "usage": {
17      "credits_reserved": 0.65,
18      "credits_charged": 0.65,
19      "billable_duration_seconds": 5,
20      "credits_settled": 0,
21      "credits_refunded": 0
22    },
23    "request_id": "req_abc123",
24    "error_code": null,
25    "error_message": null
26  }
27}

下一步

保存接受响应中的 data.id，每 5–10 秒轮询 GET /v1/tasks/{task_id}。任务成功后从 data.output.media 读取托管结果。

错误

状态码含义与处理方式
400请求字段、格式、取值或参数组合不合法，请修正后重新请求。
401API 密钥缺失、无效或未启用。
402USD 余额不足，请充值后再创建付费任务。
409幂等键已对应其他请求体，仅能对完全相同的逻辑请求复用原键。
429超过请求频率或并发上限，请遵守 Retry-After 或返回的等待时间。