兼容 OpenAI 的 AI Gateway（Beta）

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);

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)

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." }
    ]
  }'

{
  "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
  }
}

string

必填

你账户的 API 密钥。你可以在账户设置中找到它。

需要具有 ai:chat 权限范围的 API 密钥。 AI Gateway 让你通过一个兼容 OpenAI 的聊天补全端点，在你自己的产品（聊天机器人、助手、自动化流程）中使用 Square Cloud 托管的 AI 模型。如果你的代码已经在使用 OpenAI API，那么它也能直接使用 AI Gateway：将 SDK 指向我们的基础 URL，使用你的账户 API 密钥，并将模型设为 cubic。

AI Gateway 目前处于 Beta 阶段，提供免费抢先体验：Beta 期间不收取额外费用，用量只计入网关自身的令牌限制。Beta 结束后，限制和可用套餐可能会发生变化。

如何连接

基础 URL： https://api.squarecloud.app/v2/ai
API 密钥： 你的账户 API 密钥（与 Square Cloud API 和 CLI 使用的相同，可在账户页面获取）。Authorization 请求头带或不带 Bearer 前缀均可。
模型： cubic，Square Cloud 托管的模型，与驱动控制台 AI 助手的是同一个模型。

套餐与限制

每个请求都会按实际令牌数计入网关自身的令牌限制：每日限制于 UTC 00:00 重置；每周限制为每日限制的 4 倍，于每周一 UTC 00:00 重置。它们与控制台 AI 助手的限制相互独立，因此网关流量永远不会用掉助手的额度，反之亦然。Standard 和 Pro 还设有每日请求上限；每个套餐在网关上都有一个每日合理使用额度，按适度使用的需求设定（依据请求的服务成本，用于防范无人看管的密钥）。两者均于 UTC 00:00 重置。

套餐	每日令牌数	每周令牌数	每日请求数	合理使用额度	上下文窗口	最大输出	并发请求	请求间隔
Standard	2.5M	10M	1,000	基础	16,384 令牌	4,096	1	5 秒
Pro	5M	20M	5,000	基础的 2 倍	24,576 令牌	6,144	1	2 秒
Enterprise	10M 至 20M	40M 至 80M	不限	基础的 5 倍	32,768 令牌	8,192	2	无

Standard 套餐的所有规格网关限制相同，Pro 的所有规格也是如此。Enterprise 的令牌限制随套餐增长：Enterprise 32 每日 10M 令牌，Enterprise 48 为 12M，Enterprise 64 为 14M，Enterprise 96 为 16M，Enterprise 128 及以上为 20M，每周限制为其 4 倍。

Hobby 套餐（以及没有套餐的账户）无法使用 AI Gateway：升级到 Standard 或以上即可开通。

请求约定

string

为兼容 SDK 而接受此字段；网关始终以 cubic 作答。

array

必填

OpenAI 风格的消息，角色为 system、user、assistant 和 tool。内容必须是字符串：此端点仅支持文本，因此多部分数组（image_url、input_audio、file）会被拒绝并返回 400 multimodal_not_supported。每个请求最多 100 条消息。

number

OpenAI 对回答 token 上限的当前命名，OpenAI SDK 发送的就是它。与 max_tokens 同时出现时以它为准。会被静默限制在套餐的输出上限以内。

number

旧名称，仍然可用。会被静默限制在套餐的输出上限以内。

number

取值范围 0 到 2。

array

标准 OpenAI 格式的函数调用，最多 32 个工具定义。工具调用以 finish_reason: "tool_calls" 返回，你再以 role: "tool" 消息发回结果。

string | object

标准的 OpenAI tool_choice 值。

未知参数会被忽略，但有两个刻意的例外：audio 以及不等于 ["text"] 的 modalities 值会被拒绝而不是忽略，这样请求语音输出时绝不会默默返回文本。 文本输入，文本输出。 任何套餐都不接受图片、音频和文件，这是产品层面的决定，而非暂时的缺失。请发送文本并读取文本。 暂不支持： 流式输出（stream: true 会返回 400 stream_not_supported）。

内置联网搜索

当对话需要最新信息或外部信息时，模型会自行决定是否联网搜索。搜索在服务器端进行，只返回最终答案，并引用结果 URL。如果你自己声明了名为 web_search 的工具，它会取代内置工具。

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);

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)

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." }
    ]
  }'

{
  "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 重置。Pro 的额度为基础额度的 2 倍，Enterprise 为 5 倍。
429	`daily_limit_reached`	网关的每日令牌限制已用完，于 UTC 00:00 重置。升级套餐可提高该限制。
429	`weekly_limit_reached`	网关的每周令牌限制（每日限制的 4 倍）已用完，于每周一 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 秒（包括服务商排队、重试和搜索轮次）。请几秒后重试。

重试

大多数 429 和 503 响应都会通过 OpenAI SDK 能读取的响应头，告诉你的客户端何时可以重试：

代码	响应头	预期行为
`429 rate_limit_exceeded`	`Retry-After`，值为套餐规定的请求间隔秒数（Standard 5，Pro 2）	OpenAI SDK 会自动等待并重试。
`429 daily_request_limit_reached`、`daily_spend_limit_reached`、`daily_limit_reached` 和 `503 daily_capacity_reached`	`Retry-After`，值为距 UTC 00:00 的秒数，并带有 `x-should-retry: false`	SDK 不会重试；请等待重置。
`429 weekly_limit_reached`	`Retry-After`，值为距周一 UTC 00:00 的秒数，并带有 `x-should-retry: false`	SDK 不会重试；请等待重置。
`503 server_overloaded`	`Retry-After: 2`	OpenAI SDK 会自动等待并重试。
`429 concurrent_limit_reached`	无 `Retry-After`	等进行中的请求完成后再重试，或交给 SDK 默认的重试机制。

OpenAI SDK 会遵循不超过 60 秒的 Retry-After。等待时间更长时，SDK 会改用自身的退避策略，除非响应同时带有 x-should-retry: false，这会关闭其自动重试。如果不使用 OpenAI SDK，请自行读取 Retry-After，等待相应秒数后再发送下一个请求。

常见问题

它会记住对话吗？

不会，该 API 是无状态的，与 OpenAI 完全相同：每次请求都要在 messages 中发送对话历史。

使用的是哪个模型？

cubic，Square Cloud 托管的模型。没有可供选择的模型列表；接受 model 字段只是为了兼容 SDK。

可以从托管在 Square Cloud 上的应用调用它吗？

可以，这正是主要的使用场景。它是一个普通的 HTTPS API，因此在任何地方都能使用。

使用网关会影响控制台的 AI 助手吗？

不会。网关有自己的每日和每周令牌限制，与控制台助手的限制相互独立，因此大量使用网关永远不会用掉助手的额度，反之亦然。

入门

账户

应用

数据库

工作区

AI

兼容 OpenAI 的 AI Gateway（Beta）

如何连接

套餐与限制

请求约定

内置联网搜索

错误

重试

常见问题

相关内容

​如何连接

​套餐与限制

​请求约定

​内置联网搜索

​错误

​重试

​常见问题

​相关内容

如何连接

套餐与限制

请求约定

内置联网搜索

错误

重试

常见问题

相关内容