Kling 3.0 官方协议

标准 Kling 3.0 官方协议支持文生、首帧及首尾帧图生视频，输出 720p、1080p 或 4K、3–15 秒视频，可选生成音频。

已有官方 Kling 3.0 协议客户端可将 base_url 改为 https://api.aivideoapi.ai，并替换为平台 API Key，继续使用下面的官方路径和请求、响应字段。素材限制与积分收取规则以本页为准。

方法与路径	功能
`POST /text-to-video/kling-3.0`	文生视频
`POST /image-to-video/kling-3.0`	首帧或首尾帧图生视频
`GET /tasks`	按任务 ID 或外部 ID 查询
`POST /tasks`	筛选和游标分页查询

所有接口使用 Authorization: Bearer YOUR_PLATFORM_API_KEY；JSON 请求使用 Content-Type: application/json。直接使用上述路径，不额外添加 /v1。

平台模型与 Price Group 中使用独立名称 kling-3.0-official。创建请求不需要 model 字段，对外路径仍为 kling-3.0。现有统一 API 客户请继续使用原 Kling 3.0 文档。

创建任务

文生视频

最简请求默认生成 720p、5 秒、16:9 无声视频，开启智能分镜，关闭水印。设置 audio="native" 可生成音频。

curl -X POST 'https://api.aivideoapi.ai/text-to-video/kling-3.0' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"一只小猫在月光下的花园中奔跑，伴随树叶沙沙声与轻柔的脚步声。"}'

1080p 竖屏视频，同时设置回调和水印副本：

{
  "prompt": "女孩坐在火车窗边看向不断掠过的风景，头发随车厢轻轻晃动，伴随平缓的列车声。",
  "settings": {"resolution": "1080p", "duration": 5, "aspect_ratio": "9:16"},
  "options": {
    "external_task_id": "standard-text-001",
    "callback_url": "https://app.example.com/webhooks/video",
    "watermark_info": {"enabled": true}
  }
}

以下创建示例均为完整 JSON 请求体，发送到对应的文生或图生接口。示例中的素材地址和回调地址需替换为实际可访问的地址。

首帧图生视频

向 POST /image-to-video/kling-3.0 提交一张 first_frame，可选一个 prompt。输出比例跟随首帧，不传 settings.aspect_ratio。

{
  "contents": [
    {"type": "prompt", "text": "小猫缓缓转头看向镜头，微风轻拂毛发，远处传来鸟鸣。"},
    {"type": "first_frame", "url": "https://media.example.com/kitten.jpg"}
  ],
  "settings": {"resolution": "720p", "duration": 5},
  "options": {"external_task_id": "standard-image-001"}
}

也可以仅提交首帧，不填写提示词：

{
  "contents": [{"type": "first_frame", "url": "https://media.example.com/kitten.jpg"}]
}

首尾帧图生视频

首帧和尾帧各一张，通过两张图片约束视频开始和结束画面。

{
  "contents": [
    {"type": "prompt", "text": "镜头平稳推进，小猫从坐姿起身，缓缓走向花园。"},
    {"type": "first_frame", "url": "https://media.example.com/start.jpg"},
    {"type": "last_frame", "url": "https://media.example.com/end.jpg"}
  ],
  "settings": {"resolution": "1080p", "duration": 5, "audio": "off", "multi_shot": false},
  "options": {"external_task_id": "standard-frames-001"}
}

4K 有声视频

{
  "prompt": "城市日出延时摄影，伴随轻柔音乐，保持地平线稳定。",
  "settings": {"resolution": "4k", "duration": 10, "aspect_ratio": "16:9", "audio": "native", "multi_shot": false},
  "options": {"external_task_id": "standard-4k-001"}
}

Base64 首帧

首帧和尾帧的 contents[].url 均支持 PNG/JPEG Base64，可带或不带 data URL 前缀。将下面的占位内容替换为完整图片数据。平台暂存时保留原始字节，不缩放、不压缩；较大图片优先使用 URL。

