Kie.ai API 指南：密钥、Base URL 与 OpenAI 兼容首次请求

Kie.ai 用一个密钥打通了大约一百个图像、视频、音乐和聊天模型。只要搞清楚三件在入门文档里没有明说的事，这个 API 就非常直观：OpenAI 兼容的 base URL 到底在哪里、媒体生成是基于任务而非同步的、以及错误并不体现在 HTTP 状态码上。

最后这一点如果没人提醒，会白白耗掉你一个下午。所以先讲它。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

状态码在说谎

发送一个未认证的请求，你会得到 HTTP 200，真正的结果藏在 JSON body 里：

POST https://api.kie.ai/api/v1/jobs/createTask
→ HTTP 200
  {"code":401,"msg":"Unauthorized – Authentication failed..."}

积分端点和 Anthropic 兼容路径上也是如此。Kie 自己的示例代码会根据 response.status === 401 和 402 分支处理，但这些分支永远不会触发，因为上述所有情况下的传输层状态码都是 200。

要根据 body.code 分支，而不是 HTTP 状态码。未匹配的路由是例外，确实会返回真正的 404。

文档中列出的 code 枚举：

注意 501 表示你的生成失败了，而不是服务器坏了。要把它和 500 分开处理。

Base URL 与认证

Base 是 https://api.kie.ai，认证就是普通的 bearer token。密钥形如 sk-kie-...，来自账户设置页面。

Authorization: Bearer YOUR_API_KEY

文件上传在另一个主机上，https://kieai.redpandaai.co，提供 URL、stream 和 base64 三种端点。上传免费，文件 24 小时后自动删除，所以把这个主机当作暂存区，而不是存储。

OpenAI 兼容端点到底在哪里

这是大家一直在搜却很少找到的东西，因为答案并不是问题所假设的那样。不存在一个全局统一的 OpenAI 兼容 base URL。 兼容性是按模型暴露的，作为 api.kie.ai 上的路径前缀。

所以 OpenAI SDK 要指向 https://api.kie.ai/<model-slug>/v1，而不是裸主机。注意有一个文档中的 slug 含有字面量点号，gemini-3.1-pro，所以不要对 slug 做归一化处理。

对于 Claude Code，配置有明确文档，而且文档特别提醒不要追加路径：

ANTHROPIC_BASE_URL=https://api.kie.ai/claude
ANTHROPIC_API_KEY="Bearer <your-key>"

ANTHROPIC_AUTH_TOKEN 也可以，它接收不带 Bearer 前缀的密钥。

没有 /v1/models 端点。 请求它会返回硬 404。任何在启动时列出模型的 OpenAI 兼容客户端都会挂掉，而这个失败看起来像是密钥坏了，而不是路由缺失，这会让你痛苦地调试一个小时。把你的模型列表硬编码进去。

媒体生成是基于任务的

聊天是请求与响应。而所有生成图像、视频或音轨的操作，都是你提交并轮询的任务。

POST https://api.kie.ai/api/v1/jobs/createTask
{ "model": "google/nano-banana-2", "input": { ... } }

→ {"code":200,"msg":"success","data":{"taskId":"dc1928bfcbc77..."}}

然后轮询：

GET https://api.kie.ai/api/v1/jobs/recordInfo?taskId=<taskId>

响应中带有 state，它会依次经过 waiting、queuing、generating，然后进入 success 或 fail，同时还有 failCode、failMsg、costTime 和 completeTime。

在写解析器之前有一个细节值得知道：resultJson 是一个 JSON 编码的字符串，而不是对象。 你需要再解析一次才能拿到 resultUrls。原始的 param 字段也是如此。这是个小细节，但如果你假设错了，就会产生一个令人困惑的类型错误。

Kie 在自己的文档里说得很直白：createTask 返回 200 只意味着任务已创建，并不意味着它已完成。

如果你不想轮询，createTask 接受一个 callBackUrl。Webhook 使用 HMAC-SHA256 签名，通过 X-Webhook-Timestamp 和 X-Webhook-Signature 头传递，签名是对任务 ID 和时间戳用点号连接后计算得出的。

我会采用的构建顺序

如果顺序正确，让第一个请求跑通大约需要十分钟；如果顺序不对，就要长得多。

