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

# API 参考

> 同时支持 OpenAI 协议和 Anthropic Claude 协议，按需选择

RuAPI **同时支持两种 API 协议**：经典的 OpenAI 兼容，和原生 Anthropic Claude 兼容。**同一把 API key 在两边都能用**。

<CardGroup cols={2}>
  <Card title="OpenAI 协议" icon="plug">
    `POST /v1/chat/completions` —— 行业标准，几乎所有 SDK 和框架都支持。
  </Card>

  <Card title="Claude 协议" icon="brain">
    `POST /v1/messages` —— Anthropic 原生格式，支持 thinking 块和 MCP。
  </Card>
</CardGroup>

**速查：**

|            | OpenAI 兼容                      | Anthropic                        |
| ---------- | ------------------------------ | -------------------------------- |
| `base_url` | `https://www.ruapi.ai/v1`      | `https://www.ruapi.ai`（不带 `/v1`） |
| 端点         | `POST /v1/chat/completions`    | `POST /v1/messages`              |
| 鉴权头        | `Authorization: Bearer sk-...` | `x-api-key: sk-...`              |

## 基础 URL

地址取决于协议 —— 这是最容易填错的地方：

**OpenAI 兼容** —— 带 `/v1`：

```
https://www.ruapi.ai/v1
```

**Anthropic** —— 不带 `/v1`（SDK 会自动补 `/v1/messages`）：

```
https://www.ruapi.ai
```

下方端点表里的路径都是从域名根写全的。鉴权通过 `Authorization: Bearer sk-...` 头（`/v1/messages` 上 `x-api-key` 也可）。

<Warning>
  Anthropic 的 `base_url` **不要**加 `/v1` —— 多写一个 `/v1` 会导致 **404**。
</Warning>

***

## OpenAI 协议

如果你的代码已经在用 **OpenAI 官方 SDK** 或兼容框架（LangChain、LlamaIndex、Vercel AI SDK 等），用这个协议。

### 端点

```
POST https://www.ruapi.ai/v1/chat/completions
```

### 兼容性

请求/响应格式与 [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 完全一致。支持：

* `messages`（角色 `system` / `user` / `assistant` / `tool`）
* `model` —— 模型库里任意模型名（包括 Claude/Gemini/Grok/Qwen/MiniMax/GLM，我们会自动转换协议）
* `stream: true` 流式响应（Server-Sent Events）
* `tools` / `tool_choice` —— function calling
* `temperature`、`top_p`、`max_tokens` 等参数

### Python 示例（OpenAI SDK）

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的KEY",
    base_url="https://www.ruapi.ai/v1",
)

response = client.chat.completions.create(
    model="claude-opus-4-8",  # 可用模型名见主站价格页面
    messages=[
        {"role": "system", "content": "你是一个友好的助手。"},
        {"role": "user", "content": "你好！你能做什么？"},
    ],
    temperature=0.7,
)

print(response.choices[0].message.content)
print(f"消耗 token: {response.usage.total_tokens}")
```

### Node.js 示例（OpenAI SDK）

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-你的KEY",
  baseURL: "https://www.ruapi.ai/v1",
});

const response = await client.chat.completions.create({
  model: "claude-opus-4-8", // 可用模型名见主站价格页面（用 OpenAI 协议也能调 Claude）
  messages: [
    { role: "user", content: "用大白话解释量子纠缠。" },
  ],
});

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

### curl 示例（带 streaming）

```bash theme={null}
curl https://www.ruapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-你的KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "写一首关于代码的俳句。"}],
    "stream": true
  }'
```

***

## Claude 协议

如果你的代码用 **Anthropic SDK**，或者你需要 Claude 特有的功能（thinking 块、原生格式 tool calls），用这个协议。

### 端点

```
POST https://www.ruapi.ai/v1/messages
```

### 兼容性

请求/响应格式与 [Anthropic Messages API](https://docs.anthropic.com/claude/reference/messages_post) 完全一致。支持：

* `messages` 数组（Claude 原生格式）
* `system` 作为单独字段
* `model` —— Claude 模型名或其他（我们会转成 Claude 协议）
* `max_tokens`（Claude 必填）
* `stream: true`
* `tools` / `tool_choice`
* `thinking` —— 推理模型的思考模式

### Python 示例（Anthropic SDK）

```python theme={null}
from anthropic import Anthropic

client = Anthropic(
    api_key="sk-你的KEY",
    base_url="https://www.ruapi.ai",
)

response = client.messages.create(
    model="claude-opus-4-8",  # 可用模型名见主站价格页面
    max_tokens=1024,
    system="你是一个技术专家。",
    messages=[
        {"role": "user", "content": "什么是 CAP 定理？"},
    ],
)

print(response.content[0].text)
print(f"消耗：input={response.usage.input_tokens}, output={response.usage.output_tokens}")
```

### Node.js 示例（Anthropic SDK）

```javascript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "sk-你的KEY",
  baseURL: "https://www.ruapi.ai",
});

const response = await client.messages.create({
  model: "claude-opus-4-8", // 可用模型名见主站价格页面
  max_tokens: 1024,
  messages: [
    { role: "user", content: "解释 Rust borrow checker 的工作原理。" },
  ],
});

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

### curl 示例

```bash theme={null}
curl https://www.ruapi.ai/v1/messages \
  -H "x-api-key: sk-你的KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "写一首关于代码的俳句。"}]
  }'
```

<Note>
  Anthropic SDK 用的是 `x-api-key` 头，不是 `Authorization: Bearer`。RuAPI 在 `/v1/messages` 端点上 **两种头都接受**。
</Note>

***

## 该选哪个协议

| 场景                                       | 用                    |
| ---------------------------------------- | -------------------- |
| 已经在用 OpenAI SDK / LangChain / LlamaIndex | **OpenAI 协议**        |
| 写原生 Anthropic 代码，需要 thinking 块           | **Claude 协议**        |
| 现有 OpenAI 代码想调 Claude                    | **OpenAI 协议**（我们会转换） |
| Anthropic SDK 想调 gpt-5.4                 | **Claude 协议**（我们会转换） |

不管哪个 —— **同一把 API key**，token 同价，余额同账户。

## 全部端点

| 方法   | 路径                         | 用途                      |
| ---- | -------------------------- | ----------------------- |
| POST | `/v1/chat/completions`     | OpenAI Chat Completions |
| POST | `/v1/messages`             | Claude Messages         |
| POST | `/v1/embeddings`           | 嵌入向量（OpenAI 兼容）         |
| POST | `/v1/images/generations`   | 图片生成（OpenAI 兼容）         |
| POST | `/v1/audio/transcriptions` | Whisper 转录              |
| POST | `/v1/audio/speech`         | TTS 语音合成                |
| GET  | `/v1/models`               | 模型列表                    |

完整带模型清单的列表在 **首页 → 价格** 页看。