SuMu API 使用文档

SuMu API 完全兼容 OpenAI SDK 接口格式，你可以使用任何支持 OpenAI API 的客户端或库直接接入，无需修改代码逻辑。

快速开始

1. 获取 API Key

在发卡网购买兑换码后，前往兑换页面输入兑换码，即可获得一个以 sm- 开头的 API Key。

2. 配置接入参数

API Base URL

https://your-domain.com/api/v1

API Key

sm-xxxxxxxxxxxxxxxx

Model（模型名称）

任意值或留空（自动路由）

请求方式

POST

3. 发送请求

cURL

curl https://your-domain.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sm-你的密钥" \
  -d '{
    "messages": [
      {"role": "system", "content": "你是一个有用的助手"},
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "temperature": 0.7
  }'

流式输出（Streaming）

在请求体中设置 "stream": true 即可开启流式输出，实时逐字返回生成内容。

Python (Streaming)

import openai

client = openai.OpenAI(
    api_key="sm-你的密钥",
    base_url="https://your-domain.com/api/v1"
)

stream = client.chat.completions.create(
    model="default",
    messages=[
        {"role": "user", "content": "写一首关于春天的诗"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

第三方客户端接入

SuMu API 兼容 OpenAI 接口格式，可以直接在以下客户端中使用：

ChatGPT-Next-Web

在设置中选择自定义接口，填入以上参数

Base URL: https://your-domain.com/api/v1
API Key: sm-你的密钥

LobeChat

在语言模型设置中配置 OpenAI 自定义代理

API Proxy: https://your-domain.com/api/v1
API Key: sm-你的密钥

OpenCat / BotGem

添加自定义 API 提供商，填入域名和密钥

API Domain: https://your-domain.com/api/v1
API Key: sm-你的密钥

其他 OpenAI 兼容客户端

任何支持自定义 OpenAI Base URL 的应用均可接入

Base URL: https://your-domain.com/api/v1
API Key: sm-你的密钥

请求参数

参数	类型	必填	说明
`messages`	array	是	对话消息列表，每条包含 role 和 content
`model`	string	否	模型名称，可填任意值（服务端自动路由到对应模型）
`stream`	boolean	否	是否开启流式输出，默认 false
`temperature`	number	否	采样温度 0-2，值越高回复越随机，默认 1
`max_tokens`	integer	否	最大生成 token 数
`top_p`	number	否	核采样参数，与 temperature 二选一使用

错误码说明

HTTP 状态码	错误类型	说明
`401`	auth_error	API Key 缺失、格式错误或无效
`403`	auth_error	API Key 已被禁用
`429`	quota_error	Token 额度已用尽，请购买新套餐
`400`	invalid_request	请求体 JSON 格式错误
`502`	server_error	上游服务请求失败，请稍后重试
`503`	server_error	服务暂时不可用

安全须知

•妥善保管 Key — 不要将 API Key 硬编码在前端代码或公开仓库中，建议使用环境变量管理。
•一人一 Key — 每个 Key 绑定独立的 Token 额度，请勿与他人共享。
•异常检测 — 系统会自动检测异常使用模式（如同一 Key 从多个 IP 调用），异常行为可能导致 Key 被暂停。
•额度用尽 — Token 用完后 Key 自动失效，请在控制台查看剩余额度并及时续费。

常见问题

model 参数填什么？

可以填任意值（如 "gpt-3.5-turbo"），服务端会自动路由到你账号绑定的火山引擎模型。也可以留空不填。

支持哪些 OpenAI SDK 功能？

目前支持 Chat Completions 接口（/v1/chat/completions），包括普通请求和流式输出。其他接口（如 Embeddings、Images）暂不支持。

Token 是怎么计算的？

每次请求消耗的 Token 包括输入（prompt）和输出（completion）的总和，由上游模型返回的 usage 字段统计。

可以同时使用多个 Key 吗？

可以。每个 Key 有独立的额度，互不影响。你可以购买多个套餐获取多个 Key。

请求超时怎么办？

建议设置合理的超时时间（如 60 秒）。如果频繁超时，可能是上游服务压力较大，请稍后重试。