从积分端点开始，而不是从生成开始，因为它便宜、快速，能立刻告诉你密钥是否有效。记得从 body 里读 code，而不是相信 200。如果那里看到 401，说明密钥错了或者 Bearer 前缀缺失。

然后提交一个便宜的图像任务，在写任何轮询循环之前手动轮询它。你要亲眼看到状态转换，并且要在交互式环境下碰到一次双重编码的 resultJson，而不是在一个你同时还在调试的解析器里碰到。

只有这两步都跑通之后，才应该接入 webhook。签名验证很容易出微妙的错，而拿一个你还没验证过的生成流水线去调试它，等于同时面对两个问题。

值得刻意演练的失败模式是 fail 状态。提交一个你的模型会拒绝的东西，观察 failCode 和 failMsg 被填充，并确保你的代码把它当作正常结果处理。在高并发下生成失败是常态，一个只处理成功的流水线会在第一次被拒绝时卡住。

限流，以及它缺失的部分

文档中的限制是每 10 秒 20 个新生成请求，按账户计算，Kie 也把它描述为每分钟 120 个。被拒绝的请求不会进入队列。大约 100 个并发运行任务被描述为典型情况，没有硬性并发上限。单个密钥还可以额外携带每小时、每天和总量用量上限以及 IP 白名单，如果你要把密钥交给自动化程序使用，这确实很有用。

缺失的是让限流真正可用的那部分。我在任何地方都没有找到 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 或 Retry-After 的文档，观察到的响应里也没有。再加上 429 是藏在 200 里到达的，想要智能退避，就意味着要根据他们公布的窗口自己跟踪请求数，而不是从响应里读任何东西。

在你需要它之前就把这个计数器建好。

没有官方 SDK

GitHub 上有一个 Kie-AI 组织，但公开仓库为零，PyPI 上什么都没有，文档里也没有引用任何 SDK。你在 npm 上找到的包都是个人维护的第三方封装。

这并不构成否决理由，因为 REST 接口面足够小，一个下午就能封装完。但这确实意味着集成由你自己维护，而你采用的客户端库是某个人的副业项目。

媒体也不会无限期存储。生成的文件保留 14 天，日志和元数据保留两个月，签名下载 URL 20 分钟后过期。无论你生成什么，都要在创建它的同一个任务里把它搬到自己的存储中。

从编码代理运行它

让这个 API 比大多数媒体 API 更有意思的一点是，Kie 直接文档化了 Claude Code 路径。把 ANTHROPIC_BASE_URL 指向 Claude 兼容前缀，你的代理的模型调用就会经由 Kie 路由，而不是 Anthropic，用的还是那个能访问图像和视频模型的同一个密钥。

这很方便，但它改变了你所依赖的东西。你的代理的推理和它的媒体生成现在共享同一个供应商、同一个余额和同一个限流，供应商出问题会同时让两者停摆。这个取舍是否值得那点折扣，是对你自己容忍度的判断，不是一篇文章能定论的。

还有第二条路值得了解。一个社区 MCP server 把媒体模型封装成代理工具，这样你的代理可以在任务中途生成图像，而不需要你自己调用 API。Kie 没有官方 MCP server，社区那个带有常见的单人维护警告。

如果你走这条路，在发布前先设置好它的启用工具列表。MCP server 会在每一轮把每个工具的模式注入上下文，而不只是你调用它的那一轮，而这么大规模的目录在你重构路由而不是做视频时，保持加载是很昂贵的。

如果你确实这样运行代理，运维问题很快就会到来。哪个代理持有哪个密钥、上一次运行发生了什么、哪些输出来自哪个任务。HiFox 就在这一层工作，围绕执行工具：模型用量继续在你于这些工具中配置的订阅和 API 密钥上运行，而任务、结果和审查集中在一处，而不是散落在各个终端里。

统一的智能体工作流与审查队列

当您在代码库中通过环境变量配置好 API 密钥并开始并发调度多个 Coding Agent 时，关键挑战在于如何高效追溯各个智能体的任务状态、输入输出与审查结果。

HiFox 承载了智能体执行层之上的协作与管理，帮助团队将不同 Agent 的任务、PR 产出及审核统一集中在一个看板中，避免上下文散落在各个命令行终端中。