API 文档
GSH API 完全兼容 OpenAI 接口规范。如果你的项目已经在使用 OpenAI SDK 或任何兼容 OpenAI 协议的工具,只需替换 base_url 与 api_key 即可切换到国产大模型,业务代码无需任何改动。
简介
平台在你的应用与上游大模型厂商之间提供统一网关,负责协议转换、渠道路由、故障切换、限速保护与用量计量。你只需要面对一个接口地址和一个密钥。
- 统一协议:全部模型统一以 OpenAI Chat Completions 格式调用
- 统一密钥:一个
sk-gsh-Key 覆盖 DeepSeek、通义千问、Kimi、豆包、GLM 等全部模型 - 模型切换:仅通过请求体的
model字段切换,不需要更换 endpoint 或密钥 - 境内直连:服务节点部署在境内,无需代理,链路延迟低于 100ms
鉴权方式
所有请求需要在 HTTP Header 中携带 Bearer Token。API Key 在订阅开通后签发,格式为 sk-gsh- 开头的字符串。
Authorization: Bearer sk-gsh-xxxxxxxxxxxxxxxxxxxx Content-Type: application/json
接入地址
| 接口 | 路径 | 说明 |
|---|---|---|
| 对话补全 | POST /v1/chat/completions | 核心接口,支持全部对话模型 |
| 向量嵌入 | POST /v1/embeddings | 文本向量化,用于 RAG 检索 |
| 模型列表 | GET /v1/models | 查询当前 Key 可调用的模型 |
| 额度查询 | GET /v1/dashboard/billing/subscription | 查询套餐额度与已用量 |
对话补全
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 必填 | 模型名称,如 deepseek-chat、qwen-plus |
messages | array | 必填 | 对话消息列表,每项含 role 与 content |
stream | boolean | 选填 | 是否流式返回,默认 false |
temperature | number | 选填 | 随机性 0~2,默认 1,越低越确定 |
max_tokens | integer | 选填 | 限制生成的最大 token 数 |
top_p | number | 选填 | 核采样阈值 0~1,与 temperature 二选一 |
tools | array | 选填 | 工具/函数定义,见 Function Call |
response_format | object | 选填 | 设为 {"type":"json_object"} 强制 JSON 输出 |
stop | string / array | 选填 | 遇到指定字符串时停止生成 |
请求示例
curl https://api.gshpay.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-gsh-xxxxxxxxxxxxxxxx" \ -d '{ "model": "deepseek-chat", "messages": [ {"role": "system", "content": "你是一个专业的技术助手。"}, {"role": "user", "content": "解释一下什么是向量数据库"} ], "temperature": 0.7, "max_tokens": 1024 }'
响应示例
{
"id": "chatcmpl-8xk29fjs02mfk",
"object": "chat.completion",
"created": 1785600000,
"model": "deepseek-chat",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "向量数据库是专门用于存储和检索高维向量的数据库……"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 216,
"total_tokens": 244
}
}流式输出
设置 stream: true 后,服务端以 SSE(Server-Sent Events)逐块推送增量内容,格式与 OpenAI 完全一致,最后以 data: [DONE] 结束。
from openai import OpenAI client = OpenAI( base_url="https://api.gshpay.com/v1", api_key="sk-gsh-xxxxxxxxxxxxxxxx" ) stream = client.chat.completions.create( model="qwen-plus", messages=[{"role": "user", "content": "写一首关于深圳的短诗"}], stream=True ) for chunk in stream: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True)
Function Call / Tools
工具调用参数遵循 OpenAI 规范透传到上游模型。DeepSeek、通义千问、Kimi、GLM、豆包均支持工具调用能力。
const res = await client.chat.completions.create({ model: 'glm-4-plus', messages: [{ role: 'user', content: '深圳今天天气怎么样?' }], tools: [{ type: 'function', function: { name: 'get_weather', description: '查询指定城市的实时天气', parameters: { type: 'object', properties: { city: { type: 'string', description: '城市名称,如:深圳' } }, required: ['city'] } } }], tool_choice: 'auto' }); // 模型返回 tool_calls 后,执行本地函数并将结果以 role:'tool' 回传 console.log(res.choices[0].message.tool_calls);
多模态视觉
视觉模型(doubao-vision-pro、qwen-vl-max、glm-4v)支持图文混合输入,content 传数组形式,图片可用 URL 或 base64。
resp = client.chat.completions.create( model="doubao-vision-pro", messages=[{ "role": "user", "content": [ {"type": "text", "text": "这张图里有什么?"}, {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}} ] }] ) print(resp.choices[0].message.content)
向量嵌入
curl https://api.gshpay.com/v1/embeddings \ -H "Authorization: Bearer sk-gsh-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "text-embedding-v3", "input": ["深圳市湘港湾科技有限公司", "大模型 API 中转"] }'
可用嵌入模型:text-embedding-v3(通义,1024 维)、embedding-3(智谱,2048 维)、bge-large-zh(中文检索优化)。
查询可用模型
curl https://api.gshpay.com/v1/models \ -H "Authorization: Bearer sk-gsh-xxxxxxxxxxxxxxxx"
可用模型
| 厂商 | 模型名称 | 上下文 | 能力 |
|---|---|---|---|
| 深度求索 | deepseek-chat | 128K | 通用对话 · 工具调用 |
| 深度求索 | deepseek-reasoner | 128K | 深度推理 · 数学代码 |
| 阿里云 | qwen-max | 32K | 最强综合能力 |
| 阿里云 | qwen-plus | 128K | 均衡性价比 |
| 阿里云 | qwen-turbo | 1M | 超长文本 · 低成本 |
| 阿里云 | qwen-vl-max | 32K | 视觉理解 |
| 月之暗面 | kimi-k2-0905-preview | 256K | Agent 能力强 |
| 月之暗面 | moonshot-v1-128k | 128K | 长文档处理 |
| 字节跳动 | doubao-pro-32k | 32K | 高并发 · 低延迟 |
| 字节跳动 | doubao-lite-32k | 32K | 极致低成本 |
| 字节跳动 | doubao-vision-pro | 32K | 视觉理解 |
| 智谱 AI | glm-4-plus | 128K | 旗舰综合能力 |
| 智谱 AI | glm-4-air | 128K | 高性价比 |
| 智谱 AI | glm-4-flash | 128K | 极速响应 |
| MiniMax | abab6.5s-chat | 245K | 角色扮演 · 长对话 |
| 百度 | ernie-4.0-turbo | 128K | 中文理解优化 |
| 百度 | ernie-speed-128k | 128K | 快速响应 |
GET /v1/models 获取实时可用列表。模型倍率表
套餐内 Token 额度按倍率折算扣减,扣减量 = total_tokens × 倍率。
| 倍率 | 模型 | 说明 |
|---|---|---|
0.3× | glm-4-flash、ernie-speed-128k、doubao-lite-32k | 轻量模型,额度消耗最低 |
1× | deepseek-chat、qwen-turbo、glm-4-air、doubao-pro-32k | 标准倍率基准 |
3× | deepseek-reasoner、qwen-plus、kimi-k2-0905-preview | 推理增强 / 中高端模型 |
8× | qwen-vl-max、doubao-vision-pro、glm-4v | 多模态视觉模型 |
15× | qwen-max、moonshot-v1-128k、abab6.5s-chat | 旗舰长文本模型 |
30× | glm-4-plus、ernie-4.0-turbo | 顶配旗舰模型 |
速率限制
| 套餐 | RPM(请求/分钟) | 并发保障 | 单请求超时 |
|---|---|---|---|
| 体验版 | 20 | — | 120s |
| 标准版 | 500 | ✓ | 300s |
| 专业版 | 2000 | ✓ 优先调度 | 600s |
| 企业版 | 不限 | ✓ 独享渠道 | 可定制 |
触发限速时返回 429,建议客户端实现指数退避重试。Header 中会返回剩余配额信息:
X-RateLimit-Limit-Requests: 500 X-RateLimit-Remaining-Requests: 487 X-RateLimit-Reset-Requests: 6s
错误码
| 状态码 | error.code | 原因与处理 |
|---|---|---|
400 | invalid_request_error | 参数格式错误或缺失必填字段,检查请求体 |
401 | invalid_api_key | API Key 无效、已吊销或格式错误 |
403 | model_not_allowed | 当前 Key 无权调用该模型,检查模型白名单 |
404 | model_not_found | 模型名称不存在,通过 /v1/models 核对 |
402 | insufficient_quota | 套餐额度已用尽,需升级套餐或开启按量计费 |
429 | rate_limit_exceeded | 超出 RPM 限制,退避后重试或升级套餐 |
500 | internal_error | 网关内部错误,可直接重试 |
503 | upstream_unavailable | 上游全部渠道不可用,稍后重试或联系支持 |
504 | upstream_timeout | 上游响应超时,建议缩短 prompt 或改用流式 |
{
"error": {
"message": "当前套餐额度已用尽,请升级套餐或开启按量计费",
"type": "insufficient_quota",
"code": "insufficient_quota",
"param": null
}
}生态工具接入
任何支持自定义 OpenAI 兼容端点的工具都可以直接接入,只需在设置中填入以下两项:
| 工具 | 配置位置 | 填写内容 |
|---|---|---|
| Dify | 模型供应商 → OpenAI-API-compatible | API Base: https://api.gshpay.com/v1 |
| Cherry Studio | 设置 → 模型服务 → 添加提供商 | 类型选 OpenAI,地址填 https://api.gshpay.com |
| LangChain | ChatOpenAI(base_url=...) | base_url="https://api.gshpay.com/v1" |
| Cursor | Settings → Models → Override base URL | https://api.gshpay.com/v1 |
| OneAPI / NewAPI | 渠道 → 新建 → 类型 OpenAI | 代理地址 https://api.gshpay.com |
| Chatbox / LobeChat | 设置 → OpenAI → 接口代理地址 | https://api.gshpay.com/v1 |
/v1 后缀。如果调用返回 404,请检查最终请求路径是否变成了 /v1/v1/chat/completions,去掉重复的 /v1 即可。
下一步
还没有 API Key?前往 订阅套餐 页面提交申请,新用户可领取 100 万 Token 免费额度。接入过程中遇到问题,可发邮件至 1195859@qq.com,我们在服务时间内会尽快响应。