可灵 API 接入教程：任务提交、轮询与结果下载（2026）

可灵（Kling）的视频生成 API 不是“一次请求返回一段视频”的同步接口，而是先创建任务、再查询状态、最后下载结果。把它当成 Chat Completions 来写，通常会在第一步就卡住：请求返回成功，但拿不到视频，只有一条任务记录。

本文按真实接入顺序，讲清 2026 年可灵 API 的接口代际、鉴权、提交、轮询、回调、下载、幂等和迁移。接口路径和字段可能随版本调整，联调前请以官方文档为准。

说明：可灵、Kling、快手是其权利人的商标，本文仅作技术说明，与相关公司无隶属或代理关系。

一、先分清两代接口

可灵目前同时存在两套接口形态，混用是常见错误来源。

新式接口把模型版本放在路径里，例如 POST /text-to-video/kling-3.0-turbo、POST /text-to-video/kling-2.6。请求体不再需要 model_name，鉴权使用 API Key 的 Bearer 头，返回字段是 data.id 和 data.status。

旧版接口通常在 /v1/videos/... 路径下，请求体用 model_name 指定模型，鉴权使用 AccessKey/SecretKey 生成 JWT，返回字段是 task_id 和 task_status。旧接口仍可用，但新项目不建议从它起步。

本文示例以新式接口为主，文末给出两代接口的迁移清单。

二、Base URL 与鉴权

可灵文档给出的服务地址包括：

https://api-singapore.klingai.com：面向中国大陆以外服务器，官方说明它取代旧的 api.klingai.com。
https://api-beijing.klingai.com：文档示例中出现的北京地址，适合国内部署。

实际可选区域、账号适用范围和模型可用性以控制台为准。不要在不同区域之间随意切换，任务和结果通常归属于提交时的区域。

鉴权头是 Authorization: Bearer <API_KEY>，Bearer 与 Key 之间有一个空格。一个容易忽略的细节是：新式接口的查询请求也要求带 Content-Type: application/json，即使它是 GET。

Key 只能放在服务端。浏览器、App、小程序直接调用会暴露凭证，也会遇到跨域和回调不可达的问题。建议由后端统一提交任务，前端只接收任务状态。

三、提交第一个视频任务

先用最短时长、最低分辨率跑通链路，再逐步加参数。

export KLING_API_KEY="你的密钥"
export KLING_BASE_URL="https://api-singapore.klingai.com"

curl -sS -X POST "$KLING_BASE_URL/text-to-video/kling-3.0-turbo" \
  -H "Authorization: Bearer $KLING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "雨后的城市街道，镜头缓慢推进，电影感，16:9",
    "settings": {
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "duration": 5
    },
    "options": {
      "external_task_id": "demo-20261019-001",
      "callback_url": "https://example.com/kling/callback"
    }
  }'

成功响应的业务码是 0，任务 ID 在 data.id，初始状态通常为 submitted：

{
  "code": 0,
  "message": "",
  "request_id": "…",
  "data": {
    "id": "…",
    "status": "submitted",
    "create_time": 0,
    "update_time": 0,
    "external_id": "demo-20261019-001"
  }
}

参数上有几个边界：3.0 Turbo 的 duration 支持 3 到 15 秒，默认 5 秒；2.6 常见为 5 秒或 10 秒；prompt 上限约 3072 字符，官方建议控制在 2500 以内。分辨率、比例和音频能力随模型不同，别把某个模型的参数直接套到另一个模型。

四、轮询任务状态

拿到任务 ID 后，用查询接口轮询：

GET /tasks?task_ids=<任务ID>
GET /tasks?external_task_ids=<自定义ID>

task_ids 和 external_task_ids 只能二选一，多个 ID 用逗号分隔。响应中的 data 是任务数组，每个任务包含 id、status、message、create_time、update_time、external_id、outputs 和 billing。

状态有四种：

submitted：已接收，尚未开始。
processing：生成中。
succeeded：成功，可以读取 outputs。
failed：失败，查看 message 和审核原因。

轮询不要固定高频轰炸。建议从 5 秒起步，逐步退避到 15 至 30 秒，并设置总超时。视频任务可能排队，超过预期时先看并发和资源包，而不是立刻重复提交。

如果要做对账或补拉，用 POST /tasks 的游标查询，按 start_time、end_time、status、product_type 过滤，单页上限 500 条。

五、回调与签名校验

提交任务时传入 callback_url，平台会在任务状态变化时推送通知。回调比轮询更省资源，但要求你的接口可公网访问、能快速返回 200，并把实际处理放到队列里。

回调体在新式接口中包含 id、status、message、outputs、external_id 和 billing；旧版接口则是 task_id、task_status、task_result，且成功状态拼写为 succeed。两代格式不要共用同一个解析器。

