# 51token API 接口文档

一个 Base URL，接全部主流模型。任何支持 OpenAI 协议的工具，填三个值就能跑通。

- 网页版：https://tokencn.299551.com/docs/
- 本文件（整篇 Markdown，可以直接交给 AI）：https://tokencn.299551.com/docs/index.md
- 简短索引：https://tokencn.299551.com/docs/llms.txt

- Base URL：https://tokencn.299551.com/v1
- API Key：sk-（在控制台「API 密钥」页创建）
- Model：deepseek-v4.1-flash

<!-- section: quick -->
## 01 三秒接入

先跑通，再研究细节。

打开终端，把 `sk-` 后面换成你自己的令牌，回车。返回一段 JSON 就说明通了：

```bash
curl https://tokencn.299551.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

成功返回长这样：

```json
{
  "id": "chatcmpl-20261119...",
  "object": "chat.completion",
  "created": 1795076731,
  "model": "deepseek-v4.1-flash",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "你好！有什么可以帮你的？"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21}
}
```

> **记住一个原则：**Base URL 只要写到 `/v1` 为止。SDK 和客户端会自动拼上 `/chat/completions`，你自己写全了反而会 404。

<!-- section: token -->
## 02 创建令牌

令牌（API Key）就是你的调用凭证，形如 `sk-xxxxxxxx`。

1. **登录控制台**：打开 [tokencn.299551.com/sign-in](https://tokencn.299551.com/sign-in)，用账号密码登录。
2. **进入「API 密钥」页**：控制台左侧菜单 →「[API 密钥](https://tokencn.299551.com/keys)」→「创建 API 密钥」。
3. **设个名字，直接提交**：名称随便填（如 `我的电脑`），额度留空即无限、永不过期。提交后点「复制」拿到完整 `sk-` 密钥。

> **密钥只显示一次。**关掉弹窗就再也看不到明文了，请立刻粘贴到你的软件里保存好。公共电脑上用完记得在「API 密钥」页「禁用」。

### 创建时的三个设置

| 设置 | 说明 | 建议 |
|---|---|---|
| **额度** | 该令牌最多能花多少钱，留空为不限 | 个人用留空；给别人用设上限 |
| **过期时间** | 到点自动失效，留空为永不过期 | 留空 |
| **模型限制** | 只能调用指定模型 | 一般关闭 |

<!-- section: models -->
## 03 模型与价格

当前在售 11 个可填模型名，全部走 OpenAI 协议，纯文本对话。价格随时段和调价变化，**以[模型参数](https://tokencn.299551.com/models)页实时显示为准**；不知道选哪个，[按场景选模型](https://tokencn.299551.com/models?scene=cs)。

| 模型名（照抄填进 model） | 计费 | 价格 | 说明 |
|---|---|---|---|
| `deepseek-v4.1-flash` | 分时价 | [实时价 →](https://tokencn.299551.com/model?m=deepseek-v4.1-flash) | 通用对话与代码 |
| `deepseek-v4-pro` | 分时价 | [实时价 →](https://tokencn.299551.com/model?m=deepseek-v4-pro) | 深度推理、复杂代码 |
| `az-deepseek-v4-pro` | 固定价 | [实时价 →](https://tokencn.299551.com/model?m=az-deepseek-v4-pro) | deepseek-v4-pro 的另一条线路 |
| `az-glm-5.3` | 固定价 | [实时价 →](https://tokencn.299551.com/model?m=az-glm-5.3) | 智谱 GLM 线路，官方定位编程与 Agent 任务 |
| `kimi-k3` | 固定价 | [实时价 →](https://tokencn.299551.com/model?m=kimi-k3) | Kimi 旗舰，长文档与深度推理 |
| `az-kimi-k3` | 固定价 | [实时价 →](https://tokencn.299551.com/model?m=az-kimi-k3) | kimi-k3 的另一条线路 |
| `kimi-k3.1-pro` | 固定价 | [实时价 →](https://tokencn.299551.com/model?m=kimi-k3.1-pro) | 长文档分析、多轮深度问答 |
| `az-kimi-k3.1-pro` | 固定价 | [实时价 →](https://tokencn.299551.com/model?m=az-kimi-k3.1-pro) | kimi-k3.1-pro 的另一条线路 |
| `glm-5.3-flash` | 固定价 | [实时价 →](https://tokencn.299551.com/model?m=glm-5.3-flash) | — |
| `glm-5.3` | 固定价 | [实时价 →](https://tokencn.299551.com/model?m=glm-5.3) | — |
| `az-glm-5.2` | 固定价 | [实时价 →](https://tokencn.299551.com/model?m=az-glm-5.2) | — |

价格人民币 / 每百万 tokens，输入、输出、缓存读取分别计价。全部模型的实时价见 [模型参数](https://tokencn.299551.com/models)，也可以看 [定价](https://tokencn.299551.com/price) 页的总表。

> **关于 az- 前缀：**带 `az-` 的是同一个模型的另一条线路，计费方式和价格各自独立，以[模型参数](https://tokencn.299551.com/models)页为准。某条线路偶发超时，可以换另一条试试。

> **关于分时价（deepseek-v4-pro、deepseek-v4.1-flash）：**工作日 **09:00–12:00、14:00–18:00** 为高峰价，其余时段（含周末）为平时价，平时价约为高峰的一半。页面上显示的是当前时段的价格。

<!-- section: base -->
## 04 基本信息

|  |  |
|---|---|
| **Base URL** | `https://tokencn.299551.com/v1` |
| **协议** | OpenAI API（兼容 `/v1/chat/completions`） |
| **认证** | 请求头 `Authorization: Bearer sk-xxx` |
| **编码** | `Content-Type: application/json`，UTF-8 |
| **支持** | 普通响应、SSE 流式响应 |

