# 小艾引擎 API 开发文档

**版本**: v1.0
**更新日期**: 2026-02-26
**基础地址**: `https://api1.szaiai.com`

---

## 1. 概述

小艾引擎 API 提供强大的大语言模型能力，支持对话补全、流式输出和文本向量化。接口兼容主流 SDK，开发者可快速集成。

### 接入信息

| 项目 | 值 |
|------|-----|
| 基础地址 | `https://api1.szaiai.com` |
| 认证方式 | API Key（由管理员分配） |
| 请求格式 | JSON |
| 字符编码 | UTF-8 |

---

## 2. 认证

所有请求必须携带 API Key，支持两种方式：

**方式一：X-Api-Key 请求头**
```
X-Api-Key: sk-gw-your-key-here
```

**方式二：Bearer Token（兼容 OpenAI SDK）**
```
Authorization: Bearer sk-gw-your-key-here
```

---

## 3. API 接口

### 3.1 对话补全（Messages）

创建一轮对话，模型根据消息上下文生成回复。

**请求**

```
POST /v1/messages
Content-Type: application/json
```

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model | string | 是 | 模型名称，填写管理员提供的值（如 `xiaoai-chat-v1`） |
| messages | array | 是 | 对话消息列表 |
| max_tokens | integer | 是 | 最大生成 token 数（建议 1024-4096） |
| stream | boolean | 否 | 是否启用流式输出，默认 false |
| temperature | number | 否 | 采样温度 0-1，默认 1。越低越确定 |
| top_p | number | 否 | 核采样概率 0-1 |
| stop_sequences | array | 否 | 停止序列列表 |
| system | string | 否 | 系统提示词，设定模型角色和行为 |

**messages 格式**

```json
[
  {"role": "user", "content": "你好，请介绍一下你自己"},
  {"role": "assistant", "content": "你好！我是小艾引擎..."},
  {"role": "user", "content": "你能做什么？"}
]
```

支持的 role：
- `user` — 用户消息
- `assistant` — 助手消息（用于多轮对话上下文）

**响应示例**

```json
{
  "model": "xiaoai-chat-v1",
  "id": "msg-a1b2c3d4e5f6...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "你好！我是小艾引擎，一个强大的AI助手..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 42
  }
}
```

**响应字段说明**

| 字段 | 说明 |
|------|------|
| model | 模型名称 |
| id | 请求唯一标识 |
| content | 回复内容数组，每项包含 type 和 text |
| stop_reason | 停止原因：end_turn（正常结束）、max_tokens（达到上限）、stop_sequence |
| usage.input_tokens | 输入消耗的 token 数 |
| usage.output_tokens | 输出消耗的 token 数 |

---

### 3.2 对话补全（Chat Completions，OpenAI 兼容）

兼容 OpenAI Chat Completions 格式，方便从 OpenAI SDK 迁移。

**请求**

```
POST /v1/chat/completions
Content-Type: application/json
```

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model | string | 是 | 模型名称 |
| messages | array | 是 | 对话消息列表 |
| max_tokens | integer | 否 | 最大生成 token 数 |
| stream | boolean | 否 | 是否流式输出 |
| temperature | number | 否 | 采样温度 0-2 |

**响应示例**

```json
{
  "id": "cmpl-a1b2c3d4e5f6...",
  "object": "chat.completion",
  "model": "xiaoai-chat-v1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮助你的吗？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}
```

---

### 3.3 文本向量化（Embeddings）

将文本转换为向量表示，用于语义搜索、聚类等场景。

**请求**

```
POST /v1/embeddings
Content-Type: application/json
```

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model | string | 是 | 模型名称 |
| input | string 或 array | 是 | 待向量化的文本（或文本数组） |
| encoding_format | string | 否 | 返回格式：float（默认）或 base64 |

**响应示例**

```json
{
  "object": "list",
  "model": "xiaoai-embed-v1",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0091, 0.0152, ...]
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
```

---

## 4. 流式输出（Streaming）

流式模式下，模型逐步返回生成内容，适合实时展示场景。设置 `stream: true` 即可启用。

响应格式为 Server-Sent Events (SSE)，每行以 `data: ` 开头：

```
event: message_start
data: {"type":"message_start","message":{"model":"xiaoai-chat-v1",...}}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"你好"}}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"！"}}

event: message_stop
data: {"type":"message_stop"}
```

---

## 5. 错误处理

**错误响应格式**

```json
{
  "error": {
    "type": "error_type",
    "message": "错误详细描述"
  }
}
```

**常见错误码**

