API 参考

基础 URL

每个请求都发送到：

身份验证

在 API 密钥 页面创建密钥，然后将其作为 Bearer 令牌放入 Authorization 请求头中发送。系统只会存储密钥的哈希值——请在创建时立即复制，因为 GatifyAI 之后无法再次显示它。

快速开始

一个最简单的 curl、Python 或 TypeScript 请求：

curl https://gatifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

将密钥限制为特定模型

默认情况下，新密钥可以使用 GatifyAI 的任何免费模型，并在模型不可用时使用与网页聊天相同的自动故障转移。你也可以将密钥限制为特定模型或一个简短列表——此后该密钥只会按你指定的顺序使用列表中的模型，无论请求中要求的是哪个模型。请求列表之外的模型会返回 400 错误，并列出该密钥实际允许使用的模型。

以角色身份聊天

传入 model: "persona/<slug>" 即可以 社区图库 中发布的角色身份聊天——系统会自动使用该角色的性格设定和首选模型，如果你为密钥设置了允许的模型，仍会受此限制。你可以在该角色自己的页面的 API 标签页中找到其 slug 和现成的示例。

{
  "model": "persona/senior-engineer",
  "messages": [{"role": "user", "content": "Review my code."}]
}

流式与非流式

设置 stream: true 可以在生成的同时接收 token，格式与 OpenAI 的流式格式完全相同（Server-Sent Events，以 [DONE] 结束）。省略该参数或设置为 false，则会等待完整回复并返回单个 JSON 响应——这是默认行为。

错误

错误遵循 OpenAI 的错误格式：{"error": {"message": "...", "type": "..."}}。401 表示密钥缺失、无效或已被撤销。400 表示请求本身无效——通常是无法识别的模型、未发布或未知的角色 slug，或者模型不在你密钥的允许列表中。502 表示所有候选模型均未响应。

{
  "error": {
    "message": "This API key may only use: llama-3.1-8b:free",
    "type": "invalid_request_error"
  }
}

速率限制

API 请求与网页应用共享同一个按账户计算的聊天速率限制——目前没有为 API 流量单独设置的配额。