### 请求头

```http
Authorization: Bearer sk-你的令牌
Content-Type: application/json
```

<!-- section: chat -->
## 05 对话补全

POST /v1/chat/completions —— 全部模型都用这一个接口。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型 ID，见上文表格 |
| `messages` | array | 是 | 对话数组，`role` 取 `system` / `user` / `assistant` |
| `stream` | bool | 否 | `true` 时逐字返回，默认 `false` |
| `temperature` | number | 否 | 0–2，越高越随机。默认 0.7 左右，写代码建议 0.2 |
| `max_tokens` | int | 否 | 限制输出长度，省钱小技巧 |
| `top_p` | number | 否 | 与 temperature 二选一调 |
| `stop` | string / array | 否 | 遇到这些字符串就停止生成 |
| `presence_penalty` | number | 否 | -2 到 2，鼓励说新话题 |
| `frequency_penalty` | number | 否 | -2 到 2，降低重复词 |

### 多轮对话

把历史消息按顺序塞进 `messages` 即可，服务端不保存上下文，每次都要带全：

```json
{
  "model": "deepseek-v4.1-flash",
  "messages": [
    {"role": "system", "content": "你是一个简洁的助手，回答不超过三句话。"},
    {"role": "user", "content": "Python 里怎么读大文件？"},
    {"role": "assistant", "content": "用 with open 配合逐行迭代，避免一次性读取。"},
    {"role": "user", "content": "给我一段代码"}
  ],
  "temperature": 0.3
}
```

### 响应字段

| 字段 | 说明 |
|---|---|
| `choices[0].message.content` | 模型回复的正文 |
| `choices[0].finish_reason` | `stop` 正常结束；`length` 达到 max_tokens 被截断 |
| `usage.prompt_tokens` | 输入 token 数（计费依据之一） |
| `usage.completion_tokens` | 输出 token 数（计费依据之二） |

<!-- section: stream -->
## 06 流式输出

加一个 "stream": true，回复就像打字机一样逐字出现。

```bash
curl https://tokencn.299551.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "讲个笑话"}],
    "stream": true
  }'
```

返回是 SSE 格式，每行以 `data: ` 开头，最后一行固定是 `data: [DONE]`：

