Source: https://01router.com/zh/docs/agent
Base URL: https://01router.com/api/v1

# Agent 接入

把下方文档地址直接交给编程 Agent，让它将 01router 的多模型能力接入你的系统：配置连接、获取模型及字段价格、预估积分、提交请求、轮询结果。

- 正式接口地址: `https://01router.com/api/v1`
- 沙箱接口地址: `https://01router.com/api/sandbox/v1`

## 交给 Agent 的文档地址

```text
https://01router.com/docs/llms-full.txt?locale=zh&section=agent
```

## 复制给 Agent 的提示词

```text
阅读 https://01router.com/docs/llms-full.txt?locale=zh&section=agent，将 01router 的完整多模型流程接入当前系统。连接配置只需要 Base URL、API Key 和可选 Project ID，不配置固定模型。动态获取模型列表：不传 project 返回全部平台模型，传入 project 返回该项目配置下可用的模型。支持选择模型、读取字段与价格、按输入预估积分、提交请求、轮询展示结果；切换模型时更新参数表单和报价。复用现有技术栈，密钥仅保存在服务端，按文档区分真实目录/报价与沙箱模拟，汇报修改文件、配置步骤及实际验证范围。
```

## 服务端环境变量示例

```dotenv
ROUTER01_BASE_URL=https://01router.com/api/v1
ROUTER01_API_KEY=YOUR_PROJECT_API_KEY
ROUTER01_PROJECT_ID=
```

## 完整接入流程（路径相对于 Base URL）

```text
配置 Base URL + API Key + Project ID（选填）
  ↓
GET /models                         不传 project：全部平台模型
GET /models?project=PROJECT_ID       传 project：项目配置下可用的模型
  ↓ 用户选择模型（slug）
GET /models/MODEL_SLUG               平台模型：读取字段、供应商和价格
项目目录 data 中选中的模型对象        项目模型：直接读取 params、prices、provider
  ↓ 根据字段生成表单，用户填写 input
POST /quote                         预估积分和费用，不扣费
  ↓ 用户确认当前参数和报价
POST /generations                   提交 model、input 及可选 project/provider
  ↓ 保存返回的 id
GET /generations/ID                 每次至少间隔 3 秒，直到 succeeded / failed
  ↓
展示 outputs 或 error，以及实际 credits / price_usd

报价和提交都使用运行时选择的 model；未填写 Project ID 时省略 project。
聊天走 POST /chat/completions，处理 JSON / SSE 响应，不轮询生成任务。
```

## 使用说明

