API 文档

GSH API 完全兼容 OpenAI 接口规范。如果你的项目已经在使用 OpenAI SDK 或任何兼容 OpenAI 协议的工具,只需替换 base_urlapi_key 即可切换到国产大模型,业务代码无需任何改动。

简介

平台在你的应用与上游大模型厂商之间提供统一网关,负责协议转换、渠道路由、故障切换、限速保护与用量计量。你只需要面对一个接口地址和一个密钥。

鉴权方式

所有请求需要在 HTTP Header 中携带 Bearer Token。API Key 在订阅开通后签发,格式为 sk-gsh- 开头的字符串。

请求头
Authorization: Bearer sk-gsh-xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
安全提醒:API Key 等同于账户凭证,请勿硬编码在前端代码、移动端 App 或公开仓库中。建议通过服务端环境变量注入,并为不同环境创建独立的子 Key。如发生泄露,可在控制台立即吊销并重新签发。

接入地址

BASE https://api.gshpay.com/v1
接口路径说明
对话补全POST /v1/chat/completions核心接口,支持全部对话模型
向量嵌入POST /v1/embeddings文本向量化,用于 RAG 检索
模型列表GET /v1/models查询当前 Key 可调用的模型
额度查询GET /v1/dashboard/billing/subscription查询套餐额度与已用量

对话补全

POST https://api.gshpay.com/v1/chat/completions

请求参数

参数类型必填说明
modelstring必填模型名称,如 deepseek-chatqwen-plus
messagesarray必填对话消息列表,每项含 rolecontent
streamboolean选填是否流式返回,默认 false
temperaturenumber选填随机性 0~2,默认 1,越低越确定
max_tokensinteger选填限制生成的最大 token 数
top_pnumber选填核采样阈值 0~1,与 temperature 二选一
toolsarray选填工具/函数定义,见 Function Call
response_formatobject选填设为 {"type":"json_object"} 强制 JSON 输出
stopstring / array选填遇到指定字符串时停止生成

请求示例

cURLPOST
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
  }'

响应示例

Response200 OK
{
  "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
  }
}
关于计费:响应中的 usage.total_tokens 即本次调用的计量基数,实际扣减额度 = total_tokens × 模型倍率。倍率见下方模型倍率表

流式输出

设置 stream: true 后,服务端以 SSE(Server-Sent Events)逐块推送增量内容,格式与 OpenAI 完全一致,最后以 data: [DONE] 结束。

Python · 流式stream
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、豆包均支持工具调用能力。

Node.js · 工具调用tools
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-proqwen-vl-maxglm-4v)支持图文混合输入,content 传数组形式,图片可用 URL 或 base64。

Python · 图片理解vision
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)

向量嵌入

POST https://api.gshpay.com/v1/embeddings
cURL · EmbeddingsPOST
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(中文检索优化)。

查询可用模型

GET https://api.gshpay.com/v1/models
cURLGET
curl https://api.gshpay.com/v1/models \
  -H "Authorization: Bearer sk-gsh-xxxxxxxxxxxxxxxx"

可用模型

厂商模型名称上下文能力
深度求索deepseek-chat128K通用对话 · 工具调用
深度求索deepseek-reasoner128K深度推理 · 数学代码
阿里云qwen-max32K最强综合能力
阿里云qwen-plus128K均衡性价比
阿里云qwen-turbo1M超长文本 · 低成本
阿里云qwen-vl-max32K视觉理解
月之暗面kimi-k2-0905-preview256KAgent 能力强
月之暗面moonshot-v1-128k128K长文档处理
字节跳动doubao-pro-32k32K高并发 · 低延迟
字节跳动doubao-lite-32k32K极致低成本
字节跳动doubao-vision-pro32K视觉理解
智谱 AIglm-4-plus128K旗舰综合能力
智谱 AIglm-4-air128K高性价比
智谱 AIglm-4-flash128K极速响应
MiniMaxabab6.5s-chat245K角色扮演 · 长对话
百度ernie-4.0-turbo128K中文理解优化
百度ernie-speed-128k128K快速响应
完整模型列表随上游厂商发布同步更新,建议通过 GET /v1/models 获取实时可用列表。

模型倍率表

套餐内 Token 额度按倍率折算扣减,扣减量 = total_tokens × 倍率

倍率模型说明
0.3×glm-4-flash、ernie-speed-128k、doubao-lite-32k轻量模型,额度消耗最低
deepseek-chat、qwen-turbo、glm-4-air、doubao-pro-32k标准倍率基准
deepseek-reasoner、qwen-plus、kimi-k2-0905-preview推理增强 / 中高端模型
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(请求/分钟)并发保障单请求超时
体验版20120s
标准版500300s
专业版2000✓ 优先调度600s
企业版不限✓ 独享渠道可定制

触发限速时返回 429,建议客户端实现指数退避重试。Header 中会返回剩余配额信息:

Response Headers
X-RateLimit-Limit-Requests: 500
X-RateLimit-Remaining-Requests: 487
X-RateLimit-Reset-Requests: 6s

错误码

状态码error.code原因与处理
400invalid_request_error参数格式错误或缺失必填字段,检查请求体
401invalid_api_keyAPI Key 无效、已吊销或格式错误
403model_not_allowed当前 Key 无权调用该模型,检查模型白名单
404model_not_found模型名称不存在,通过 /v1/models 核对
402insufficient_quota套餐额度已用尽,需升级套餐或开启按量计费
429rate_limit_exceeded超出 RPM 限制,退避后重试或升级套餐
500internal_error网关内部错误,可直接重试
503upstream_unavailable上游全部渠道不可用,稍后重试或联系支持
504upstream_timeout上游响应超时,建议缩短 prompt 或改用流式
错误响应格式4xx / 5xx
{
  "error": {
    "message": "当前套餐额度已用尽,请升级套餐或开启按量计费",
    "type": "insufficient_quota",
    "code": "insufficient_quota",
    "param": null
  }
}

生态工具接入

任何支持自定义 OpenAI 兼容端点的工具都可以直接接入,只需在设置中填入以下两项:

工具配置位置填写内容
Dify模型供应商 → OpenAI-API-compatibleAPI Base: https://api.gshpay.com/v1
Cherry Studio设置 → 模型服务 → 添加提供商类型选 OpenAI,地址填 https://api.gshpay.com
LangChainChatOpenAI(base_url=...)base_url="https://api.gshpay.com/v1"
CursorSettings → Models → Override base URLhttps://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,我们在服务时间内会尽快响应。