BYOK

BYOK（自带密钥，Bring Your Own Key）让你为受支持的提供商（OpenAI、Anthropic、Google）注册自己的上游凭据。注册之后，VibeToken 会在每个经该提供商路由的请求中使用它——费用直接计入你的上游账户；VibeToken 绝不会对 BYOK 调用向你收费。 这是数据，而非调用方令牌。 你永远不会在 Authorization 请求头中向 VibeToken 出示 BYOK 凭据。你只需通过下面的端点注册一次；VibeToken 会在请求时静默地使用它。 这些端点的鉴权方式： JWT（已登录的控制台会话）或 API Key。

运行时行为

当对 /v1/chat/completions（或图像 / 视频 / 音频）的调用解析到某个你已配置 BYOK 凭据的提供商时：

候选项按 priority DESC, created_at DESC 排序。disabled=true 的行会被排除。
每个候选项尝试一次。成功时 last_used_at 前移，last_error 清空。
失败时记录 last_error，并尝试下一个候选项。
若没有任何候选项成功：
- 如果该提供商下你的任意一行设置了 always_use=true → 返回上游错误。不会回退到平台密钥。
- 否则 → VibeToken 会回退到它针对该提供商的平台凭据。

列出提供商密钥

GET https://vibetoken.cn/api/v1/byok

查询参数

string

筛选到单个提供商：openai、anthropic 或 google。

响应

[
  {
    "id": "01J...",
    "provider": "openai",
    "label": "My OpenAI (prod)",
    "api_key_prefix": "sk-proj-…",
    "base_url": null,
    "config_json": null,
    "always_use": false,
    "disabled": false,
    "priority": 0,
    "last_used_at": "2026-04-23T12:00:00Z",
    "last_error": null,
    "created_at": "2026-04-22T09:00:00Z",
    "updated_at": "2026-04-23T12:00:00Z"
  }
]

明文的 api_key 永远不会被返回。config_json 中的敏感字段（secretAccessKey、private_key、api_key、token 等）会被掩码为 "***"。

创建提供商密钥

POST https://vibetoken.cn/api/v1/byok

请求体

string

必填

openai、anthropic、google 之一。

string

必填

1–100 个字符。面向用户的名称，例如 “Personal OpenAI (prod)”。

string

上游凭据。除非由 config_json 携带（例如 Vertex 服务账户 JSON），否则必填。

string

可选，覆盖上游的 base URL。必须为 HTTPS。

object

提供商特定的额外配置（例如 Azure {endpoint_url, deployment_id}、Bedrock {region, …}、Vertex 服务账户 JSON + region）。此对象内的密钥字段会在所有读取响应中被掩码。

boolean

默认值:"false"

设为 true 时，若该提供商的每个 BYOK 候选项都失败，则禁用平台密钥回退。

number

默认值:"0"

限定在 [-1000, 1000] 范围内。当同一 (user, provider) 存在多行时，值更高者胜出。相同时按 created_at DESC 决定。

示例

curl -X POST https://vibetoken.cn/api/v1/byok \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "label": "My OpenAI (prod)",
    "api_key": "sk-proj-xxxxxxxxxxxx",
    "always_use": true
  }'

更新提供商密钥

PUT https://vibetoken.cn/api/v1/byok/{id}

以下任意子集：

string

object

boolean

暂停凭据而不删除它。true 会将其从候选列表中排除。

number

删除提供商密钥

DELETE https://vibetoken.cn/api/v1/byok/{id}

返回 204。对该提供商的下一次推理调用会跳过已删除的行。

轮换凭据

安全的做法是先增后删：

# 1. Add the new credential (will be tried first due to higher created_at)
curl -X POST .../byok -d '{"provider":"openai","label":"prod-2026-04","api_key":"sk-proj-NEW"}'

# 2. Verify by making a normal /v1/chat/completions call — check `last_used_at` on the new row

# 3. Delete the old credential
curl -X DELETE .../byok/<old-id>

快速开始

API 参考

运行时行为

列出提供商密钥

查询参数

响应

创建提供商密钥

请求体

示例

更新提供商密钥

删除提供商密钥

轮换凭据

​运行时行为

​列出提供商密钥

​查询参数

​响应

​创建提供商密钥

​请求体

​示例

​更新提供商密钥

​删除提供商密钥

​轮换凭据

运行时行为

列出提供商密钥

查询参数

响应

创建提供商密钥

请求体

示例

更新提供商密钥

删除提供商密钥

轮换凭据