PRACTESTIC 赤色词元
API REFERENCE · v1

OpenAI 兼容接口文档

用一套协议接通 DeepSeek、Kimi、智谱、MiniMax、阿里云百炼、火山方舟与腾讯云 TokenHub。 客户持有自己的虚拟 Key,网关负责鉴权、模型路由、转发与用量记录。

Chat Completions SSE 流式 OpenAI SDK 本机监听
GET http://127.0.0.1:3919/v1
POST http://127.0.0.1:3919/v1/chat/completions Authorization: Bearer vk-…

快速开始

三步完成第一次调用。网关只监听本机,应用与网关需要在同一台机器上。

1

获取虚拟 Key

PRACTESTIC 会为每个客户生成独立的 vk- 虚拟 Key,并按需开通对应平台。 平台真实 Key 由 PRACTESTIC 托管,不会下发给调用方。

2

填入 Base URL

把客户端的 API 地址改为 http://127.0.0.1:3919/v1,协议选择 OpenAI 兼容。

3

选一个模型发起请求

模型 ID 使用 平台/模型,例如 deepseek/deepseek-flash。完整列表见 模型广场。

仅本机可用

服务默认绑定 127.0.0.1,不会暴露到局域网或公网。 如果需要跨机访问,请自行在前面加反向代理与访问控制。

认证

所有 /v1 请求都必须携带客户虚拟 Key。平台真实 Key 不会下发给客户端。

请求头
Authorization: Bearer vk-xxxxxxxxxxxxxxxx
情况HTTP返回
缺少 Authorization 或格式错误401invalid api key
虚拟 Key 不存在或已轮换401invalid api key
客户被禁用403user disabled
  • 虚拟 Key 在「客户」页面创建客户时生成,可复制、轮换、停用。
  • 客户的平台 Key 与虚拟 Key 分离;删除客户会同时删除其名下平台 Key。
  • 本地数据以明文保存,用于个人自建场景,请勿把本机服务暴露给不可信网络。

Base URL 与兼容性

Base URLhttp://127.0.0.1:3919/v1
协议OpenAI Chat Completions
认证Bearer 虚拟 Key
模型命名provider/model
流式text/event-stream
监听范围127.0.0.1 only

网关实现了 OpenAI Chat Completions 的核心语义,因此任何支持自定义 Base URL 的 OpenAI 客户端都可以直接接入。 上游平台返回的字段、错误与 usage 会原样透传。

GET /v1/models

返回当前客户可调用、且未被连通性检测标记为不可用的对话模型。没有平台 Key 的厂商、 非对话模型、权限外模型都不会出现。

请求示例
curl http://127.0.0.1:3919/v1/models \
  -H "Authorization: Bearer $PRACTESTIC_API_KEY"
响应示例
{
  "object": "list",
  "data": [
    {
      "id": "deepseek/deepseek-flash",
      "object": "model",
      "owned_by": "deepseek",
      "context_length": 1000000,
      "max_output_tokens": 384000,
      "input_modalities": ["text", "image"],
      "reasoning": {
        "parameter": "reasoning_effort",
        "levels": [
          { "name": "off", "value": "none" },
          { "name": "low", "value": "low" },
          { "name": "high", "value": "high" },
          { "name": "max", "value": "max" }
        ]
      }
    }
  ]
}
字段类型说明
idstring全局唯一模型 ID,格式 provider/model
owned_bystring平台标识:deepseek / kimi / zhipu / minimax / bailian / volcengine / tencent
context_lengthnumber | null上下文窗口,单位 tokens
max_output_tokensnumber | null最大输出 tokens
input_modalitiesstring[]输入模态:text / image / video / audio
reasoningobject | null推理档位定义,见 推理档位
同名模型如何区分

不同平台可能提供同一个模型,例如 kimi/kimi-k3 与 tencent/kimi-k3。 带平台前缀的 ID 永远路由到指定平台;不带前缀时优先选择该客户有 Key 的平台。