{
  "contents": [
    {"type": "prompt", "text": "镜头缓慢推进至主体，伴随轻柔的环境音。"},
    {"type": "first_frame", "url": "data:image/jpeg;base64,REPLACE_WITH_FULL_IMAGE_BASE64"}
  ],
  "settings": {"resolution": "1080p", "duration": 8},
  "options": {"external_task_id": "standard-base64-001"}
}

明确分镜

提示词使用 镜头 n, 秒数, 描述; 格式，以半角逗号和分号分隔；英文描述也需保留中文 镜头 标记。支持 1–6 个镜头，编号从 1 连续递增，各镜头时长为至少 1 秒的整数，总和必须等于 settings.duration。每个镜头描述请控制在 512 字符以内。

settings.multi_shot 默认为 true：普通提示词使用智能分镜，识别到该格式时使用明确分镜。设为 false 后，即使提示词含分镜语法，也保留原提示词按单镜头生成。

{
  "prompt": "镜头 1, 2, 月光下的花园全景，树叶轻轻摇动;镜头 2, 3, 小猫仰望月亮的特写，伴随轻柔脚步声;",
  "settings": {"resolution": "720p", "duration": 5, "aspect_ratio": "16:9"},
  "options": {"external_task_id": "standard-shots-001"}
}

首帧图生视频也可在 prompt 素材项中使用相同格式：

{
  "contents": [
    {"type": "prompt", "text": "镜头 1, 2, 小猫缓缓转头看向镜头;镜头 2, 3, 小猫沿花园小路走向远处;"},
    {"type": "first_frame", "url": "https://media.example.com/kitten.jpg"}
  ],
  "settings": {"resolution": "1080p", "duration": 5},
  "options": {"external_task_id": "standard-image-shots-001", "watermark_info": {"enabled": true}}
}

参数和素材限制

字段	可选值和行为
`prompt`	文生视频必填，正向和负向描述均写入此字段
`contents`	图生视频必填，恰好一个 `first_frame`，可选一个 `last_frame`、最多一个 `prompt`
`contents[].type`	`first_frame` / `last_frame` 搭配 `url`，或 `prompt` 搭配 `text`
`settings.resolution`	`720p`（默认）、`1080p`、`4k`
`settings.audio`	`off`（默认）或 `native`；`original` 不支持
`settings.multi_shot`	布尔值，默认 `true`；设为 `false` 关闭多镜头
`settings.duration`	3–15 秒整数，默认 `5`
`settings.aspect_ratio`	仅文生视频使用：`16:9`（默认）、`9:16`、`1:1`
`options.external_task_id`	可选客户任务 ID，去重规则见下文
`options.callback_url`	可选 HTTP(S) 状态通知地址
`options.watermark_info.enabled`	布尔值，默认 `false`；开启后额外返回水印副本

本入口不支持仅尾帧、参考图片或视频、视频编辑、主体 ID 和主体管理，也不提供独立负向提示词字段。尾帧必须与首帧一起提交。正向和负向描述均写入官方 prompt 字段。

本服务图片要求：JPEG/JPG/PNG，不含透明通道，宽高分别为 300–8000 像素，宽高比为 1:2.5–2.5:1，文件不超过 10 MB；普通提示词不超过 2500 字符。该范围小于官方标准版的图片 50 MB、文生提示词 3072 字符限制。

平台不增加图片大小和提示词长度的前置拦截，不压缩图片、不截断文本，仅进行协议转换后原样提交。超出范围的输入仍可能在生成时被拒绝，并返回清洗后的错误。分镜描述请控制在 512 字符内，避免生成侧缩短内容。

当前部署的整个 JSON 请求体上限为 4.5 MB，包含 Base64 编码和其他字段的开销。超限请求可能在进入接口前被拒绝；较大图片请使用 HTTP(S) URL。参见请求体限制。

