# PingToken AI API(对外中继面) PingToken 对外中继 API 契约(单一真源)。覆盖范围 = 代码实际注册且可用的公开 AI 端点(router/relay-router.go、router/video-router.go、router/dashboard.go);后台管理 API(/api/* 门户专用)与 501 未实现桩不在本契约内。 鉴权:令牌密钥(Token Key)三种形态等价——OpenAI 惯例 `Authorization: Bearer sk-…`、Anthropic 惯例 `x-api-key: sk-…`、Gemini 惯例 `x-goog-api-key` 头或 `?key=` 查询参数。 Base URL:OpenAI 协议线填 `{baseUrl}/v1`;Anthropic 协议线填根地址 `{baseUrl}`(SDK 自动拼接 /v1/messages);Gemini 协议线填根地址 `{baseUrl}`。 错误契约(买家 7 码):400 invalid_request / 401 token_invalid / 404 invalid_request / 429 client_rate_limited / 503 service_unavailable。 > 机器可读契约:`GET /openapi.json`(OpenAPI 3.1)。本页与其同源生成;人类交互版在 https://pingtoken.cc/docs 。 ## 快速开始 1. 注册并登录(https://pingtoken.cc/sign-up)。 2. 确认余额(控制台钱包页)。 3. 创建 API 密钥(控制台「API Key」页,形如 `sk-…`)。 4. 发起第一次调用(示例见「文本对话 API」章)。 ## 认证与 Base URL | 协议 | Base URL | 鉴权头 | |---|---|---| | OpenAI(chat/images/audio/embeddings 等) | `{baseUrl}/v1` | `Authorization: Bearer $PINGTOKEN_API_KEY` | | Anthropic(/v1/messages) | `{baseUrl}`(根地址,SDK 自动拼接 /v1/messages) | `x-api-key: $PINGTOKEN_API_KEY`(同时兼容 Bearer) | | Gemini(/v1beta/models) | `{baseUrl}`(根地址) | `x-goog-api-key: $PINGTOKEN_API_KEY` 或 `?key=` | | SystemOne(/v1/systemone) | `{baseUrl}/v1` | `Authorization: Bearer $PINGTOKEN_API_KEY` | ⚠️ Anthropic 协议手动在根地址后再拼 `/v1` 会得到 404——SDK 已自动拼接。 ## 文本对话 API ### 请求示例(cURL) ```bash # OpenAI 协议(Base URL 带 /v1) curl https://pingtoken.cc/v1/chat/completions \ -H "Authorization: Bearer $PINGTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"{目标模型名称}","messages":[{"role":"user","content":"你好"}]}' # Anthropic 协议(Base URL 为根地址) curl https://pingtoken.cc/v1/messages \ -H "x-api-key: $PINGTOKEN_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{"model":"{目标模型名称}","max_tokens":1024,"messages":[{"role":"user","content":"你好"}]}' ``` ### 核心请求参数 | 参数 | 必填 | 说明 | |---|---|---| | `model` | 是 | 目标模型名称 | | `messages` | chat/messages 线是 | 对话消息数组(`role` + `content`) | | `input` | Responses 线 | 文本或结构化输入 | | `max_tokens` | Claude 线必填 | 最大输出 token | | `stream` | 否 | 流式开关(默认 false;true 时为 SSE) | | `temperature` | 否 | 采样温度 0~2 | ## 图像生成 API - `POST /v1/images/generations`(Base URL 带 /v1):`prompt` 与 `model` 必填;`n` 当前仅支持 1;`size` 支持 2^n 比例(512x512 / 1024x1024 / 1024x1536 / 1024x1792 / 4096x4096),16:9 等其他比例会静默降级为 1024x1024。 - `POST /v1/images/edits`:须携带 1~5 张参考图,单张 ≤10MB。 - 水印三态:跟随参数 / 平台统一水印 / 自定义水印(平台启用自定义时 `watermark_text` 必填,≤64 字符)。 - 按次计费:单价 × 张数系数 × 尺寸系数。返回平台转存链接(`/api/image/...`),保留 7 天,到期自动清理。 ## SystemOne 决策 API `POST /v1/systemone`(决策线专用,不可经 `/v1/chat/completions` 调用,否则 400)。与 TypeSafe 直连同形(drop-in:换 base_url 与 key 即用)。 | 字段 | 必填 | 约束 | |---|---|---| | `model` | 是 | 决策模型名(如 `Kev-4B`) | | `state` | 是 | 决策上下文(字符串 / JSON / 数组) | | `questions` | 是 | 题集 ≤32 题;整体请求体 ≤64KiB | 题型与返回语义:`noul` / `boolean` → `{noul: 0..1}` 概率;`choice` → `{choice, probabilities, confidence}` 闭集单选;`score` → `{score, legend}` 有序量表评分。 ## 视频生成 API 异步任务两步:创建(`POST /v1/videos` 或 `POST /v1/video/generations`)→ 轮询(`GET /v1/videos/{task_id}`)→ 取内容(`GET /v1/videos/{task_id}/content`)。另支持 Kling 官方形态(`/kling/v1/videos/text2video` 等)与即梦 Action 直通(`POST /jimeng/`)。时长/秒数按上游系数计费。 ## 音频 / 向量 / 重排序 - `POST /v1/audio/speech`(TTS)、`POST /v1/audio/transcriptions`、`POST /v1/audio/translations`。 - `POST /v1/embeddings`、`POST /v1/rerank`。 ## 余额与计费 - 余额:`GET /v1/balance`;OpenAI legacy 形态 `GET /v1/dashboard/billing/subscription` 返回 `hard_limit_usd` 与 `total_usage_usd`,**余额 = `hard_limit_usd − total_usage_usd`**(无限额度令牌 `*_usd` 回报 1e8)。 - 计费规则:文本/决策按实际 token(输入/输出/缓存分项);图像按次计费;失败调用不计费;触发 429 遵循退避重试。 ## 错误码(买家契约) | HTTP | code | 含义 | |---|---|---| | 400 | `invalid_request` | 参数不合法 | | 400 | `context_length_exceeded` | 请求超出模型上下文上限(按聚合模型 context_length 判定,未配置用平台默认;秒级拒绝不计费) | | 401 | `token_invalid` | 密钥无效/缺失/已删除 | | 404 | `invalid_request` | 模型不存在或未绑定 | | 429 | `client_rate_limited` | 触发限流或超额 | | 503 | `service_unavailable` | 服务暂时不可用 | ## 常见问题 1. **支持哪些模型?** 以模型广场实时目录为准(文档「模型与能力」章实时读取)。 2. **生图为什么 16:9 被改尺寸?** 上游仅支持 2^n 比例,非支持比例静默降级为 1024x1024。 3. **图片链接多久失效?** 平台转存链接保留 7 天,到期自动清理,请及时转存。 4. **兼容哪些客户端?** OpenAI/Anthropic/Gemini 标准 SDK 与主流客户端(Claude Code、Cherry Studio、cc-switch 等)零改造接入。 5. **密钥泄露怎么办?** 立即在控制台删除该 API Key 并换新;已删除密钥即刻失效(401 token_invalid)。 6. **429 如何处理?** 遵循退避重试;持续 429 说明触发限流或超额,请降低并发或充值。 --- ## 端点参考(API Reference) ### 模型查询 | 方法 | 路径 | 说明 | |---|---|---| | GET | `/v1/models` | 模型列表(三协议自适应) — 携带 `anthropic-version` 请求头 → Anthropic 格式;携带 `x-goog-api-key` 头或 `?key=` 参数 → Gemini 格式;否则 OpenAI 格式。可见性 = 可服务的已发布聚合模型 ∪ 本人自用调用名 ∪ 本人用户级聚合名;AUTO 开启时含 `auto` 虚拟名。 | | GET | `/v1/models/{model_path}` | 单模型查询 — 模型名支持 `vendor/model` 斜杠形态(单段参数不吞斜杠)。不带 `anthropic-version` 头按 OpenAI 格式;带头按 Anthropic 格式。不可服务/不存在的聚合按 404 处理。 | | GET | `/v1beta/models` | 模型列表(Gemini 格式) | | GET | `/v1beta/openai/models` | 模型列表(v1beta 下 OpenAI 格式) | ### 文本对话 | 方法 | 路径 | 说明 | |---|---|---| | POST | `/v1/models/{model_path}` | Gemini 中继(/v1/models/{model}:{action} 形态) — Gemini 协议入站的 /v1/models 路径中继分支,经 Distribute 解析模型名后按 Gemini 信封转发。 | | POST | `/v1beta/models/{path}` | Gemini generateContent 中继 — Gemini API 原生路径 `/v1beta/models/{model}:{action}`(generateContent / streamGenerateContent 等),按 Gemini 信封转发。 | | POST | `/v1/chat/completions` | 对话补全(OpenAI 兼容) | | POST | `/v1/completions` | 文本补全(OpenAI 兼容 legacy) | | POST | `/v1/messages` | Claude Messages(Anthropic 原生) — Anthropic Messages API 形态;Base URL 填根地址(SDK 自动拼接 /v1/messages)。请求须带 `anthropic-version` 头;鉴权 `x-api-key` 与 Bearer 均可。`max_tokens` 必填。 | | POST | `/v1/responses` | OpenAI Responses | | POST | `/v1/responses/compact` | OpenAI Responses(压缩形态) | | POST | `/v1/alpha/search` | Codex 独立联网搜索(Alpha) | | GET | `/v1/realtime` | Realtime WebSocket — OpenAI Realtime WebSocket 升级端点。 | | POST | `/v1/moderations` | 内容审核 | ### 图像生成 | 方法 | 路径 | 说明 | |---|---|---| | POST | `/v1/images/generations` | 图像生成 — 按次计费(单价 × 张数系数 × 尺寸系数)。size 支持 2^n 比例(512x512 / 1024x1024 / 1024x1536 / 1024x1792 / 4096x4096),16:9 等非 2^n 比例静默降级 1024x1024。返回平台转存链接(/api/image/...),保留 7 天。水印三态:official / PingToken / 自定义(平台启用自定义时 watermark_text 必填 ≤64 字符)。 | | POST | `/v1/images/edits` | 图像编辑 — 须携带 1~5 张参考图,单张 ≤10MB。 | | POST | `/v1/edits` | 图像编辑(别名,与 /v1/images/edits 等价) | ### 视频生成 | 方法 | 路径 | 说明 | |---|---|---| | POST | `/v1/video/generations` | 视频生成(异步任务创建) | | GET | `/v1/video/generations/{task_id}` | 视频任务查询 | | POST | `/v1/videos` | 视频创建(OpenAI videos 兼容) | | GET | `/v1/videos/{task_id}` | 视频任务查询(OpenAI videos 兼容) | | GET | `/v1/videos/{task_id}/content` | 视频内容下载 — 接受令牌鉴权(Token Key)或会话鉴权(dashboard)。 | | POST | `/v1/videos/{video_id}/remix` | 视频再创作(remix) | | POST | `/kling/v1/videos/text2video` | Kling 文生视频 | | POST | `/kling/v1/videos/image2video` | Kling 图生视频 | | GET | `/kling/v1/videos/text2video/{task_id}` | Kling 文生视频任务查询 | | GET | `/kling/v1/videos/image2video/{task_id}` | Kling 图生视频任务查询 | | POST | `/jimeng/?Action=…` | 即梦官方 API 直通(火山引擎 Action 形态) — 映射到官方 `?Action=CVSync2AsyncSubmitTask&Version=2022-08-31` 与 `?Action=CVSync2AsyncGetResult&Version=2022-08-31`。 | ### 音频 | 方法 | 路径 | 说明 | |---|---|---| | POST | `/v1/audio/speech` | 语音合成(TTS) | | POST | `/v1/audio/transcriptions` | 语音转写 | | POST | `/v1/audio/translations` | 语音翻译 | ### 向量与重排序 | 方法 | 路径 | 说明 | |---|---|---| | POST | `/v1/embeddings` | 向量嵌入 | | POST | `/v1/engines/{model}/embeddings` | 向量嵌入(legacy engines 形态) | | POST | `/v1/rerank` | 重排序 | ### SystemOne 决策 | 方法 | 路径 | 说明 | |---|---|---| | POST | `/v1/systemone` | SystemOne 决策协议 — 决策线专用端点(不可经 /v1/chat/completions 调用,否则 400)。与 TypeSafe 直连 wire 同形(drop-in)。计费与 chat 完全同构(按 usage token 计费)。约束:questions 必填且 ≤32 题;整体 body ≤64KiB;题型 ∈ noul / boolean / choice / score。 | ### 余额与用量 | 方法 | 路径 | 说明 | |---|---|---| | GET | `/v1/balance` | 令牌余额查询 | | GET | `/v1beta/balance` | 令牌余额查询(Gemini 形态) | | GET | `/v1/dashboard/billing/subscription` | OpenAI legacy billing 配额查询 — `hard_limit_usd − total_usage_usd` 一步得剩余余额(cc-switch Usage Script 等工具推荐算法)。无限额度令牌 `*_usd` 回报 1e8。`/dashboard/billing/subscription` 双形态等价。 | | GET | `/v1/dashboard/billing/usage` | OpenAI legacy billing 用量查询 — `{object:"list",total_usage}`(美分);`daily_costs` 不返回。`/dashboard/billing/usage` 双形态等价。 | | GET | `/dashboard/billing/subscription` | OpenAI legacy billing 配额查询(无 /v1 前缀形态) | | GET | `/dashboard/billing/usage` | OpenAI legacy billing 用量查询(无 /v1 前缀形态) |