免费 API 导入

GET/POST /admin/api/v1/free-api/* · 导入 OpenAI 兼容免费 API Key 并自动生成模型路由。

免费 API 导入用于把 Groq、Cerebras、OpenRouter、GitHub Models 等 OpenAI 兼容服务接入 CokeAPI 号池。导入后系统会创建 upstream 账号、归入独立账号组，并可自动生成 free/<provider>/<model> 公开模型路由。

该接口属于管理后台接口，使用管理员登录态 Bearer Token 鉴权，不使用对外 /v1 的 sk- API Key。360 相关供应商或 360.cn / 360.com Base URL 已禁用，不能导入。

使用流程

调用 GET /admin/api/v1/free-api/catalog 获取支持的免费 API 供应商与模型清单。
选择供应商、填写一个或多个 API Key。
调用 POST /admin/api/v1/free-api/import 导入账号。
如 generate_routes=true，系统会写入 billing.model_prices 并生成公开模型名。
用户使用 POST /v1/chat/completions 调用返回的 generated_models。

Catalog 接口

项目	值
Method	`GET`
Path	`/admin/api/v1/free-api/catalog`
鉴权	管理员 Bearer Token

Catalog 响应字段

参数	类型	必填	默认值	说明
provider_key	string	是	—	供应商标识，如 `groq`、`openrouter`、`custom`
display_name	string	是	—	展示名称
base_url	string	是	—	默认 OpenAI 兼容 Base URL
auth_type	string	是	—	当前为 `api_key`
platform	string	是	—	当前为 `openai`
default_model	string	否	—	默认导入模型
models	array	是	—	可导入模型列表
rpm_limit	int	否	0	建议账号级 RPM 限制
tpm_limit	int	否	0	建议账号级 TPM 限制
daily_quota	int	否	0	建议每日额度
monthly_quota	int	否	0	建议每月额度
risk_level	string	否	—	风险级别：`likely_ok`、`caution`、`custom`
risk_note	string	否	—	供应商使用限制说明
docs_url	string	否	—	供应商官方文档

导入接口

项目	值
Method	`POST`
Path	`/admin/api/v1/free-api/import`
鉴权	管理员 Bearer Token

curl https://admin.cokeapi.com/admin/api/v1/free-api/import \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_key": "groq",
    "api_keys": ["gsk_xxx", "gsk_yyy"],
    "models": ["llama-3.3-70b-versatile"],
    "generate_routes": true
  }'

import httpx

resp = httpx.post(
    "https://admin.cokeapi.com/admin/api/v1/free-api/import",
    headers={"Authorization": "Bearer <admin_token>"},
    json={
        "provider_key": "groq",
        "api_keys": ["gsk_xxx", "gsk_yyy"],
        "models": ["llama-3.3-70b-versatile"],
        "generate_routes": True,
    },
)
resp.raise_for_status()
print(resp.json()["data"])

const resp = await fetch("https://admin.cokeapi.com/admin/api/v1/free-api/import", {
  method: "POST",
  headers: {
    Authorization: "Bearer <admin_token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    provider_key: "groq",
    api_keys: ["gsk_xxx", "gsk_yyy"],
    models: ["llama-3.3-70b-versatile"],
    generate_routes: true,
  }),
});

if (!resp.ok) throw new Error(await resp.text());
console.log((await resp.json()).data);

请求参数

参数	类型	必填	默认值	说明
provider_key	string	是	—	Catalog 返回的供应商标识。`custom` 表示自定义 OpenAI 兼容端点
api_key	string	否	—	单个 API Key，支持用换行或逗号分隔多个 Key
api_keys	array	否	—	多个 API Key。`api_key` 和 `api_keys` 至少填一个
base_url	string	否	Catalog 默认值	自定义 Base URL；`custom` 必填
models	array	否	default_model	要导入的上游模型。非 `custom` 供应商只能选择 Catalog 中存在的模型
name	string	否	`freeapi-<provider>`	账号名称前缀。批量导入时自动追加序号
weight	int	否	10	账号池权重，范围 1–1000
priority	int	否	100	加入账号组时的优先级，范围 1–1000
route_weight	int	否	1	自动路由权重，范围 1–1000
rpm_limit	int	否	Catalog 默认值	覆盖账号级 RPM 限制，0 表示不限制
tpm_limit	int	否	Catalog 默认值	覆盖账号级 TPM 限制，0 表示不限制
daily_quota	int	否	Catalog 默认值	覆盖账号每日额度，0 表示不限制
monthly_quota	int	否	Catalog 默认值	覆盖账号每月额度，0 表示不限制
generate_routes	bool	否	false	是否自动创建 `free/<provider>/<model>` 公开路由

响应示例

管理后台接口统一返回 { code, msg, data, trace_id }：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "imported": 2,
    "skipped": 0,
    "account_id": 123,
    "group_id": 45,
    "routes_created": 1,
    "generated_models": [
      "free/groq/llama-3.3-70b-versatile"
    ]
  },
  "trace_id": "01HX..."
}

路由生成规则

字段	值
provider	`upstream`
channel	`provider_key`
upstream_model	选中的上游模型 ID
model_code	`free/<provider_key>/<upstream_model>`
kind	`chat`
input/output 价格	`0`

例如导入 Groq 的 llama-3.3-70b-versatile 后，用户可直接调用：

curl https://cokeapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "free/groq/llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "你好"}]
  }'

错误码

code	type	含义	HTTP
400101	`invalid_param`	参数错误、未知 provider、Base URL 非法、未选择模型或未填写 API Key	400
401101	`unauthorized`	未登录管理后台	401
403101	`forbidden`	非管理员或无权限	403
500001	`internal`	服务未初始化、AES 加密失败或系统配置异常	500
500002	`db_error`	账号、账号组或系统配置写入失败	500

注意事项

API Key 会在入库前加密存储，并用 provider_key + base_url + api_key 计算哈希去重；重复导入会计入 skipped。
generate_routes=true 会修改系统配置 billing.model_prices，建议先在测试环境验证。
custom 供应商适合接入任意 OpenAI 兼容服务，但必须自行确认服务条款、额度和稳定性。
360 相关 provider 名或 Base URL 会被拒绝导入。

本页目录