接入信息

正式地址	https://www.shaqma.com（本机 hosts 劫持 + 自签证书，仅本机可访问）
Base URL	http://localhost:3000/v1
认证方式	Authorization: Bearer sk-你的密钥（个人 API Key；管理接口还要求 admin 角色）
模型 ID	Shaqma-Pro（增强版：-Search / -Agent / -DeepSearch 后缀，仅 :3001/域名网关）
协议	OpenAI Chat Completions 兼容

对话补全 POST /v1/chat/completions

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "Shaqma-Pro",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

Python 示例

from openai import OpenAI
client = OpenAI(base_url="http://localhost:3000/v1", api_key="sk-你的密钥")
resp = client.chat.completions.create(
    model="Shaqma-Pro",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

联网搜索 / Agent / 深度查找（应用层增强，走 :3001）

在模型 ID 后加后缀即可获得增强能力。增强路由在应用层网关 http://localhost:3001/v1（也可走 https://www.shaqma.com/v1，计费与日志仍计入 new-api）：

模型 ID	能力	说明
Shaqma-Pro	纯对话	裸模型，:3000 / :3001 网关均可调用
Shaqma-Pro-Search	联网搜索	服务端自动搜索 Bing（关键词清洗 + 逐级截短回退），实时结果注入后作答，附来源链接
Shaqma-Pro-Agent	Agent 工具	模型自主多轮调用工具：联网搜索、网页抓取、PowerShell 命令执行、文件读写（最多 5 轮）
Shaqma-Pro-DeepSearch	深度查找	多关键词交叉检索 + 精读网页正文，过程静默只输出综合结论

curl https://www.shaqma.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "Shaqma-Pro-DeepSearch",
    "messages": [{"role": "user", "content": "DDR5 内存价格走势"}],
    "stream": false
  }'

聊天页输入框上方有「联网搜索」「Agent 模式」「深度查找」开关；Playground 直接选带后缀的模型即可。外部模型（OpenAI/DeepSeek/Kimi/MiMo）在「模型广场 → 添加模型」接入后，同样支持 -Search/-Agent/-DeepSearch 后缀。

客户端接入

客户端	配置
Hermes Agent	Provider 类型 OpenAI 兼容，Base URL http://localhost:3000/v1，模型名填 Shaqma-Pro
OpenClaw / Claude Code 类	Anthropic 协议客户端需经协议转换层（opencodex 代理 localhost:10100），或选用支持 OpenAI 协议的客户端直连
其他 OpenAI 客户端	填 Base URL + API Key + 模型 ID Shaqma-Pro 即可

鉴权与密钥

需要身份的业务接口统一用 Authorization: Bearer sk-…（个人 API Key）；管理接口还要求账号角色为 admin。浏览器里登录后走会话 Cookie，不用手动填 Key。

怎么拿 Key	说明
平台页面	开放平台 →「API 密钥」→ 创建新 Key。密钥只显示这一次，请立即保存
接口创建	POST /api/me/keys，body {"name":"我的key"} → 返回 {key, notice}
查看 / 删除	GET /api/me/keys ｜ DELETE /api/me/keys/:id

对话补全 POST /v1/chat/completions —— 请求参数

参数	类型	必填	说明
model	string	是	模型 ID，如 Shaqma-Pro；可带增强后缀（见下表）
messages	array	是	[{"role":"user","content":"你好"}]，role 支持 system/user/assistant
stream	bool	否	true = SSE 流式（data: {...} 帧，末尾 data: [DONE]）；默认 false
temperature	number	否	采样温度，默认按模型
max_tokens	int	否	输出上限
tools	array	否	OpenAI 工具协议（配合 -Agent 后缀时服务端还会自带联网/抓网页等工具）

示例见上方「对话补全」（curl）与「Python 示例」。

其他 /v1 接口

方法 / 路径	说明
GET /v1/models	可用模型列表（带 input_price/output_price/locked/min_plan）；GET /api/models?all=1 可看到被套餐锁住的模型
POST /v1/completions	文本补全（OpenAI 兼容）
POST /v1/embeddings	向量嵌入（上游支持时可用）
POST /api/chat	应用层对话（见下方「应用层流式对话」）：支持 -Search/-Agent/-DeepSearch 全部增强能力，响应 text/event-stream

应用层流式对话 POST /api/chat

参数	类型	说明
messages	array	同 /v1（必填）
model	string	模型 ID，默认 Shaqma-Pro；可带 -Search/-Agent/-DeepSearch 后缀，服务端会自动切模式
temperature	number	采样温度
conversation_id	string	会话 ID（用于服务端记录与记忆库关联）
search / agent / deepsearch	bool	等效于加后缀的增强开关（三选一）
think	bool	强制深度思考（升级 reasoner）
image_url	string	带图提问（图片描述/理解）

响应 Content-Type: text/event-stream，帧格式与 /v1 一致（data: {...}，末尾 data: [DONE]），可直接用 OpenAI SDK 的流式解析器读取。

账号接口

方法 / 路径	参数	说明
POST /api/auth/register	username, password, accepted_terms	注册（新用户送初始额度）
POST /api/auth/login	username, password	登录，返回会话 Cookie
POST /api/auth/logout	—	退出登录
GET /api/auth/me	—	当前用户（用户名/套餐/余额）
POST /api/auth/password	old_password, new_password	改密码（需登录）
POST /api/auth/redeem	code	兑换码充值（SQ- 开头）
POST /api/auth/guest	—	访客临时身份
POST /api/auth/consent	—	记录条款同意
GET /api/config	—	品牌名 / 默认模型 / 是否需要登录

