服务 API

kimi web 启动的本地服务暴露两组程序化接口：REST API（/api/v1，另有 /api/v2/sessions 和 /api/v2/mcp）和 WebSocket 事件流（/api/v1/ws）。本页是这两组接口的协议参考。如何启动服务及其命令行选项见 kimi 命令 参考；端到端的上手流程见下文「用 API 驱动一个会话」。

本页是一份经过整理、面向人阅读的参考：下文逐一记录每个端点的参数、请求体与响应结构。每个端点精确的机器可读 schema 以服务的在线规范文档为准：GET /openapi.json（OpenAPI）与 GET /asyncapi.json（AsyncAPI），两者都由服务运行时实际执行的校验 schema 生成。两者都需要鉴权；当本页与在线规范不一致时，以在线规范为准。

注意

本页描述的 REST 与 WebSocket API 为实验性特性：不保证接口稳定性，端点、字段与事件类型可能随任何版本更改。集成时请以你所用版本服务的 /openapi.json 与 /asyncapi.json 文档为准。

基础约定

地址

默认地址为 http://127.0.0.1:58627。端口被占用时，服务会用下一个端口重试（至多 100 次）；可用 --port / --host 修改绑定。同一 home 目录下可并存多个实例，运行中的实例登记在 ~/.kimi-code/server/instances/。

鉴权