素材 URL 必须允许无需登录直接下载。回调 URL 须可由 API 服务访问并直接接受 POST。两类地址都需使用 HTTP(S)，且不能包含用户名和密码；回调不跟随重定向。

去重与创建响应

同账号、同模型下，使用相同 options.external_task_id 和相同参数重试会返回已有任务，不重复扣费。参数不同会返回冲突；文生与图生也视为不同请求。新任务请使用新 ID。外部 ID 按模型分别去重，建议客户在整个接入中保持全局唯一，避免查询歧义。不传或传空外部 ID 时不提供此去重保障。

创建成功返回异步任务摘要：

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "81bb383c-bf77-41dc-b123-dc5f0688a064",
  "data": {
    "id": "29bd04f8-3c15-4374-a364-4b484782d235",
    "status": "submitted",
    "create_time": 1789603200000,
    "update_time": 1789603200000,
    "external_id": "standard-text-001"
  }
}

仅传入外部 ID 时包含 external_id。时间戳均为 Unix 毫秒。创建摘要不含 outputs、billing 和任务级 message；幂等重试可能返回处于后续状态的已有任务。

按 ID 查询任务

使用 GET /tasks，task_ids 和 external_task_ids 必须且只能选择一个，均支持英文逗号分隔的批量 ID。

curl --get 'https://api.aivideoapi.ai/tasks' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
  --data-urlencode 'task_ids=29bd04f8-3c15-4374-a364-4b484782d235'

curl --get 'https://api.aivideoapi.ai/tasks' \
  -H 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
  --data-urlencode 'external_task_ids=standard-text-001,standard-image-001'

统一查询返回当前账号匹配的标准 3.0 官方协议、Omni 和 Turbo 任务。多个模型使用同一外部 ID 时，会返回所有匹配任务，不覆盖其中一条。不存在的任务和其他账号任务不返回，无匹配时为 data: []。同一任务 ID 重复传入时只返回一次。查询读取平台记录，不触发生成或轮询。

处理中返回体

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "d482570f-e19c-4d82-af57-4959ef8bf837",
  "data": [{
    "id": "29bd04f8-3c15-4374-a364-4b484782d235",
    "status": "processing",
    "create_time": 1789603200000,
    "update_time": 1789603230000,
    "external_id": "standard-text-001",
    "message": "",
    "outputs": [],
    "billing": []
  }]
}

submitted 表示已受理或等待处理；processing 包含生成、保存结果与最终积分结算阶段。两个状态的 outputs 和 billing 均为空数组。

成功返回体

此示例对应上面的 1080p、5 秒文生任务，账号倍率为 1。

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "9ebfc933-3d04-424b-9f11-707d0c701ce1",
  "data": [{
    "id": "29bd04f8-3c15-4374-a364-4b484782d235",
    "status": "succeeded",
    "create_time": 1789603200000,
    "update_time": 1789603320000,
    "external_id": "standard-text-001",
    "message": "",
    "outputs": [{
      "type": "video",
      "id": "29bd04f8-3c15-4374-a364-4b484782d235",
      "url": "https://media.example.com/results/standard-text-001.mp4?signature=example",
      "watermark_url": "https://media.example.com/results/standard-text-001-watermarked.mp4?signature=example",
      "duration": "5"
    }],
    "billing": [{"charge_type": "unit", "amount": "153.85", "package_type": "video"}]
  }]
}

请完整使用返回的 url 和可选 watermark_url，保留全部签名参数。平台直接透传这些地址，不更换域名或转存文件。请及时下载，地址可能过期；保留任务和积分记录不延长文件可用期，也不保证至少 30 天可下载。duration 和 billing[].amount 均为十进制字符串。

失败返回体

外层 code=0 仅表示查询成功，视频生成结果需检查任务的 status。

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "42685723-917a-4ea7-82ef-cdf7c03aeaa9",
  "data": [{
    "id": "7689f980-0f92-4d31-bc7b-bc848d051d70",
    "status": "failed",
    "create_time": 1789603200000,
    "update_time": 1789603260000,
    "external_id": "standard-failed-001",
    "message": "Video generation could not be completed.",
    "outputs": [],
    "billing": []
  }]
}

