NewAPI 接入教程

1. 它怎么接

设置 → 模型 → 添加模型提供商 → 选 NewAPI：填你的网关地址与 NewAPI 令牌即可，不需要再选端点类型。

端点元数据来自网关公开的 GET /api/pricing：它有一张端点字典，把端点类型 映射到真实路径，例如

{
  "image-generation": { "path": "/v1/images/generations" },
  "image-edit":       { "path": "/v1/images/edits" },
  "openai":           { "path": "/v1/chat/completions" }
}

每个模型条目还带 supported_endpoint_types，所以「这个模型能不能出图」 不用猜命名（例如 grok-imagine-image 这种名字里没有 image 语义的也能认出来）。 列出哪些模型仍以令牌可见的 /v1/models 为准 —— 元数据只用来 判定模态与端点，不会把令牌用不了的模型塞进列表。

2. 在 NewAPI 侧准备三样东西

1. 站点地址：你平时打开 NewAPI 面板的域名（本教程用 https://your-newapi.example.com 做占位示例，请换成你自己的站）。 OpenAI 兼容入口是它的 /v1，所以 Base URL 填 https://your-newapi.example.com/v1。
2. 令牌：NewAPI 面板 → 令牌 → 添加令牌，复制 sk- 开头的那串。令牌的分组决定你能用哪些模型，这是最容易踩的坑：
   应用里拉到的目录是 GET /v1/models，它只列你这个令牌分组下可用的模型； 而网页面板上的价目表（/pricing、GET /api/pricing）列的是 全站所有分组的模型，两者数量经常不一样。
   典型现象：价目表有 13 个模型、令牌目录只有 3 个 —— 另外 10 个挂在别的分组 （如 GPT-Image-4K、Nano Banana、Grok-imagine-image）， 拿这个令牌去调会直接 503： No available channel for model … under group GPT-Image。
   要用那些模型，就在面板里给令牌换一个覆盖目标模型的分组，或新建一个对应分组的令牌。
3. 模型名：NewAPI 面板 → 渠道 / 模型，记下你要用的 模型 id 原文（如 gpt-4o-mini、deepseek-chat、 flux.1-schnell、gpt-image-2.5-flare）。手填模型时必须一字不差， 大小写与连字符都要对。

填进本软件之前，建议先用命令行确认这几个接口是通的：

# 模型列表（令牌可见的目录 + 认证检查）
curl -H "Authorization: Bearer sk-你的令牌" https://your-newapi.example.com/v1/models

# 文本对话
curl -X POST https://your-newapi.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

# 出图（图片模型 id 换成你目录里的那个）
curl -X POST https://your-newapi.example.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2.5-flare","prompt":"a red ball","n":1}'

3. 在本软件里添加 NewAPI 提供商

1. 打开设置 → 模型（模型与密钥是全局设置，对所有工程生效）。
2. 顶部「添加模型提供商」下拉选 NewAPI，点 添加。 新卡片会自动展开并滚到眼前。
3. 显示名称：保持默认的 NewAPI 即可，也可以改成你的站名。
4. API Base URL：把默认的占位地址换成你自己的网关，例如 https://your-newapi.example.com/v1（见第 1 节的提醒）。
5. API Key：粘贴 NewAPI 令牌。右侧眼睛按钮可临时显示明文核对。
6. 勾上 启用 —— 不启用的提供商不会出现在任何节点的模型下拉里。

4. 拉取文本模型

1. 切到 文本 页签。
2. 点 拉取可用模型（按钮会短暂显示「正在验证 API Key…」，这一步同时就是 密钥与连通性检查）。
3. 成功时按钮右侧显示 共 N 个模型。列表已按模态过滤： 能出图的模型会被归到「图片」页签，不会出现在这里。
4. 用筛选框搜、用「全选当前列表 / 清空选择」批量操作，勾选你要用的模型。
5. 需要指定默认时，在 默认生成模型 下拉里选一个（该下拉只列已勾选项）。

编辑生成节点时，模型下拉里就会出现 NewAPI · 模型名 这一项。下拉为空时， 检查器会提示「请先在设置中配置可用的文本模型（需 API Key 并勾选模型）」，回到这一步补齐即可。

5. 手动添加模型（重点）

每张提供商卡片都有一个手填输入框 「手动填写模型 / 接入点 / Resource ID」， 旁边是 「添加并勾选」 按钮（按回车等效）。填 id → 点按钮，模型立刻加入当前页签的 列表并自动勾选，输入框随后清空。

5.1 什么时候需要手填

• 图片模型通常不用手填：拉取时会读网关的端点元数据，自动把能出图的模型 放进「图片」页签（见第 1 节）。只有元数据取不到、或某个模型的 id 看不出图片语义时才需要手填 —— 手填项与自动拉到的项会合并进同一个列表。
• 拉取返回 404 / 405：网关没有实现 /models。列表会是空的但 不报错（这是预期行为），直接手填即可，不影响生成。
• 「端点返回的 N 个模型都是图片生成模型」：令牌分组下只有图片渠道， 文本页签自然没有可用模型 —— 去「图片」页签勾选，或去网关给令牌换一个含对话渠道的分组。
• 拉取报「网关未返回模型列表」：地址或令牌有问题，或者令牌没绑任何渠道。
• 只想用其中几个：懒得在几百个模型里翻，直接手填想要的 id。
• NewAPI 上换了模型名：重新手填新 id，旧的手填项可以取消勾选。

