兼容 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 期间，除套餐每日 AI 令牌额度外不收取额外费用。Beta 结束后，限制和可用套餐可能会发生变化。

如何连接

基础 URL： https://api.squarecloud.app/v2/ai
API 密钥： 你的账户 API 密钥（与 Square Cloud API 和 CLI 使用的相同，可在账户页面获取）。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 或以上即可开通。

请求约定

string

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

array

必填

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

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 重置。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。

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

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

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

会：两者消耗同一个每日 AI 令牌额度，因此大量使用网关会减少控制台助手可用的额度，反之亦然。

入门

账户

应用

数据库

工作区

AI

兼容 OpenAI 的 AI Gateway（Beta）

如何连接

套餐与限制

请求约定

内置联网搜索

错误

常见问题

相关内容

​如何连接

​套餐与限制

​请求约定

​内置联网搜索

​错误

​常见问题

​相关内容

如何连接

套餐与限制

请求约定

内置联网搜索

错误

常见问题

相关内容