AI SDK 的 Kling AI Provider 演进全解析从异步视频任务到 Webhook 回调与安全加固【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai本篇技术指南以ai-sdk/klingai提供商的 CHANGELOG.md 为主线结合 README.md 与src/下的实现源码系统梳理 Kling AI 视频生成 Provider 从3.0.0初始版本到4.0.41的能力演进涵盖三种视频生成模式文生视频 / 图生视频 / 运动控制、单 API Key 与 legacy JWT 双认证体系、doStart/doStatus异步任务生命周期、轮询与 Webhook 回调、URL 安全校验加固以及 v3.0 的多镜头、元素与声音控制等新增能力。读完本文你将能完整掌握该 Provider 的安装配置、认证方式、Provider Options 全参数语义以及底层异步调用链的实现原理。版本演进脉络一个视频 Provider 的成长路线从 CHANGELOG.md 可以看到ai-sdk/klingai的清晰演进轨迹3.0.0initial klingai providerProvider 首次落地3.0.1增加 text-to-video 与 image-to-video 支持c43aeb23.0.2归一化 Provider 专属模型选项类型名并确保导出99fbed8废弃别名KlingAIVideoProviderOptions仍兼容可用3.0.4增加 Kling v3.0 的 T2V / I2V 支持3b197024.0.0v7 预发布三个 Major 变更——移除全部 CommonJS 导出改为纯 ESMef992f8、启动 v7 预发布8359612、统一 Provider 实现代码模式并重命名部分导出符号04e9009旧名以 deprecated 别名继续工作同时将最低 Node.js 版本提升至 22支持 22 / 24 / 267fc6bd6并附带 kling v3.0 motion control 支持e569f5d与generateAudio一等调用选项0416e3e4.0.3 / 4.0.8为视频生成引入frameImages与inputReferences一等公民调用选项后者支持视频而非仅图片参考输入用于 reference-to-video 生成0274f34、0f93c574.0.16支持单 API Key 认证29a7a584.0.21异步 APIpoll / webhook落地79e133c4.0.38 / 4.0.10视频状态轮询与响应 URL 的安全校验加固a580ec8、4be62c14.0.41webhookUrl作为callback_url转发ef3bac4。这一演进本质上是 AI SDK 视频模型接口VideoModelV4从同步doGenerate走向异步doStart/doStatus的缩影本文后续将逐一深入。安装与 Provider 实例安装ai-sdk/klingai是 AI SDK 生态中的独立 Provider 包通过 npm 安装npm i ai-sdk/klingai从 package.json 可以看到该包为纯 ESMtype: moduleexports只暴露import/default入口这与 CHANGELOG 4.0.0 中移除 CommonJS 导出的 Major 变更一致——使用require()的老代码必须切换到 ESMimport语法。包声明engines.node 22即最低要求 Node.js 22。运行时依赖仅ai-sdk/provider与ai-sdk/provider-utilsworkspace 内联peerDependencies 要求zod^3.25.76 || ^4.1.8。创建 Provider 实例直接导入默认实例import { klingai } from ai-sdk/klingai;或使用createKlingAI自定义配置import { createKlingAI } from ai-sdk/klingai; const klingai createKlingAI({ apiKey: your-api-key, // 可选 // accessKey / secretKeylegacy JWT 认证 // baseURLAPI 基础地址默认 https://api-singapore.klingai.com // headers自定义请求头 // fetch自定义 fetch 实现中间件 / 测试 });在 klingai-provider.ts 的实现中createKlingAI会以withoutTrailingSlash归一化baseURL默认值为源码中声明的https://api-singapore.klingai.comL68通过resolveKlingAIAuthToken异步解析 Bearer Token并追加ai-sdk/klingai/${VERSION}的 User-Agent 后缀withUserAgentSuffix返回一个specificationVersion: v4的 Provider 对象其中video(modelId)与videoModel(modelId)创建KlingAIVideoModel实例而languageModel/embeddingModel/imageModel等方法一律抛出NoSuchModelErrorL103-L114明确该 Provider 只做视频。认证方式演进从 JWT 签名到单 API Key这是 CHANGELOG4.0.1629a7a58引入的关键变化也是升级时最容易踩坑的地方。推荐单 API KeyBearer TokenKling AI 现在签发单 API Key直接作为 Bearer Token 发送。设置方式二选一export KLINGAI_API_KEYyour-api-keyimport { createKlingAI } from ai-sdk/klingai; const klingai createKlingAI({ apiKey: your-api-key });LegacyaccessKey / secretKey 签名 JWT旧版 accessKey / secretKey 组合继续可用Provider 会为每个请求签名一个短时效 JWTexport KLINGAI_ACCESS_KEYyour-access-key export KLINGAI_SECRET_KEYyour-secret-keyconst klingai createKlingAI({ accessKey: your-access-key, secretKey: your-secret-key, });在 klingai-auth.ts 的generateKlingAIAuthToken中可以看到 JWT 生成细节使用 HS256HMAC-SHA256算法通过 Web Crypto APIcrypto.subtle实现无需任何外部依赖天然兼容 Node.js、Edge 与浏览器运行时。Payload 包含issaccess key、exp当前时间 1800 秒即 30 分钟有效、nbf当前时间 - 5 秒容忍时钟偏差签名输入采用 base64urlURL 安全、无填充编码的header.payload拼接。凭据解析优先级resolveKlingAIAuthToken 严格按以下顺序解析显式设置优先于环境变量API Key 优先于 accessKey/secretKeyapiKey选项accessKeysecretKey选项两者都提供时才走 JWTKLINGAI_API_KEY环境变量KLINGAI_ACCESS_KEYKLINGAI_SECRET_KEY环境变量。若全部缺失会抛出LoadAPIKeyError错误消息明确提示四种可行的凭据传入方式。视频生成三种模式README 明确该 Provider 当前支持三种视频生成模式模型 ID 由 klingai-video-settings.ts 中的KlingAIVideoModelId联合类型完整声明含kling-v3.0-t2v、kling-v3.0-i2v、kling-v3.0-motion-control。模式由模型 ID 后缀自动判定-t2v、-i2v、-motion-control见 klingai-video-model.ts 的detectMode。文生视频Text-to-Video可用模型kling-v1-t2v、kling-v1.6-t2v、kling-v2-master-t2v、kling-v2.1-master-t2v、kling-v2.5-turbo-t2v、kling-v2.6-t2v以及 v3.0 系列。import { klingai } from ai-sdk/klingai; import { experimental_generateVideo } from ai; const { videos } await experimental_generateVideo({ model: klingai.video(kling-v2.6-t2v), prompt: A chicken flying into the sunset in the style of 90s anime., aspectRatio: 16:9, duration: 5, providerOptions: { klingai: { mode: std, }, }, });图生视频Image-to-Video可用模型kling-v1-i2v、kling-v1.5-i2v、kling-v1.6-i2v、kling-v2-master-i2v、kling-v2.1-i2v、kling-v2.1-master-i2v、kling-v2.5-turbo-i2v、kling-v2.6-i2v以及 v3.0 系列。支持首帧图 可选尾帧控制const { videos } await experimental_generateVideo({ model: klingai.video(kling-v2.6-i2v), prompt: { image: https://example.com/start-frame.png, text: The cat slowly turns its head and blinks, }, duration: 5, providerOptions: { klingai: { // Pro 模式是首尾帧控制的前置条件 mode: pro, // 可选尾帧图片 imageTail: https://example.com/end-frame.png, }, }, });运动控制Motion Control可用模型kling-v2.6-motion-control、kling-v3.0-motion-control。使用参考运动视频驱动角色动作const { videos } await experimental_generateVideo({ model: klingai.video(kling-v2.6-motion-control), prompt: { image: https://example.com/character.png, text: The character performs a smooth dance move, }, providerOptions: { klingai: { videoUrl: https://example.com/reference-motion.mp4, characterOrientation: image, mode: std, }, }, });源码层面buildMotionControlBodyklingai-video-model.ts会在缺少videoUrl、characterOrientation、mode三者之一时抛出KLINGAI_VIDEO_MISSING_OPTIONS错误这三者会映射为 API 请求体中的video_url、character_orientation、mode字段。Provider Options 全参数详解providerOptions.klingai是 Kling AI 专属配置入口完整类型定义见 klingai-video-model-options.ts运行时由 zod schemaklingaiVideoModelOptionsSchemaL200-L276校验。核心参数如下选项T2VI2VMotion Control说明modestd/prostd/prostd/pro生成质量模式std性价比高pro质量更高但耗时更长negativePrompt支持支持—负面提示词最长 2500 字符映射negative_promptsoundV2.6 pro 专属V2.6 pro 专属—on/off控制是否同步生成声音cfgScale支持V1.x支持V1.x—提示词遵循度范围 [0, 1]v2.x 模型不支持cameraControl支持支持—镜头运动预设见下文imageTail—Pro 模式—尾帧图片URL 或 base64映射image_tailstaticMask—支持—静态笔刷蒙版URL 或 base64dynamicMasks—支持—动态笔刷配置最多 6 组每组含蒙版与运动轨迹点videoUrl——必填参考运动视频 URL.mp4/.mov≤100MB边长 340px–3850pxcharacterOrientation——必填image参考视频最长 10s或video最长 30skeepOriginalSound——支持yes/no是否保留参考视频原声默认yeswatermarkEnabled支持支持支持是否同时生成带水印结果映射watermark_info.enabledpollIntervalMs支持支持支持轮询间隔默认 5000mspollTimeoutMs支持支持支持最大等待时长默认 600000ms10 分钟cameraControl的type可选simple | down_back | forward_up | right_turn_forward | left_turn_forwardconfig可细调horizontal、vertical、pan、tilt、roll、zoom不指定时模型会根据文本/图片智能匹配镜头。值得注意的是klingai-video-model.ts 定义了HANDLED_PROVIDER_OPTIONS集合凡是不在该集合内的未知选项会通过addPassthroughOptionsL805-L815原样透传到请求体为后续 Kling AI API 新参数提供前向兼容。异步任务生命周期轮询与 Webhook这是 CHANGELOG4.0.2179e133c引入、4.0.41ef3bac4完善的机制性变更VideoModelV4接口允许模型实现doStart、doStatus、handleWebhookOption替代或补充doGenerateexperimental_generateVideo接受poll和webhook选项来编排完成流程。同步式轮询poll未指定webhook时generateVideo默认走轮询。其底层即 KlingAIVideoModel 的两个核心方法doStartL219-L305根据模型 ID 后缀检测模式detectMode再按模式选择buildT2VBody/buildI2VBody/buildMultiImageBody/buildMotionControlBody构建请求体通过postJsonToApiPOST 到对应端点modeEndpointMapL142-L147 定义/v1/videos/text2video、/v1/videos/image2video、/v1/videos/multi-image2video、/v1/videos/motion-control响应经 zod schemaklingaiCreateTaskSchema解析后取出task_id返回{ operation: { taskId, endpointPath } }供后续状态查询。doStatusL307-L367GET{baseURL}{endpointPath}/{taskId}查询任务状态task_status为succeed时返回completed并解析task_result.videos每个视频含id、url、可选的watermark_url与durationfailed时返回error及task_status_msg其余视为pending。getApiModelNameL159-L168负责将 SDK 模型 ID 转为 Kling AI API 的model_name剥离模式后缀、v3.0归一为v3、点号转连字符例如kling-v2.6-t2v → kling-v2-6、kling-v2.1-master-i2v → kling-v2-1-master。轮询节奏由pollIntervalMs默认 5000ms与pollTimeoutMs默认 600000ms控制且轮询配置支持自定义 delay 实现以兼容持久化工作流durable workflow场景。Webhook 回调webhookUrl → callback_urlCHANGELOG4.0.41的变更进一步细化了 Webhook 行为doStart会将调用方传入的webhookUrl转发为请求体中的callback_url字段覆盖文本转视频、图生视频、多图转视频与运动控制全部四种模式显式 URL 优先于 Provider 自带的原始回调 URL。该实现在 klingai-video-model.ts// Progress notifications require a protocol-aware receiver, so omit handleWebhookOption. // Forward webhookUrl for a caller-owned receiver that filters progress notifications. if (options.webhookUrl ! null) { body.callback_url options.webhookUrl; }源码注释说明了设计取舍进度通知需要协议感知的接收方因此该 Provider 未实现handleWebhookOption而是把回调 URL 交给调用方自持的接收端generateVideo({ webhook })在未收到回调时继续回退到轮询兜底。安全加固响应 URL 与轮询重定向校验CHANGELOG4.0.104be62c1与4.0.38a580ec8反映了 Provider 在安全维度的重要演进getFromApi新增validateUrl标志doStatus轮询调用点显式开启validateUrl: true并配合trustedOrigin: this.config.baseURL——与开发者配置的 Provider 端点同源的 URL含重定向跳可豁免目标校验自托管与 localhost 部署不受影响其余跳转仍全部校验klingai-video-model.ts。校验规则见 contributing/secure-url-handling.md拒绝私有/回环/链路本地地址每个重定向跳都重新校验跨源重定向时剥离 proxy/metadata/cookie 请求头且仅保留 user-agent被拦截的 URL 抛出DownloadError。可选的credentialedOrigin保证 API Key 不会发往响应提供的异源主机。轮询重定向校验同时覆盖 MiniMax、Kling AI 与 ByteDance 三家视频 Provider4.0.38并补齐了 IPv4 组播、TEST-NET 文档段与 IPv6 文档段等校验区间。v3.0 新增能力多镜头、元素控制与声音控制在 CHANGELOG 3.0.4v3.0 t2v/i2v、4.0.0v3.0 motion control基础上Provider Options 中沉淀了 v3.0 专属能力类型与 schema 均在 klingai-video-model-options.ts 中定义多镜头生成multi-shotmultiShot: true时视频被拆分为最多 6 个故事板镜头。shotType: customize表示通过multiPrompt自定义每个镜头每个镜头含index、prompt≤512 字符、duration各镜头时长之和须等于总时长shotType: intelligence表示模型根据主提示自动切分。注意开启 multi-shot 后主prompt参数会被 API 忽略。请求体映射为multi_shot、shot_type、multi_prompt见 buildT2VBody。元素控制element controlelementList支持视频角色元素与多图元素。I2V 下最多 3 个参考元素且不能与voiceList共存Motion Control 下当前仅支持 1 个元素引用元素时生成视频只能参考视频中人物的朝向。映射为element_list。声音控制voice controlvoiceList最多 2 个声音参考通过提示词中的voice_1模板语法引用使用voiceList且提示词引用声音 ID 时sound必须设为on。映射为voice_list。与标准调用选项的协同与限制结合源码标准 SDK 选项与 Kling AI 的映射/限制如下aspectRatioT2V 与多图转视频支持映射aspect_ratioI2V 不支持输出尺寸由输入图决定产生unsupported警告Motion Control 同样不支持。durationT2V / I2V / 多图转视频支持数字转字符串映射durationMotion Control 不支持输出时长跟随参考视频。generateAudio4.0.0 起的一等选项T2V / I2V 下优先于providerOptions.klingai.sound决定sound字段。image与frameImagesI2V 优先取frameImages中的first_frame回退到image尾帧优先取last_frame回退到imageTail。Kling AI 不接受视频作为帧图或参考输入——isVideoFile检测到视频时会给出unsupported警告并忽略L46-L127。inputReferencesreference-to-video仅 I2V 模型支持传入多张参考图时自动切换到mi2v模式并走/v1/videos/multi-image2video端点非 I2V 模型上传入会得到警告并被忽略。不支持的通用选项resolution、seed、fps均不支持n 1也仅生成 1 个视频见addUniversalWarningsL369-L407。版本迁移注意事项ESM-only4.0.0 起所有包移除 CommonJS 导出require()用户必须迁移到importNode 版本最低 22支持 22 / 24 / 26依赖链CHANGELOG 中几乎每个 Patch 版本都伴随ai-sdk/provider与ai-sdk/provider-utils的同步升级升级 Kling AI Provider 时建议整仓使用 pnpm workspace 保持依赖一致废弃别名4.0.0 重命名的导出符号如KlingAIVideoProviderOptions→KlingAIVideoModelOptions通过 deprecated 别名继续工作可平滑过渡认证方式优先切换到单 API Key若仍用 accessKey/secretKey注意其按请求签发的 JWT 仅 30 分钟有效长任务场景需关注 API 侧对时效的容忍度。如需深入了解实现细节可继续阅读以下仓库文件Provider 实例与设置klingai-provider.ts认证与 JWT 生成klingai-auth.ts视频模型核心实现doStart / doStatus / 请求体构建klingai-video-model.tsProvider Options 类型与 zod 校验klingai-video-model-options.ts模型 ID 联合类型klingai-video-settings.ts错误响应处理klingai-error.ts测试用例覆盖三种模式的请求体断言klingai-video-model.test.ts 与 klingai-auth.test.tsURL 安全校验规范contributing/secure-url-handling.md【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考