加载中...

开发者文档 - 贵州大模型云算力 Token 平台

开发者文档

本页只覆盖对客户公开的开发者接口：推理 API、购卡/充值/查单、自助额度查询和 Key 管理。后台管理路由、支付 webhook、运维排查接口不在公开文档范围内。

接入前先看这 7 点

目前支持 OpenAI 兼容接口、OpenAI 原生 Responses、Claude 原生 Messages 三种接入方式。
大部分 OpenAI-compatible 客户端优先使用 https://gpt-agent.cc/v1/chat/completions。
在 Codex、Cherry Studio 等客户端中调用 GPT 模型时，优先使用 https://gpt-agent.cc/v1/responses。
配置 Claude Code 或 Anthropic-compatible 客户端时，优先使用 https://gpt-agent.cc/v1/messages。
多数客户端优先填 Base URL: https://gpt-agent.cc/v1；如果 /v1 校验失败，再尝试 https://gpt-agent.cc。
支持 Python、Node.js、curl 直接接入。
首购成功后自动交付首个 API Key；已有 API Key 可直接充值。

购买 API 已有 API Key？去充值

接入地址

先判断你的客户端要填的是完整接口地址，还是 Base URL；再按使用的模型和协议选择对应端点。

OpenAI 兼容接口

适配大部分 OpenAI 兼容客户端。

https://gpt-agent.cc/v1/chat/completions

大多数 OpenAI-compatible 客户端都可以直接接这个端点。
如果客户端要求填写完整接口地址，而不是 Base URL，优先用这个。

OpenAI 原生接口（Responses）

适用于 GPT 模型原生调用。

https://gpt-agent.cc/v1/responses

在 Codex、Cherry Studio 等客户端里使用 GPT 模型时，优先选择 responses 端点。
只有客户端不支持 responses 时，再退回到 chat/completions。

Claude 原生接口（Messages）

适用于 Claude 原生协议。

https://gpt-agent.cc/v1/messages

配置 Claude Code 时，优先使用 messages 端点。
Anthropic-compatible / Claude-compatible 客户端也优先走这个。

OpenAI 兼容推理 API 参考

POST/v1/chat/completions

摘要

默认推荐先按 Anthropic 协议使用 /v1/messages；本节展示的是给 OpenAI SDK 和仅支持 OpenAI 协议的客户端使用的兼容端点。

请求格式

POST /v1/chat/completions
Content-Type: application/json
Authorization: Bearer sk-your-api-key

{
  "model": "your-model-id",
  "messages": [
    { "role": "system", "content": "You are a concise assistant." },
    { "role": "user", "content": "Give me a one-line introduction." }
  ],
  "temperature": 0.7
}

字段	类型	必填	说明
`model`	string	Yes	上游模型标识符，由运行时暴露。
`messages`	array	Yes	OpenAI 格式的聊天消息数组。
`temperature`	number

多语言 SDK 示例

先用下面这些最小示例跑通，再迁移到自己的业务代码或第三方客户端。

下面示例默认演示 OpenAI 兼容的 chat/completions；如果在 Codex、Cherry Studio 中调用 GPT 模型，优先改用 responses；配置 Claude Code 时优先使用 messages。

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://gpt-agent.cc/v1"
)

response = client.chat.completions.create(
    model="your-model-id",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手。"},
        {"role": "user", "content": "用一句话介绍你自己。"}
    ]
)

print(response.choices[0].message.content)

流式输出（实时响应）示例

启用流式输出可以实时接收生成的 token，显著提升用户体验。

为什么要使用流式输出？

降低感知延迟 - 用户无需等待完整响应，可以立即看到内容
更好的长文本体验 - 内容像人类打字一样逐步显示
成本相同 - 与同步输出成本完全一致，只是传输方式不同

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://gpt-agent.cc/v1"
)

stream = client.chat.completions.create(
    model="your-model-id",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手。"},
        {"role": "user", "content": "用一句话介绍你自己。"}
    ],
    stream=True  # Enable streaming
)

# Print tokens as they arrive
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")
print()  # Newline at the end

平台 REST API 参考

下面是对客户公开的站内辅助接口，用于购买、充值、查单、额度查询和 Key 管理。

GET/api/topup/packages

鉴权: 公开

列出当前可用的固定充值套餐，适用于已有 API Key 的用户。

请求示例

GET /api/topup/packages

响应示例

{
  "ok": true,
  "data": [
    {
      "id": "pkg_100",
      "code": "topup_100",
      "name": "100 CNY package",
      "currency": "CNY",
      "priceCents": 10000,
      "baseQuotaAmount": 6000000000,
      "bonusQuotaAmount": 1000000000,
      "quotaAmount": 7000000000
    }
  ]
}