安全上，可在控制台创建 Webhook Secret（以 whsec_ 开头）。回调会带 webhook-id、webhook-timestamp、webhook-signature 三个头，签名内容是 {webhook-id}.{webhook-timestamp}.{rawBody}，算法为 HMAC-SHA256，结果 Base64 编码。校验时注意三点：时间戳应在正负 5 分钟内、签名要用原始请求体计算、比较时应使用常量时间函数。官方支持新旧 secret 在 7 天宽限期内并存，适合平滑轮换。

回调可能重复或乱序，处理逻辑要以任务 ID 做幂等，状态只向前推进，不要把 processing 覆盖回 submitted。

六、下载与保存结果

成功任务的视频在 outputs 数组里，type 为 video 的项包含 url、watermark_url、duration 和 id。其中 url 是带防盗链格式的下载地址，直接嵌入网页或第三方系统可能被拒绝。

两个硬约束：

结果链接在生成后约 30 天被清理，不能当作永久 CDN 地址。
防盗链意味着应在服务端下载，再转存到自己的对象存储。

建议的落库流程是：任务成功后立即下载，校验 Content-Type 和文件大小，计算校验和，写入对象存储，再把自有地址和任务 ID 关联。对外分发时使用自己的签名 URL，并设置过期时间。

七、幂等、重试与并发

视频任务最贵的错误是“超时后重复提交”。请求超时并不代表任务没创建，可能只是响应没回来。

external_task_id 是主要的幂等手段：提交前生成稳定 ID 并落库，超时后用 GET /tasks?external_task_ids=... 反查，确认没有任务再重试。同一个账号下该 ID 必须唯一。不要用随机 UUID 做重试键，否则每次重试都会生成新任务。

并发方面，官方文档说明只有“创建任务”计入并发，查询不计；平台不会替你排队，超过资源包槽位会返回 1303。所有 API Key 共用同一账号的并发池。推荐的退避策略是至少 1 秒起步的指数退避，并在应用侧维护提交队列，按空闲槽位放行。

八、常见错误对照

业务码	HTTP	含义	处理建议
1002	401	凭证无效	检查 Key、区域和请求头
1103	403	无接口或模型权限	确认账号与资源包已开通该模型
1101	429	后付费欠费	充值后重试
1102	429	资源包用完或过期	购买资源包或切换计费方式
1201	400	参数值不合法	读 `message`，核对时长、比例、分辨率
1301	400	内容审核未通过	修改提示词或素材，不要原样重试
1302	429	请求过于频繁	降低频率，指数退避
1303	429	并发超限	排队提交，等待槽位释放
1203	404	资源或模型不存在	核对路径与模型版本
5002	500	服务内部超时	保留任务 ID，稍后查询而非重复提交

排错时先看 HTTP 状态，再看业务码，最后看 request_id。把这三项一起记入日志，联系支持时能显著缩短定位时间。

九、从旧版迁移的检查清单

鉴权从 AccessKey/SecretKey 的 JWT 切换到 API Key Bearer，旧接口保留 JWT 兼容。
路径从 /v1/videos/... 改为按模型划分的 /text-to-video/kling-3.0-turbo 等形式。
请求体移除 model_name，模型由路径决定。
返回字段从 task_id、task_status 改为 id、status。
成功状态从 succeed 改为 succeeded。
查询从按任务的 GET 路径改为 GET /tasks?task_ids=...。
结果从 task_result.videos 改为 outputs 中 type=video 的项。
回调解析器按新旧格式分开，避免字段错配。
增加 30 天结果清理和防盗链的转存逻辑。
用 external_task_id 补齐幂等，并做一轮超时、重复回调、审核失败的故障演练。

迁移时建议新旧并行：新接口跑灰度流量，旧接口保留回滚窗口，确认成功率、耗时和账单都符合预期后再下线。

十、在网关接入的检查点

如果通过中商起航 AI 网关统一接入，除了 Key 和 Base URL，还要确认视频通道是否已开通、异步任务是否原样透传、external_task_id 和回调是否保留、结果 URL 如何交付。文本模型的 OpenAI 兼容接口不能直接用于视频任务。

可以先查看模型与价格，再注册并创建测试 Key。用一条 5 秒任务验证提交、查询、下载全链路，再决定生产流量怎么切。

常见问题

可灵 API 是同步还是异步？

异步。提交只返回任务 ID，需要轮询 GET /tasks 或接收回调，成功后再从 outputs 下载视频。

Base URL 应该用新加坡还是北京？

取决于服务器位置、账号归属和模型可用区域。官方文档同时出现两个地址，接入前在控制台确认，并保持任务提交与查询使用同一区域。

任务一直停在 processing 怎么办？

先看并发槽位和资源包是否充足，再确认任务是否排队。超过预期时用任务 ID 查询，不要重复提交；必要时联系支持并提供 request_id。

结果 URL 能直接放到网站或小程序里吗？

不建议。链接有防盗链格式，且约 30 天后清理。应在服务端下载并转存对象存储，再通过自有签名 URL 对外提供。

失败重试会不会重复扣费？

取决于失败原因和平台计费规则。审核失败通常不应原样重试；网络超时应先按 external_task_id 反查任务，确认未创建后再提交。上线前阅读计费说明并用小额任务验证。