筛选与分页查询

发送 POST /tasks。默认查询截至当前时间的最近 30 天，每页最多 100 条；limit 为 1–500 的整数。start_time 和 end_time 使用 Unix 毫秒数值，也兼容仅含数字的毫秒时间戳字符串。

{
  "start_time": 1789603200000,
  "end_time": 1789689600000,
  "limit": 100,
  "filters": [
    {"key": "status", "values": ["succeeded"]},
    {"key": "product_type", "values": ["video"]}
  ]
}

status 支持 submitted、processing、succeeded、failed。product_type 接受官方的 video、image、try_on；当前接口只包含标准 3.0 官方协议、Omni、Turbo 视频任务，因此只筛选其他产品类型时返回空结果。

最后一页的响应示例：

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "3d6a01c0-a624-4934-9361-15d09a4c1586",
  "data": {
    "result": [{
      "id": "29bd04f8-3c15-4374-a364-4b484782d235",
      "status": "succeeded",
      "create_time": 1789603200000,
      "update_time": 1789603320000,
      "external_id": "standard-text-001",
      "message": "",
      "outputs": [{"type": "video", "id": "29bd04f8-3c15-4374-a364-4b484782d235", "url": "https://media.example.com/results/standard-text-001.mp4?signature=example", "duration": "5"}],
      "billing": [{"charge_type": "unit", "amount": "153.85", "package_type": "video"}]
    }],
    "count": 1,
    "next_cursor": "",
    "has_more": false
  }
}

has_more=true 时，使用返回的 next_cursor 继续查询：

{"cursor": "REPLACE_WITH_NEXT_CURSOR", "limit": 100}

游标保存原查询的时间范围、筛选条件和模型范围，请原样传入。任务按创建时间倒序，同一时间用任务 ID 稳定排序。旧 v1 游标继续只查 Omni，旧 v2 游标继续查询 Omni＋Turbo；新 v3 游标包含标准 3.0 官方协议、Omni、Turbo 三个模型。count 表示本页返回的任务数。

回调通知

创建时设置 options.callback_url。标准 3.0 官方协议对实际观察到的每次状态变化建立独立事件：submitted、processing、succeeded 或 failed。未观察到的中间状态不会补造；重复查询或幂等创建不会产生新事件。

回调正文是单个任务对象，字段与查询结果中的一项一致，不包含外层 code、request_id、data。每个事件保留状态变化当时的任务快照。成功事件在积分结算完成后建立。

已提交的回调示例：

{
  "id": "29bd04f8-3c15-4374-a364-4b484782d235",
  "status": "submitted",
  "create_time": 1789603200000,
  "update_time": 1789603200000,
  "external_id": "standard-text-001",
  "message": "",
  "outputs": [],
  "billing": []
}

processing 事件使用相同结构，并更新状态和时间。成功回调示例：

{
  "id": "29bd04f8-3c15-4374-a364-4b484782d235",
  "status": "succeeded",
  "create_time": 1789603200000,
  "update_time": 1789603320000,
  "external_id": "standard-text-001",
  "message": "",
  "outputs": [{
    "type": "video",
    "id": "29bd04f8-3c15-4374-a364-4b484782d235",
    "url": "https://media.example.com/results/standard-text-001.mp4?signature=example",
    "watermark_url": "https://media.example.com/results/standard-text-001-watermarked.mp4?signature=example",
    "duration": "5"
  }],
  "billing": [{"charge_type": "unit", "amount": "153.85", "package_type": "video"}]
}

失败回调为 status="failed"，message 为失败说明，outputs 和 billing 为空，与前文失败查询的任务对象一致。

签名与验签