POST /v1/chat/completions

发起对话补全。网关会把 provider/model 还原成平台原始模型 ID,再转发到对应上游。

请求体
{
  "model": "deepseek/deepseek-flash",
  "messages": [
    { "role": "system", "content": "你是一个简洁的助手。" },
    { "role": "user", "content": "用一句话解释 MoE。" }
  ],
  "temperature": 0.7,
  "max_tokens": 512,
  "stream": false
}
参数必需说明
model是模型 ID,推荐使用 provider/model
messages是OpenAI 消息数组,role 支持 system / user / assistant / tool
stream否设为 true 时返回 SSE;网关自动请求上游包含 usage
temperature否透传给上游,取值范围以各平台文档为准
max_tokens否透传给上游的最大输出 token 数
tools / tool_choice否透传;是否支持取决于具体模型
reasoning_effort否推理强度,取值见 推理档位
非流式响应
{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "deepseek-flash",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "MoE 用多个专家网络…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 96,
    "total_tokens": 120
  }
}

流式输出

把 stream 设为 true,网关以 SSE 原样透传上游数据块,并在末尾补齐带 usage 的数据块。

SSE 片段
data: {"id":"chatcmpl-…","choices":[{"delta":{"content":"MoE"}}]}

data: {"id":"chatcmpl-…","choices":[{"delta":{"content":" 用多个"}}]}

data: {"id":"chatcmpl-…","choices":[{"delta":{},"finish_reason":"stop"}],
       "usage":{"prompt_tokens":24,"completion_tokens":96,"total_tokens":120}}

data: [DONE]
  • 网关会向上游注入 stream_options.include_usage = true,便于统计真实 token。
  • 客户端主动断开时,本次请求记为 499,已产生的 usage 仍会写入本地账本。
  • 上游返回的非 2xx 响应会连同状态码与响应体原样返回,不会包装成 200。

推理档位

/v1/models 的 reasoning 字段给出该模型支持的参数名与档位值。 没有该字段的模型不支持预设,请求里传了也可能被上游忽略或拒绝。

平台 / 模型参数可用档位
DeepSeekreasoning_effortnone / low / high / max
Kimi K3 系列reasoning_effortlow / high / max(不能关闭思考)
智谱 GLM-5.3reasoning_effortlow / high / max
智谱 GLM-5.2reasoning_effortnone / minimal / low / medium / high / xhigh / max
智谱 GLM-5 / 5.1 / 4.7thinking.typedisabled / enabled
火山方舟推理模型reasoning_effortnone / minimal / low / medium / high / xhigh / max
请求示例
{
  "model": "deepseek/deepseek-flash",
  "messages": [{ "role": "user", "content": "证明根号 2 是无理数" }],
  "reasoning_effort": "high"
}

客户端配置

任何支持 OpenAI 兼容接口的客户端都可以接入,只需要三项配置。

API 地址 / Base URLhttp://127.0.0.1:3919/v1
API Key客户的 vk-… 虚拟 Key
模型从 /v1/models 选择

DeepSeek Harness

类型选 OpenAI 兼容;Provider ID practestic,Base URL 填上方地址,模型填 deepseek/deepseek-flash。

Cherry Studio / ChatBox

添加自定义 OpenAI 提供商,API Host 填 Base URL(不带 /v1 时以客户端要求为准),粘贴虚拟 Key。

LangChain / LlamaIndex

使用 ChatOpenAI(base_url=…, api_key=…),模型名传 provider/model。

脚本与后端服务

OpenAI Python / Node SDK 均可;网关兼容 Bearer 认证与标准 JSON 请求体。

DSH 视频插件

在 DeepSeek Harness 里生成视频:下载插件,解压后在「插件 → 添加插件」选择目录。 安装后打开「设置 → 视频生成」,填写本页 Base URL 和虚拟 Key,选择 Seedance 模型即可。 聊天输入框旁也会出现「视频」入口。

