> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodesms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 对接说明

> 了解接口地址、鉴权方式和错误处理，快速接入 AI 模型接口。

本服务提供 OpenAI 兼容格式的 AI 模型接口。已经使用 OpenAI SDK 或支持 OpenAI 协议的工具，只需替换 **接口地址** 和 **API Key** 即可接入。

## 接口地址

| 项目 | 值 |
| - | - |
| Base URL | `https://t.ato2.nodesms.com/v1` |
| 协议 | HTTPS |
| 数据格式 | JSON（`application/json`）；图像编辑、音频转录、音频翻译使用 `multipart/form-data` 上传文件 |

## 获取 API Key

1. 登录 [https://t.ato2.nodesms.com](https://t.ato2.nodesms.com)。
2. 进入令牌管理页面，创建一个新令牌。
3. 复制生成的 Key（以 `sk-` 开头）。

> [!WARNING]
>
> API Key 等同于账户密码，请勿在前端代码、公开仓库或客户端应用中暴露。

## 鉴权方式

所有请求都需要在请求头中携带 API Key：

```http theme={"dark"}
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
```

## 快速测试

```bash theme={"dark"}
curl https://t.ato2.nodesms.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

> [!NOTE]
>
> 文档中的模型名称仅为示例，实际可用模型请调用 [模型列表](https://docs.nodesms.com/aitoken/api/models.md) 接口（`GET /v1/models`）查询。

## 在 SDK 中使用

```python Python theme={"dark"}
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxxxxxxxx",
    base_url="https://t.ato2.nodesms.com/v1",
)
```

```javascript Node.js theme={"dark"}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxxxxxxxxxxxxx",
  baseURL: "https://t.ato2.nodesms.com/v1",
});
```

在第三方客户端（如 Cherry Studio、LobeChat、NextChat 等）中，选择 OpenAI 类型，并将 API 地址填写为 `https://t.ato2.nodesms.com`（部分客户端需要填写带 `/v1` 的完整地址）。

## 错误处理

接口出错时返回 OpenAI 兼容的错误结构：

```json theme={"dark"}
{
  "error": {
    "message": "错误信息",
    "type": "错误类型",
    "param": null,
    "code": null
  }
}
```

| 字段 | 类型 | 说明 |
| - | - | - |
| `message` | string | 错误信息 |
| `type` | string | 错误类型 |
| `param` | string 或 null | 相关参数 |
| `code` | string 或 null | 错误代码 |

| HTTP 状态码 | 含义 | 处理建议 |
| - | - | - |
| `400` | 请求参数错误 | 检查请求体字段和格式 |
| `401` | API Key 无效或缺失 | 检查 `Authorization` 请求头 |
| `403` | 无权访问该模型 | 确认令牌可用的模型范围 |
| `404` | 资源不存在 | 检查路径或任务 ID 是否正确 |
| `429` | 请求频率限制或额度不足 | 降低频率或充值后重试 |
| `500` / `502` / `503` | 服务端或上游异常 | 稍后重试 |

> [!TIP]
>
> 每个接口文档页面右侧均嵌有 API Playground，填入 API Key 即可直接在线调试接口。

## 接口列表

### 模型

> **[模型列表](https://docs.nodesms.com/aitoken/api/models.md)**
>
> `GET /v1/models`

### 聊天

> **[ChatCompletions格式](https://docs.nodesms.com/aitoken/api/chat-completions.md)**
>
> `POST /v1/chat/completions`

> **[Responses格式](https://docs.nodesms.com/aitoken/api/responses.md)**
>
> `POST /v1/responses`

> **[文本补全](https://docs.nodesms.com/aitoken/api/completions.md)**
>
> `POST /v1/completions`

### 嵌入与重排序

> **[向量嵌入](https://docs.nodesms.com/aitoken/api/embeddings.md)**
>
> `POST /v1/embeddings`

> **[重排序](https://docs.nodesms.com/aitoken/api/rerank.md)**
>
> `POST /v1/rerank`

### 图像

> **[图像生成](https://docs.nodesms.com/aitoken/api/images.md)**
>
> `POST /v1/images/generations`

> **[图像编辑](https://docs.nodesms.com/aitoken/api/image-edits.md)**
>
> `POST /v1/images/edits/`

### 音频

> **[音频合成](https://docs.nodesms.com/aitoken/api/audio-speech.md)**
>
> `POST /v1/audio/speech`

> **[音频转录](https://docs.nodesms.com/aitoken/api/audio-transcriptions.md)**
>
> `POST /v1/audio/transcriptions`

> **[音频翻译](https://docs.nodesms.com/aitoken/api/audio-translations.md)**
>
> `POST /v1/audio/translations`

### 视频

> **[创建视频生成任务](https://docs.nodesms.com/aitoken/api/videos.md)**
>
> `POST /v1/video/generations`

> **[获取视频生成任务状态](https://docs.nodesms.com/aitoken/api/video-status.md)**
>
> `GET /v1/video/generations/{task_id}`

### 内容审查

> **[内容审查](https://docs.nodesms.com/aitoken/api/moderations.md)**
>
> `POST /v1/moderations`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.