会话同步与我的用量

方法 / 路径	参数	返回
GET /api/chats	—	{chats:[…], updated_at} 云端会话副本（多端共享）
PUT /api/chats	chats（数组，≤500 条、≤6MB）	{ok, updated_at}
GET /api/me/usage	—	总用量 + 近 30 天按日 + 按模型 + 最近 100 条明细（含 token 与费用）
GET /api/me/context	—	上下文容量使用率（容量 1000 万 token）+ 全文检索状态
GET /api/personas / POST / DELETE /:id	name, prompt, desc, icon	自定义人格（预设角色）

平台数据接口（开放平台页用，需登录）

方法 / 路径	参数	说明
GET /platform/api/overview	—	总览：余额/套餐/调用量/消耗
GET /platform/api/usage/daily	days（≤90，默认 7）	按日用量
GET /platform/api/usage/by-model	days	按模型用量
GET /platform/api/usage/by-key	days（默认 30）	按 Key 用量
GET /platform/api/logs	p（页码）、size（≤100，默认 20）	调用日志（分页）
GET /platform/api/models	—	模型广场（含定价与套餐门槛）
GET /platform/api/keys / POST / DELETE /:id	name	Key 管理
POST /platform/api/keys/:id/speedtest	—	Key 连通性与延迟测试（admin）
GET /platform/api/chain-health	—	链路健康（中转站/上游可用性）
GET /platform/api/memories / POST / DELETE /:id / POST toggle	content ｜ id, enabled	记忆库（长期记忆条目）
GET /api/memories/sync	since（时间戳）	增量同步记忆（客户端记忆库）
GET /platform/api/skills / POST toggle / GET market / POST install	name, enabled ｜ id	Skill 配置中心（联网搜索/阅读网页/执行命令等开关）
GET /platform/api/downloads	—	下载中心清单
GET /platform/api/providers / POST / DELETE /:id	provider, baseUrl, apiKey, models, name	上游供应商接入（admin）
GET /platform/api/admin/stats · users(q) · codes · prices	— ｜ amount, count, batch ｜ model, input_price, output_price, min_plan	管理后台：统计 / 用户（改套餐·余额·状态·重置密码）/ 兑换码 / 模型定价（admin）
POST /platform/api/settings/dirs	—	记忆库目录设置（admin）

扩展能力接口

方法 / 路径	参数	说明
POST /api/image/generate	prompt, negative, width, height, steps, cfg, seed	文生图
POST /api/image/video	prompt, image_url, seconds	图/文生视频
POST /api/image/describe	url, question	图片理解（看图答题）
POST /api/upload/image	data（base64）	上传图片取回可访问 URL
POST /api/asr	audio（base64 音频）	语音识别（转文字）
POST /api/tts	text, voice（默认 zh-CN-XiaoxiaoNeural）, rate（如 +0%）	语音合成（返回音频，带缓存）
POST /api/3d/generate	prompt（≤500 字）	3D 建模生成（返回单文件 HTML，含画质自检）
POST /api/game3d/generate	prompt（≤500 字）	3D 游戏生成（返回 HTML + 体积/耗时/重试次数）
GET /api/image/health	—	图像/视频服务健康状态
GET /api/app/version	—	桌面/安卓客户端版本（App 用它判断是否要更新）

错误码

状态码	含义	响应体示例
400	参数错误	{"error":{"message":"…"}}
401	未认证 / Key 无效	{"error":{"message":"invalid api key"}}
402	余额/额度不足	{"error":{"message":"…","type":"billing_error"}}
403	套餐/角色不够	{"error":{"message":"…","type":"permission_error","need_plan":"vip"}}
404	对象不存在（如 Key 已删）	{"error":{"message":"key 不存在"}}
500	服务端异常	{"error":{"message":"…"}}
502	上游/中转站不可达	{"error":{"message":"无法连接中转站: …"}}

额度与计费

计费方式	按 token 计费（输入/输出分别定价），每次调用写一条用量日志；GET /api/me/usage 可查明细
模型价格	GET /v1/models 的 input_price/output_price 字段；管理端可在「模型定价」里改
套餐门槛	模型带 min_plan，不满足时调用返回 403（need_plan 告诉你要哪档）
速率限制	本服务为自用部署，未启用速率限制；实际门槛是余额（402）与套餐（403）
上下文容量	每账号 1000 万 token 虚拟上下文（全文检索），用 GET /api/me/context 看使用率

端点总览（一眼版）

分类	端点
OpenAI 兼容	GET /v1/models ｜ POST /v1/chat/completions ｜ POST /v1/completions ｜ POST /v1/embeddings
应用层增强	POST /api/chat（SSE）｜模型后缀 -Search / -Agent / -DeepSearch
账号	/api/auth/register|login|logout|me|password|redeem|guest|consent
我的数据	/api/me/keys ｜ /api/chats ｜ /api/me/usage ｜ /api/me/context ｜ /api/personas
平台面板	/platform/api/overview|usage/*|logs|models|keys|chain-health|memories|skills|downloads|providers|admin/*|settings/dirs
多模态	/api/image/generate|video|describe|upload ｜ /api/asr ｜ /api/tts ｜ /api/3d/generate ｜ /api/game3d/generate