说明

使用此端点渲染公开充值选项，无需在客户端硬编码。

POST/api/purchase/orders

鉴权: 公开

为指定套餐创建首购订单并保存联系邮箱。

请求示例

{
  "email": "[email protected]",
  "planCode": "starter",
  "sourcePage": "pricing"
}

响应示例

{
  "ok": true,
  "data": {
    "orderNo": "BUY202604060930ABCD",
    "amountCents": 29900,
    "contactEmail": "[email protected]",
    "payUrl": "/pricing/pay?orderNo=BUY202604060930ABCD&contactEmail=buyer%40example.com"
  }
}

错误码对照表

推理 API

HTTP	名称	含义	处理建议
`400`	INVALID_REQUEST	JSON 格式错误、参数无效或不支持的请求格式。	检查请求体并与 OpenAI 兼容的 schema 进行对比。
`401`	UNAUTHORIZED	API Key 缺失、已过期或无效。	检查 Bearer Token 并确认 Key 仍然存在。
`429`	RATE_LIMIT	短时间内发送了过多请求。	使用退避策略重试并降低突发流量。
`500`	UPSTREAM_ERROR	上游运行时或代理返回了内部错误。	稍后重试，如问题持续请检查状态/监控。

平台 REST API

错误码	HTTP

限流说明

认证、密码重置和额度查询端点包含冷却时间和轻量级防滥用保护。
收到 429 响应时应视为可重试，并在客户端使用指数退避策略。
对于结账 API，在网络故障后重试创建订单时请复用相同的 x-idempotency-key。
突发流量和脚本化重试应在客户端进行限流，以避免临时封禁。

模型与定价

模型可用性

模型可用性由上游 newAPI / CLI 代理运行时管理，因此具体模型列表可能独立于本站变化。
调用 /v1/chat/completions 时请使用上游运行时暴露的模型 ID。
下方价格表描述的是本站销售的购买和充值套餐，而非按模型的 Token 计费。

当前套餐定价

类型	套餐	价格	原额度	赠送	到账总额	说明
购买	10 元首购套餐	¥10.00	0.25B	0B	0.25B	首购套餐，支付后自动配发初始 API Key。
购买	20 元首购套餐	¥20.00	0.5B	0B	0.5B	首购套餐，支付后自动配发初始 API Key。

成功响应格式

{
  "id": "chatcmpl_01JEXAMPLE",
  "object": "chat.completion",
  "created": 1712380800,
  "model": "your-model-id",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "This endpoint is compatible with the OpenAI chat format."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 16,
    "total_tokens": 37
  }
}

字段	类型	说明
`id`	string	唯一的补全标识符。
`choices`	array	返回的候选补全结果。
`choices[].message`	object	助手回复内容。
`usage`	object	提示词、补全和总 Token 计数。
`model`	string	请求使用的模型 ID。

POST/api/purchase/orders/pay

鉴权: 公开

为已有的首购订单准备支付会话。

请求示例

{
  "orderNo": "BUY202604060930ABCD",
  "contactEmail": "[email protected]"
}

响应示例

{
  "ok": true,
  "data": {
    "orderNo": "BUY202604060930ABCD",
    "provider": "xunhupay",
    "checkoutUrl": "https://pay.example.com/checkout/abc",
    "qrcodeUrl": "https://pay.example.com/qrcode/abc"
  }
}

说明

使用订单创建时返回的订单号和联系邮箱。

POST/api/purchase/orders/query

鉴权: 公开

通过订单号和联系邮箱查询首购订单。

请求示例

{
  "orderNo": "BUY202604060930ABCD",
  "contactEmail": "[email protected]"
}

响应示例

{
  "ok": true,
  "data": {
    "orderNo": "BUY202604060930ABCD",
    "status": "PAID",
    "deliveryState": "DELIVERED",
    "contactEmail": "[email protected]"
  }
}

说明

订单号/邮箱不匹配时返回 404 和 purchase_order_not_found。

POST/api/topup/preview

鉴权: 公开

验证 API Key 是否存在且可以接收额外额度。

请求示例

{
  "apiKey": "sk-live_example"
}

响应示例

{
  "ok": true,
  "data": {
    "tokenName": "生产密钥",
    "availableQuota": 5400000000,
    "usedQuota": 1600000000,
    "totalQuota": 7000000000
  }
}

说明

客户端通常在展示充值套餐选择前调用此接口。

POST/api/topup/orders

鉴权: 公开

为已有 API Key 创建充值订单。

请求示例

{
  "apiKey": "sk-live_example",
  "packageCode": "topup_100",
  "contactEmail": "[email protected]",
  "couponCode": "SPRING10"
}

响应示例

