接入说明

将客户端的 Base URL 设置为 New API 网关根地址。本文对应 2026-10-17 的本地代码，包含尚未提交的改动。部署其他版本时，请核对该版本提供的路径。

鉴权

模型和插件接口使用网关令牌，通过 Authorization: Bearer {{relayToken}} 传入。后台管理接口使用登录获得的 access_token，或接口允许的个人访问令牌（PAT）。每个后台接口的说明列出了角色和 PAT scope 要求。

修改密码、绑定账号、创建 PAT、读取渠道密钥等操作还需要安全验证。先调用 /api/verify 或对应的 Passkey/OAuth 验证接口，再把返回的凭据放入 X-Security-Proof 请求头。凭据绑定操作的 scope、目标资源 context 和当前身份，使用一次后失效。

后台 API 可能在 HTTP 200 响应中返回 success: false，客户端需要检查这个字段。鉴权和限流错误也可能返回 401、403 或 429。message_key 与 message_params 供前端翻译消息。

选择接口

统一协议包括 /v1/responses、/v1/videos、/v1/images/generations 和 /v1/images/edits。客户端按统一格式发送请求，网关根据模型、已启用插件和渠道配置选择处理方式。

使用厂商 SDK 时，可以选择插件提供的厂商格式接口。网关提供 /ali、/doubao、/kling 等前缀路径，也会在路径空闲时提供厂商原路径。较早版本的网关可能只有带前缀的路径，鉴权仍使用网关 Bearer 令牌。

POST /v1/tasks/{key} 是通用兼容入口，key 填插件名，body 使用插件驱动要求的通用请求格式。GET /v1/tasks/{key} 用于查询任务，此时 key 填创建响应中的任务 ID。新客户端优先选择统一协议或厂商格式接口。

创建、查询和下载

创建响应中的 id、task_id、request_id 或 operation.name 使用网关分配的任务 ID。查询、续作和草稿引用都使用这个 ID。查询接口检查任务所属用户，然后返回后台轮询保存的结果。

Responses 支持三种调用方式：stream=true 接收 SSE，background=true 立即取得待处理 Response，两个字段都省略时等待最终结果。插件需要声明对应的 supports。GET Responses 查询网关保存的插件任务；普通上游中继的 Response 是否可检索，要以对应实现为准。

图片统一协议等待生成结束后返回图片。对异步厂商，网关会在这次请求内轮询。等待超时会返回 504，后台任务仍继续处理。带 retainResult=false 的厂商同步图片接口，以及立即完成的 openai_image 任务，都需要从本次响应中读取图片，后续查询无法取回结果。

下载任务产物时，使用产物列表返回的完整 content_url，保留其中的 access 签名参数。Vertex AI 插件的产物列表为空，Responses 完成时返回文字说明；视频数据可从厂商格式的 fetchPredictOperation 查询结果中读取。任务完成且保存了有效的视频结果地址时，也可调用 GET /v1/videos/{task_id}/content 下载。

内置插件

插件	版本	原生路由声明数	宿主协议
alibaba	1.4.2	14	openai_responses, openai_video, openai_image
doubao	1.3.0	6	openai_responses, openai_video, openai_image
google	1.1.0	4	openai_responses, openai_video
hailuo	1.3.0	8	openai_responses, openai_video
jimeng	1.1.0	1	openai_responses, openai_video
kling	1.1.0	8	openai_responses, openai_video
sora	1.1.0	0	openai_responses, openai_video
sunoapi	1.1.0	3	openai_responses
vertex-ai	1.1.0	2	openai_responses, openai_video
vidu	1.1.0	10	openai_responses, openai_video
xai	1.1.0	8	openai_responses, openai_video

Sora 使用统一视频和 Responses 协议。xAI 厂商格式任务与统一视频任务共用 GET /v1/videos/{task_id}，返回格式取决于创建任务时使用的接口。

Google 和 Vertex AI 创建视频时，模型段包含 :predictLongRunning。Vertex AI 查询使用 :fetchPredictOperation，请求体携带创建接口返回的完整 operation name。

字段与版本

请求字段取自代码中的 DTO 和插件解码器。厂商扩展字段、动态响应字段以各接口说明为准；Schema 允许扩展字段时，字段是否有效仍由插件和上游检查。

价格由网关管理员配置。usageSchema 中的数值是插件报告的用量，客户端无需把价格写进这些字段。

“历史接口（迁移核对）”保留已移除路径和路径写法不同的旧记录。“未实现的兼容路由”中的接口在当前代码中返回 501。

接入指南与内置插件总览（2026-10-17 源码同步）

接入说明#

鉴权#

选择接口#

创建、查询和下载#

内置插件#

字段与版本#

接入说明

鉴权

选择接口

创建、查询和下载

内置插件

字段与版本