下载插件 ZIP 下载 TGZ

当前视频适配为火山方舟 Seedance;使用前请先在方舟控制台激活对应模型。 视频接口为 /v1/video/models、/v1/videos、/v1/videos/{id}。

OpenAI SDK 示例

Python
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:3919/v1",
    api_key="vk-xxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="kimi/kimi-k3.1-pro",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
Node.js
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://127.0.0.1:3919/v1',
  apiKey: process.env.PRACTESTIC_API_KEY,
});

const resp = await client.chat.completions.create({
  model: 'tencent/hy4',
  messages: [{ role: 'user', content: '你好' }],
});
console.log(resp.choices[0].message.content);

模型目录

目录由各平台官方接口与文档同步,并在每次更新后执行真实连通性检测。 不可用的模型会从网关隐藏,但保留在模型页并标记原因。

平台模型条目对话模型实测可用官网
正在读取模型目录…
模型 ID 规则

目录中的原始 ID 可能被多个平台复用。网关统一加上平台前缀, 例如 volcengine/deepseek-v4-1-flash-261017。调用时传完整 ID 最稳妥。

错误码

HTTP含义排查方向
400请求体不合法检查 JSON、model 与 messages
401虚拟 Key 无效确认 Key 未被轮换,且请求头为 Bearer
403客户被禁用,或模型不在权限内检查客户状态与模型权限
404模型不存在先请求 /v1/models,使用返回的完整 ID
499客户端主动断开客户端超时或手动取消;用量按已产生部分记录
502上游连接失败平台网络、DNS 或代理异常,稍后重试
503缺少平台 Key 或上游不可用联系 PRACTESTIC 补齐该平台 Key,或换一个模型
4xx / 5xx上游原样返回平台侧限流、余额不足或参数错误,按响应体处理

网关自身的错误统一为:

错误结构
{
  "error": {
    "message": "model not allowed",
    "type": "gateway_error",
    "code": 403
  }
}

用量与计费

0金额估算
1次请求一行账本
T+1部分平台账单延迟
手动平台侧配额
  • 网关只记录上游真实返回的 usage:输入 / 输出 tokens、请求数、模型、状态与耗时。
  • 不估算金额,不换算积分。金额以各平台官方余额与账单为准。
  • 日粒度不可用的平台会在看板明确标注「无日粒度」,不会用月账单均摊成日数据。
  • 部分平台账单存在 T+1 / T+2 延迟,延迟会在账单中标注,不提前展示未出账金额。
  • 配额不在此系统强制执行;如有需要,请在各平台控制台手动配置。
  • 「全部」消费来自本地账本,覆盖自系统开始记录以来的月份;更早历史以平台账单为准。

常见问题

为什么 /v1/models 比我预期的少?

只返回同时满足以下条件的模型:该客户有对应平台 Key、模型为对话类且状态可用、 没有在最近一次连通性检测中失败、并且在客户权限范围内。

同一个模型名出现在多个平台怎么办?

使用带平台前缀的完整 ID,例如 kimi/kimi-k3 与 tencent/kimi-k3。 完整 ID 会精确路由,不会串台。

返回 503 缺少平台 Key 怎么处理?

联系 PRACTESTIC 为该客户开通对应平台,系统会尝试创建平台 Key。 平台登录失效时需要先重新登录,再重试。

流式请求没有 usage 怎么办?

网关会向上游请求 include_usage。若某平台仍不返回 usage, 该次请求会以缺失 usage 记入账本,不会伪造数字。

可以给不同客户限制模型吗?

可以。PRACTESTIC 支持为每个客户配置允许的模型列表;不在列表中的模型会返回 403 model not allowed,也不会出现在该客户的 /v1/models 中。

如何轮换或停用虚拟 Key?

联系 PRACTESTIC 轮换或停用。轮换后旧 Key 立即失效;停用客户后该客户的所有请求返回 403 user disabled。