Kling 3.0 Turbo

kling-3.0-turbo 支持文生视频与单首帧图生视频，输出 720p 或 1080p、3–15 秒的有声视频。

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

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

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

创建任务

文生视频

最简请求默认生成 720p、5 秒、16:9 视频，关闭水印。Turbo 固定音画同出，无需也不支持音频开关。

curl -X POST 'https://api.aivideoapi.ai/text-to-video/kling-3.0-turbo' \
  -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": "turbo-text-001",
    "callback_url": "https://app.example.com/webhooks/video",
    "watermark_info": {"enabled": true}
  }
}

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

首帧图生视频

向 POST /image-to-video/kling-3.0-turbo 提交一张 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": "turbo-image-001"}
}

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

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

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": "turbo-base64-001"}
}

明确分镜

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

识别到该格式后自动启用明确分镜，无需传 multi_shot；普通提示词默认按单镜头生成。

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

参数和素材限制

字段	可选值和行为
`prompt`	文生视频必填，正向和负向描述均写入此字段
`contents`	图生视频必填，恰好一个 `first_frame`，最多一个 `prompt`
`contents[].type`	`first_frame` 搭配 `url`，或 `prompt` 搭配 `text`
`settings.resolution`	`720p`（默认）或 `1080p`
`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`；开启后额外返回水印副本

Turbo 不支持尾帧、参考图片或视频、视频编辑、主体、4K、独立负向提示词字段和音频开关。

本服务图片要求：JPEG/JPG/PNG，不含透明通道，宽高分别为 300–8000 像素，宽高比为 1:2.5–2.5:1，文件不超过 10 MB；普通提示词不超过 2500 字符。该范围小于官方 Turbo 的图片 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": "turbo-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=turbo-text-001,turbo-image-001'

统一查询返回当前账号匹配的 Turbo 和 Omni 任务。如果两个模型使用同一外部 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": "turbo-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": "turbo-text-001",
    "message": "",
    "outputs": [{
      "type": "video",
      "id": "29bd04f8-3c15-4374-a364-4b484782d235",
      "url": "https://media.example.com/results/turbo-text-001.mp4?signature=example",
      "watermark_url": "https://media.example.com/results/turbo-text-001-watermarked.mp4?signature=example",
      "duration": "5"
    }],
    "billing": [{"charge_type": "unit", "amount": "192.31", "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": "turbo-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；当前接口只包含 Turbo/Omni 视频任务，因此只筛选其他产品类型时返回空结果。

最后一页的响应示例：

{
  "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": "turbo-text-001",
      "message": "",
      "outputs": [{"type": "video", "id": "29bd04f8-3c15-4374-a364-4b484782d235", "url": "https://media.example.com/results/turbo-text-001.mp4?signature=example", "duration": "5"}],
      "billing": [{"charge_type": "unit", "amount": "192.31", "package_type": "video"}]
    }],
    "count": 1,
    "next_cursor": "",
    "has_more": false
  }
}

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

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

游标保存原查询的时间范围、筛选条件和模型范围，请原样传入。任务按创建时间倒序，同一时间用任务 ID 稳定排序。旧版 Omni 游标继续只查 Omni，新游标包含两个模型。count 表示本页返回的任务数。

回调通知

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

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

已提交的回调示例：

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

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

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

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

签名与验签

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