```text
data: {"choices":[{"delta":{"role":"assistant","content":"为"}}]}

data: {"choices":[{"delta":{"content":"什么"}}]}

data: {"choices":[{"delta":{"content":"程序员"}}]}

data: [DONE]
```

> 解析要点：取 `choices[0].delta.content` 拼起来；遇到 `[DONE]` 就停。 `delta` 里可能没有 `content` 字段（比如只返回 role），要判空再用。

> **思考模型建议用流式：**`kimi-k3.1-pro` 等思考模型建议设 `"stream": true`。非流式要等整段回答生成完才一次性返回，等待时间会明显更长。

<!-- section: list -->
## 07 模型列表

不确定模型名？问一下接口，比自己猜靠谱。

```bash
curl https://tokencn.299551.com/v1/models \
  -H "Authorization: Bearer sk-你的令牌"
```

```json
{
  "object": "list",
  "data": [
    {"id": "deepseek-v4.1-flash", "object": "model", "owned_by": "51token"},
    {"id": "kimi-k3", "object": "model", "owned_by": "51token"},
    ...
  ]
}
```

注意：这个接口只返回**你的令牌有权调用**的模型。如果某个模型不在这里，调用时会报「模型不存在」。

<!-- section: clients -->
## 08 客户端配置

挑出大家最常用的几款，直接照着填。

| 软件 | 怎么填 |
|---|---|
| **Cherry Studio** | 设置 → 模型服务 → **OpenAI** → API 地址填 `https://tokencn.299551.com`，密钥填 `sk-`，在「模型」里手动添加 `deepseek-v4.1-flash` |
| **ChatBox** | 设置 → 模型提供方 → **OpenAI API 兼容** → API 域名 `https://tokencn.299551.com/v1`，API 密钥填 `sk-`，模型名自己输 |
| **NextChat / ChatGPT-Next-Web** | 设置 → 自定义接口 → 接口地址 `https://tokencn.299551.com`，API Key 填 `sk-`，自定义模型名 `deepseek-v4.1-flash` |
| **LobeChat** | 设置 → 语言模型 → OpenAI → 代理地址 `https://tokencn.299551.com/v1`，填入密钥，模型列表选自定义 |
| **Cline / Roo Code** | API Provider 选 **OpenAI Compatible** → Base URL `https://tokencn.299551.com/v1` → API Key → Model ID `deepseek-v4-pro` |
| **Cursor** | Settings → Models → OpenAI API Key 填 `sk-` → Override OpenAI Base URL 填 `https://tokencn.299551.com/v1` → 点 Verify |
| **Continue (VS Code)** | `config.json` 里 models 增加一项：`"provider": "openai"`、`"apiBase": "https://tokencn.299551.com/v1"`、`"model": "deepseek-v4.1-flash"` |
| **Dify** | 设置 → 模型供应商 → **OpenAI-API-compatible** → Base URL `https://tokencn.299551.com/v1` → API Key → 模型名手填 |
| **沉浸式翻译** | 翻译服务 → **OpenAI** → 自定义 API 接口 `https://tokencn.299551.com/v1/chat/completions`（这里是完整地址），模型名从 [模型参数](https://tokencn.299551.com/models) 页复制 |

> **注意这个坑：**大部分软件的「API 地址」要写到 `/v1`；但沉浸式翻译、少数老软件要求填**完整路径** `/v1/chat/completions`。报 404 时，先试试补上或去掉 `/chat/completions`。

<!-- section: sdk -->
## 09 代码示例

官方 OpenAI SDK 原样可用，只改 base_url 和 key。

```python Python
from openai import OpenAI

client = OpenAI(
    base_url="https://tokencn.299551.com/v1",
    api_key="sk-你的令牌",
)

resp = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "用一句话解释什么是向量数据库"}],
)
print(resp.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "写一首关于秋天的短诗"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

```javascript Node.js
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://tokencn.299551.com/v1",
  apiKey: "sk-你的令牌",
});

const resp = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);
```

```go Go
package main

import (
	"context"
	"fmt"

	"github.com/sashabaranov/go-openai"
)

