> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.
# 兼容 OpenAI 的 AI Gateway（Beta）
> 通过兼容 OpenAI 的 POST /v2/ai/chat/completions，在你自己的产品中使用 Square Cloud 托管的 cubic 模型，支持工具调用和联网搜索。
你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
需要具有 `ai:chat` [权限范围](/zh/api-reference/authentication#权限范围)的 API 密钥。
AI Gateway 让你通过一个**兼容 OpenAI** 的聊天补全端点，在你**自己的**产品（聊天机器人、助手、自动化流程）中使用 Square Cloud 托管的 AI 模型。如果你的代码已经在使用 OpenAI API，那么它也能直接使用 AI Gateway：将 SDK 指向我们的基础 URL，使用你的账户 API 密钥，并将模型设为 `cubic`。
AI Gateway 目前处于 **Beta 阶段，提供免费抢先体验**：Beta 期间，除套餐每日 AI 令牌额度外不收取额外费用。Beta 结束后，限制和可用套餐可能会发生变化。
## 如何连接
* **基础 URL：** `https://api.squarecloud.app/v2/ai`
* **API 密钥：** 你的账户 API 密钥（与 Square Cloud API 和 CLI 使用的相同，可在[账户页面](https://squarecloud.app/account)获取）。`Authorization` 请求头带或不带 `Bearer ` 前缀均可。
* **模型：** `cubic`，Square Cloud 托管的模型，与驱动控制台 AI 助手的是同一个模型。
## 套餐与限制
每个请求都会按实际令牌数从套餐的**每日 AI 令牌额度**中扣除（与控制台助手共用同一额度，于 UTC 00:00 重置）。Standard 和 Pro 还设有每日请求上限；每个套餐在网关上都有一个每日合理使用额度，按适度使用的需求设定（依据请求的服务成本，用于防范无人看管的密钥）。两者在同一时间重置。
| 套餐 | 每日请求数 | 合理使用额度 | 上下文窗口 | 最大输出 | 并发请求 | 请求间隔 |
| - | - | - | - | - | - | - |
| Standard | 1,000 | 基础 | 16,384 令牌 | 4,096 | 1 | 5 秒 |
| Pro | 5,000 | 基础 | 24,576 令牌 | 6,144 | 1 | 2 秒 |
| Enterprise | 不限 | 基础的 5 倍 | 32,768 令牌 | 8,192 | 2 | 无 |
Hobby 套餐（以及没有套餐的账户）无法使用 AI Gateway：升级到 Standard 或以上即可开通。
## 请求约定
为兼容 SDK 而接受此字段；网关始终以 `cubic` 作答。
OpenAI 风格的消息，角色为 `system`、`user`、`assistant` 和 `tool`。内容必须是**字符串**：此端点仅支持文本，因此多部分数组（`image_url`、`input_audio`、`file`）会被拒绝并返回 `400 multimodal_not_supported`。每个请求最多 **100 条消息**。
会被静默限制在套餐的输出上限以内。
取值范围 0 到 2。
标准 OpenAI 格式的函数调用，最多 **32 个工具定义**。工具调用以 `finish_reason: "tool_calls"` 返回，你再以 `role: "tool"` 消息发回结果。
标准的 OpenAI `tool_choice` 值。
未知参数会被忽略，但有两个刻意的例外：`audio` 以及不等于 `["text"]` 的 `modalities` 值会被**拒绝**而不是忽略，这样请求语音输出时绝不会默默返回文本。
**文本输入，文本输出。** 任何套餐都不接受图片、音频和文件，这是产品层面的决定，而非暂时的缺失。请发送文本并读取文本。
**暂不支持：** 流式输出（`stream: true` 会返回 `400 stream_not_supported`）。
### 内置联网搜索
当对话需要最新信息或外部信息时，模型会自行决定是否联网搜索。搜索在服务器端进行，只返回最终答案，并引用结果 URL。如果你自己声明了名为 `web_search` 的工具，它会取代内置工具。
```javascript JavaScript (OpenAI SDK) theme={"system"}
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.squarecloud.app/v2/ai",
apiKey: process.env.SQUARECLOUD_API_KEY,
});
const completion = await client.chat.completions.create({
model: "cubic",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Explain what Square Cloud is in one sentence." },
],
});
console.log(completion.choices[0].message.content);
```
```python Python (OpenAI SDK) theme={"system"}
from openai import OpenAI
client = OpenAI(
base_url="https://api.squarecloud.app/v2/ai",
api_key="YOUR_API_KEY",
)
completion = client.chat.completions.create(
model="cubic",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain what Square Cloud is in one sentence."},
],
)
print(completion.choices[0].message.content)
```
```bash cURL theme={"system"}
curl --request POST \
--url https://api.squarecloud.app/v2/ai/chat/completions \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "cubic",
"messages": [
{ "role": "user", "content": "Explain what Square Cloud is in one sentence." }
]
}'
```
```json theme={"system"}
{
"id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b",
"object": "chat.completion",
"created": 1754179200,
"model": "cubic",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Square Cloud is a cloud platform that hosts your applications, bots, websites and databases with zero infrastructure setup."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 24,
"total_tokens": 52
}
}
```
## 错误
所有错误都使用 OpenAI 的结构 `{ "error": { "message", "type", "param", "code" } }`，包括身份验证、权限范围、速率限制、无效请求体、`500` 和 `503` 错误，且 `code` 始终为小写。
| 状态 | 代码 | 含义与处理方式 |
| - | - | - |
| 401 | `access_denied` | API 密钥缺失、无效、已吊销或已过期。 |
| 403 | `upgrade_required` | 该套餐无法使用 AI Gateway（Hobby 或没有套餐）。请升级到 Standard 或以上。 |
| 403 | `missing_scope` | API 密钥缺少此端点所需的权限范围。 |
| 403 | `resource_not_allowed` | API 密钥仅限于不涵盖本次请求的资源。 |
| 400 | `invalid_json_body` / `invalid_messages` / `invalid_tools` / `invalid_tool_choice` / `invalid_temperature` / `invalid_max_tokens` | 请求体格式错误：请修正被指出的字段。 |
| 400 | `stream_not_supported` | 请移除 `stream: true`；流式输出暂不可用。 |
| 400 | `multimodal_not_supported` | 此端点仅支持文本。请将每条消息的 `content` 以字符串发送，并去掉 `audio` 以及 `["text"]` 以外的 `modalities`。 |
| 400 | `context_length_exceeded` | 消息加上工具定义超出了套餐的上下文窗口。请缩短历史记录或升级套餐。 |
| 400 | `invalid_request` | 模型后端拒绝了该请求：几乎总是工具调用协议错误（某条 `tool` 消息没有对应前面的 `tool_calls`，或调用 ID 重复）。 |
| 413 | `payload_too_large` | 请求体超出了此端点接受的大小。请缩短历史记录。 |
| 429 | `concurrent_limit_reached` | 已有一个请求正在处理中；请等待其完成（Enterprise 允许同时 2 个）。 |
| 429 | `rate_limit_exceeded` | 请求发送速度快于套餐允许的间隔；请在客户端添加延迟。 |
| 429 | `daily_request_limit_reached` | 已达到套餐的每日请求上限（Standard 1,000 / Pro 5,000），于 UTC 00:00 重置。Enterprise 没有上限。 |
| 429 | `daily_spend_limit_reached` | 已达到套餐在网关上的每日合理使用额度，于 UTC 00:00 重置。Enterprise 的额度为基础额度的 5 倍。 |
| 429 | `daily_limit_reached` | 每日 AI 令牌额度已用完，于 UTC 00:00 重置。升级套餐可提高额度。 |
| 429 | `rate_limited` | 已达到账户或 API 密钥的请求限制；请等待后重试。 |
| 500 | `internal_server_error` | 意外故障。请重试。 |
| 503 | `server_overloaded` | 容量暂时已满，或请求超过了 90 秒的总时限；请稍后重试（OpenAI SDK 会自动重试）。 |
| 503 | `daily_capacity_reached` | AI Gateway 面向整个平台的每日共享容量已用完。于 UTC 00:00 重置；在此之前重试无济于事。 |
| 503 | `database_unavailable` | 平台暂时不可用。请几秒后重试。 |
其中三个代码看起来相似，但含义不同：
* `429 daily_spend_limit_reached`：**你的**密钥的每日限制，由套餐决定。
* `503 daily_capacity_reached`：网关在**平台**层面的每日容量，由所有客户共享。
* `503 server_overloaded`：暂时过载，或请求总耗时超过 90 秒（包括服务商排队、重试和搜索轮次）。请几秒后重试。
## 常见问题
不会，该 API 是无状态的，与 OpenAI 完全相同：每次请求都要在 `messages` 中发送对话历史。
`cubic`，Square Cloud 托管的模型。没有可供选择的模型列表；接受 `model` 字段只是为了兼容 SDK。
可以，这正是主要的使用场景。它是一个普通的 HTTPS API，因此在任何地方都能使用。
会：两者消耗同一个每日 AI 令牌额度，因此大量使用网关会减少控制台助手可用的额度，反之亦然。
## 相关内容
* SDK：[`api.ai.chat()`](/zh/sdks/js/ai)（JavaScript）、[`client.ai.chat()`](/zh/sdks/py/ai)（Python）、[`c.AI.Chat()`](/zh/sdks/go/ai)（Go）