5.2 手填文本模型

1. 停在 文本 页签。
2. 在「手动填写模型 / 接入点 / Resource ID」输入框里填 NewAPI 上的 模型 id 原文，例如 deepseek-chat。
3. 点 添加并勾选（或回车）。
4. 如需默认，在「默认生成模型」里选它。

5.3 手填图片模型

1. 切到 图片 页签，先点一次 拉取可用模型 —— 正常情况下 能出图的模型会直接列出来（图片目录按网关端点元数据挑选，不是恒为空）。
2. 没列出来的，在同一个位置的输入框里填图片模型 id，例如 gpt-image-2.5-flare、flux.1-schnell。填 NewAPI 上真实存在的名字， 不要写「图片模型」这类描述。
3. 点 添加并勾选。
4. 在「默认生成模型」下拉里把它设为默认（该下拉只列已勾选项）。

5.4 手填项会不会被覆盖

• 不会。重新点「拉取可用模型」时，已勾选但不在远端目录里的模型会被保留并补回 列表（远端偶发空列表时同样保留上次结果）。
• 重复 id 不会重复添加：已经在列表里的 id 只会被重新勾选一次。
• 只有勾选才会落盘。勾上才写进设置文件；取消勾选会连同它的能力快照一起移除。
• 只有勾选过的模型能被节点选到。节点下拉只列已勾选项；若模型 id 从别的途径 （MCP、模板、旧工程）写进了节点但没在这里勾选，执行时会被静默回退到默认模型或第一个已勾选模型。

6. 在节点里用起来

1. 文本生成节点：模型下拉选 NewAPI · 你的文本模型，写指令，执行。
2. 图片生成节点：模型下拉选 NewAPI · 你的图片模型。 需要参考图时，把图片连到该节点的图片输入口 —— 有参考图时会自动改走 /images/edits。
3. 分辨率与画质：请求体按需带 size / quality / n；size 只在能映射到 1024x1024 / 1536x1024 / 1024x1536 时才发送，映射不了就不带。 有些中转模型只认自己的尺寸，报错时先看执行日志里的实际请求。
4. 执行过程与失败原因都在执行日志里：认证类失败会附带 「请检查设置中的 API Key 是否正确、已保存，且提供商 Base URL 匹配」。

7. 常见问题

• 「拉取可用模型」是灰的：NewAPI 提供商必须填了令牌才会启用该按钮。 先填 Key（并确认「启用」已勾选）。
• 报「API Key 无效，已禁止拉取模型：…」：Key 复制错、令牌被禁用 / 过期， 或该令牌的分组不允许这个请求。
• 报「连接测试失败：code=ENOTFOUND …」：域名解析不了 —— 拼错域名、 本地网络或代理问题。域名能被浏览器打开不代表本软件能连（本软件在主进程直连，不走系统代理设置）。
• 拉取 404 / 405，或返回空列表：网关没实现 /models。 直接在第 5 节手填模型 id，生成不受影响。
• 图片页签拉取后为空：先确认令牌分组里有图片渠道；若提示「远端返回空列表， 已保留上次拉取结果」，说明网关目录里没有可判定的图片模型，手填即可（第 5.3 节）。
• 生成时报「暂不支持视频生成 / 语音合成 / 3D 模型生成」：NewAPI 提供商只有文本 与图片。视频请用内置的视频提供商或 ComfyUI（见 ComfyUI 接入教程）。
• Base URL 填错的典型症状：少写 /v1 或把 /chat/completions 也写进去，都会 404。
• 面板价目表有十几个模型，应用里只拉到几个：应用读的是 GET /v1/models，只列你这个令牌分组下可用的模型； 面板价目表列的是全站所有分组。要用价目表里的其它模型，去面板给令牌换分组（见第 2 节）。
• 拉取报 503 / No available channel：该模型在你的令牌分组下 没有可用渠道，不是软件的问题；换分组，或改用同分组里别的模型。
• 文本页签一个模型都没有、图片页签有：令牌分组下只有图片渠道，属于正常情况， 应用会明确提示「返回的模型都是图片生成模型」。
• 模型名对不上：请以 NewAPI 面板上显示的 id 为准，手填时逐字符核对； 中转站常给模型加前缀或后缀（如 -free、-thinking、-4k）。
• API Key 存在哪：本机设置文件（Windows 示例： %APPDATA%\AIArtEngine\aiartengine-settings.json），明文保存， 不会上传到应用官方服务器；请自行保管好这台机器上的设置文件。

延伸阅读： NewAPI 官方文档 · 使用手册 · 设置。