开篇从“等视频”到“省下几小时”——为什么你需要一份能直接落地的 API 集成手册做视频内容的同学应该都有过这种体验手头攒了一堆脚本想批量生成几分钟的演示视频结果要么逐个在网页上粘贴提示词、点生成、等进度条、再下载要么辛辛苦苦写好了一版自动化脚本却在鉴权、任务轮询这些环节上反复踩坑。我自己第一次接触Kling 视频生成 API时也是抱着“把网页操作搬进代码”的朴素想法去的结果发现事情远没那么简单它不是简单的 HTTP POST 就能搞定里面涉及签名、任务状态机、参数选型、限流策略等等一系列工程细节。这篇东西就是把我实际对接 Kling 视频生成 API 的完整过程、踩过的坑、最后跑通的方案整理出来。它适合谁看两类人最合适一类是刚拿到 API 权限、想做点自动化尝试的开发者另一类是已经在用网页版、但是被大量重复操作磨得没脾气的运营同学——哪怕你不会写代码看明白整体流程和参数逻辑也能在团队里更有效地提出需求。先说结论Kling 视频生成 API 走的是“提交任务—异步生成—轮询状态—获取结果”这套标准流程核心难点集中在鉴权签名和任务状态机处理上。只要这两块没问题整个链路基本就能稳跑。下面我按照自己从零到一实现的顺序把每一个环节都掰开讲清楚。1. 整体设计思路与方案选型1.1 为什么是“异步任务”架构—— 重新认识视频生成的工程逻辑我第一次看文档时有个疑惑为什么生成一个视频不直接同步返回结果我 POST 一个请求等两三分钟拿到视频不就行了后来一想现实情况根本不允许。视频生成不是数据库查询它是一个计算密集型任务。一个几秒钟的短视频在 GPU 上要跑几十秒甚至几分钟。如果 API 用同步方式HTTP 连接要保持数分钟不断开中间任何一个网络抖动、代理超时、负载均衡断连整个请求就废了。而且服务端为了高性能不可能为一堆长时间任务长期占用连接资源。所以几乎所有正经的视频生成服务都采用异步任务模型你提交一个任务服务端立刻返回一个任务 ID然后你拿着这个 ID 去轮询查询任务的执行状态直到它变为“成功”再去取结果。想清楚这一层后面的代码结构也就自然浮现了一个提交任务的函数一个轮询状态的函数一个结果下载函数外加一个把它们串起来的主流程。这种设计还有一个额外好处你可以一口气提交 N 个任务然后统一轮询实现批量并发生成这在纯网页操作里是做不到的。1.2 技术栈选择Python Requests还是上异步框架做 API 集成很多人会纠结要不要用 httpx、aiohttp要不要搭异步框架我的看法是先跑通再优化。我最初用的是 Python 3.10 requests 库纯同步写法。为什么因为视频生成任务本身的瓶颈不在网络吞吐而在于 GPU 算力同步轮询完全够用。一个任务从提交到完成可能耗时两分钟你在这两分钟里用同步 requests 循环查询每次查询才几百毫秒资源占用几乎可以忽略。等后续真要大规模并发比如几十个任务同时跑的时候再把核心调用改成 httpx 的 AsyncClient代码改动也就集中在两三个函数里。当然如果你从一开始就知道任务量巨大直接用 httpx asyncio 也没问题。我给的建议是目录结构从一开始就为将来扩展留好位置kling_api/ ├── client.py # 核心客户端鉴权与请求封装 ├── models.py # 数据模型任务状态、参数结构 ├── tasks.py # 任务提交、状态查询、结果获取 ├── config.py # 配置项API Key、基础地址、超时时间 └── examples/ └── basic_generate.py # 最小可运行的生成示例这个结构不复杂但把鉴权、业务、配置分离后面接不同的业务场景单条生成、批量生成、定时任务都会很顺手。2. 核心准备与鉴权机制详解2.1 获取访问凭证别把 Secret Key 当密码到处丢对接任何商业 API第一步都是获取访问凭证。Kling 的凭证体系分两组一组是 Access KeyAK相当于你的登录账号标识另一组是 Secret KeySK相当于你的密码用来签名请求。完整流程是先在开放平台完成开发者认证创建一个应用然后系统会生成一对 AK/SK。这里有个非常关键的注意事项Secret Key 只会在创建时完整展示一次之后你再进控制台只能看到脱敏后的字符串。所以创建完成立即把 SK 复制到安全的地方比如本地密码管理器或者环境变量配置文件里。我见过不止一个同事把 SK 直接写在代码仓库里结果项目开源出去几分钟就被别人扫走白白消耗了大量 API 额度还产生了一堆不明费用。建议的配置方式在项目根目录建一个.env文件然后用 pydantic 或 python-dotenv 读取。KLING_ACCESS_KEYyour_ak_here KLING_SECRET_KEYyour_sk_here KLING_BASE_URLhttps://api.example.com/v1注意生产环境禁止把.env提交进 Git.gitignore里务必加上。2.2 签名机制一段需要亲手推一遍的 JWT 生成逻辑Kling 的 API 鉴权用的是 JWTJSON Web Token HMAC-SHA256 签名。通俗讲它就是把你的 AK、SK 和一个时间戳通过特定算法揉成一个加密字符串放在请求头里。这个机制带来的好处是服务端不需要存储你的 SK只要用同样的算法算一遍能匹配上就说明请求确实来自持有 SK 的人。JWT 的组成部分是三段式Header头部、Payload载荷、Signature签名最终以header.payload.signature的形式拼成一个字符串。Kling 官方的要求是Header{alg: HS256, typ: JWT}Payload{iss: {access_key}, exp: {过期时间戳}, nbf: {生效时间戳}}这里面的iss填 ACCESS_KEYexp是过期时间推荐设成当前时间加 1800 秒半小时nbf可以设成当前时间减 5 秒防止客户端和服务端的时间偏差导致签名在最开始几秒被判定无效。实现代码其实不难我用 Python 手工实现了一版不依赖额外库也能跑通方便大家理解原理import time import base64 import hashlib import hmac import json def base64_url_encode(data: bytes) - str: return base64.urlsafe_b64encode(data).rstrip(b).decode(utf-8) def generate_jwt(access_key: str, secret_key: str) - str: header {alg: HS256, typ: JWT} now int(time.time()) payload { iss: access_key, exp: now 1800, nbf: now - 5, } header_enc base64_url_encode(json.dumps(header).encode(utf-8)) payload_enc base64_url_encode(json.dumps(payload).encode(utf-8)) signing_input f{header_enc}.{payload_enc}.encode(utf-8) signature hmac.new( secret_key.encode(utf-8), signing_input, hashlib.sha256 ).digest() signature_enc base64_url_encode(signature) return f{header_enc}.{payload_enc}.{signature_enc}如果你的环境里有PyJWT库直接用它更省事import jwt import time def generate_jwt(access_key: str, secret_key: str) - str: now int(time.time()) return jwt.encode( {iss: access_key, exp: now 1800, nbf: now - 5}, secret_key, algorithmHS256 )两条路都验证过结果一致。但建议至少把手工版跑一遍这样将来遇到“明明签名没问题但服务端报 401”的情况你能快速定位是哪个环节出了偏差。2.3 鉴权请求头与常见鉴权错误排查JWT 生成好之后每个请求都要带上这个 Token放在Authorization头里格式是Bearer {jwt}。这是标准做法服务端解析请求头后验证签名和有效期。实际操作中我遇到过三类高频鉴权失败问题时间不同步你的服务器时间和 API 服务器时间差太多导致nbf未生效或exp已过期。解决方法是用 NTP 同步本机时间或者在生成 token 时把nbf往前调 30 秒。SK 复制出错创建应用时复制 SK中途多了个看不见的空格或换行导致签名结果完全不同。建议在代码里对 SK 先做 strip 处理。JWT 过期如果你的任务流程很长比如先提交任务、隔了很久才轮询JWT 过期会导致后续请求失败。所以不要把 token 生成一次然后全程复用而是每次请求前都重新生成或者至少保证 token 有效期覆盖整个任务流程。3. 核心 API 端点实操全流程3.1 提交视频生成任务参数结构与代码实现Kling 的核心 API 可以抽象成三件事提交任务、查询任务、获取结果。我按这个思路逐个讲解。提交任务接口的路径一般是/v1/videos/text2video用 POST 方法请求体是 JSON。核心参数包括参数类型说明model_namestring模型版本如kling-v1、kling-v1-6等promptstring正向提示词描述你想生成的画面内容negative_promptstring反向提示词告诉模型不要出现什么内容cfg_scalefloat提示词相关度数值越大越贴近提示词但画质可能受限modestringstd或pro标准模式与专业模式camerastring镜头控制参数如none、horizontal、verticaldurationstring视频长度常见5或10aspect_ratiostring画面比例如16:9、9:16、1:1这里特别提醒两点。第一prompt的写法会直接影响生成质量后面会单独展开。第二cfg_scale不是越高越好。我实测下来文本转视频场景下cfg_scale设在 0.5~0.7 之间效果最自然太高容易导致画面元素堆砌、运动不流畅。直接看代码。我封装了一个submit_task函数它接收提示词和参数字典返回任务 IDimport requests class KlingClient: def __init__(self, access_key: str, secret_key: str, base_url: str https://api.example.com/v1): self.access_key access_key self.secret_key secret_key self.base_url base_url def _headers(self) - dict: token generate_jwt(self.access_key, self.secret_key) return {Authorization: fBearer {token}, Content-Type: application/json} def submit_task(self, prompt: str, model_name: str kling-v1, negative_prompt: str , cfg_scale: float 0.5, mode: str std, camera: str none, duration: str 5, aspect_ratio: str 16:9) - str: payload { model_name: model_name, prompt: prompt, negative_prompt: negative_prompt, cfg_scale: cfg_scale, mode: mode, camera: camera, duration: duration, aspect_ratio: aspect_ratio, } resp requests.post( f{self.base_url}/videos/text2video, jsonpayload, headersself._headers(), timeout30 ) resp.raise_for_status() data resp.json() if data.get(code) ! 0: raise RuntimeError(f任务提交失败: {data.get(message)}) return data[data][task_id]请求发送后正常情况下服务端会返回一个task_id格式是一长串字母数字组合。这个 ID 就是后面所有查询操作的主键一定要保存好。3.2 任务状态机轮询的正确姿势与超时设计视频生成不能秒回提交任务后需要不断地查询状态。Kling 的任务状态是一个典型的状态机大致流转路径是submitted已提交 → processing生成中 → succeeded成功 ↘ failed失败 / cancelled取消轮询代码的优劣直接影响到你程序的健壮性。很多初学者会犯一个低级错误用死循环一直查不加最大重试次数。结果任务因为某种原因挂住程序就永远卡在轮询里。正确做法是设置轮询间隔和最大超时时间。轮询间隔一般取 5~10 秒比较合理太短会频繁打 API既浪费配额又可能触发限流太长又影响整体效率。最大超时时间建议根据视频时长设定5 秒视频给 5 分钟10 秒视频给 10 分钟。如果超时仍未成功主动放弃并标记任务异常。import time def wait_for_task(self, task_id: str, poll_interval: int 5, timeout: int 300) - dict: start_time time.time() while time.time() - start_time timeout: task_info self.get_task(task_id) status task_info[status] if status succeeded: return task_info elif status in (failed, cancelled): raise RuntimeError(f任务结束状态为 {status}原因: {task_info.get(error_message, 未知)}) time.sleep(poll_interval) raise TimeoutError(f任务 {task_id} 在 {timeout} 秒内未完成)这里有个细节值得说明get_task返回的字段在不同状态下含义不同。submitted状态下只有任务元信息processing状态会有进度信息有的版本有progress字段succeeded状态才会包含视频地址。所以轮询时不要指望一开始就能读取视频链接。3.3 结果获取与视频下载别让链接过期坑了你任务成功后返回结果里通常包含视频的临时下载地址。这个地址有两个特点一是需要鉴权才能下载通常会带签名参数二是有有效期一般在几十分钟到几小时不等。所以拿到链接后最好是立即下载不要拖。下载视频我建议用流式方式边下边写盘避免大文件一次性载入内存。另外要处理好文件名避免用任务 ID 直接命名因为后续人工识别时根本不知道哪个视频对应哪段内容def download_video(self, video_url: str, save_path: str) - None: with requests.get(video_url, streamTrue, timeout60) as r: r.raise_for_status() with open(save_path, wb) as f: for chunk in r.iter_content(chunk_size8192): if chunk: f.write(chunk)保存路径建议按业务语义组织比如output/ ├── 20250115_产品宣传_01.mp4 ├── 20250115_产品宣传_02.mp4 └── 20250115_功能介绍_01.mp43.4 完整链路串联一段可以拿去直接改的示例脚本把上面的片段串成一个完整的可运行脚本方便你理解整个流程import os import time import requests from dotenv import load_dotenv load_dotenv() client KlingClient( access_keyos.getenv(KLING_ACCESS_KEY), secret_keyos.getenv(KLING_SECRET_KEY) ) task_id client.submit_task( prompt一只橘猫在窗台上晒太阳阳光透过玻璃洒进来猫咪偶尔伸懒腰画面温暖惬意, negative_prompt模糊, 变形, 抖动, cfg_scale0.6, modepro, camerahorizontal, duration5, aspect_ratio16:9 ) print(f任务已提交: {task_id}) task_info client.wait_for_task(task_id, poll_interval8, timeout600) video_url task_info[video_url] client.download_video(video_url, foutput/{task_id}.mp4) print(视频已下载完成)这段代码虽然短但已经覆盖了核心闭环。你可以在自己的项目里基于这个骨架做二次开发接入数据库记录任务状态、接入消息队列做任务分发、接入定时任务系统做批量生成等。4. 进阶参数调试与效果优化4.1 模型版本选型同一个提示词不同版本差异很大Kling 的 API 支持多个模型版本不同版本在画质、运镜、语义理解能力上有明显差异。以我实际对比测试的经验来说旧的kling-v1版本生成速度快适合快速验证提示词想法但复杂场景的语义还原能力一般。更新的kling-v1-6版本在镜头运动、光影表现、多物体交互方面提升明显画面更细腻适合最终成片。我做测对比时用的提示词是“清晨的城市街道薄雾笼罩一辆红色跑车从远处驶来镜头跟随车辆移动”v1 版本生成的画面更像静态背景板上加了车辆平移v1-6 版本则有真实的推镜感、雾气也更有层次。所以建议测试阶段用旧版省时省算力正式成片用新版保证质量。4.2 提示词工程把画面“说”清楚而不是“写”漂亮很多人容易把视频生成提示词当成写作题堆砌一堆华丽的形容词。但在 Kling 这种视频生成模型里提示词的核心作用是描述“画面发生了什么”而不是“氛围有多么美”。我总结了一套实用的提示词结构四层递进主体设定画面里谁在做什么。例如“一个穿红色裙子的女孩在花田里奔跑”。环境与背景发生在哪里什么天气、什么光线。例如“傍晚金黄色的阳光大片向日葵田”。镜头与运动镜头是固定的还是移动的怎么动。例如“镜头缓慢从侧面跟随女孩”。风格与细节画风、质感、特殊效果。例如“电影感浅景深空气中有飘散的花瓣”。把这四层拼在一起提示词大概是一个穿红色裙子的女孩在向日葵田里奔跑傍晚金黄色阳光镜头缓慢从侧面跟随女孩 电影感浅景深空气中有飘散的花瓣画面温暖自然还有一个经验不要写时间上的前后关系比如“先……然后……最后……”视频生成模型对这种时序描述的理解能力还比较有限写多了容易让画面逻辑混乱。同样反向提示词也不是越多越好聚焦在最容易翻车的几点上模糊、变形、撕裂、过度曝光。4.3 镜头控制与画幅选择先想清楚视频发在哪里Kling 提供了camera参数控制镜头运动方向常见的取值有none固定镜头、horizontal水平横移、vertical垂直升降、zoom_in推近、zoom_out拉远。这里要结合你的视频用途来做选择。如果视频是要发在抖音、快手这类竖屏平台用9:16画幅镜头运动尽量选vertical或zoom_in竖屏上下移动的空间感会更好。如果是 B 站、西瓜视频这种横屏平台用16:9镜头用horizontal横移更有电影感。还要注意aspect_ratio和mode的搭配pro模式支持更丰富的镜头控制std模式在某些版本里可能忽略镜头参数。提交任务前最好在文档里确认一下当前模型支持的参数组合。4.4 参数组合调试口诀与实测数据我在反复测试中总结了一套调参口诀“时长先定镜次之比例随渠道跳跃要谨慎”。时长先定一个主时长5 秒和 10 秒的生成等待时间差异很大批量任务里混用时容易造成排队不均。镜头先跑一版none固定镜头确认画面主体没问题后再叠加镜头运动因为画面构图和镜头运动是互相影响的。比例根据最终发布渠道一次定死不要中途换比例同一条提示词在不同比例下画面构图差异巨大。cfg_scale不要一开始就给高值从 0.5 起步往前往后试两档找到“贴合提示词但不死板”的甜点。一组常用的推荐参数组合仅供参考场景model_namemodecfg_scalecameraaspect_ratio产品展示kling-v1-6pro0.5horizontal16:9人物特写kling-v1-6pro0.55zoom_in9:16场景空镜kling-v1std0.4vertical16:9快速验证kling-v1std0.6none1:15. 常见错误与排查技巧实录5.1 HTTP 状态码与业务状态码的双层判断Kling API 的错误信息有两层。第一层是 HTTP 状态码比如 401 未授权、429 请求过多、500 服务端错误第二层是响应体里的业务代码比如code字段非 0 时表示业务失败。调试时这两层都要看我一开始只盯着 HTTP 状态码结果有一次 HTTP 返回 200但业务码是10007提示“触发内容审核”直接被拦了。如果只看 HTTP 层你会以为请求成功了结果后面轮询任务永远是失败状态。我建议在客户端封装里统一做两层判断def _request(self, method: str, url: str, **kwargs): resp requests.request(method, url, headersself._headers(), **kwargs) if resp.status_code ! 200: raise ApiError(fHTTP {resp.status_code}: {resp.text}) data resp.json() if data.get(code) ! 0: raise ApiError(f业务错误 {data.get(code)}: {data.get(message)}) return data这样业务错误在源头就被拦截后续逻辑不用每个函数都检查一遍。5.2 高频踩坑点内容审核、限流与任务悬挂这三个问题是我在实际运行里遇到频率最高的。内容审核Kling 对 prompt 有严格的安全审核。如果你的提示词里含有敏感词或者画面涉及人物肖像风险任务会直接失败。错误信息里通常会标注“prompt contains sensitive content”。这个没有绕过办法只能修改措辞。我遇到过一个案例提示词写“一个人拿着刀站在街角”画面本身没什么问题但“刀”这个字触发了审核。把提示词改成“一个人站在街角戴着帽子表情凝重”画面意境差不多就过了。限流Kling 对单账号有 QPS 和日配额限制。我刚开始并发测试时一次性提交了 20 个任务结果前几个提交成功后后续的直接报 429。后来改成“提交一个、等一下、再提交下一个”的方式或在代码里设置一个信号量控制并发整体就稳了。建议把最大并发控制在 5 以内具体数字看你的账号套餐。任务悬挂偶尔会有任务长时间卡在processing状态既不成功也不失败。这种情况大概率是服务端排队过载最好的处理方式是设置轮询超时后自动放弃然后隔一段时间用同样的提示词重新提交一次。不要无限等下去。5.3 一个值得复用的任务管理小技巧把状态机搬到本地轮询本身不复杂但如果你同时跑几十个任务每次查询都要遍历一遍任务列表就会觉得缺乏条理。我后来做了一个轻量级的本地任务状态表用一个 JSON 文件记录每个任务的提交时间、当前状态、结果地址{ task_abc123: { prompt: ..., status: succeeded, submit_time: ..., video_url: ... } }每次轮询前后更新这个表这样即使程序中途崩溃重启后也能知道哪些任务完成了、哪些还没跑完。这个技巧在做批量生成时特别管用本质上相当于把 API 的状态机和本地业务状态做了一个映射任务多了之后你会感激这个设计的。6. 写在最后的几点实操体会整个 Kling 视频生成 API 集成下来我对它的定位有了更清晰的认知它不是一个“即插即用”的工具而是一个需要你用工程思维去驾驭的平台。JWT 签名算法不复杂但要求严谨任务轮询逻辑不难写但要求耐心设计提示词调优没有标准答案但规律可循。我个人实际项目里最常用到的一个小经验永远先跑一个最小验证用例确认鉴权、提交、轮询、下载全链路通了再开始写批量逻辑。否则一旦批量逻辑写完才发现接口版本变了或者参数名写错排查成本会翻好几倍。这个 API 后续能做的事情也很多比如把生成任务接进定时触发器每天自动生成一批短视频草稿或者做一个简单的内部工具页让不懂技术的内容同事填个表单就能触发生成再或者是把生成结果自动同步到素材库直接对接剪辑软件工作流。只要底层集成稳定上面这些玩法都只是时间问题。至少对我来说能把这套链路跑通视频内容的产出效率已经提升了一个量级这种实打实的变化远比“多学了一个 API”更让人有成就感。
