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

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

最后这一点如果没人提醒，能让你搭进去一个下午。所以先讲它。

状态码在说谎

发一个未认证的请求，你会收到 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 产出及审核统一集中在一个看板中，避免上下文散落在各个命令行终端中。