API 使用说明

账号注册

注册福利

🔗 注册链接：点击注册

配置步骤

1. 获取令牌

登录后台系统
进入"令牌"页面
点击"添加令牌"获取 API Key

提示：创建令牌时可同时配置智能路由模式，让系统自动帮你选择最优渠道，详见下方「智能路由」章节。

2. 接口配置

BASE_URL 可选地址

https://4zapi.com
https://4zapi.com/v1
https://4zapi.com/v1/chat/completions

注意：不同客户端可能需要使用不同的 BASE_URL，建议依次尝试以上地址

3. 模型选择

模型名称位于首页 → "支持模型"列表的第一列

配置示例

{
  "base_url": "https://4zapi.com",
  "api_key": "your_token_here",
  "model": "selected_model_name"
}

智能路由

智能路由让你在不更改代码的情况下灵活控制每次请求的渠道选择策略，实现价格最低、速度最快、成功率最高或全局最优路由。

路由模式一览

模式	说明
系统默认	不设置，由平台全局策略决定
智能自动（`auto`）	跨所有可访问渠道，综合速度 / 成功率 / 价格自动选最优
价格优先（`price`）	选当前可用渠道中单价最低的
速度优先（`speed`）	选当前可用渠道中响应速度最快的
成功率优先（`success_rate`）	选近期成功率最高的渠道

三种设置方式

路由模式支持三种设置方式，优先级从高到低：

模型名后缀  >  请求体 provider.sort  >  令牌路由模式

方式一：模型名后缀（最简单，单次生效）

在模型名末尾加上冒号后缀，无需修改任何配置，即可对本次请求应用指定路由模式。

{
  "model": "gpt-6-luna:price",
  "messages": [...]
}

支持的后缀：

后缀	效果	兼容写法（OpenRouter 风格）
`:price`	价格最低	`:floor`
`:speed`	速度最快	`:nitro`
`:success_rate`	成功率最高	`:stable`

后缀只影响路由选择，不会传递给上游模型。不在列表中的后缀（如 :beta、:v2）会原样保留在模型名中。

方式二：请求体 `provider.sort`（单次生效）

在请求体中加入 provider 字段，仅对本次请求生效，不影响令牌的持久配置。

{
  "model": "gpt-6-luna",
  "messages": [{"role": "user", "content": "你好"}],
  "provider": {
    "sort": "speed"
  }
}

provider.sort 支持的值：price / speed / success_rate / floor / nitro / stable

注意：provider.sort 不支持 "auto"，传入 "auto" 或未知值会被忽略，自动回落到令牌配置的路由模式。

方式三：令牌路由模式（推荐，持久生效）

在创建或编辑令牌时选择路由模式，对该令牌的所有请求永久生效，调用方无需额外操作。

操作路径：令牌管理 → 新建/编辑令牌 → 路由优先模式

选项	适用场景
系统默认（不设置）	无特殊需求，跟随平台全局策略
智能自动（auto）	希望平台自动寻找全局最优渠道，无需手动维护
价格优先（price）	预算敏感型任务，优先控制成本
速度优先（speed）	实时交互场景，优先响应延迟
成功率优先（success_rate）	重要任务，优先保障成功率

智能自动（auto）说明：

会自动扩展渠道候选范围到账号下所有可访问分组，不受令牌原始分组限制

综合速度、成功率、价格三个维度评分，实时选出最优渠道

计费倍率以实际路由到的渠道所属分组为准

路由预览（配置前先模拟）

在正式切换路由模式前，可通过路由预览接口查看不同模式下会路由到哪个渠道、预计费率是多少：

GET https://4zapi.com/api/user/routing-preview?model=gpt-6-luna&priority=price&prompt_tokens=500

参数	说明
`model`	必填，要查询的模型名
`priority`	可选，模式：`auto` / `price` / `speed` / `success_rate`
`prompt_tokens`	可选，输入 Token 数，用于估算费用

返回示例：

{
  "priority_applied": "price",
  "estimated_group": "standard",
  "estimated_price_per_1k": 0.002,
  "price_multiplier": 0.4,
  "warning": false,
  "channel_available": true,
  "prompt_tokens": 500,
  "estimated_cost": 1.0
}

字段	说明
`estimated_group`	预测路由到的渠道分组
`estimated_price_per_1k`	每 1000 Token 预计单价（美元）
`price_multiplier`	与系统默认 auto 模式的价格倍率（< 1 表示更便宜）
`warning`	`true` 表示该模式比 auto 贵 1.5 倍以上，建议留意
`estimated_cost`	按输入 Token 数估算的本次请求费用

常见问题

Q：模型名后缀和 provider.sort 同时设置，哪个生效？

模型名后缀优先级更高。设置了 :price 后缀后，即使请求体中有 provider.sort，也会以后缀为准。

Q：令牌设置了路由模式，调用时还能临时切换吗？

可以。在请求体中加入 provider.sort 或使用模型名后缀，均可覆盖令牌配置的路由模式，且只对该次请求生效，不影响令牌设置。

Q：auto（智能自动）和不设置路由模式有什么区别？

两者都使用综合评分算法，但 auto 会额外扩展候选渠道到账号下所有可访问分组，找到更大范围内的最优选择；不设置则仅在令牌配置的分组内选渠道。

Q：使用 auto 模式路由到了其他分组，费率会变吗？

会。计费倍率以实际路由到的渠道所属分组为准。建议使用路由预览接口提前确认目标分组和预计费率。

测试验证

可通过以下方式验证配置是否正确：

在聊天页面进行在线测试
使用 API 工具（如 Postman、curl）进行接口测试
使用路由预览接口确认智能路由生效

提示：建议先在聊天页面进行测试，确认配置正确后再进行开发集成