由账号管理员配置独立的标准 3.0 Webhook Secret，与平台 API Key 分开管理，不放在创建任务请求中。每次投递读取当前有效密钥；普通轮换后，新密钥和前一个密钥共同签名七天。紧急撤销立即移除旧密钥；删除配置后停止签名，也适用于待投递事件。

请求头	内容
`webhook-id`	事件 ID，重试保持一致；不同状态变化使用不同 ID
`webhook-timestamp`	本次投递的 Unix 秒时间戳
`webhook-signature`	一个或多个以空格分隔的 `v1,BASE64_SIGNATURE`

使用 Standard Webhooks 对原始请求体验签。例如使用 JavaScript standardwebhooks 包：

import { Webhook } from "standardwebhooks";

const rawBody = await request.text();
const verifiedTask = new Webhook(process.env.STANDARD_WEBHOOK_SECRET).verify(rawBody, {
  "webhook-id": request.headers.get("webhook-id"),
  "webhook-timestamp": request.headers.get("webhook-timestamp"),
  "webhook-signature": request.headers.get("webhook-signature"),
});
// 先按事件 ID 幂等保存，再确认接收。

自行实现时，移除密钥的 whsec_ 前缀，将剩余内容 Base64 解码，使用 HMAC-SHA256 签名 webhook-id.webhook-timestamp.rawBody，再将摘要 Base64 编码。以常量时间比较任一受支持的 v1 签名，校验时间窗口（通常为五分钟），并按事件 ID 去重。不能将解析后的 JSON 重新序列化用于验签。

未配置密钥时不发送三个 webhook-* 头。处理未签名回调前，应通过带鉴权的 GET /tasks 确认当前任务状态，再执行业务操作；状态更新须幂等，不能用较早事件覆盖终态。

接收与重试

持久保存或入队事件后，在 10 秒内返回 HTTP 2xx。视频下载等耗时操作放到异步处理。超时、网络错误、非 2xx 和重定向均视为投递失败。

第一次：事件可投递后发送。
第二次：第一次失败后延迟 3 分钟。
第三次：第二次失败后延迟 10 分钟。

每个事件最多三次。单任务按事件顺序投递，较早事件重试可能延迟后续通知，但不阻塞生成和结算。重试保留事件 ID 和正文，重新生成时间戳和签名；实际投递可能晚于计划时间。重试耗尽后可通过查询接口补齐业务状态。

回调失败不会把成功任务改成失败，不会退积分或再次发起生成。

积分收取规则

720p：无声 23.1 积分/秒，有声 34.6 积分/秒。
1080p：无声 30.8 积分/秒，有声 46.2 积分/秒。
4K：无声、有声均为 115.4 积分/秒。
文生、首帧、首尾帧同价。以上为账号倍率 1 的基础售价，单价展示保留一位小数；实际结算使用展示舍入前的配置单价。
按请求时长预扣，成功后根据实际用量结算：round(round(单价 × 秒数, 2) × 账号倍率, 2)。每个任务保留创建时的单价和倍率快照。
默认倍率下，5 秒无声视频为 720p：115.38 积分、1080p：153.85 积分、4K：576.92 积分；不能直接用展示的一位小数单价计算总额。
成功任务以 billing[].amount 为实际平台积分消耗，返回十进制字符串，charge_type="unit"、package_type="video"。
明确失败只退还一次预扣积分。提交结果或任务状态不明时，不自动重提或退款。生成成功后的异常，包括结算重试和回调失败，均不会进入失败退款流程。不支持取消任务。

从官方客户端迁移

将 https://api-beijing.klingai.com 替换为 https://api.aivideoapi.ai，将鉴权凭证替换为平台 API Key。保留官方路径、prompt / contents、settings、options 和响应解析逻辑，不添加 /v1，也不将内部模型名称写入 URL。

迁移前核对本页素材限制、主体暂不支持、积分计费及回调签名密钥配置。原统一 API 的 model="kling-3.0" 与本入口是独立模型，价格和账号倍率分别配置，不能直接复用统一 API 的请求体。