> ## 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.

# AI

> 通过 @squarecloud/api 的 api.ai.chat() 调用 Square Cloud AI Gateway：兼容 OpenAI 的聊天补全，不支持流式传输。

`api.ai.chat(request)` 调用 [AI Gateway](/en/api-reference/ai-gateway)，这是一个**兼容 OpenAI** 的聊天补全 endpoint。它需要 `ai:chat` 作用域以及 Standard 或更高级别的套餐。

```typescript theme={"system"}
const completion = await api.ai.chat({
    model: "cubic",
    messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "What is Square Cloud?" },
    ],
    max_tokens: 512,
});

console.log(completion.choices[0].message.content);
console.log(completion.usage.total_tokens);
```

## 请求

| 字段                      | 说明                                                                                             |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| `model`                 | `cubic`。为兼容性而接受：没有其他模型                                                                         |
| `messages`              | `{ role, content?, tool_call_id?, tool_calls? }`，`role` 为 `system`、`user`、`assistant` 或 `tool` |
| `tools` / `tool_choice` | OpenAI 函数调用                                                                                    |
| `max_tokens`            | 回答的最大 token 数                                                                                  |
| `temperature`           | 采样温度                                                                                           |

响应采用 OpenAI 的格式：`id`、`object`、`created`、`model`、`choices`（`index`、`message`、`finish_reason`）和 `usage`。

## 不支持流式传输

`ai.chat()` 不进行流式传输：它返回完整的补全结果。`stream: true` 会返回 400 `stream_not_supported`。

## 超时

网关为每个请求总共提供 **90 秒**，之后返回 503 `server_overloaded`。SDK 至少等待 120 秒才会超时，因此你会收到网关的响应。

## 错误

AI 错误使用 OpenAI 格式，因此其代码为**小写**。它们仍然会抛出 [`SquareCloudAPIError`](/zh/sdks/js/errors)，`code` 被设为 OpenAI 代码（没有代码时则为其 `type`）：

```typescript theme={"system"}
import { SquareCloudAPIError } from "@squarecloud/api";

try {
    await api.ai.chat({ messages: [{ role: "user", content: "Hi" }] });
} catch (error) {
    if (error instanceof SquareCloudAPIError && error.code === "server_overloaded") {
        // safe to retry yourself
    }
}
```

| 状态  | 代码                                                                                                      | 触发条件                   |
| --- | ------------------------------------------------------------------------------------------------------- | ---------------------- |
| 400 | `stream_not_supported`                                                                                  | 发送了 `stream: true`     |
| 400 | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | 某个字段格式错误               |
| 400 | `context_length_exceeded`                                                                               | 对话超出了套餐的上下文窗口          |
| 401 | `access_denied`                                                                                         | 无效的 API 密钥             |
| 403 | `upgrade_required`                                                                                      | 该套餐无权访问 AI Gateway     |
| 429 | `rate_limit_exceeded`, `concurrent_limit_reached`                                                       | 请求过快，或已有请求正在进行中        |
| 429 | `daily_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached`                       | 每日额度已用完（UTC 00:00 重置）  |
| 503 | `server_overloaded`                                                                                     | 容量已满或已超过 90 秒期限：可以安全重试 |
| 503 | `daily_capacity_reached`                                                                                | 平台的每日容量已用完             |

SDK **从不重试** AI 错误：该请求是非幂等的 `POST`。套餐限制请参见 [AI Gateway 参考](/en/api-reference/ai-gateway)。