企业接入
企业签约开通后,由管理员签发项目 API Key。选一个已授权模型,用 cURL、Python 或 Node.js 跑通首条请求,再到企业日志核对词元用量。
快速接入
Token Pyxis 仅为签约企业开通服务,官网不提供公开注册。请向企业管理员确认网关地址和访问权限。 查看开通与授权流程
发出第一条请求
在服务端设置 BASE_URL 为网关根地址(不含 /v1),并将企业密钥放入 TOKEN_PYXIS_API_KEY。
用所选模型的 ID 替换 MODEL_ID。
环境变量示例
export BASE_URL="https://tokenpyxis.com"
export TOKEN_PYXIS_API_KEY="sk-your-key"如企业另有专用网关,请使用实际部署地址。用部署环境的密钥管理系统注入真实密钥。
POST /v1/chat/completionsBASE_URL="${BASE_URL:-https://tokenpyxis.com}"
curl -i "${BASE_URL%/}/v1/chat/completions" \
-H "Authorization: Bearer $TOKEN_PYXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"messages": [
{
"role": "user",
"content": "你好,介绍一下你能做什么。"
}
]
}'成功后先确认模型输出,再记录响应头 x-request-id,到企业控制台的「日志」核对模型和词元用量。 查看对账步骤
Base URL 与认证
用企业部署的网关地址作为 BASE_URL。直接发送 HTTP 请求时拼接完整端点;使用 SDK 时按下表设置根地址,避免重复拼接 /v1。
| 访问方式 | 地址与路径 | 请求凭证 |
|---|---|---|
| OpenAI | SDK 根地址 https://tokenpyxis.com/v1POST /v1/chat/completions | Authorization: Bearer sk-… |
| Anthropic | SDK 根地址 https://tokenpyxis.comPOST /v1/messages | x-api-key: sk-… |
| Gemini | 按原生 HTTP 路径请求POST /v1beta/models/{model}:generateContent | x-goog-api-key: sk-… |
| 企业管理 | https://tokenpyxis.com/api/enterprise/… | 登录 JWTAuthorization: Bearer <jwt> |
| 公开目录 | GET /api/public/models | 公开选型信息,无需鉴权 |
词元(Token)是模型处理输入、生成输出时的用量单位。API Key 用于模型调用,登录 JWT 用于企业管理。
端点总览
先在模型广场核对目标模型的能力,再选择对应端点。实际可用能力取决于企业权限和上游渠道。
| 分组 | 端点 | 方法 | 说明 |
|---|---|---|---|
| OpenAI 格式 | /v1/chat/completions | POST | 对话补全(主力;流式 / 工具 / 联网搜索) |
/v1/embeddings | POST | 向量嵌入 | |
/v1/responses | POST | Responses 状态协议 | |
/v1/images/generations | POST | 图像生成(按次计价) | |
/v1/audio/speech | POST | 语音合成(TTS) | |
/v1/audio/transcriptions | POST | 语音识别(multipart) | |
/v1/rerank | POST | 重排序 | |
/v1/videos/generations · /v1/videos/{id} | POST GET DEL | 视频生成(提交 + 轮询 + 取消) | |
/v1/realtime | WS | Realtime 双向语音(WebSocket) | |
| Anthropic 格式 | /v1/messages | POST | Claude 消息协议(含 thinking / 缓存点) |
| Gemini 格式 | /v1beta/models/{model}:generateContent | POST | 原生内容生成 |
/v1beta/models/{model}:streamGenerateContent | POST | 原生流式内容生成 | |
/v1beta/models | GET | 原生模型列表(需 API Key) | |
| 模型列表 | /v1/models | GET | OpenAI 兼容模型列表(需 Key) |
| 公开接口 | /api/public/models | GET | 公开目录(定价 / 能力 / 分组折扣) |
/api/public/groups | GET | 分组折扣 | |
/api/public/providers | GET | 上游生态聚合 | |
/api/public/status | GET | 实例版本与日志留存配置 | |
| 企业侧(JWT) | /api/enterprise/* | JWT | 钱包 / 日志 / 用量 / 兑换码 / 任务等 |
限流与配额
请求可能同时受到平台、分组、企业、套餐、API Key 和渠道的限制。RPM 为最近 60 秒内的请求数。HTTP 推理的 TPM 在请求开始前按预计输入和输出预留,完成后按上游用量记入滑动窗口,包括缓存读写。流式首词元延迟从网关接收请求计至首个模型输出事件。遇到 429 rate_limited 时优先遵循 Retry-After(如有),并采用带抖动的指数退避;遇到 402 时核对余额和额度。
模型列表
OpenAI 兼容模型列表(需 sk- 密钥;仅返回该 Key 白名单内可调用的模型)。
curl https://tokenpyxis.com/v1/models -H "Authorization: Bearer sk-your-key"
{
"object": "list",
"data": [
{"id": "deepseek-chat", "object": "model", "owned_by": "maas-gateway"},
{"id": "glm-4.5", "object": "model", "owned_by": "maas-gateway"}
]
}公开目录供技术选型,展示已配置启用渠道及有效凭证的上架模型,返回目录价、倍率、能力、别名与分组折扣,也是官网模型广场的数据源。调用权限请使用企业 API Key 查询。
{
"models": [
{
"id": "deepseek-chat", "display_name": "DeepSeek V3", "aliases": null,
"capability": {"chat": true, "messages": true, "responses": true, "embeddings": false},
"input_price": 2000000, "output_price": 8000000,
"cache_read_price": null, "cache_read_ratio": 0.1,
"cache_write_price": null, "cache_write_1h_price": null,
"multiplier": 1.0, "per_call_price": null
}
],
"groups": [{"name": "标准分组", "discount_rate": 0.7, "note": null}],
"currency": "CNY",
"price_unit": "micros / 1M tokens(1 元 = 1000000 micros)",
"updated_at": 1794470153748
}获取分组折扣、按供应商聚合的模型信息和平台配置状态。状态响应含当前请求日志配置天数 log_retention_days 与生成内容提示。
curl https://tokenpyxis.com/api/public/status
{"service":"maas-gateway","version":"0.1.0","status":"operational",
"aigc_notice":"生成式人工智能输出内容由 AI 生成…","log_retention_days":180}OpenAI 接口格式
使用 OpenAI 兼容的对话补全格式。工具、视觉等能力取决于模型和渠道。平台配置了搜索供应商时,可使用扩展字段 web_search。
| 参数 | 必填 | 说明 |
|---|---|---|
model | 必填 | 模型 ID 或别名(见模型广场;须在 Key 白名单内) |
messages | 必填 | 对话消息数组(system / user / assistant / tool) |
stream | 可选 | true 启用流式 SSE,以 data: [DONE] 结束 |
temperature / top_p | 可选 | 采样参数,透传上游 |
max_tokens | 可选 | 最大输出词元数 |
tools / tool_choice | 可选 | 函数调用定义(原样透传上游) |
web_search | 可选 | 平台扩展:联网搜索(见下节) |
| 模型名修饰符 | 可选 | model@thinking / @nothinking(思考开关)、@effort-none|low|medium|high|max(OpenAI o 系努力档→reasoning_effort);未知修饰符 400 |
| 平台侧预检:max_tokens 系列须正整数;images n∈[1,10000];video seconds/duration∈(0,86400];stream 须布尔 | ||
curl https://tokenpyxis.com/v1/chat/completions \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-chat",
"messages": [{"role":"system","content":"You are helpful."},{"role":"user","content":"你好"}],
"temperature": 0.7,
"stream": false
}'from openai import OpenAI
client = OpenAI(base_url="https://tokenpyxis.com/v1", api_key="sk-your-key")
resp = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://tokenpyxis.com/v1", apiKey: "sk-your-key" });
const resp = await client.chat.completions.create({
model: "deepseek-chat",
messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);{
"id": "chatcmpl-…", "object": "chat.completion",
"choices": [{"index": 0, "finish_reason": "stop",
"message": {"role": "assistant", "content": "你好,世界"}}],
"usage": {"prompt_tokens": 12, "completion_tokens": 6, "total_tokens": 18}
}每次调用在控制台「请求日志」留存明细;计费金额可按定价快照逐微元复算。 模型可用端点由管理端「能力」勾选控制(capability 键与端点一一对应:chat / messages / responses / embeddings / images / speech / transcriptions / rerank / video / realtime),未开放端点返回 400。
"stream": true 时返回 text/event-stream:
data: {"id":"chatcmpl-…","choices":[{"delta":{"content":"你"}}]}
data: {"id":"chatcmpl-…","choices":[{"delta":{"content":"好"}}]}
data: [DONE]- 以
data: [DONE]哨兵判断流结束(客户端请以哨兵为准); - 客户端中断后,已处理部分仍可能产生词元用量;以企业日志的最终记录为准;
- 敏感词拦截在请求体预检执行(HTTP 数据面 403);流式中途的 TPM 检查与帧级敏感词扫描仅
/v1/realtime会话具备。
请求体携带 web_search 即可开启:平台侧调用搜索源(Tavily / Serper,由运营方配置),结果注入上下文后转发上游。搜索失败不阻断推理请求(自动降级为无搜索直连)。该字段不会透传上游,未配置搜索源时开关不生效。
// 三种形态任选:
{"model":"deepseek-chat","messages":[…],"web_search":true}
{"model":"deepseek-chat","messages":[…],"web_search":{"enabled":true,"query":"2025 大模型备案 政策"}}
{"model":"deepseek-chat","messages":[…],"web_search":"今天的最新新闻"}向量嵌入(模型须开放 embeddings 能力)。
curl https://tokenpyxis.com/v1/embeddings \
-H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
-d '{"model":"text-embedding-v3","input":"Token Pyxis 文本向量"}'{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.0123,-0.0456,…]}],
"usage":{"prompt_tokens":8,"total_tokens":8}}使用 Responses 请求结构。流式、工具调用和多轮状态以所选模型及渠道为准。
按快速接入设置环境变量,将 MODEL_ID 替换为已授权且支持此协议的模型 ID。
curl -i "https://tokenpyxis.com/v1/responses" \
-H "Authorization: Bearer $TOKEN_PYXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"input": "用一句话介绍自己。"
}'使用已开通的企业模型 ID 和该操作的参数调用。可用操作及计费单位在模型详情中显示。
- 异步任务返回平台任务 ID。通过
GET /v1/media/tasks/{id}查询进度和结果,通过POST /v1/media/tasks/{id}/cancel请求取消。 - 语音合成支持 JSON 或 SSE。流式调用应读取到携带计费用量的末帧。
- 实时语音识别使用
GET /v1/audio/realtime?model=MODEL_ID升级 WebSocket,发送 16 kHz 单声道 PCM 及任务事件。 - 收到
submission_pending时,保留任务 ID 查询,避免重复提交同一任务。
图像生成。按次计价(per_call_price,尺寸/质量档位按上游协议透传),提交成功即计费、失败不计费。
curl https://tokenpyxis.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
-d '{"model":"cogview-3","prompt":"水墨风格的远山与孤舟","size":"1024x1024"}'{"created":1794473600000,"data":[{"url":"https://…/img-0.png"}]}语音合成(TTS):文本转音频,按输出音频时长/token 计价(随上游协议)。
curl https://tokenpyxis.com/v1/audio/speech \
-H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
-d '{"model":"tts-1","input":"欢迎使用 Token Pyxis","voice":"alloy"}' \
--output speech.mp3语音识别(ASR):multipart 上传音频文件转文本。
curl https://tokenpyxis.com/v1/audio/transcriptions \ -H "Authorization: Bearer sk-your-key" \ -F file=@speech.mp3 -F model=whisper-1
重排序(RAG 检索精排):按 query 与文档列表相关性重排。
curl https://tokenpyxis.com/v1/rerank \
-H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
-d '{"model":"reranker-v2","query":"什么是大模型网关","documents":["网关聚合…","今天天气…"]}'视频生成(异步任务):提交走完整治理管线(鉴权 / 白名单 / 敏感词 / 限流 / 预检),成功按实际秒数结算,失败 / 取消不计费;24h 未完成自动判失败。协议支持 Sora / 火山方舟 / 可灵 Kling / Google Veo / 通用任务网关。
curl https://tokenpyxis.com/v1/videos/generations \
-H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
-d '{"model":"kling-v1","prompt":"城市夜景延时摄影","duration":5}'{"id":"vtask_…","object":"video.generation.task","model":"kling-v1",
"status":"in_progress","progress":5,"created_at":1794473600123}轮询节奏建议 10s 起步退避至 30s;24h 未完成自动判失败且不计费。
任务轮询:建议 10s 起步退避至 30s(服务端调度节奏),任务 24h 超时自动判失败。
{"id":"vtask_…","object":"video.generation.task","model":"kling-v1",
"status":"completed","progress":100,
"video":{"video_url":"https://…/video.mp4"},"created_at":1794473600123}status 枚举:in_progress | completed | failed | cancelled;计费按实际秒数结算,失败/取消不计费。
Realtime 双向语音(WebSocket 升级)。连接建立需带 Authorization: Bearer sk- 头与必填 query 参数 ?model=;帧上限 1MiB,会话中期 TPM 检查与帧级敏感词扫描生效(错误帧 code 为 moderation_blocked)。
wss://tokenpyxis.com/v1/realtime?model=MODEL_IDGemini 接口格式
客户端可用 Google Gemini generateContent 调用。启用的原生 Gemini 渠道保留原始请求结构和 SSE 事件,同时执行企业授权、内容策略、限流和计量。鉴权支持 Authorization: Bearer sk- 与 Gemini SDK 标准头 x-goog-api-key 两种形态。
非流式生成。请求体为 Gemini 原生结构:contents(role: user / model,parts.text)+ systemInstruction + generationConfig(temperature / topP / topK / maxOutputTokens)。
按快速接入设置环境变量,将 MODEL_ID 替换为已授权且支持此协议的模型 ID。
curl -i "https://tokenpyxis.com/v1beta/models/MODEL_ID:generateContent" \
-H "x-goog-api-key: $TOKEN_PYXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "用一句话介绍自己。"
}
]
}
]
}'{
"candidates": [{
"content": {"role": "model", "parts": [{"text": "我是 Token Pyxis 的助手"}]},
"finishReason": "STOP"
}],
"modelVersion": "gemini-2.5-pro",
"usageMetadata": {"promptTokenCount": 100, "candidatesTokenCount": 20, "totalTokenCount": 120}
}原生 Gemini 渠道保留 tools、inlineData、safetySettings 和 cachedContent 等字段。跨协议渠道支持基本文本对话,需原生处理的请求会收到明确错误。
流式生成(alt=sse)。网关逐段转发文本与结束原因。上游返回用量时,流中也会提供 usageMetadata。
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"…"}]},"finishReason":"STOP"}],
"usageMetadata":{…}}Gemini 格式模型列表(name 为 models/{id},含 supportedGenerationMethods)。
{"models": [{"name": "models/deepseek-chat", "displayName": "deepseek-chat",
"supportedGenerationMethods": ["generateContent", "streamGenerateContent"]}]}Anthropic 接口格式
Claude Messages 协议(请求体与 Anthropic 官方一致):system / messages / max_tokens / thinking / cache_control 缓存点(缓存写 5m 与 1h 两档独立计价)均支持,流式事件原样透传。
按快速接入设置环境变量,将 MODEL_ID 替换为已授权且支持此协议的模型 ID。
curl -i "https://tokenpyxis.com/v1/messages" \
-H "x-api-key: $TOKEN_PYXIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"max_tokens": 64,
"messages": [
{
"role": "user",
"content": "用一句话介绍自己。"
}
]
}'{"id":"msg_…","type":"message","role":"assistant",
"content":[{"type":"text","text":"要点如下…"}],
"usage":{"input_tokens":520,"cache_read_input_tokens":0,"cache_creation_input_tokens":96,"output_tokens":210}}企业侧 API
已开通的企业账号和获授权的成员账号可在权限范围内调用企业侧 API。使用登录 JWT 认证,写操作和财务接口按角色授权。
curl -X POST https://tokenpyxis.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"YOUR_PROVISIONED_USERNAME","password":"YOUR_PASSWORD"}'
// 响应:{"token":"<jwt>","refresh_token":"rt_…","kind":"enterprise"}
// 后续请求携带:Authorization: Bearer <jwt>| 端点 | 说明 | 关键查询参数 |
|---|---|---|
GET /api/enterprise/wallet | 钱包余额与流水列表 | — |
GET /api/enterprise/models | 本企业生效模型目录(响应含 prices:"effective" 标记与折扣链实算价) | —(无参数) |
GET /api/enterprise/logs | 请求日志(多维筛选 / 分页) | page,size,key,model,status,from,to(毫秒时间戳),request_id(精确) |
GET /api/enterprise/logs/stats | 同过滤器聚合请求数、错误、词元及套餐抵扣前计价 | 同 logs |
单笔日志的 sale_micros 为套餐词元抵扣前的用量计价,wallet_charge_micros 为已记账钱包实扣。金额均为整数微元。实扣字段为 0 表示结算确认且扣款为零,为 null 表示当前无对应结算记录。
curl https://tokenpyxis.com/api/enterprise/wallet -H "Authorization: Bearer <jwt>"
| 端点 | 说明 | 关键查询参数 |
|---|---|---|
GET /api/enterprise/usage | 日聚合用量(词元 / 金额 / 错误) | days=N(1~365)或 from_day,to_day;可选 group_by=key|department|model|channel(可组合)与 key 过滤 |
GET /api/enterprise/usage/export | CSV 导出(带 BOM,Excel 直开) | days=N 或 from_day,to_day(与 usage 同口径) |
GET /api/enterprise/insights | 今日 / 本月消费 + 缓存命中与节省 | — |
| 端点 | 说明 |
|---|---|
POST /api/enterprise/redeem | 由有权限的企业管理员使用平台按约提供的兑换码入账({"code":"…"}) |
GET /api/enterprise/tasks | 视频 / 异步任务列表与状态 |
GET /api/enterprise/captures | 请求正文捕获(默认关闭;开启时 AES-GCM 加密存储,仅本企业可读) |
GET /api/enterprise/audit | 本企业操作审计 |
错误码
| HTTP | code | 含义 / 处理建议 |
|---|---|---|
| 400 | invalid_request | 参数不合法(缺字段/类型错/模型白名单外/协议能力未开放/出网拦截等),按 message 修正 |
| 401 | invalid_api_key 等 | 核对端点要求的 API Key 或登录 JWT,以及凭证状态和有效期。 |
| 402 | insufficient_balance | 余额不足或可用额度用尽。由企业管理员核对余额、额度与合同约定的结算方式。 |
| 403 | permission_denied / ip_banned | 权限不足(含敏感内容拦截,message 注明);或来源 IP 触发风控自动封禁,请联系管理员 |
| 404 | not_found | 模型下架 / 路由不存在 |
| 408 | request_timeout | 客户端请求超时 |
| 409 | already_exists / seats_exceeded | 资源已存在(幂等冲突);或成员席位已满 |
| 413 | request_too_large | 请求体超限(数据面 32MiB / 控制面 1MiB) |
| 429 | rate_limited | 多级限流触发 / 池耗尽,按 Retry-After 指数退避重试 |
| 500 | internal_error | 保存请求编号,核对日志和任务状态后决定是否重试。 |
| 502 / 504 | upstream_error | 上游失败或超时。符合条件时网关会尝试同模型的其他候选渠道。已收到流式内容或任务编号时,先检查原请求再重发。 |
| 503 | overloaded / no_available_channel / budget_unavailable / service_unavailable | 平台繁忙;无可用渠道(全部熔断/禁用);预算数据短暂不可用;依赖组件未启用(如请求捕获库未挂载)请稍后或联系管理员 |
| 503(公开目录) | unavailable | 公开目录数据短暂不可用,请稍后刷新(缓存通常会自动恢复) |
敏感内容拦截:HTTP 数据面返回 403 permission_denied(message 注明命中敏感词);/v1/realtime WebSocket 会话内的错误帧 code 为 moderation_blocked。
计费口径
模型广场展示词元(Token)目录价和按量费用。词元部分按各项用量与各自单价求和后,乘模型倍率和企业生效折扣,再加按接口计量的固定费用。企业可在「模型与价格」确认生效价,费用与结算方式按签署的企业合同执行。
| 维度 | 单位 | 说明 |
|---|---|---|
| 输入 input | 元 / 百万词元 | 普通输入词元 |
| 输出 output | 元 / 百万词元 | 模型生成的词元 |
| 缓存读 cache_read | 元 / 百万词元 | 命中前缀缓存读取部分(未单列时 = 输入价 × 缓存读比) |
| 缓存写 cache_write | 元 / 百万词元 | 5 分钟与 1 小时档分别计价(如模型支持) |
| 按次 per_call | 按接口计量 | 图像按张、异步视频按秒,其他按接口约定计次(不乘倍率与折扣;images 按 n 计次) |
- 内部记账单位为整数
micros(1 元 = 1,000,000 micros)。实际费用以账本和请求定价快照为准。 - 适用的订阅池用量优先由套餐覆盖,超出部分按结算规则使用钱包余额。
- 假设模型倍率为 1,普通输入、缓存读、输出的价格分别为每百万词元 1 元、0.5 元、1 元。普通输入 960、缓存读 40、输出 200 词元,生效折扣为 7 折时,词元费用为 826 micros(0.000826 元)。
- 钱包允许单次透支放行结算(上游成本已发生不漏账),后续请求由预检拦截;
- 每笔请求的定价快照随账本落库,管理端按 request_id 对账复算。
合规与内容标识
将模型输出作为产品功能提供给最终用户时,请按适用的内容标识要求设计展示、下载和转发流程。
- 数据面默认可返回
X-AIGC-Label: AIGC-generated响应头。将它作为接入侧提示信号,并按适用规则为生成内容加上显式提示或文件元数据标识。 - 平台部署中请求日志默认留存 180 天。现行《网络安全法》第二十三条第三项要求相关网络日志留存不少于六个月,实际部署应按适用的留存要求配置。
- 请求正文捕获默认关闭。数据处理、标识适用范围与问题反馈见合规声明和数据安全。