- 开始前：用户只需填写 Base URL、API Key 和选填的 Project ID，可在 https://01router.com/settings/projects 获取项目 ID 和 Key。不要求填写固定模型 ID，model 来自运行时的模型选择。未提供 Key 时，先完成公开模型目录、配置和报价流程，再用占位密钥验证沙箱任务；真实密钥由用户在系统配置中填写，不要粘贴到对话或日志中。
- 1. 检查目标项目：读取项目规范、依赖清单、环境配置、现有 AI 客户端、服务端路由和相关界面。复用现有架构和依赖，明确要实现的用户流程；仅在项目中无法确定时询问需求。
- 2. 配置连接：读取 ROUTER01_BASE_URL、ROUTER01_API_KEY 和选填的 ROUTER01_PROJECT_ID（或系统中的等价配置）。Base URL 使用当前服务的 /api/v1 地址，接口路径只追加一次。Project ID 为空时完全省略 project 参数，不发送 ?project=；有值时，目录查询使用 project 查询参数，报价和创建请求使用 JSON 的 project 字段。受保护接口发送 Authorization: Bearer <key>，JSON 请求发送 Content-Type: application/json。API Key 仅存于服务端环境文件或密钥管理中，不能进入浏览器产物、公开环境变量或日志。
- 3. 动态获取模型列表：阅读 https://01router.com/docs/llms.txt?locale=zh 中的接口参考。无 Project ID 时请求 GET https://01router.com/api/v1/models，返回全部平台模型；有 Project ID 时请求 GET https://01router.com/api/v1/models?project=PROJECT_ID，返回项目配置下可用的模型（若项目开启「全部模型」，也包含平台模型）。两者都从 data 数组读取，可追加 type 过滤。使用 slug 作为选择值，展示 name、type 等信息；更换项目后刷新列表、清除无效选择，不硬编码模型清单。目录公开可读，但实际调用仍受 API Key 所属项目限制，配置的 Project ID 必须与 Key 对应。
- 4. 获取选中模型的字段和价格：无 Project ID 时请求 GET /models/MODEL_SLUG，读取 params、providers[].params、providers[].prices、fromMicros 和 fromUnit；有 Project ID 时直接读取项目列表中对应 slug 的完整配置，包括 params、prices、provider、fromMicros 和 fromUnit。当前 /models/MODEL_SLUG 只查询平台模型，不支持 project 过滤，也不能用项目自定义 slug 查询。根据 params 的 name、type、required、default、options、min、max、maxItems、maxLength 动态生成和校验表单；平台模型指定供应商时采用该供应商的字段约束。切换模型时清除不兼容字段。价格规则包含 unit、conditions、priceMicros，美元金额为 priceMicros / 1,000,000；fromMicros 只是起步单价，不是本次请求的总价。
- 5. 预估本次生成的积分：用户选定模型并填写参数后，向正式 API 的 POST /quote 发送 model（选中的 slug）和 input（表单参数）；配置了 Project ID 时带 project，显式选择供应商时带 provider。无需 API Key，也不扣积分。读取 providers 中的 credits、price_usd、unit、quantity，并展示 unavailable 原因；参数变化时防抖重新报价，忽略过期响应。供应商按价格排序，未指定时第一项是默认候选；若允许用户选择报价，提交时保持相同的模型、参数和供应商，项目固定供应商优先。/quote 返回平台扣费预估，项目目录价格可包含售价比例，不要将两者混用，也不要硬编码美元到积分的换算比例。最终以任务实际返回的 credits、price_usd 为准。聊天按实际 token 用量结算，不把生成任务报价当成聊天最终费用。
- 6. 提交请求：图片、视频和音频使用 POST /generations，发送与当前报价一致的 model 和 input，以及适用的 project、provider。model 每次取当前选择，不从固定环境变量读取。API Key 自动关联其所属项目，project 可省略；显式填写时必须与 Key 所属项目一致，否则返回 403。保存返回的 id 和状态，避免按钮重复提交。聊天使用 POST /chat/completions，传 model、messages 及适用的 project/provider，按需要处理普通响应或 stream=true 的 SSE；聊天不走生成任务轮询。需要同步生图时按 /images/generations 文档接入。
- 7. 轮询结果：对异步生成任务，以至少 3 秒间隔请求 GET /generations/ID，携带同一 API Key，并设置总超时。queued、processing 时继续等待，succeeded 时展示 outputs、credits 和 price_usd，failed 时展示 error 并停止。保存任务 ID，页面恢复时继续查询已有任务；停止轮询不等于取消任务。同步生图返回 504 且带有 error.id 时，轮询该 ID，不重新提交。
- 8. 处理异常：非 2xx 响应读取 error.message 和 error.code，分别处理鉴权失败（401）、余额不足（402）、权限限制（403）、参数错误（400）、模型或项目不存在（404）和限流（429）。可重试的读取请求使用有上限的退避策略。创建任务或聊天请求发生结果不明的网络错误时，不盲目重试，以免重复执行和计费。
- 9. 分阶段验证：用正式 API 验证无项目/有项目的模型列表、动态字段、价格展示和 /quote（这些公开读取和报价不扣费）。再按 https://01router.com/docs/llms-full.txt?locale=zh&section=sandbox 使用沙箱 https://01router.com/api/sandbox/v1 验证任务提交、轮询与 X-Sandbox-Error 错误流程，没有真实 Key 时可使用 sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。沙箱不支持 /quote，也不模拟项目模型映射、项目限制、模型专属参数校验或真实价格，不能用沙箱证明这些能力已验证。至少检查切换模型和参数后报价刷新、成功与失败终态以及轮询超时。
- 10. 交付完整流程：按目标项目规范运行相关检查，补充三个连接配置项（Project ID 选填）和使用说明，列出修改文件及已验证步骤。正式 Base URL 为 https://01router.com/api/v1，沙箱地址仅用于模拟测试。真实付费调用前确认用户授权和有效 Key；沙箱与生产任务 ID 分开处理，明确尚未验证的流程，不将模拟结果当作生产接入成功。