| HTTP 状态码 | 错误类型 | 说明 |
|------------|---------|------|
| 400 | invalid_request_error | 请求参数错误（如 JSON 格式无效） |
| 401 | authentication_error | API Key 无效或缺失 |
| 403 | permission_error | 权限不足（如 Key 已禁用或过期） |
| 429 | rate_limit_error | 请求频率超限，请降低调用频率 |
| 502 | upstream_error | 服务暂时不可用，请稍后重试 |

**建议的重试策略**：遇到 429 或 502 错误时，采用指数退避（1s, 2s, 4s...）重试，最多重试 3 次。

---

## 6. 代码示例

### 6.1 Python — 对话补全

```python
import anthropic

client = anthropic.Anthropic(
    api_key="sk-gw-your-key-here",
    base_url="https://api1.szaiai.com"
)

response = client.messages.create(
    model="xiaoai-chat-v1",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "请用三句话介绍人工智能"}
    ]
)

print(response.content[0].text)
```

### 6.2 Python — 流式输出

```python
import anthropic

client = anthropic.Anthropic(
    api_key="sk-gw-your-key-here",
    base_url="https://api1.szaiai.com"
)

with client.messages.stream(
    model="xiaoai-chat-v1",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一首关于春天的诗"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

### 6.3 Python — OpenAI 兼容模式

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-gw-your-key-here",
    base_url="https://api1.szaiai.com/v1"
)

response = client.chat.completions.create(
    model="xiaoai-chat-v1",
    messages=[
        {"role": "user", "content": "什么是机器学习？"}
    ]
)

print(response.choices[0].message.content)
```

### 6.4 Node.js

```javascript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "sk-gw-your-key-here",
  baseURL: "https://api1.szaiai.com",
});

const response = await client.messages.create({
  model: "xiaoai-chat-v1",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好" }],
});

console.log(response.content[0].text);
```

### 6.5 cURL

```bash
curl https://api1.szaiai.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk-gw-your-key-here" \
  -d '{
    "model": "xiaoai-chat-v1",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'
```

### 6.6 文本向量化

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-gw-your-key-here",
    base_url="https://api1.szaiai.com/v1"
)

response = client.embeddings.create(
    model="xiaoai-embed-v1",
    input="人工智能是计算机科学的一个分支"
)

print(f"向量维度: {len(response.data[0].embedding)}")
```

---

## 7. 多轮对话

实现多轮对话需要将历史消息传入 messages 数组：

```python
messages = [
    {"role": "user", "content": "我叫小明"},
    {"role": "assistant", "content": "你好小明！很高兴认识你。"},
    {"role": "user", "content": "我叫什么名字？"}
]

response = client.messages.create(
    model="xiaoai-chat-v1",
    max_tokens=256,
    messages=messages
)
# 模型会回答"你叫小明"
```

---

## 8. 系统提示词

通过 system 参数设定模型的角色和行为：

```python
response = client.messages.create(
    model="xiaoai-chat-v1",
    max_tokens=1024,
    system="你是一位专业的法律顾问，用通俗易懂的语言解答法律问题。",
    messages=[
        {"role": "user", "content": "租房合同到期后房东不退押金怎么办？"}
    ]
)
```

---

## 9. 使用限制

| 限制项 | 默认值 | 说明 |
|--------|--------|------|
| 请求频率 | 60 次/分钟 | 可按需调整，联系管理员 |
| 单次请求体大小 | 50 MB | 支持大文档、图片 base64 |
| max_tokens 上限 | 取决于模型 | 通常 4096-8192 |

---

## 10. SDK 安装

小艾引擎 API 兼容主流 SDK，选择以下任一方式安装：

**Python — Messages 接口**
```bash
pip install anthropic
```

**Python — Chat Completions / Embeddings 接口**
```bash
pip install openai
```

**Node.js — Messages 接口**
```bash
npm install @anthropic-ai/sdk
```

**Node.js — Chat Completions / Embeddings 接口**
```bash
npm install openai
```

---

## 11. 常见问题

**Q: model 参数填什么？**
A: 填写管理员分配给您的模型名称。对话接口填 `xiaoai-chat-v1`，向量化接口填 `xiaoai-embed-v1`。具体以管理员提供为准。

**Q: 支持图片输入吗？**
A: 支持。在 content 中使用 image 类型的内容块，传入 base64 编码的图片即可。

**Q: 流式输出和普通模式有什么区别？**
A: 流式模式下模型边生成边返回，首个 token 到达更快，适合聊天界面实时显示。普通模式等全部生成完毕后一次性返回。

**Q: 如何计算费用？**
A: 按 input_tokens + output_tokens 计费，具体单价请联系管理员。

---

> **技术支持**: 如有问题请联系管理员获取帮助。