func main() {
	cfg := openai.DefaultConfig("sk-你的令牌")
	cfg.BaseURL = "https://tokencn.299551.com/v1"
	c := openai.NewClientWithConfig(cfg)

	resp, err := c.CreateChatCompletion(context.Background(),
		openai.ChatCompletionRequest{
			Model: "deepseek-v4.1-flash",
			Messages: []openai.ChatCompletionMessage{
				{Role: openai.ChatMessageRoleUser, Content: "你好"},
			},
		})
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Choices[0].Message.Content)
}
```

```bash cURL
curl https://tokencn.299551.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

> **直接复用官方 SDK 的好处：**重试、超时、并发、流式解析全都自带，不用自己写 HTTP。只要 SDK 支持自定义 `base_url`，就能接。

<!-- section: billing -->
## 10 计费说明

- **按 token 计费**，输入和输出分别按[模型参数](https://tokencn.299551.com/models)页的单价计算，无最低消费。
- **全站以人民币计价**：余额、扣费记录和报错里的金额都是人民币（¥）。
- **缓存命中更便宜**：相同前缀的重复请求，缓存部分按更低的缓存价计算（通常为输入价的 1–3 折）。
- **实时查账**：控制台「[使用日志](https://tokencn.299551.com/usage-logs)」页能看到每次请求的模型、token 数和扣费金额。

> **省钱的三条实测经验：** 1. 先问「一句话回答」时设 `max_tokens: 200`，能砍掉大量无意义的废话输出。 2. 批量任务（打标签、分类、抽取）按[场景推荐](https://tokencn.299551.com/models?scene=batch)选单价低的模型。 3. `deepseek-v4-pro` 的低峰价是高峰的一半，定时任务挪到晚上跑。

<!-- section: tips -->
## 11 使用建议

- **按场景选模型**：见 [模型参数 · 按场景推荐](https://tokencn.299551.com/models?scene=cs)，每个场景给出推荐和备选。
- **思考模型请开 `stream=true`**：本站模型默认都会先思考再回答，非流式要等整段回答生成完才返回；开流式能更早看到输出（见[流式输出](https://tokencn.299551.com/docs/#stream)）。
- **思考内容计入输出 token**：需要短回答的任务，请在提示词里要求「简短作答」。
- **`az-glm-5.3` 的 `max_tokens` 建议设到 4000 以上**，否则可能全部用在思考上、没有正文。
- **部分模型按时段计价**（deepseek-v4-pro、deepseek-v4.1-flash），价格以[模型参数](https://tokencn.299551.com/models)页实时显示为准。

<!-- section: errors -->
## 12 错误码

对照这张表，90% 的问题能自己解决。

| 状态码 | 返回信息 | 原因与处理 |
|---|---|---|
| `401` | `Invalid token` | 密钥错误。检查是否漏了 `sk-` 前缀、是否有空格换行、令牌是否被禁用 |
| `401` | `无效的令牌` | 令牌已删除或过期，重新创建一个 |
| `403` | `无权访问该模型` | 令牌设了模型限制，或你的账号暂未开通该模型 |
| `404` | `Invalid URL` | 路径不对。Base URL 应为 `https://tokencn.299551.com/v1`，别重复拼 `/v1` |
| `400` | `model not found` | 模型名拼错。调 `/v1/models` 看准确 ID，注意大小写和连字符 |
| `429` | `负载已饱和，请稍后再试` | 瞬时并发太高，等 2–5 秒重试；或换 `az-` 前缀的备用线路 |
| `403` | `Insufficient user quota, remaining quota: ¥… Not enough quota to pre-consume for this request: …` | 账户余额不足，补足余额后重试 |
| `403` | `token quota is not enough, token remain quota: …` | 这个令牌设的额度用完了（账户可能还有余额）。到令牌页调高额度或改成不限 |
| `500` | `No available channel` | 该模型暂时没有可用线路。换模型，或联系管理员 |
| `503` | `service unavailable` | 服务临时故障，自动重试即可，一般几十秒内恢复 |

所有错误都返回统一结构，方便程序统一处理：

```json
{
  "error": {
    "message": "Invalid token (request id: 20261119082559897...)",
    "type": "new_api_error",
    "code": ""
  }
}
```

> 报错里的 **request id** 是排查凭证。联系客服时贴这一串，比描述半天问题有用得多。

<!-- section: faq -->
## 13 常见问题

**填好了但报 404，怎么回事？**

九成是路径重复或缺失。**Base URL 只写到 `/v1`**，例如 `https://tokencn.299551.com/v1`。如果你的软件要求填完整地址，那就填 `https://tokencn.299551.com/v1/chat/completions`。两种写法不能混着来。

**报 401 Invalid token，密钥明明是对的**

按顺序检查三件事：一、`sk-` 前缀有没有一起复制；二、粘贴时是不是带进了空格或换行；三、这个令牌在控制台里是不是「已启用」状态。三条都没问题就重建一个令牌试试。

**不知道该选哪个模型？**

打开[模型参数](https://tokencn.299551.com/models)页，顶部选使用场景（智能客服、运营分析、营销文案、长文档、代码、批量任务、复杂推理），会给出推荐和备选，卡片上有实测首字、出字速度和实时价。质量没有做过分场景测评，建议先用少量数据试用。

**模型名到底该填什么？**

严格照抄本文第 03 节的 ID，比如 `deepseek-v4.1-flash`，不能写成 `DeepSeek-V4.1-Flash`，也不要带引号。不确定就调 `/v1/models` 拿准确列表。

**流式输出没反应 / 一次性全蹦出来**

两个原因：一是请求里没设 `"stream": true`；二是中间有代理或 Nginx 缓冲了响应。自己部署的网关记得关掉 `proxy_buffering`。用官方 SDK 的话这些都不用管。

**多轮工具调用（function calling）报 400，怎么传？**

**用 `/v1/chat/completions` 时**，请按 Chat 的格式续接：把模型返回的那条 `assistant` 消息（含 `tool_calls`）原样放回 `messages`，再追加一条 `role: "tool"` 的消息，用 `tool_call_id` 对上那次调用的 `id`，`content` 填函数的执行结果。如果在这个接口里按 Responses 的格式续接（发 `function_call_output` 条目或带 `previous_response_id`），会返回 400：

```text
function_call_output requires item_reference ids matching each call_id on HTTP requests; continuation via previous_response_id is only supported on Responses WebSocket v2
```

正确的续接写法（第二轮请求，实测返回 200）：

```json
{
  "model": "deepseek-v4.1-flash",
  "messages": [
    {"role": "user", "content": "北京现在天气怎么样？"},
    {"role": "assistant", "content": null, "tool_calls": [
      {"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"北京\"}"}}
    ]},
    {"role": "tool", "tool_call_id": "call_1", "content": "{\"weather\": \"晴\", \"temp\": 12}"}
  ],
  "tools": [{"type": "function", "function": {"name": "get_weather", "description": "查询城市天气",
    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]
}
```

**用 `/v1/responses` 时**，`tools` 里的函数名不合法或有重名，会返回 400「the tool name is invalid or duplicated」，请检查每个函数的 `name`，不要重复。

**能传图片让模型看吗？**

目前上架的 11 个模型都是纯文本模型，不支持图片和文件输入。传图会报参数错误。

**响应很慢，是不是接口有问题？**

先看控制台「使用日志」页那次请求的耗时。如果普遍在 3 秒内首字节，属于正常网络往返；如果某个模型特别慢，换它的另一条线路（`az-` 前缀）试试；思考模型请开 `stream=true`。程序里建议把超时设到 **60 秒以上**，推理类模型的长回答经常超过 30 秒。

**怎么知道花了多少钱？**

控制台首页看余额，「使用日志」页看每一笔明细，含模型、token 数、扣费。

**一个密钥能在几台设备上用？**

不限设备数，同一个 `sk-` 可以到处填。但并发请求会共享同一个令牌的限流额度，设备多的话建议每台建一个，方便单独排查和禁用。