{
  "ok": true,
  "data": {
    "orderNo": "TOP202604060935WXYZ",
    "amountCents": 9000,
    "contactEmail": "[email protected]",
    "payUrl": "/topup/pay?orderNo=TOP202604060935WXYZ&contactEmail=buyer%40example.com"
  }
}

说明

packageCode 或 tokenUnits 取决于当前定价模式。

POST/api/topup/orders/pay

鉴权: 公开

为已有的充值订单准备支付会话。

请求示例

{
  "orderNo": "TOP202604060935WXYZ",
  "contactEmail": "[email protected]"
}

响应示例

{
  "ok": true,
  "data": {
    "orderNo": "TOP202604060935WXYZ",
    "provider": "xunhupay",
    "checkoutUrl": "https://pay.example.com/checkout/topup"
  }
}

说明

支付提供商返回的数据可能包含二维码和移动端 URL 变体。

POST/api/topup/orders/query

鉴权: 公开

通过订单号和联系邮箱查询充值订单。

请求示例

{
  "orderNo": "TOP202604060935WXYZ",
  "contactEmail": "[email protected]"
}

响应示例

{
  "ok": true,
  "data": {
    "orderNo": "TOP202604060935WXYZ",
    "status": "PAID",
    "credited": true
  }
}

说明

订单号/邮箱不匹配时返回 404 和 topup_order_not_found。

POST/api/quota/summary

鉴权: 公开

返回 API Key 的当前额度总量和计费衍生的余额信息。

请求示例

{
  "apiKey": "sk-live_example"
}

响应示例

{
  "ok": true,
  "data": {
    "tokenName": "生产密钥",
    "totalTokens": 7000000000,
    "usedTokens": 1600000000,
    "remainingTokens": 5400000000,
    "responseTimeMs": 283
  }
}

说明

错误载荷中返回 INVALID_KEY、RATE_LIMIT、SERVER_ERROR、NETWORK 或 UNKNOWN。

POST/api/quota/logs

鉴权: 公开

返回 API Key 的使用日志条目，包含缓存命中元数据和响应时间。

请求示例

{
  "apiKey": "sk-live_example"
}

响应示例

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "log_01",
        "modelName": "gpt-4o-mini",
        "quota": 3200,
        "hasCacheHit": false
      }
    ],
    "total": 1,
    "truncated": false
  }
}

说明

后端可能会截断过大的日志历史。

GET/api/tokens

鉴权: 需要会话 Cookie

列出当前登录用户拥有的 API Key。

请求示例

GET /api/tokens

响应示例

{
  "ok": true,
  "items": [
    {
      "id": "key_01",
      "displayName": "默认密钥",
      "maskedKey": "sk-****abcd",
      "status": "ACTIVE"
    }
  ]
}

说明

仪表盘登录后的 Key 管理页面使用此接口。

POST/api/tokens

鉴权: 需要会话 Cookie

为当前登录用户创建新的 API Key。

请求示例

{
  "displayName": "Default Key"
}

响应示例

{
  "ok": true,
  "token": {
    "id": "key_01",
    "displayName": "Default Key",
    "maskedKey": "sk-****abcd",
    "status": "ACTIVE"
  },
  "plainKey": "sk-live_once_only"
}

说明

完整的 plainKey 仅在创建时返回一次。

PATCH/api/tokens/{id}/disable

鉴权: 需要会话 Cookie

禁用当前登录用户拥有的 API Key。

请求示例

PATCH /api/tokens/key_01/disable

响应示例

{
  "ok": true,
  "token": {
    "id": "key_01",
    "status": "REVOKED"
  }
}

说明

Key ID 不属于当前用户时返回 404。

DELETE/api/tokens/{id}

鉴权: 需要会话 Cookie

删除当前登录用户拥有的 API Key。

请求示例

DELETE /api/tokens/key_01

响应示例

{
  "ok": true
}

说明

删除不可逆，且会更新关联的上游 Token 状态。

`invalid_payload`	400	JSON 请求体不符合端点 schema。
`purchase_order_create_failed`	400	首购订单创建失败。
`purchase_pay_failed`	400	首购支付会话创建失败。
`purchase_order_not_found`	404	未找到匹配的首购订单（订单号/邮箱不匹配）。
`topup_preview_failed`	400	目标 API Key 无法通过充值验证。
`topup_order_create_failed`	400	充值订单创建失败。
`topup_pay_failed`	400	充值支付会话创建失败。
`topup_order_not_found`	404	未找到匹配的充值订单（订单号/邮箱不匹配）。
`INVALID_KEY`	400	提供的 API Key 未被额度查询后端接受。
`RATE_LIMIT`	500	额度查询上游正在限流。
`SERVER_ERROR`	500	额度查询上游暂时不可用。