除以下例外，所有 /api/* 路径（含 /openapi.json 与 /asyncapi.json）都要求 bearer token：

• OPTIONS 预检请求
• GET /api/v1/healthz（探活）
• 静态 web 资源（非 /api/ 路径）

携带方式：REST 用 Authorization: Bearer <token> 请求头；WebSocket 升级请求接受同一请求头，或子协议 kimi-code.bearer.<token>。token 的生成与轮换见 在网页中使用：开始使用。

鉴权失败返回 HTTP 401，信封 code 为 40101。在非 loopback 绑定上，同一来源 60 秒内鉴权失败 10 次会被封禁 60 秒，期间每个请求都返回 HTTP 429（code 为 42901）。

响应信封

所有 JSON 响应统一包在信封里：

{
  "code": 0,
  "msg": "success",
  "data": {},
  "request_id": "01JZX4A6E7M8V0R3Q0N2K2M5Q9"
}

• code：业务结果，0 表示成功；错误码分段见下文。
• data：成功时的业务数��。注意部分「错误」信封也携带非空 data——例如重复解决审批返回 40902 且 data.resolved 为 false——客户端应先判 code 再看 data。
• request_id：本次请求的 ULID；客户端可用 X-Request-Id 请求头指定，非法值会被服务端重新生成。

HTTP 状态码几乎总是 200，业务结果以 code 为准。例外情况：

场景	HTTP 状态
鉴权失败 / 触发限流	401 / 429
创建供应商、导入供应商目录成功	201
删除供应商成功	204
二进制与流式端点	支持时返回 206（Range 分段）/ 304（ETag 未变），各端点能力不同，详见「二进制与流式端点」
GET /api/v1/files/{file_id} 下载错误	真实 404 / 500（响应体仍为信封）

其中 201 的响应体仍是标准信封（code 为 0），只是状态行遵循 REST 的资源创建惯例；204 按定义没有响应体，删除成功以状态码本身为准。

错误码

错误码按段位分组：

段位	含义	示例
0	成功
400xx	请求参数错误	40001 校验失败（details 逐字段说明）、40003 供应商由 OAuth 托管
401xx	鉴权与就绪状态	40101 未授权、40110 未配置供应商、40113 模型未解析
404xx	资源不存在	40401 会话、40408 MCP 服务、40409 文件路径
409xx	状态冲突	40901 会话忙、40902 审批已解决、40922 分页条件与 page_token 不符
410xx	资源已过期	41001 审批超时、41002 提问超时、41003 临时文件过期
413xx	体积或边界超限	41302 读取文件超 10 MB、41304 路径越出会话目录
429xx	限流	42901 鉴权失败封禁、42902 文件监听数超限
500xx	服务端内部错误	50001 未捕获异常、50003 持久化失败
6xxxx / 7xxxx / 8xxxx	工具运行时 / LLM 供应商 / MCP 透传错误，msg 保留上游原文

分页

列表端点有两种分页风格：

• 游标式：before_id / after_id（互斥）加 page_size（1–100），响应为 { items, has_more }。用于会话列表、消息列表、转录等。
• page_token：不透明令牌（绑定了查询条件的指纹），用于 POST /api/v1/search 与 GET /api/v2/sessions。翻页途中改变任何查询条件会使令牌失效：v2 返回 40922，search 返回 40001。GET /api/v2/sessions 另提供无状态的 page 页码模式作为替代。

用 API 驱动一个会话

下面用 curl 走一遍最小流程：确认服务状态 → 创建会话 → 订阅事件 → 提交提示词 → 回读历史。示例假设服务跑在默认地址，token 已存入 shell 变量 TOKEN。

1. 确认服务状态：

curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:58627/api/v1/meta

所有 JSON 响应都包在统一信封里——{ "code": 0, "msg": "success", "data": ..., "request_id": "..." }，业务结果以 code 为准（0 表示成功），HTTP 状态码只表达传输层结果。

2. 创建会话，metadata.cwd 指定工作目录：

curl -s -X POST http://127.0.0.1:58627/api/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"cwd": "/path/to/project"}}'

返回的 data.id（形如 session_...）就是后续所有请求要用的会话 id。

3. 连接 WebSocket 并订阅会话事件。任何 WebSocket 客户端都可以；下面是一个零依赖的 Node.js 脚本（Node.js 22+ 内置 WebSocket 客户端）：

// subscribe.mjs —— 用法：TOKEN=... node subscribe.mjs session_...
const ws = new WebSocket('ws://127.0.0.1:58627/api/v1/ws', [
  `kimi-code.bearer.${process.env.TOKEN}`,
]);
ws.onmessage = (e) => console.log(e.data);
ws.onopen = () =>
  ws.send(
    JSON.stringify({
      type: 'subscribe',
      id: '1',
      payload: { session_ids: [process.argv[2]] },
    }),
  );

4. 提交提示词：

curl -s -X POST http://127.0.0.1:58627/api/v1/sessions/<session_id>/prompts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": [{"type": "text", "text": "用一句话介绍这个仓库"}]}'

订阅端会依次看到 turn.started（轮次开始）→ assistant.delta（流式文本增量）→ 发生工具调用时的 tool.call.started / tool.result → turn.ended（轮次结束）。

5. 随时可以用 REST 回读历史消息：

curl -s -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:58627/api/v1/sessions/<session_id>/messages?page_size=20"

REST 端点

下文按资源分组列出端点。路径里的 :{action} 后缀是动作约定——对单个资源 POST 到 路径:动作 执行非 CRUD 操作（如会话的 :fork、:archive）。

服务与元信息

方法与路径	说明
GET /api/v1/healthz	探活，免鉴权
GET /api/v1/meta	服务版本、能力集、server_id、实验开关
POST /api/v1/shutdown	优雅退出（先回 200 再关闭）；仅 loopback 绑定时挂载

GET /api/v1/healthz

供脚本与进程管理器使用的探活端点。它是唯一豁免 bearer token 的 /api 端点（见 鉴权），应答时不触碰配置与引擎。

成功时 data 为 { "ok": true }。

GET /api/v1/meta

返回本实例的身份信息与能力集。大多数字段在启动时即固定；experimental_flags 与 features 按请求实时解析，因此开关翻转或某个 feature 失败会体现在下一次响应中。

成功时 data 携带：

字段	类型	说明
server_version	string	服务版本
capabilities	object	能力集——websocket、file_upload、fs_query、mcp、tasks、terminal，均恒为 true
server_id	string	本服务实例的唯一 id
started_at	string	启动时间，ISO 8601 格式
open_in_apps	array	可作为 open-in 目标的宿主应用（finder / cursor / vscode / iterm / terminal）；目前恒为空
dangerous_bypass_auth	boolean	服务是否以 --dangerous-bypass-auth 启动（客户端可跳过 token 提示）
backend	string	引擎后端，v1 或 v2；本服务恒为 v2
web_title	string	来自 --web-title 的自定义浏览器标签页标题；未设置时省略
experimental_flags	object	实验开关 id → 是否启用，按请求时解析
features	array	引擎 feature，形如 { name, state, meta }；state 为 Pending / Activating / Active / Unloading / Failed

POST /api/v1/shutdown

请求服务优雅退出。响应先发出，随后立即执行关闭，因此调用方可以信任收到的响应。该路由仅在 loopback 绑定时挂载——非 loopback 绑定时它根本不会被注册（请求得到 404），除非服务以 --allow-remote-shutdown 启动。

成功时 data 为 { "ok": true }。

登录与用量

这组端点驱动托管 Kimi OAuth 登录的生命周期，并暴露账号级信息。托管供应商名为 managed:kimi-code；下面每个端点上可选的 provider 参数都默认取它。

方法与路径	说明
GET /api/v1/auth	鉴权状态快照
POST /api/v1/oauth/login	发起 OAuth device-code 登录流程
GET /api/v1/oauth/login	轮询登录流程状态
DELETE /api/v1/oauth/login	取消进行中的登录流程
POST /api/v1/oauth/logout	登出托管供应商
GET /api/v1/oauth/usage	套餐额度与加油包
GET /api/v1/oauth/userinfo	账号资料
GET /api/v1/oauth/region	解析客户端所属区域（mainland-cn / global）

GET /api/v1/auth

鉴权状态快照：默认模型能否解析到可用的供应商配置，以及托管供应商的登录状态。当全局 default_model 别名存在于模型表中且能解析到已配置的供应商时，models_ready 为 true——包括自带 base_url 的平铺（providerless）模型，以及通过 KIMI_MODEL_* 环境变量注入的模型。它不做凭据校验，因此此后的对话请求仍可能以 40111 / 40112 失败。

成功时 data 携带 models_ready（布尔值）、providers_count（已配置供应商数量）与 managed_provider（null，或 { name, status }，其中 status 为 authenticated / expired / revoked / unauthenticated 之一）。全局默认模型别名本身改从 GET /api/v1/config 的 default_model 读取，本端点不再携带。

POST /api/v1/oauth/login

为托管供应商发起 OAuth device-code 登录流程；发起新流程会中止同一供应商进行中的流程。账号已登录时无需用户交互，响应会立即报告 authenticated。

参数	位置	类型	说明
provider	body	string	托管供应商名称。默认 managed:kimi-code
region	body	string	mainland-cn 或 global；覆盖 GET /api/v1/oauth/region 一节描述的区域解析结果，仅对本次流程生效

成功时 data 有两种形态。进行中的流程——{ flow_id, provider, status: "pending", verification_uri, verification_uri_complete, user_code, expires_in, interval, expires_at }：打开 verification_uri_complete（或打开 verification_uri 并输入 user_code），然后每隔 interval 秒轮询 GET /api/v1/oauth/login，直到流程完结或超过 expires_at（expires_in 是以秒表示的同一时限）。已登录的快速路径——{ flow_id, provider, status: "authenticated" }。

GET /api/v1/oauth/login

轮询某供应商的登录流程状态。尚未发起过流程时返回 null。

参数	位置	类型	说明
provider	query	string	托管供应商名称。默认 managed:kimi-code

成功时 data 为 null 或流程快照：{ flow_id, provider, status, verification_uri, verification_uri_complete, user_code, expires_in, expires_at, interval }，其中 status 为 pending / authenticated / denied / expired / cancelled。流程离开 pending 后，resolved_at 记录其到达终态的时间，error_message 描述失败的流程。

DELETE /api/v1/oauth/login

取消某供应商进行中的登录流程。没有进行中的流程时，该调用为空操作，返回最近一次已知状态。

参数	位置	类型	说明
provider	query	string	托管供应商名称。默认 managed:kimi-code

成功时 data 为 { cancelled, status }：只有确实中止了一个 pending 流程时 cancelled 才为 true，status 为调用后的流程状态。

POST /api/v1/oauth/logout

登出托管供应商：丢弃已存储的 OAuth 凭据、中止进行中的登录流程，并把托管供应商从配置中移除。OAuth 托管的供应商拒绝手动编辑与删除（见下文 PUT / DELETE /api/v1/providers/{provider_id}），因此要移除它需先登出。

参数	位置	类型	说明
provider	body	string	托管供应商名称。默认 managed:kimi-code

成功时 data 为 { logged_out: true, provider }。

GET /api/v1/oauth/usage

托管账号的套餐额度与加油包，实时取自账号服务。上游失败不会让信封失败——它以 kind: "error" 的形式带内返回。

参数	位置	类型	说明
provider	query	string	托管供应商名称。默认 managed:kimi-code

成功时 data 为 { kind: "ok", quota } 或 { kind: "error", message, status? }，其中 status 为上游 HTTP 状态码（如存在）。在 ok 形态中，quota 为 { usages, extraUsage }：usages 按窗口携带 { usedRatio, resetAt? } 条目——limit5h、limit7d、monthTotal、monthCode——其中 usedRatio 为 0–1 浮点数，resetAt 为 RFC3339 重置时间，客户端按实际下发的条目渲染；extraUsage（可空）是按量付费钱包：{ balanceCents, totalCents, monthlyChargeLimitEnabled, monthlyChargeLimitCents, monthlyUsedCents, currency }。

GET /api/v1/oauth/userinfo

托管账号的资料，带内 kind: "error" 约定与 GET /api/v1/oauth/usage 相同。

参数	位置	类型	说明
provider	query	string	托管供应商名称。默认 managed:kimi-code

成功时 data 为 { kind: "ok", userInfo } 或 { kind: "error", message, status? }。userInfo 始终携带 userId、nickname、status、region、userLevel、userLevelName、domain、domainName，并可能附加 globalId、bio、avatar、username、email、phone（{ countryCode, number }）、createdTime 与 lastLoginTime。

GET /api/v1/oauth/region

解析该客户端所属的 Kimi 区域。结果在本地推导，不经网络探测：优先取环境变量或配置固定的 OAuth host，其次是已配置的 OAuth key，再次是 home 目录中的区域标记文件；默认为 mainland-cn。

成功时 data 为 { region }，region 为 mainland-cn / global 之一。

配置

方法与路径	说明
GET /api/v1/config	读取全局配置（密钥字段脱敏）
POST /api/v1/config	合并式更新配置，并广播 event.config.changed

GET /api/v1/config

返回解析后的全局配置——config.toml 叠加覆盖层后的生效结果。密钥已脱敏：每个供应商只报告 has_api_key，绝不返回存储的密钥。

成功时 data 为配置对象；其字段与 顶层字段 记录的顶层域一一对应：

字段	类型	说明
providers	object	供应商 id → { type, base_url?, default_model?, has_api_key } 的映射
default_provider	string	全局默认供应商 id
default_model	string	全局默认模型别名
models	object	模型别名 → 模型记录的映射
thinking	object	Thinking 模式的默认参数
plan_mode	boolean	Plan 模式开关
yolo	boolean	派生值：default_permission_mode 为 yolo 时为 true
default_permission_mode	string	新会话的默认权限模式
default_plan_mode	boolean	新会话是否以 Plan 模式启动
permission	object	初始权限规则
hooks	array	生命周期钩子
services	object	内置外部服务配置
merge_all_available_skills	boolean	是否合并所有可用目录中的 Agent Skills
extra_skill_dirs	array	额外的 Skill 搜索目录
loop_control	object	Agent 循环控制参数
background	object	后台任务运行参数
subagent	object	subagent 配置
secondary_model	object	subagent 的次级模型池
experimental	object	实验开关 id → 是否启用
telemetry	boolean	是否启用匿名遥测
raw	object	原始解析的 config.toml 内容，包含未建模字段

POST /api/v1/config

合并式更新全局配置：请求体中的每个顶层域被深合并进对应域，未出现在请求体中的域保持不动。把 yolo 设为 true 是 default_permission_mode: "yolo" 的简写；被拒绝的补丁（值非法或持久化失败）返回 40001 与底层错误信息。

每一次配置变更——经本端点成功更新、在进程外编辑 config.toml，或服务端内部写入（如 OAuth 登录刷新）——都会广播全局 event.config.changed 事件。短时间窗内的多次变更会合并为一个事件，其 changedFields 携带受影响的域名（camelCase 配置域，例如 defaultModel），config 携带当前完整的配置投影（与 GET /api/v1/config 响应同形状）。

请求体是部分配置对象——上述响应域中除 raw 外的任意子集，均为可选：

参数	位置	类型	说明
providers	body	object	供应商 id → 供应商表的映射
default_provider	body	string	全局默认供应商 id
default_model	body	string	全局默认模型别名
models	body	object	模型别名 → 模型记录的映射
thinking	body	object	Thinking 模式的默认参数
plan_mode	body	boolean	Plan 模式开关
yolo	body	boolean	true 映射为 default_permission_mode: "yolo"；false 被忽略
default_permission_mode	body	string	manual / yolo / auto
default_plan_mode	body	boolean	新会话是否以 Plan 模式启动
permission	body	object	初始权限规则
hooks	body	array	生命周期钩子
services	body	object	内置外部服务配置
merge_all_available_skills	body	boolean	是否合并所有可用目录中的 Agent Skills
extra_skill_dirs	body	array	额外的 Skill 搜索目录
loop_control	body	object	Agent 循环控制参数
background	body	object	后台任务运行参数
subagent	body	object	subagent 配置
secondary_model	body	object	subagent 的次级模型池
experimental	body	object	实验开关 id → 是否启用
telemetry	body	boolean	是否启用匿名遥测

成功时 data 为完整的更新后配置，形态与 GET /api/v1/config 相同。

模型与供应商

这组端点管理模型配置的两半——config.toml 的 供应商 表与模型别名表——外加一个由服务端代理的 models.dev 目录，用于一次性导入。模型别名 id 就是配置中的别名键：通过供应商管理端点创建的别名形如 provider_id/model（例如 my-provider/kimi-for-coding），而模型别名表中的裸键（如 turbo）原样使用；API 中任何接收 model_id 的地方（包括全局 default_model）指的都是这个别名 id。:{action} 路由上不支持的动作返回 40001。

方法与路径	说明
GET /api/v1/models	列出已配置的模型别名
POST /api/v1/models/{model_id}:set_default	设置全局默认模型
GET /api/v1/providers	列出供应商
POST /api/v1/providers	创建供应商（201）
GET /api/v1/providers/{provider_id}	读取供应商（含已存密钥）
PUT /api/v1/providers/{provider_id}	整体替换供应商配置
DELETE /api/v1/providers/{provider_id}	删除供应商（204）
POST /api/v1/providers/{provider_id}:refresh	刷新该供应商的模型元数据
POST /api/v1/providers:{action}	集合级动作：refresh / refresh_oauth / import_catalog / import_registry
GET /api/v1/catalog/providers	浏览 models.dev 目录（服务端代理）
GET /api/v1/catalog/providers/{catalog_id}	读取目录中单个条目

GET /api/v1/models

列出所有供应商下已配置的模型别名。

成功时 data.items 为 { provider, model, display_name?, max_context_size, capabilities?, support_efforts?, default_effort? } 数组：model 是别名 id（供应商管理的别名为 provider_id/model，否则为裸键），provider 是所属供应商 id，max_context_size 是以 token 计的上下文窗口，capabilities / support_efforts / default_effort 描述能力标志与 Thinking 模式的 effort 支持。

POST /api/v1/models/{model_id}:set_default

把全局 default_model 设为一个已存在的别名。model_id 是配置中的别名键原样——裸键如 POST /api/v1/models/turbo:set_default；当 id 含 / 时需做 URL 编码，如 POST /api/v1/models/my-provider%2Fkimi-for-coding:set_default。

参数	位置	类型	说明
model_id	path	string	必填。 配置中的模型别名键原样；含 / 时需 URL 编码

成功时 data 为 { default_model, model }——当前生效的别名及其目录项（形态与 GET /api/v1/models 的单项相同）。

• 40001：路径中的动作后缀非法或不支持
• 40413：不存在该 id 的模型别名

GET /api/v1/providers

列出每个已配置供应商及其凭据与模型发现状态，不泄露任何密钥。这也是其他供应商端点引用的供应商条目形态。

成功时 data.items 为如下结构的数组：

字段	类型	说明
id	string	供应商 id
type	string	通信协议：kimi / openai / openai_responses / anthropic / google-genai / vertexai
base_url	string	API 基础 URL，如已设置
default_model	string	该供应商的默认模型别名，如已设置
has_api_key	boolean	是否已存储凭据
status	string	存在 API 密钥或缓存的 OAuth token 时为 connected，否则为 unconfigured（error 在 schema 中保留）
models	array	该供应商的模型别名 id

POST /api/v1/providers

一次保存创建供应商及其模型别名；响应为 HTTP 201 加标准信封。当全局 default_model 完全未配置时（全新安装），会以新供应商的 default_model（或第一个模型）播种；已有默认值绝不被修改。

参数	位置	类型	说明
id	body	string	必填。 供应商 id——字母、数字、-、_ 与空格；必须以字母或数字开头
type	body	string	必填。 通信协议：kimi / openai / openai_responses / anthropic / google-genai / vertexai
api_key	body	string	API 密钥，存储于 config.toml
base_url	body	string	API 基础 URL；不得包含环境变量占位符（${...}）
default_model	body	string	该供应商的默认模型；必须是 models[].model 之一
models	body	array	必填。 至少一条，不允许重复的 model 值；条目结构见下文

每个 models[] 条目声明一个别名，其 id 为 id/model：

字段	类型	说明
model	string	必填。 上游模型名
max_context_size	integer	必填。 以 token 计的上下文窗口，≥ 1
display_name	string	显示名
capabilities	array	能力��志，如 thinking 或 image_in
max_output_size	integer	最大输出 token 数，≥ 1
support_efforts	array	支持的 Thinking 模式 effort 档位
adaptive_thinking	boolean	自适应 thinking 开关

成功时 data 为创建好的供应商条目（形态与 GET /api/v1/providers 的单项相同）。

• 40921：已存在该 id 的供应商

GET /api/v1/providers/{provider_id}

读取单个供应商。与列表路由不同，设置了密钥时响应会暴露存储的 api_key，以便本地编辑表单预填——暴露端口时请牢记这一点。

参数	位置	类型	说明
provider_id	path	string	必填。 供应商 id

成功时 data 为供应商条目，存有密钥时附带 api_key。

• 40412：供应商不存在

PUT /api/v1/providers/{provider_id}

一次保存整体替换供应商：type、base_url 与模型列表被重写，该供应商的别名按 models 重建——不再列出的别名从 config.toml 中消失，其他供应商的别名不受影响。api_key 是三态的：省略表示保留已存密钥，"" 表示清除，其他值表示替换。除 new_id 重命名迁移外，全局默认指针绝不被修改。

参数	位置	类型	说明
provider_id	path	string	必填。 当前供应商 id
new_id	body	string	重命名供应商；providers 键、模型别名、default_provider、指向旧别名的 default_model 以及 subagent 次级模型池都会随之迁移。id 规则与 POST /api/v1/providers 相同
type	body	string	必填。 通信协议：kimi / openai / openai_responses / anthropic / google-genai / vertexai
api_key	body	string	三态，见上文
base_url	body	string	API 基础 URL；不得包含环境变量占位符（${...}）
default_model	body	string	该供应商的默认模型；必须是 models[].model 之一
models	body	array	必填。 至少一条，不允许重复的 model 值；条目结构与 POST /api/v1/providers 相同

成功时 data 为 { provider }，即保存后的供应商条目。

• 40001：重命名后的别名 id 会与其他供应商的别名冲突
• 40003：供应商由 OAuth 托管——请改用 POST /api/v1/oauth/logout 登出
• 40412：供应商不存在
• 40921：new_id 已被占用

DELETE /api/v1/providers/{provider_id}

删除供应商及其全部模型别名；subagent 次级模型池会级联清理。全局 default_provider / default_model 指针保持不动，即使它们指向被删的供应商——那是用户的设置，不由本端点代为回收。

参数	位置	类型	说明
provider_id	path	string	必填。 供应商 id

成功时服务应答 204 且无响应体——状态行本身即表示删除成功（见 响应信封）。

• 40003：供应商由 OAuth 托管——请改用 POST /api/v1/oauth/logout 登出
• 40412：供应商不存在

POST /api/v1/providers/{provider_id}:refresh

从上游来源重新发现单个供应商的模型元数据，并重写该供应商的别名。模型来源为静态的供应商不经任何网络调用直接报告 unchanged。至少一个供应商的别名发生变化时，服务会广播全局 event.model_catalog.changed 事件。

参数	位置	类型	说明
provider_id	path	string	必填。 供应商 id

成功时 data 为刷新报告：changed 是 { provider_id, provider_name, added, removed }（新增 / 移除的别名数）的数组，unchanged 是无差异的供应商 id 数组，failed 是 { provider, reason } 的数组。

• 40001：路径中的动作后缀非法或不支持
• 40412：供应商不存在

POST /api/v1/providers:refresh

刷新每个供应商的模型元数据。请求体可选且被忽略。

成功时 data 为与 POST /api/v1/providers/{provider_id}:refresh 相同的刷新报告（changed / unchanged / failed）。

POST /api/v1/providers:refresh_oauth

与 POST /api/v1/providers:refresh 相同的刷新，仅限 OAuth 凭据的供应商。请求体可选且被忽略。

成功时 data 为刷新报告（changed / unchanged / failed）。

POST /api/v1/providers:import_catalog

把一个 models.dev 目录条目导入为已配置供应商；响应为 HTTP 201 加标准信封。通信协议与端点来自目录解析，目录中的每个模型都写为一个别名。导入已存在的 id 等同于刷新——供应商条目及其别名按目录重写，省略 api_key 表示保留已存密�。全局默认指针绝不被修改，仅在完全未配置默认模型时，以第一个导入的模型播种 default_model。

参数	位置	类型	说明
catalog_id	body	string	必填。 来自 GET /api/v1/catalog/providers 的目录条目 id
id	body	string	覆盖目录 id 作为本地供应商 id。id 规则与 POST /api/v1/providers 相同
api_key	body	string	导入供应商的 API 密钥
base_url	body	string	覆盖目录解析出的端点；条目的 needs_base_url 为 true 时必填

成功时 data 为 { provider, models_imported }——供应商条目与写入的别名数量。

• 40001：缺少 catalog_id 或其他请求体校验失败
• 40003：目标供应商已存在且由 OAuth 托管
• 40004：条目无法导入（被拒绝、要求 base_url、没有可导入的模型，或其 id 不能用作供应商 id）
• 40417：不存在该 catalog_id 的目录条目
• 50004：models.dev 目录不可用

POST /api/v1/providers:import_registry

把一个 models.dev 形态的私有注册表——一个 api.json URL 加可选的 Bearer key——导入为已配置供应商；响应为 HTTP 201 加标准信封。每个列出的供应商都带 source 记录写入，以便定时刷新重新发现。重复导入同一 URL 会移除上游已消失的供应商——URL 是注册表的稳定身份，因此轮换 key 是安全的。全局默认指针遵循与 :import_catalog 相同的规则。

参数	位置	类型	说明
url	body	string	必填。 注册表 api.json 的 URL
api_key	body	string	注册表的 Bearer key；省略时复用上一次导入同一 URL 所用的 key

成功时 data 为 { providers, models_imported }——供应商条目数组与写入的别名总数。

• 40001：缺少 url 或其他请求体校验失败
• 40003：某个列出的供应商已存在且由 OAuth 托管
• 40005：注册表无法获取或解析，或未列出可导入的供应商

GET /api/v1/catalog/providers

浏览 models.dev 目录，由服务端代理，带 10 分钟内存缓存与内置快照兜底。条目保持上游目录顺序。服务无法导入的条目携带 rejected: true 与机器可读的 reject_reason；needs_base_url: true 的条目在导入时要求提供 base URL。

成功时 data.items 为 { id, name, wire_type, base_url, guessed, needs_base_url, rejected, reject_reason, env_key, models } 数组：wire_type 是解析出的协议（可空，枚举与供应商 type 相同），base_url 是解析出的端点（可空；needs_base_url 或被拒绝的条目为 null），guessed 标记启发式解析，env_key 是上��约定的 API 密钥环境变量（可空），models 是 { id, name?, max_context_