// Generated by scripts/build-docs-search.py; edit the template, not this file. (() => { if (window.__nlDocsSearch) return; window.__nlDocsSearch = true; const data = [{"title":"非线智能-NoneLinear技术文档","heading":"","url":"/index","text":"使用 OpenAI 与 Anthropic 兼容接口接入模型，或直接在你熟悉的工具里开始。开始第一次调用 → 在工具里使用已经遇到问题？搜索模型、配置或报错 ⌘ / Ctrl K"},{"title":"非线智能-NoneLinear技术文档","heading":"从这里开始","url":"/index#从这里开始","text":"快速开始 ↗ 获取 API Key，选好地址，运行你的第一个请求。首次接入工具接入 ↗ Claude Code、Codex、Cherry Studio、WorkBuddy 等工具配置。无需写代码 API 参考 ↗ 查找请求地址、鉴权方式、输入参数与返回结果。接口规范模型与能力 ↗ 按任务选择模型，查询生图尺寸、参考图与模型差异。模型用法开发指南 ↗ 流式输出、工具调用、多模态与 SDK 集成。构建应用帮助中心 ↗ 从错误现象出发，找到检查步骤和下一步操作。问题排查"},{"title":"非线智能-NoneLinear技术文档","heading":"按问题查找","url":"/index#按问题查找","text":"准备接入如何完成第一次 API 调用？ → Base URL 应该填哪个？ → 我使用的软件怎么配置？ → 调用出错返回 401、402 或 5xx？ → 返回 429 或被限流？ → 请求成功但没有图片？ → 模型与费用生图尺寸和参考图怎么填？ → 为什么没有命中缓存？ → 在哪里查看调用费用？ →"},{"title":"非线智能-NoneLinear技术文档","heading":"已有 OpenAI 项目？","url":"/index#已有-openai-项目？","text":"使用你已有的 SDK，把 API Key 和 Base URL 换成 NoneLinear 的配置。模型 ID 请从模型广场原样复制，各模型支持的能力以对应文档为准。 python Python import os from openai import OpenAI client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\", ) 还没设置环境变量或安装 SDK？按照快速开始完成准备，再发送请求。"},{"title":"快速开始","heading":"选择使用方式","url":"/quickstart#选择使用方式","text":"在软件里使用 ↗ 使用 Claude Code、Codex 或聊天客户端？直接找到对应工具的配置教程。通过 API 接入 ↗ 使用 Python、cURL 或已有应用？继续下面的步骤。"},{"title":"快速开始","heading":"准备账号与模型","url":"/quickstart#准备账号与模型","text":"1. 登录 NoneLinear 控制台，在 API Key 管理创建或获取密钥。 2. 在模型广场复制账号可用的模型 ID。你也可以先在模型广场中体验模型。 3. 在账户余额确认额度。示例请求会按所选模型计费。"},{"title":"快速开始","heading":"选择 API 地址","url":"/quickstart#选择-api-地址","text":"OpenAI 兼容 https://api.nonelinear.com.cn/v1 复制地址 Anthropic 兼容 https://api.nonelinear.com.cn/anthropic 复制地址下面使用 OpenAI 兼容接口。Anthropic SDK 的配置见 Messages 接口。不要把完整的 /chat/completions 地址填进 SDK 的 Base URL。"},{"title":"快速开始","heading":"运行一次请求","url":"/quickstart#运行一次请求","text":""},{"title":"快速开始","heading":"设置 API Key","url":"/quickstart#设置-api-key","text":"示例从环境变量 NONELINEAR_API_KEY 读取 API Key，运行前先在终端设置： bash macOS / Linux export NONELINEAR_API_KEY=\"你的 API Key\" powershell Windows PowerShell $env:NONELINEAR_API_KEY=\"你的 API Key\" 该变量只在当前终端窗口有效，请在同一窗口中运行下面的示例。变量名只是本文档的示例约定，如果你已用其他方式保存 API Key，把代码中的变量名换成自己的即可。"},{"title":"快速开始","heading":"发送第一个请求","url":"/quickstart#发送第一个请求","text":"先安装 OpenAI SDK： bash pip install --upgrade openai python Python import os from openai import OpenAI 初始化客户端，使用 NoneLinear 的 Base URL client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\", ) 发起对话请求 response = client.chat.completions.create( model=\"DeepSeek-V3.2\", 示例模型，可换成模型列表中的其他模型 ID messages=[ {\"role\": \"user\", \"content\": \"帮我分析一下企业引入大模型治理的三个关键点。\"} ], ) print(response.choices[0].message.content) bash cURL curl https://api.nonelinear.com.cn/v1/chat/completions \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"DeepSeek-V3.2\", \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}], \"stream\": false }' Python 会打印模型回答。cURL 适用于 macOS / Linux、Git Bash 或 WSL。成功时返回 JSON，模型的回答在 choices[0].message.content 中，本次消耗的 token 数在 usage 中。返回 401 时，请检查 API Key 是否正确、环境变量是否已在当前终端中设置。其他错误见错误处理。"},{"title":"快速开始","heading":"确认成功，再继续","url":"/quickstart#确认成功，再继续","text":"收到可见的模型回答后，在调用明细核对时间、模型和用量。只有 HTTP 200、但正文为空时，继续查看空输出排查。接入你的应用 ↗ 查看文本、图像、视频及平台接口。逐字显示回答 ↗ 通过流式响应改善对话体验。生成第一张图片 ↗ 独立示例、返回结果与模型参数入口。解决接入问题 ↗ 鉴权、地址、余额、限流与网络排查。"},{"title":"工具接入","heading":"","url":"/scenes/overview","text":"不必先学会 API。找到你的工具，按对应教程配置；不同软件对地址的补全方式不同，请使用教程里的字段值。"},{"title":"工具接入","heading":"编程助手","url":"/scenes/overview#编程助手","text":"Claude Code ↗ 一键安装、手动配置和 CC-Switch，按你的系统选择。终端 · IDE Codex App / CLI ↗ 配置供应商与模型，核对桌面端和 CLI 的实际配置。桌面 · 终端 OpenCode ↗ 通过 CC-Switch 或配置文件接入。编程 Agent Cline ↗ 在 VS Code 中配置兼容接口。编辑器插件 Trae ↗ 添加自定义模型并开始对话。编辑器 Reasonix ↗ 选择终端或桌面配置方式。桌面 · 终端"},{"title":"工具接入","heading":"办公与 Agent","url":"/scenes/overview#办公与-agent","text":"WorkBuddy ↗ 在日常办公任务中使用自定义模型。 Claude Cowork ↗ 配置桌面客户端的第三方推理。 OpenClaw ↗ 为本地 Agent 配置模型供应商。 Hermes Agent ↗ 配置终端 Agent 的服务地址与模型。"},{"title":"工具接入","heading":"聊天客户端","url":"/scenes/overview#聊天客户端","text":"Cherry Studio ↗ 添加服务商、获取模型并验证对话。 Chatbox ↗ 配置模型提供方与 API 地址。 RikkaHub ↗ 在 Android 上配置模型与对话。"},{"title":"工具接入","heading":"工作流与扩展","url":"/scenes/overview#工作流与扩展","text":"Dify ↗ 将模型接入工作流和应用。 LangBot ↗ 为机器人配置模型服务。 NoneLinear 生图 Skill ↗ 在 Agent 中用自然语言生图、改图和融合参考图。"},{"title":"工具接入","heading":"没有找到你的工具？","url":"/scenes/overview#没有找到你的工具？","text":"先确认软件支持自定义 API 地址及对应协议，再对照协议与地址说明。若它只支持官方账号登录，不能仅通过更换 API Key 接入。写代码使用 LangChain、LangGraph 或 Agno，请查看开发指南。配置后不生效，见客户端排查。"},{"title":"Claude Code","heading":"","url":"/scenes/dev-tools/claude-code","text":"通过 Anthropic 兼容接口接入。先准备 API Key，再选择与你的系统和使用方式对应的教程。 API 地址 https://api.nonelinear.com.cn/anthropic 复制地址开始前在 API Key 管理为工具设置独立 Key 和合理限额。修改已有配置前先备份；同一时间使用一种配置方式，避免反复覆盖。"},{"title":"Claude Code","heading":"选择配置方式","url":"/scenes/dev-tools/claude-code#选择配置方式","text":"以下方式选择其中一种即可，不需要全部执行：你的情况推荐方式是否需要提前安装 Node.js --- --- --- Linux，想最快完成一键安装与配置：Linux 不需要 Windows，想最快完成一键安装与配置：Windows 不需要 macOS，或想手动控制配置手动配置：macOS / Linux 需要 Windows，想手动控制配置手动配置：Windows 需要需要在多个供应商之间切换，或想用图形界面管理通过 CC-Switch 配置需要需要通过 OpenAI Compatible 接口路由多个模型通过 ClaudeCodeRouter 配置需要配置完成后，建议再阅读费用与缓存注意事项。在 VS Code、JetBrains 中使用，见在 IDE 中使用。"},{"title":"Claude Code","heading":"验证配置","url":"/scenes/dev-tools/claude-code#验证配置","text":"1. 保存配置后，退出客户端并重新打开终端。直接接入运行 claude ；使用 CCR 时运行 ccr code 。 2. 在 Claude Code 中输入 /status ，核对当前模型和服务地址。模型 ID 从模型广场原样复制。 3. 在空目录或小型测试项目中发送一条简短请求，例如“只回复：连接正常”。请求会按实际输入上下文和所选模型计费。 4. 在调用明细核对请求时间、模型和用量。收到回复且找到对应记录后，再继续业务任务。文本对话成功后，工具调用、文件操作等能力仍需按实际任务验证。"},{"title":"Claude Code","heading":"常见问题","url":"/scenes/dev-tools/claude-code#常见问题","text":"现象先检查下一步 --- --- --- 401 / 认证失败当前进程读取的 Key、服务地址及配置是否被覆盖鉴权排查模型不存在模型 ID、协议，以及空的角色槽位模型切换与映射改了配置仍使用旧模型终端和客户端是否重新启动客户端配置不生效 429 / 限流响应正文、Key 限额及请求频次限流排查没继续输入却出现费用后台辅助请求、Haiku 槽位和上下文费用与缓存仍无法定位保留版本、时间、模型与脱敏错误提交排查信息"},{"title":"Claude Code","heading":"继续使用","url":"/scenes/dev-tools/claude-code#继续使用","text":"模型与角色槽位 ↗ 切换模型，明确 Sonnet、Opus、Haiku 的请求映射。费用与缓存 ↗ 理解完整上下文、缓存和后台辅助调用。在 IDE 中使用 ↗ 接入 VS Code 或 JetBrains。"},{"title":"一键安装与配置（推荐）","heading":"","url":"/scenes/dev-tools/claude-code/quick-setup","text":"← Claude Code 概览 · 切换模型脚本会下载 Claude Code 官方客户端、配置 NoneLinear API 地址和模型，然后自动启动 Claude Code。无需提前安装 Node.js 或 npm。开始前，先获取 NoneLinear API Key。脚本会替换当前用户的 ~/.claude/settings.json 。已有文件会先备份，但原来的自定义设置不会自动合并。已有配置需要保留时，先阅读下方的恢复原配置。"},{"title":"一键安装与配置（推荐）","heading":"Windows 一键安装与配置","url":"/scenes/dev-tools/claude-code/quick-setup#windows-一键安装与配置","text":"以下截图来自 Windows 10、PowerShell 5.1、Claude Code 2.1.316 的实际安装和对话。脚本会下载当前的最新客户端，界面可能随版本调整。"},{"title":"一键安装与配置（推荐）","heading":"1. 运行安装命令","url":"/scenes/dev-tools/claude-code/quick-setup#1-运行安装命令","text":"在 64 位 Windows 中打开 PowerShell，进入准备使用 Claude Code 的项目文件夹，再粘贴下面的命令并按回车： powershell irm https://nonelinear.com.cn/static/shell/nonelinear-bootstrap-claudecode-v0.1-0816.ps1 iex 脚本会下载并校验客户端，安装到当前用户的 .local\\bin 目录，并把该目录加入用户 PATH。看到 Claude Code successfully installed! 后，等待输入 API Key 的提示。"},{"title":"一键安装与配置（推荐）","heading":"2. 输入 API Key，完成首次启动","url":"/scenes/dev-tools/claude-code/quick-setup#2-输入-api-key，完成首次启动","text":"在 Windows PowerShell 中输入 API Key 时，请使用鼠标右键粘贴，不要按 Ctrl+V ，粘贴后按回车。当前脚本会明文显示输入内容，请勿分享包含 Key 的终端截图。配置保存后，脚本会自动启动 Claude Code。首次启动时，按提示选择主题、阅读使用说明；出现文件夹信任确认时，核对路径，只信任自己的项目目录。"},{"title":"一键安装与配置（推荐）","heading":"3. 发送一条消息验证","url":"/scenes/dev-tools/claude-code/quick-setup#3-发送一条消息验证","text":"进入对话界面后，输入： text 只回复：连接成功。不要调用工具，不要读取或修改文件。收到回复后，再到控制台调用明细核对请求时间和模型。本页实测使用脚本默认模型 deepseek-v4.1-flash 。之后使用时，在项目目录打开新的 PowerShell，运行 claude 即可。需要更换模型，见切换模型。"},{"title":"一键安装与配置（推荐）","heading":"Linux 一键安装与配置","url":"/scenes/dev-tools/claude-code/quick-setup#linux-一键安装与配置","text":"进入项目目录，然后执行（ your_project 替换为你的项目路径）： bash cd your_project curl -fsSL https://nonelinear.com.cn/static/shell/nonelinear-bootstrap-claudecode-v0.1-0816.sh bash 脚本会根据系统架构下载并校验官方客户端，提示输入 API Key，再写入配置并启动 Claude Code。按提示完成首次启动，发送上面的简短消息验证连接。"},{"title":"一键安装与配置（推荐）","heading":"脚本写入的配置","url":"/scenes/dev-tools/claude-code/quick-setup#脚本写入的配置","text":"截至 2026 年 11 月 2 日，Windows 和 Linux 线上脚本写入以下模型配置。脚本更新后，以安装时写入的 settings.json 为准。用途配置字段模型 ID --- --- --- 默认对话模型 ANTHROPIC_MODEL deepseek-v4.1-flash Sonnet 槽位 ANTHROPIC_DEFAULT_SONNET_MODEL claude-sonnet-5.5 Opus 槽位 ANTHROPIC_DEFAULT_OPUS_MODEL claude-opus-5.5 Haiku 槽位 ANTHROPIC_DEFAULT_HAIKU_MODEL glm-5.3 ANTHROPIC_BASE_URL 配置为： text https://api.nonelinear.com.cn/anthropic Windows 配置文件位于 %USERPROFILE%\\.claude\\settings.json ，Linux 位于 ~/.claude/settings.json 。这些文件含 API Key，不要整份发给他人。"},{"title":"一键安装与配置（推荐）","heading":"恢复原配置","url":"/scenes/dev-tools/claude-code/quick-setup#恢复原配置","text":"先退出 Claude Code，在配置目录找到本次安装前的备份，将它复制为 settings.json ，再重新启动客户端。复制前核对备份时间，避免选到其他配置。系统备份文件名 --- --- Windows settings.json.backup.时间戳 Linux settings.json.bak.时间戳备份保留的是安装前的整个配置文件。恢复它会同时恢复其中的地址、Key 和自定义设置；原先没有配置文件时，不会生成这份备份。"},{"title":"一键安装与配置（推荐）","heading":"安装或连接遇到问题","url":"/scenes/dev-tools/claude-code/quick-setup#安装或连接遇到问题","text":""},{"title":"一键安装与配置（推荐）","heading":"下载客户端超时","url":"/scenes/dev-tools/claude-code/quick-setup#下载客户端超时","text":"如果命令已开始执行，却在下载客户端时超时，先确认当前 PowerShell 能访问 https://downloads.claude.ai/claude-code-releases/latest 。浏览器能访问，不代表终端也能访问。配置好终端可用的网络或代理后，再运行安装命令。"},{"title":"一键安装与配置（推荐）","heading":"新终端提示找不到 claude","url":"/scenes/dev-tools/claude-code/quick-setup#新终端提示找不到-claude","text":"关闭旧 PowerShell，重新打开后运行 claude --version 。如果仍提示找不到命令，可先用完整路径验证安装： powershell & \"$env:USERPROFILE\\.local\\bin\\claude.exe\" --version 完整路径可用时，检查用户 PATH 中是否包含 %USERPROFILE%\\.local\\bin ；完整路径也不存在时，回看安装输出中的下载或安装错误。"},{"title":"一键安装与配置（推荐）","heading":"出现模型未识别提示","url":"/scenes/dev-tools/claude-code/quick-setup#出现模型未识别提示","text":"如果提示 Model isn't recognized ，并包含 context assumed to be 200k tokens ，表示客户端没有内置这个模型的上下文信息，临时按 200k 处理；这不是模型的实际上下文上限。可以先发送一条简短消息验证。本页中的 deepseek-v4.1-flash 在出现该提示时仍完成了对话。如果请求失败，按实际响应排查，见调用报错。"},{"title":"一键安装与配置（推荐）","heading":"重新配置后仍显示旧模型","url":"/scenes/dev-tools/claude-code/quick-setup#重新配置后仍显示旧模型","text":"退出当前 Claude Code，核对 settings.json 中的 ANTHROPIC_MODEL ，再重新启动。如果启动命令带了 --model ，或曾在 /model 中保存过其他选择，也需要一并检查，见切换模型。"},{"title":"手动配置","heading":"","url":"/scenes/dev-tools/claude-code/manual","text":"← Claude Code 概览 · 配置成功后如何验证手动配置需要先安装 Claude Code CLI，再写入以下配置项： - ANTHROPIC_BASE_URL ： https://api.nonelinear.com.cn/anthropic - ANTHROPIC_AUTH_TOKEN ：从 NoneLinear 官网获取 API Key - ANTHROPIC_MODEL ：按需选择模型，可在模型列表查看可用模型"},{"title":"手动配置","heading":"安装 Claude Code","url":"/scenes/dev-tools/claude-code/manual#安装-claude-code","text":"使用 npm 安装需要 Node.js 18 或更高版本。在命令行界面执行： bash npm install -g @anthropic-ai/claude-code 安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功： bash claude --version"},{"title":"手动配置","heading":"macOS 和 Linux 手动配置","url":"/scenes/dev-tools/claude-code/manual#macos-和-linux-手动配置","text":"在终端执行以下命令打开 Claude Code 配置文件（也可以用任意文本编辑器打开该文件）： bash vim ~/.claude/settings.json 编辑配置文件，文件内容如下。请将你的 NoneLinear API Key 替换为实际 API Key。如果文件里已经有 env ，不要新建第二个 env ，把下面的配置项追加到现有 env 对象里即可。 json { \"env\": { \"ANTHROPIC_AUTH_TOKEN\": \"你的 NoneLinear API Key\", \"ANTHROPIC_BASE_URL\": \"https://api.nonelinear.com.cn/anthropic\", \"ANTHROPIC_MODEL\": \"gpt-5.5\", \"ANTHROPIC_DEFAULT_SONNET_MODEL\": \"gpt-5.5\", \"ANTHROPIC_DEFAULT_OPUS_MODEL\": \"claude-opus-4.8\", \"ANTHROPIC_DEFAULT_HAIKU_MODEL\": \"deepseek-v4-pro\", \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\" } } 然后重新打开终端窗口，配置才能生效。启动 Claude Code：进入项目目录，执行 claude 命令，即可开始使用。下面的 your_project 需要替换为你的项目路径。 bash cd your_project claude Linux 多用户与权限注意事项在多用户共享的 Linux 服务器上，或者存在 root 账户交替操作时，请注意以下两点，避免配置失效或启动时报错： - 避免使用 sudo 启动或配置 Claude Code ：使用 sudo 可能会将 ~/.claude 目录的所有权变更为 root ，导致普通用户无法读取配置。若配置未生效，可以执行： bash sudo chown -R $USER:$USER ~/.claude - 共享临时沙箱冲突：若因其他用户或 root 优先启动，导致出现 /tmp/claude 权限不足报错，可以清理 Claude Code 的临时沙箱目录： bash sudo rm -rf /tmp/claude"},{"title":"手动配置","heading":"Windows 手动配置","url":"/scenes/dev-tools/claude-code/manual#windows-手动配置","text":"在 Windows 系统下长期开发，可以使用 setx 写入用户环境变量。以下命令在 CMD 中执行。请将下方的你的 NoneLinear API Key 替换为实际 API Key。写入 ANTHROPIC_AUTH_TOKEN 时，需要用英文双引号包裹，避免 API Key 中的特殊字符被 CMD 解析或截断。模型 ID 同样建议用英文双引号包裹。 cmd setx ANTHROPIC_AUTH_TOKEN \"你的 NoneLinear API Key\" setx ANTHROPIC_BASE_URL \"https://api.nonelinear.com.cn/anthropic\" setx ANTHROPIC_MODEL \"gpt-5.5\" setx ANTHROPIC_DEFAULT_SONNET_MODEL \"gpt-5.5\" setx ANTHROPIC_DEFAULT_OPUS_MODEL \"claude-opus-4.8\" setx ANTHROPIC_DEFAULT_HAIKU_MODEL \"deepseek-v4-pro\" setx CLAUDE_CODE_ATTRIBUTION_HEADER \"0\" setx 更改后，必须关闭当前 CMD（或 Git CMD）窗口，重新打开一个新窗口，新的值才会生效。在新窗口中执行以下命令检查环境变量是否生效： cmd if defined ANTHROPIC_AUTH_TOKEN (echo Token is configured) else (echo Token is missing) echo %ANTHROPIC_BASE_URL% echo %ANTHROPIC_MODEL% 启动 Claude Code：进入项目目录，执行 claude 命令，即可开始使用。下面的 your_project 需要替换为你的项目路径。 cmd cd your_project claude"},{"title":"通过 CC-Switch 配置","heading":"","url":"/scenes/dev-tools/claude-code/cc-switch","text":"← Claude Code 概览 · 配置成功后如何验证如果你需要在多个 API 供应商之间快速切换，或者希望以图形界面管理多个 API Key，推荐使用 CC-Switch 工具。CC-Switch 是一款跨平台桌面应用，本质是\"配置切换器\"——它会把你选中的供应商信息写入 ~/.claude/settings.json ，免去手动编辑配置文件的麻烦。使用前请先按安装 Claude Code 安装 Claude Code CLI。"},{"title":"通过 CC-Switch 配置","heading":"安装 CC-Switch","url":"/scenes/dev-tools/claude-code/cc-switch#安装-cc-switch","text":"CC-Switch 开源项目地址：https://github.com/farion1231/cc-switch ，从 Releases 页面里，找到 \"Assets\" (资产/附件) 列表，下载对应平台的安装包。 macOS 推荐使用 Homebrew 一行安装： bash brew tap farion1231/ccswitch brew install --cask cc-switch 或从 Releases 页面下载 .dmg 文件（区分 Apple Silicon 和 Intel 芯片），双击安装后拖入\"应用程序\"文件夹。首次启动若提示\"未识别的开发者\"，请进入系统设置 → 隐私与安全性，在底部点击\"仍要打开\"。 Windows 从 Releases 页面下载 CC-Switch-vX.X.X-Windows.msi （推荐，支持自动更新）或便携版 zip，双击 msi 文件按引导安装即可。 Linux Releases 页面提供 .deb 、 .rpm 、 .AppImage 、 .flatpak 四种分发格式，按你的发行版选择。Arch 用户可直接执行： bash paru -S cc-switch-bin"},{"title":"通过 CC-Switch 配置","heading":"添加 NoneLinear 供应商","url":"/scenes/dev-tools/claude-code/cc-switch#添加-nonelinear-供应商","text":"以 Windows 系统为例，启动 CC-Switch 后，按以下步骤添加 NoneLinear 配置：第 1 步：右上角 + 按钮，选择\" Claude \"类型，再选择\" 自定义配置 \"（NoneLinear 暂未收录为内置预设）。第 2 步：在\"添加新供应商\"页面填写基础信息：字段填写内容 --- --- 供应商名称 NoneLinear （自定义，便于识别即可）官网链接 https://nonelinear.com.cn/ API Key 从账号页面获取请求地址 https://api.nonelinear.com.cn/anthropic 填写完成后，点击右下角\" + 添加 \"按钮。第 3 步：进入\"编辑供应商\"页面，展开高级选项，按以下方式配置：字段填写内容 --- --- API 格式选择 Anthropic Messages (原生) 认证字段保持默认 ANTHROPIC_AUTH_TOKEN（默认）模型映射部分，按需填入模型列表中的模型 ID。新版 CC-Switch 的 Claude 配置里，主要是配置 Sonnet 、 Opus 、 Haiku 三个槽位；每个槽位通常包含一个显示名称和一个实际请求模型。下表仅为示例，如果需要换成其他模型，请以模型列表中的实际模型 ID 为准。新版 CC-Switch 也可以在配置页点击获取模型列表，直接读取 NoneLinear 可用模型，并在模型映射下拉框中选择模型：槽位显示名称示例实际请求模型示例 --- --- --- Sonnet gpt-5.5 gpt-5.5 Opus claude-opus-4.8 claude-opus-4.8 Haiku deepseek-v4-pro deepseek-v4-pro 默认兜底模型只在 Claude Code 请求没有明确落到 Sonnet、Opus 或 Haiku 角色时使用，通常可以留空，也可以按实际需要填入一个兜底模型。填好后勾选右上角\" 写入通用配置 \"，然后点击右下角\" 保存 \"按钮。CC-Switch 会自动将配置写入 ~/.claude/settings.json 的 env 字段。如果使用的是新版 Claude Code，建议同时在 CC-Switch 的 JSON 配置模块里写入下面的环境变量，用于关闭动态 attribution header，减少它对缓存复用的影响： json { \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\" } 第 4 步：在供应商列表中点击 NoneLinear 条目右侧的\" 启用 \"按钮。第 5 步：重新打开终端后运行 claude 命令，即可开始使用。"},{"title":"通过 CC-Switch 配置","heading":"切换供应商","url":"/scenes/dev-tools/claude-code/cc-switch#切换供应商","text":"后续需要切换时，有两种方式： - 方式一：打开 CC-Switch 主界面，点击目标供应商的\"启用\"按钮。 - 方式二：在系统托盘（macOS 菜单栏 / Windows 任务栏右下角）右键点击 CC-Switch 图标，从快捷菜单中直接选中目标供应商。切换完成后，需要重启 claude 命令（退出当前会话并在新终端重新执行 claude ），新配置才会生效。"},{"title":"通过 ClaudeCodeRouter 配置","heading":"","url":"/scenes/dev-tools/claude-code/router","text":"← Claude Code 概览 · 配置成功后如何验证 ClaudeCodeRouter（CCR）使用 OpenAI Compatible 格式接入，适合需要在 Claude Code 中接入 OpenAI Compatible 接口，或需要多供应商、多模型路由的场景。使用前请先按安装 Claude Code 安装 Claude Code CLI。先安装 ClaudeCodeRouter： bash npm install -g @musistudio/claude-code-router 配置 API 有两种方式，一种通过 CCR 的配置界面，另一种则是通过 config.json ，选择其中一种即可。通过 CCR 配置后，必须使用 ccr code 命令启动，而不是 claude 命令。"},{"title":"通过 ClaudeCodeRouter 配置","heading":"使用 CCR 配置界面","url":"/scenes/dev-tools/claude-code/router#使用-ccr-配置界面","text":"启动配置界面： bash ccr ui 浏览器会自动打开配置界面，然后就可以添加模型供应商： - 在配置界面中，点击\"添加供应商\"。 - 填写以下信息： - 供应商：填写 nonelinear - API 完整地址：填写 https://api.nonelinear.com.cn/v1/chat/completions - API 密钥：在 NoneLinear 官网获取。 - 模型：可以在模型列表找到想要的模型，填入，然后点击“保存”。上述配置保存后，在页面右侧配置路由信息。如果你有多个模型可用： - 主模型：使用较强的模型（如 deepseek-v4-pro、GLM-5.1 等） - 后台/思考模型：可以使用同一个模型或稍弱的模型 - 长上下文模型：选择支持长上下文的模型如果只有一个模型，所有路由都选择同一个供应商即可。配置完成后，点击 \"保存并重启\"。然后执行 ccr code 启动 Claude Code。如果正常响应，说明配置成功，如图所示："},{"title":"通过 ClaudeCodeRouter 配置","heading":"编辑 config.json","url":"/scenes/dev-tools/claude-code/router#编辑-config-json","text":"进入 .claude-code-router 文件夹： bash cd ~/.claude-code-router 使用编辑器打开并编辑 config.json 文件（下面的模型仅供参考），将 NoneLinear 的 API Key 替换为实际 API Key： json { \"PORT\": 3456, \"Providers\": [ { \"name\": \"nonelinear\", \"api_base_url\": \"https://api.nonelinear.com.cn/v1/chat/completions\", \"api_key\": \"NoneLinear 的 API Key\", \"models\": [ \"DeepSeek-V3.2\", \"claude-sonnet-4.5\" ] } ], \"Router\": { \"longContextThreshold\": 60000, \"default\": \"nonelinear,DeepSeek-V3.2\", \"background\": \"nonelinear,claude-sonnet-4.5\", \"think\": \"nonelinear,claude-sonnet-4.5\", \"longContext\": \"nonelinear,claude-sonnet-4.5\", \"webSearch\": \"nonelinear,claude-sonnet-4.5\" } } 如果使用 vim 编辑： - 终端输入命令： vim config.json - 输入 i 切换到输入模式，在光标当前位置开始输入文本 - 添加上述 JSON 配置内容，可以根据自己需要选择合适的模型 - 编辑好之后，按 Esc 退出编辑模式，接着输入 :w 保存文件，再输入 :q 退出 vim 编辑器然后重启 CCR： bash ccr start 启动 Claude Code 时输入： bash ccr code"},{"title":"切换模型","heading":"","url":"/scenes/dev-tools/claude-code/models","text":"← Claude Code 概览 · 查看一键脚本的模型配置进入 Claude Code 后，在对话框输入： text /model 用方向键选择明确的模型 ID，再按界面提示确认。下面是 Windows 上 Claude Code 2.1.316 的实际菜单：一键脚本配置的默认模型 deepseek-v4.1-flash 在图中作为独立选项显示，勾号表示当前选择。 Custom Sonnet model 、 Custom Opus model 、 Custom Haiku model 分别来自配置文件中的三个模型槽位；具体值见脚本写入的配置。菜单第一项 Default (recommended) 是客户端自身的默认选项，不等于一键脚本配置的默认模型。要使用 deepseek-v4.1-flash ，请选择这个明确的模型 ID。菜单中的其他内置型号和价格也不代表 NoneLinear 的可用模型或计费价格，请以控制台为准。"},{"title":"切换模型","heading":"当前会话与后续会话","url":"/scenes/dev-tools/claude-code/models#当前会话与后续会话","text":"此版本菜单提示：按回车保存为后续会话的默认选择；按 s 仅用于当前会话；按 Esc 取消。其他客户端版本请按各自界面提示操作。切换后发送一条简短消息，并在控制台调用明细核对实际模型。出现在菜单里，只表示客户端识别了该配置，不代表当前账号一定可以调用。"},{"title":"切换模型","heading":"修改配置文件后如何生效","url":"/scenes/dev-tools/claude-code/models#修改配置文件后如何生效","text":"修改 ~/.claude/settings.json 中的模型配置后，退出当前 Claude Code，再重新执行 claude 。如果启动时仍是其他模型，检查启动命令中是否带了 --model ，以及 /model 中保存的选择。先在菜单中选择要用的完整模型 ID，再发消息验证；不必反复重装客户端。"},{"title":"费用与缓存注意事项","heading":"","url":"/scenes/dev-tools/claude-code/costs","text":"← Claude Code 概览 · 配置成功后如何验证 Claude Code 是编程 Agent，账单按完整请求计算。一句简单问候也可能产生明显费用，开始使用前请阅读本节，尤其是 Claude 系列模型的使用建议。"},{"title":"费用与缓存注意事项","heading":"为什么问一句“您好”，Claude Opus 就花费几块钱","url":"/scenes/dev-tools/claude-code/costs#为什么问一句“您好”，claude-opus-就花费几块钱","text":"Claude Code 是编程 Agent，不是普通聊天窗口。即使用户只输入“您好”，请求里也会包含系统提示词、工具定义、会话状态、历史上下文，以及可能读取到的项目文件、命令结果等内容。账单按完整请求计算，不只按用户输入的几个字计算。Claude Opus 系列输入价格较高，一句简单问候，就会产生几块钱费用。"},{"title":"费用与缓存注意事项","heading":"按任务类型选择模型","url":"/scenes/dev-tools/claude-code/costs#按任务类型选择模型","text":"- 连通性测试：建议在空目录或小目录中测试，优先使用 deepseek-v4-flash 等性价比更高的模型，不建议直接用 Claude 系列模型测试。 - 规划、复杂拆解、关键判断：可以使用 Claude 系列或 GPT 系列等更强模型。 - 常规代码修改、调试、批量文档编辑：优先使用 deepseek-v4 、GPT 系列等更经济的模型。 - 长时间连续开发：建议通过 /model 按任务切换模型，不要所有任务都固定使用 Claude 系列模型。"},{"title":"费用与缓存注意事项","heading":"Claude 系列模型的缓存命中率问题","url":"/scenes/dev-tools/claude-code/costs#claude-系列模型的缓存命中率问题","text":"Claude 系列模型的缓存复用要求比较严格：两次请求中的系统提示词、工具定义、历史对话等内容需要尽量保持一致，才更容易触发缓存复用。在 Claude Code 里，请求上下文会随着文件读取、工具调用、命令结果和会话状态变化而变化，缓存命中率通常不稳定。对成本敏感时，建议把 Claude 系列模型留给关键判断和复杂推理。"},{"title":"费用与缓存注意事项","heading":"空槽位会使用 Claude Code 默认模型名","url":"/scenes/dev-tools/claude-code/costs#空槽位会使用-claude-code-默认模型名","text":"Claude Code 的 /model 会按 Sonnet、Opus、Haiku 等角色槽位切换模型。如果只配置了其中一个槽位，其他槽位留空，切换到空槽位时，Claude Code 会使用该角色的默认模型名发起请求。 NoneLinear 可以接收并处理这类请求，因此会出现“我没有配置 Opus 槽位，但后台看到 Opus 相关消耗”的情况。建议把 Sonnet、Opus、Haiku 槽位都明确绑定到你希望使用的模型；如果不希望使用 Opus，就不要让 Opus 槽位保持空配置。"},{"title":"费用与缓存注意事项","heading":"闲置或结束后会出现 Haiku 槽位的 recap 消耗","url":"/scenes/dev-tools/claude-code/costs#闲置或结束后会出现-haiku-槽位的-recap-消耗","text":"新版 Claude Code 默认启用会话自动摘要机制（Session recap / Away Summary）。当终端结束交互、离开或保持闲置时，Claude Code 会在后台调用 Haiku 槽位模型，对当前会话做 recap，总结开发上下文。如果没有配置 Haiku 槽位，Claude Code 会默认使用 Haiku 4.5 模型做 recap。如果 Haiku 槽位映射为 deepseek-v4-pro ，即使用户没有继续输入，也会在后台看到 deepseek-v4-pro 的 API 消耗记录；如果 Haiku 槽位为空，则会看到 claude-haiku-4.5 相关消耗。对成本敏感时，建议给 Haiku 槽位绑定更经济的模型，并把这类后台摘要消耗纳入预期。"},{"title":"费用与缓存注意事项","heading":"关闭 Claude Code 动态 attribution header","url":"/scenes/dev-tools/claude-code/costs#关闭-claude-code-动态-attribution-header","text":"新版本 Claude Code 会在请求里自动加入一行包含动态随机哈希值的 attribution header，这会让请求内容每次都发生变化，从而影响缓存命中。建议在 Claude Code 配置的 env 字段里加入： json { \"env\": { \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\" } } 如果配置文件里已经有 env ，不要新建第二个 env ，直接把 \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\" 追加到现有 env 对象里即可。上文手动配置和 VS Code 插件的示例已包含该项。常见配置文件位置如下：系统 Claude Code 配置文件位置 --- --- macOS / Linux ~/.claude/settings.json Windows C:\\Users\\ \\.claude\\settings.json WSL ~/.claude/settings.json 如果是通过系统环境变量配置，也可以按系统写入环境变量，例如 Windows 可执行： cmd setx CLAUDE_CODE_ATTRIBUTION_HEADER \"0\""},{"title":"在 IDE 中使用","heading":"","url":"/scenes/dev-tools/claude-code/ide","text":"← Claude Code 概览 · 配置成功后如何验证使用 Claude Code IDE 插件前，需要先安装 Claude Code CLI。 - 如果已经按上文任一方式配置好 Claude Code CLI，可以直接安装并使用 IDE 插件。 - 如果希望在 VS Code 插件里单独填写配置，可以参考下面的 VS Code 示例。"},{"title":"在 IDE 中使用","heading":"JetBrains 系列（IntelliJ IDEA、PyCharm、WebStorm 等）","url":"/scenes/dev-tools/claude-code/ide#jetbrains-系列（intellij-idea、pycharm、webstorm-等）","text":"1. 进入 Settings → Plugins → Marketplace 。 2. 搜索 \"Claude Code\" 并安装。 3. 重启后，点击右上角的图标开始使用。单击 Claude Code 图标，进入 Claude Code 页面开始使用。"},{"title":"在 IDE 中使用","heading":"VS Code","url":"/scenes/dev-tools/claude-code/ide#vs-code","text":"1. 在扩展市场搜索 Claude Code，安装这个插件： 2. 安装好之后，打开插件的配置，如下图所示： 3. 填入以下信息。请将你的 NoneLinear API Key 替换为实际 API Key；示例中的模型 ID 可以直接复制使用，如需更换模型，请到模型列表查询对应模型 ID。 json { \"claudeCode.preferredLocation\": \"panel\", \"claudeCode.environmentVariables\": [ { \"name\":\"ANTHROPIC_BASE_URL\", \"value\":\"https://api.nonelinear.com.cn/anthropic\" }, { \"name\":\"ANTHROPIC_AUTH_TOKEN\", \"value\":\"你的 NoneLinear API Key\" }, { \"name\": \"ANTHROPIC_MODEL\", \"value\": \"gpt-5.5\" }, { \"name\": \"ANTHROPIC_DEFAULT_OPUS_MODEL\", \"value\": \"claude-opus-4.8\" }, { \"name\": \"ANTHROPIC_DEFAULT_SONNET_MODEL\", \"value\": \"gpt-5.5\" }, { \"name\": \"ANTHROPIC_DEFAULT_HAIKU_MODEL\", \"value\": \"deepseek-v4-pro\" }, { \"name\": \"CLAUDE_CODE_ATTRIBUTION_HEADER\", \"value\": \"0\" } ], \"workbench.colorTheme\": \"Default Light Modern\" } 需要注意的是， ANTHROPIC_MODEL 和 ANTHROPIC_DEFAULT_SONNET_MODEL 建议保持为同一个模型，因为 Claude Code 的 /model 切换中会使用这个默认主模型槽位。 4. 点击 VS Code 右上角的 Claude Code 图标，进入 Claude Code 页面，即可开始使用。"},{"title":"Codex App / CLI","heading":"","url":"/scenes/dev-tools/codex-app","text":"Codex App 是 OpenAI 官方桌面版 Codex，Codex CLI 是命令行版 Codex；两者都可以接入 NoneLinear。Codex App 下载安装地址：OpenAI Codex。以下三种方式都会写入 Codex App 与 CLI 共用的配置文件，任选一种即可：单供应商直接用一键配置脚本，需要在多个供应商之间切换时推荐用 cc-switch。你的情况推荐方式 --- --- Windows，只使用 NoneLinear 方式一：Windows 一键配置 macOS / Linux，只使用 NoneLinear 方式二：macOS / Linux 一键配置需要在多个供应商之间切换方式三：通过 cc-switch 配置配置完成后，按验证配置确认接入成功。"},{"title":"Codex App / CLI","heading":"前置要求","url":"/scenes/dev-tools/codex-app#前置要求","text":"- Windows 一键配置或 cc-switch 方式：先安装并运行一次 Codex App 或 Codex CLI。 - macOS / Linux 一键配置：未安装 Codex CLI 时，命令会自动完成安装。 - 已获取 NoneLinear API Key：获取 API Key。 - 使用 cc-switch 时，需要先安装最新版 cc-switch。安装方式可参考 Claude Code 文档中的安装 CC-Switch。"},{"title":"Codex App / CLI","heading":"方式一：Windows 一键配置","url":"/scenes/dev-tools/codex-app#方式一：windows-一键配置","text":"在已安装 Codex 的 Windows 用户账户下，打开 PowerShell 并运行： powershell irm https://docs.nonelinear.com.cn/downloads/codex-setup-windows.ps1 iex 在菜单中输入 1 （Configure or update NoneLinear）。提示输入 API Key 时，请使用鼠标右键粘贴，不要按 Ctrl+V （部分 PowerShell 窗口在隐藏输入模式下会把 Ctrl+V 当作控制字符读入，导致后续请求报错）。输入内容默认不显示，粘贴后直接按回车即可。输入 Key 后，选择默认模型： - deepseek-v4.1-flash - gpt-6-luna - gpt-6.1-sol - gpt-5.6-terra - deepseek-v4-pro - glm-5.3 脚本会先向 https://api.nonelinear.com.cn/v1/responses 发送一条简短请求，验证 API Key 与所选模型是否可用（消耗极少量 token）。验证通过后，自动备份现有配置并写入 NoneLinear 供应商、默认模型和模型目录。完成后请重新打开 Codex 并新建对话窗口，按验证配置测试是否接入成功。默认配置目录为当前 Windows 用户的 ~/.codex （若设置了 CODEX_HOME 则使用该目录）。API Key 会写入 config.toml 供 Codex 调用，请勿外传该文件。输入 Key 的过程不会在终端回显，也不会写入 PowerShell 命令历史。如需恢复一键配置前的状态，再次运行上述命令并在菜单中输入 2 （Restore）。该操作会还原到首次运行一键配置前的备份；如果期间你手动改过配置文件，请先自行备份。"},{"title":"Codex App / CLI","heading":"方式二：macOS / Linux 一键配置","url":"/scenes/dev-tools/codex-app#方式二：macos-/-linux-一键配置","text":"支持 macOS 12 及以上版本（Apple 芯片或 Intel），以及 x86_64 / ARM64 Linux。Linux 需有 bash 、 curl 、 gzip 和 SHA-256 校验工具（ sha256sum 或 shasum ）。首次使用无需提前安装 Codex CLI。命令会检测现有安装；未安装时，下载 OpenAI 官方发布的原生程序包并安装 Codex CLI，再继续配置 NoneLinear。已安装时直接复用，不自动升级。此步骤安装的是命令行版；使用 Codex App 的用户仍可共用配置。"},{"title":"Codex App / CLI","heading":"1. 运行一键配置命令","url":"/scenes/dev-tools/codex-app#1-运行一键配置命令","text":"如果 Codex 已在运行，先退出；然后在终端执行： bash curl -fsSL https://docs.nonelinear.com.cn/downloads/nonelinear-setup-unix.sh bash -s -- --client codex 命令会自动下载适合当前系统的配置工具，校验后打开菜单。首次选择 1 时，如未检测到 Codex CLI，会先完成安装；按提示等待安装结束，再选择模型。整个过程无需安装 Python 或 Node。"},{"title":"Codex App / CLI","heading":"2. 选择模型，输入 API Key","url":"/scenes/dev-tools/codex-app#2-选择模型，输入-api-key","text":"在操作菜单中选择 1 （添加或更新配置），再选择模型序号（默认为 deepseek-v4.1-flash ，可选列表与上方 Windows 一致）。出现粘贴 NoneLinear API Key（隐藏输入）提示时，粘贴 Key 并按回车。终端不会显示字符或星号，无需重复粘贴。脚本会发起一次简短请求验证所选模型（正常计费）；验证未通过时不会改动原配置。看到配置成功：和所选模型 ID 后，重新打开终端并运行 codex ；使用 Codex App 时，重新打开应用。在新对话中按验证配置检查回复。"},{"title":"Codex App / CLI","heading":"更换模型或撤销配置（可选）","url":"/scenes/dev-tools/codex-app#更换模型或撤销配置（可选）","text":"先退出 Codex，再次运行上方完整的一键配置命令： - 输入 1 ：更换模型或更新 API Key。 - 输入 2 ：恢复首次运行一键配置前的状态。恢复会还原 config.toml 和模型目录文件，期间的手动修改也会回退。脚本会先另存当前文件，并显示保存位置。恢复配置不会卸载 Codex CLI。配置默认写入 ~/.codex （若设置了 CODEX_HOME 则使用该目录）。Key 保存在 config.toml 中，原配置备份在同目录的 nonelinear-unix-codex-backup 下。配置文件和备份均包含 Key，请勿公开分享。"},{"title":"Codex App / CLI","heading":"方式三：通过 cc-switch 配置","url":"/scenes/dev-tools/codex-app#方式三：通过-cc-switch-配置","text":"最新版 cc-switch 的 Codex 配置同时适用于 Codex App 和 Codex CLI。下文以 Codex App 界面为例，Codex CLI 的配置步骤完全相同。"},{"title":"Codex App / CLI","heading":"第 1 步：进入 cc-switch 的 Codex 配置页","url":"/scenes/dev-tools/codex-app#第-1-步：进入-cc-switch-的-codex-配置页","text":"打开 cc-switch，点击顶部的 Codex 图标进入供应商配置页。如果已添加过 NoneLinear，直接点击对应卡片编辑；如果尚未添加，点击右上角 + 新增供应商。 !cc-switch Codex 配置页"},{"title":"Codex App / CLI","heading":"第 2 步：配置 NoneLinear 供应商","url":"/scenes/dev-tools/codex-app#第-2-步：配置-nonelinear-供应商","text":"在供应商编辑页填写以下信息：字段填写内容 :--- :--- 供应商名称 NoneLinear 官网链接 https://nonelinear.com.cn/ API Key 你的 NoneLinear API Key API 请求地址 https://api.nonelinear.com.cn/v1 !cc-switch 配置 NoneLinear Codex App 供应商"},{"title":"Codex App / CLI","heading":"第 3 步：添加模型映射","url":"/scenes/dev-tools/codex-app#第-3-步：添加模型映射","text":"在模型映射中添加要在 Codex App / CLI 里使用的模型：字段填写内容 :--- :--- 菜单显示名在 Codex App / CLI / cc-switch 中展示的名称，例如 deepseek-v4-pro 实际请求模型 NoneLinear 的真实模型 ID，例如 deepseek-v4-pro 上下文窗口可选；不确定时可留空或按模型实际上下文长度填写如需配置多个模型，可逐行添加。模型 ID 必须与 NoneLinear 模型列表中的名称完全一致。 !cc-switch 配置 Codex App 模型映射新版 cc-switch 也支持在配置页直接点击获取模型列表，自动拉取 NoneLinear 可用模型并在下拉框中选择： !cc-switch 获取 NoneLinear Codex 模型列表配置完成后点击保存并启用该配置，然后按验证配置确认接入成功。"},{"title":"Codex App / CLI","heading":"Token 消耗注意事项","url":"/scenes/dev-tools/codex-app#token-消耗注意事项","text":"Codex App / CLI 是编程 Agent，而非普通聊天窗口。每次请求的账单 token 按完整上下文计算，包含系统提示词、工具定义、会话状态、历史消息，以及 Agent 自动读取的目录结构、文件片段和命令输出。因此在大型项目或长会话中，哪怕只发一句简单问候，也会附带大量上下文，消耗远多于普通聊天的输入 token。首次测试建议在空目录或小型项目下进行，发送“请只回复 OK”之类简单指令即可，避免一开始就在大型代码仓库中测试。"},{"title":"Codex App / CLI","heading":"验证配置","url":"/scenes/dev-tools/codex-app#验证配置","text":"三种配置方式的验证方法相同，按你使用的客户端对应测试即可（建议在空目录或小项目下测试，原因见Token 消耗注意事项）。"},{"title":"Codex App / CLI","heading":"Codex App","url":"/scenes/dev-tools/codex-app#codex-app","text":"重新打开 Codex App，新建对话或进入项目目录，发送一条简单测试消息，例如： text 这个目录下有没有 py 脚本如果 Codex App 能正常读取项目并返回结果，说明 NoneLinear 接入成功。 !Codex App 接入 NoneLinear 后验证成功"},{"title":"Codex App / CLI","heading":"Codex CLI","url":"/scenes/dev-tools/codex-app#codex-cli","text":"重新打开终端，进入项目目录并运行： bash codex 发送一条简单测试消息，如果 CLI 能正常返回结果，说明配置已生效。"},{"title":"Codex App / CLI","heading":"常见现象排查说明","url":"/scenes/dev-tools/codex-app#常见现象排查说明","text":"以下说明通过 cc-switch 接入 Codex App / CLI 时的两个常见现象（截图中的 gpt-5.5 、 deepseek-v4-flash 、 kimi-k2.6 仅为示例模型名）。"},{"title":"Codex App / CLI","heading":"为什么 API 明细里会出现未配置的 gpt-5.4-mini","url":"/scenes/dev-tools/codex-app#为什么-api-明细里会出现未配置的-gpt-5-4-mini","text":"该现象仅出现在 Codex App 中。 gpt-5.4-mini 是 OpenAI 官方在 Codex App 底层写死的后台辅助模型。当 Codex App 读取项目文件、检索代码或整理上下文时，会自动发起 gpt-5.4-mini 请求，不受 cc-switch 模型列表或界面当前所选模型的影响。 NoneLinear 会正常接收并处理这些辅助请求，因此你会在调用明细里看到 gpt-5.4-mini 的记录。如下图所示，主对话回答使用的是你在 cc-switch 中配置的模型，而 gpt-5.4-mini 则是 Codex App 自动并发调用的子任务模型： !Codex API 调用明细中主代理与子代理并发调用"},{"title":"Codex App / CLI","heading":"为什么 Codex CLI 能显示自定义模型，Codex App 只显示内置选项","url":"/scenes/dev-tools/codex-app#为什么-codex-cli-能显示自定义模型，codex-app-只显示内置选项","text":"在相同的 cc-switch 配置下，Codex CLI 可以正常列出你配置的自定义模型（下图中的模型名仅为示例）： !Codex CLI 可以显示 cc-switch 自定义模型但 Codex 桌面端的模型下拉框目前是前端写死的，不支持动态读取自定义模型列表，界面上只会显示官方的 GPT-5.5 系列与“极低、低、中、高、超高、最高”等推理强度选项： !Codex App 模型选择器显示官方模型与推理额度界面只显示 GPT-5.5 并不影响 cc-switch 配置生效——实际请求仍会走 cc-switch 中已启用的模型（默认使用列表中的第一个模型）。如果同一台电脑上同时安装了 Codex CLI 和 Codex App：在 Codex CLI 中切换模型后，重新打开 Codex App 并新建对话窗口，新窗口就会跟随使用 CLI 刚切换的模型；而旧对话窗口则会继续沿用原来的模型。"},{"title":"OpenCode","heading":"","url":"/scenes/dev-tools/opencode","text":"OpenCode 是一款开源的 AI 编程 Agent，支持终端界面、桌面应用和 IDE 扩展。本文使用 CC Switch 的 OpenCode 模块，以 OpenAI Compatible 格式接入 NoneLinear API。"},{"title":"OpenCode","heading":"前置要求","url":"/scenes/dev-tools/opencode#前置要求","text":"- 已获取 NoneLinear API Key。 - 已确认要使用的模型 ID，可在 NoneLinear 模型列表中查询。 - 已安装最新版 CC Switch。下载安装方式可参考 Claude Code 文档中的 CC Switch 安装说明。"},{"title":"OpenCode","heading":"1. 安装 OpenCode","url":"/scenes/dev-tools/opencode#1-安装-opencode","text":"macOS 和 Linux 推荐使用 OpenCode 官方安装脚本： bash curl -fsSL https://opencode.ai/install bash 也可以使用 npm 或 Homebrew： bash npm install -g opencode-ai bash brew install anomalyco/tap/opencode Windows 可以使用 npm、Chocolatey 或 Scoop： powershell npm install -g opencode-ai powershell choco install opencode powershell scoop install opencode 安装完成后，执行以下命令；如果能够显示版本号，说明安装成功： bash opencode --version 更多安装方式和平台说明请查看 OpenCode 官方安装文档。"},{"title":"OpenCode","heading":"2. 进入 CC Switch 的 OpenCode 配置页","url":"/scenes/dev-tools/opencode#2-进入-cc-switch-的-opencode-配置页","text":"打开 CC Switch，切换到顶部的 OpenCode 模块，点击右上角 + ，然后选择自定义配置。在基础信息区域填写：字段填写内容 :--- :--- 供应商标识 nonelinear 供应商名称 NoneLinear 官网链接 https://nonelinear.com.cn/ 供应商标识是写入 OpenCode 配置文件的唯一 ID，只能使用小写字母、数字和连字符。后续在 OpenCode 中看到的模型名称会以 nonelinear/模型ID 的形式显示。 !在 CC Switch 中新增 OpenCode 自定义供应商"},{"title":"OpenCode","heading":"3. 配置 NoneLinear API","url":"/scenes/dev-tools/opencode#3-配置-nonelinear-api","text":"继续向下填写接口信息：字段填写内容 :--- :--- 接口格式 OpenAI Compatible API Key 你的 NoneLinear API Key Base URL https://api.nonelinear.com.cn/v1 在额外选项中添加一项：键名值 :--- :--- setCacheKey true setCacheKey: true 会让 OpenCode 为该供应商的请求始终设置缓存键，有利于支持提示词缓存的模型复用稳定上下文。CC Switch 会自动把 true 解析为布尔值。 !配置 NoneLinear API 地址、密钥和缓存键 API Key 属于敏感凭据，请勿在截图、聊天记录或公开仓库中泄露。本文截图中的 API Key 已隐藏。"},{"title":"OpenCode","heading":"4. 添加模型","url":"/scenes/dev-tools/opencode#4-添加模型","text":"填写 API Key 和 Base URL 后，在模型配置区域点击获取模型列表。CC Switch 会调用 NoneLinear 的模型接口，并在下拉列表中显示当前可用模型。选择需要的模型后，可以按需填写显示名称。模型 ID 必须与 NoneLinear 模型列表中的名称保持一致，包括大小写、连字符和版本号。如果没有自动获取到模型，也可以点击添加模型手动填写。需要多个模型时，逐行添加即可。 !获取并添加 NoneLinear 模型配置完成后，点击右下角添加；回到供应商列表后，启用刚创建的 NoneLinear 配置。"},{"title":"OpenCode","heading":"5. 在 OpenCode 中验证","url":"/scenes/dev-tools/opencode#5-在-opencode-中验证","text":"关闭已运行的 OpenCode 会话，重新打开终端并进入一个空目录或小型项目： bash cd /path/to/your-project opencode 进入 OpenCode 后执行： text /models 在模型列表中选择 nonelinear 供应商下的模型，然后发送一条简单测试消息，例如： text 请只回复 OK 能够正常返回结果，说明 NoneLinear API 已接入成功。首次在项目中使用时，还可以执行： text /init OpenCode 会分析项目，并在项目根目录生成 AGENTS.md ，用于记录项目结构和开发规范。建议将该文件提交到 Git。"},{"title":"OpenCode","heading":"常见问题","url":"/scenes/dev-tools/opencode#常见问题","text":""},{"title":"OpenCode","heading":"获取模型列表失败","url":"/scenes/dev-tools/opencode#获取模型列表失败","text":"确认 API Key 有效，且 Base URL 完整填写为 https://api.nonelinear.com.cn/v1 。如果仍然失败，可以根据 NoneLinear 模型列表手动添加模型。"},{"title":"OpenCode","heading":"OpenCode 中看不到 NoneLinear 或新模型","url":"/scenes/dev-tools/opencode#opencode-中看不到-nonelinear-或新模型","text":"确认供应商已经保存并启用，然后完全退出当前 OpenCode 会话并重新运行 opencode 。在 /models 中查找 nonelinear 供应商。"},{"title":"OpenCode","heading":"为什么简单问题也会消耗较多 Token","url":"/scenes/dev-tools/opencode#为什么简单问题也会消耗较多-token","text":"OpenCode 是编程 Agent，请求中还会包含系统提示词、工具定义、历史上下文以及读取到的项目文件和命令结果。初次连通性测试建议使用空目录或小目录，并优先选择性价比较高的模型。更多配置方式可查看 OpenCode 提供商文档。"},{"title":"Reasonix","heading":"","url":"/scenes/dev-tools/reasonix","text":"Reasonix 是一款面向代码开发的 AI Agent 工具，提供桌面版和终端版。两种版本都可以通过 OpenAI Chat Completions 兼容接口接入 NoneLinear，核心配置保持一致：配置项填写内容 :--- :--- API 协议 OpenAI-compatible / OpenAI Chat Completions API 地址 / Base URL https://api.nonelinear.com.cn/v1 API Key 你的 NoneLinear API Key 模型 ID 在模型列表中选择，例如 deepseek-v4-pro 不要在截图、工单、公开仓库或聊天群中暴露真实 API Key。如果怀疑 Key 泄露，请立即在 NoneLinear 控制台删除并重新生成。"},{"title":"Reasonix","heading":"前置要求","url":"/scenes/dev-tools/reasonix#前置要求","text":"- 已获取 NoneLinear API Key：获取 API Key。 - 已确认要使用的模型 ID：模型列表。 - 如果使用终端版，需要安装 Node.js 18 或更高版本：Node.js 下载。"},{"title":"Reasonix","heading":"一、桌面版接入","url":"/scenes/dev-tools/reasonix#一、桌面版接入","text":""},{"title":"Reasonix","heading":"1. 下载并安装桌面版","url":"/scenes/dev-tools/reasonix#1-下载并安装桌面版","text":"打开 Reasonix 官网的安装区域：https://reasonix.io/ start，切换到 Desktop / 桌面端，根据系统下载安装包：系统选择 :--- :--- macOS Universal DMG，适用于 Apple Silicon 和 Intel Windows Installer，适用于 Windows 10+ Linux .deb 或通用 tar.gz 安装后启动 Reasonix，进入设置页面。"},{"title":"Reasonix","heading":"2. 进入模型接入设置","url":"/scenes/dev-tools/reasonix#2-进入模型接入设置","text":"在 Reasonix 桌面版中打开设置 → 模型 → 接入。如果还没有添加过供应商，页面会显示供应商接入区域，点击 + 添加模型服务。 !Reasonix 桌面版添加模型服务入口"},{"title":"Reasonix","heading":"3. 添加 NoneLinear 供应商","url":"/scenes/dev-tools/reasonix#3-添加-nonelinear-供应商","text":"添加供应商时，可以使用自定义供应商，并按下面方式填写：字段填写内容 :--- :--- 自定义供应商名称 NoneLinear 接入协议 OpenAI-compatible API 地址 https://api.nonelinear.com.cn/v1 完整 URL 关闭密钥你的 NoneLinear API Key Reasonix 会自动把 /chat/completions 拼接到 Base URL 后面，所以 API 地址只需要填写 https://api.nonelinear.com.cn/v1 ，不要额外填写完整请求路径。 !Reasonix 桌面版配置 NoneLinear 供应商"},{"title":"Reasonix","heading":"4. 测试并获取模型","url":"/scenes/dev-tools/reasonix#4-测试并获取模型","text":"填写 API 地址和密钥后，点击测试并获取模型。如果连接成功，Reasonix 会返回可用模型列表。你可以直接从发现的模型中勾选要启用的模型，也可以在模型列表中手动填写模型 ID。模型 ID 必须与 NoneLinear 模型列表完全一致，包括大小写、连字符和版本号。 !Reasonix 桌面版测试并获取模型"},{"title":"Reasonix","heading":"5. 启用并验证","url":"/scenes/dev-tools/reasonix#5-启用并验证","text":"保存供应商配置后，回到 Reasonix 主界面，在模型选择器中选择刚刚启用的 NoneLinear 模型。发送一条简单测试消息，例如： text 请用一句话说明你当前可以帮助我做什么。如果 Reasonix 正常返回内容，说明桌面版已经接入成功。"},{"title":"Reasonix","heading":"二、终端版接入","url":"/scenes/dev-tools/reasonix#二、终端版接入","text":""},{"title":"Reasonix","heading":"1. 安装 Reasonix CLI","url":"/scenes/dev-tools/reasonix#1-安装-reasonix-cli","text":"在终端、CMD 或 PowerShell 中执行： bash npm i -g reasonix@next 安装完成后检查版本： bash reasonix --version 如果能看到版本号，说明安装成功。"},{"title":"Reasonix","heading":"2. 启动配置向导","url":"/scenes/dev-tools/reasonix#2-启动配置向导","text":"首次接入时执行： bash reasonix setup Reasonix 会进入交互式配置向导。后续正常使用时执行 reasonix 即可，只有需要重新配置时才使用 reasonix setup 。"},{"title":"Reasonix","heading":"3. 选择第三方 OpenAI 兼容模型","url":"/scenes/dev-tools/reasonix#3-选择第三方-openai-兼容模型","text":"在 Provider 选择界面，选择添加第三方OpenAI兼容模型： 1. 使用上下方向键移动到该选项。 2. 按空格键选中。 3. 按回车键确认。 Reasonix 的选择界面需要先按空格选中，再按回车确认。只按回车可能不会选中当前选项。 !Reasonix CLI 选择第三方 OpenAI 兼容模型"},{"title":"Reasonix","heading":"4. 填写 NoneLinear 配置","url":"/scenes/dev-tools/reasonix#4-填写-nonelinear-配置","text":"配置向导会依次提示填写以下信息：提示项填写内容 :--- :--- Base URL https://api.nonelinear.com.cn/v1 API Key 环境变量名可使用默认建议名，也可以填写 NONELINEAR_API_KEY API Key 你的 NoneLinear API Key 模型名称例如 deepseek-v4-pro 其中 Base URL 不要填写到 /chat/completions ，Reasonix 会自动拼接请求路径。 !Reasonix CLI 填写 NoneLinear 配置信息"},{"title":"Reasonix","heading":"5. 确认 API Key","url":"/scenes/dev-tools/reasonix#5-确认-api-key","text":"填写完成后，Reasonix 可能会提示是否重新输入 API Key。方括号中是你在上一步使用的环境变量名，使用默认建议名时显示如下： text 重新输入 [CUSTOM_API_NONELINEAR_COM_API_KEY]？[y/N]: 如果确认 API Key 已正确输入，直接按回车或输入 N 后回车即可。若需要重新输入，输入 y 后回车。"},{"title":"Reasonix","heading":"6. 启动使用","url":"/scenes/dev-tools/reasonix#6-启动使用","text":"配置完成后，在项目目录中执行： bash reasonix 进入 Reasonix 交互界面后，可以发送一条简单测试消息确认模型是否可用。"},{"title":"Reasonix","heading":"常见问题","url":"/scenes/dev-tools/reasonix#常见问题","text":""},{"title":"Reasonix","heading":"API 地址应该填什么？","url":"/scenes/dev-tools/reasonix#api-地址应该填什么？","text":"填写 Base URL： text https://api.nonelinear.com.cn/v1 不要填写： text https://api.nonelinear.com.cn/v1/chat/completions"},{"title":"Reasonix","heading":"模型 ID 应该怎么填？","url":"/scenes/dev-tools/reasonix#模型-id-应该怎么填？","text":"模型 ID 必须与 NoneLinear 模型列表中展示的 ID 完全一致。示例： text deepseek-v4-pro deepseek-v4-flash gpt-5.5 DeepSeek-V3.2-Think"},{"title":"Reasonix","heading":"配置后调用失败怎么办？","url":"/scenes/dev-tools/reasonix#配置后调用失败怎么办？","text":"优先检查以下三项： - API Key 是否完整复制，前后不要带空格。 - API 地址是否为 https://api.nonelinear.com.cn/v1 。 - 模型 ID 是否与 NoneLinear 模型列表完全一致。"},{"title":"Reasonix","heading":"如何更换模型？","url":"/scenes/dev-tools/reasonix#如何更换模型？","text":"桌面版可以在设置 → 模型 → 接入中编辑供应商，重新勾选或填写模型。终端版可以重新执行： bash reasonix setup 然后按配置向导重新填写模型 ID、API Key 或 Base URL。"},{"title":"Reasonix","heading":"参考链接","url":"/scenes/dev-tools/reasonix#参考链接","text":"- Reasonix 官网下载 - Reasonix 官方文档 - Reasonix npm - NoneLinear API Key 获取 - NoneLinear 模型列表"},{"title":"Cline","heading":"接入 Cline","url":"/scenes/dev-tools/cline#接入-cline","text":"Cline 是一款强大的 AI 编程助手插件，支持在多种 IDE 中使用。通过接入 NoneLinear API，你可以充分发挥 Cline 的自动化编程能力。"},{"title":"Cline","heading":"1. 安装与部署","url":"/scenes/dev-tools/cline#1-安装与部署","text":"在 Trae 、 Cursor 或 VS Code 的扩展商店中搜索「Cline」，点击安装按钮完成部署。"},{"title":"Cline","heading":"2. 配置步骤","url":"/scenes/dev-tools/cline#2-配置步骤","text":""},{"title":"Cline","heading":"2.1 Cursor","url":"/scenes/dev-tools/cline#2-1-cursor","text":"启动 Cline 插件并登录 Cline 账号后进入设置页面，在 API Provider（API提供商）的下拉选项中，务必选择「OpenAI Compatible」模式。 !Cline 配置界面这是接入自建平台的核心步骤——该模式允许我们使用任何遵循 OpenAI 接口规范的服务。然后在模型配置界面依次填写： - Base URL ： https://api.nonelinear.com.cn/v1 - API Key ：访问 NoneLinear 官网获取 - Model Name ：可以在模型列表中找到想要使用的模型名称 !可选的模型列表如果使用 gpt-5.5-high 、 DeepSeek-V3.2-Think 这类模型名称中已经带有明显思考模式标识的模型，NoneLinear 会根据模型命名在平台内部配置好对应的思考参数，无需在 Cline 中额外调整思考相关选项。将上述三个参数填入后，点击「Done」即可。 !Cline 接入成功界面 !Cline 对话成功界面"},{"title":"Cline","heading":"2.2 Trae","url":"/scenes/dev-tools/cline#2-2-trae","text":"Trae 安装 Cline 并接入 API 的操作流程与 Cursor 完全一致： 1. 在插件商店找到 Cline 插件并安装。 2. 配置「OpenAI Compatible」模式。 3. 填入对应的 Base URL 、 API KEY 和 Model Name 。 !Trae 配置界面"},{"title":"Cline","heading":"2.3 VS Code","url":"/scenes/dev-tools/cline#2-3-vs-code","text":"VS Code 同样可以安装 Cline 插件，整个配置流程与 Trae 和 Cursor 一样。"},{"title":"Cline","heading":"3. 注意事项","url":"/scenes/dev-tools/cline#3-注意事项","text":"- 确保选择的是「OpenAI Compatible」模式。 - 使用带思考模式标识的模型时，例如 gpt-5.5-high 、 DeepSeek-V3.2-Think ，按正常方式填写模型名称即可，NoneLinear 会在平台侧处理对应的思考参数。 - 如果连接失败，请检查 API Key 是否正确，以及网络是否通畅。"},{"title":"Trae","heading":"","url":"/scenes/dev-tools/trae","text":"Trae 国际版支持添加自定义 OpenAI Chat Completions 兼容模型。将模型配置为自定义服务，并填写 NoneLinear 的 API 地址、API Key 和模型 ID 后，即可在 Trae 中调用 NoneLinear 模型进行代码问答、Agent 辅助开发和多模态任务。"},{"title":"Trae","heading":"前置要求","url":"/scenes/dev-tools/trae#前置要求","text":"- 已安装 Trae 国际版。下载地址：https://www.trae.ai/。 - 已获取 NoneLinear API Key：获取 API Key。 - 已确认要使用的模型 ID：模型列表。"},{"title":"Trae","heading":"配置步骤","url":"/scenes/dev-tools/trae#配置步骤","text":""},{"title":"Trae","heading":"1. 进入模型设置","url":"/scenes/dev-tools/trae#1-进入模型设置","text":"打开 Trae 后，点击右上角的设置图标，进入设置页面。在左侧菜单中选择模型，然后在模型管理区域点击添加模型。 !Trae 进入模型设置并添加模型"},{"title":"Trae","heading":"2. 选择自定义配置","url":"/scenes/dev-tools/trae#2-选择自定义配置","text":"在添加模型弹窗中，切换到自定义配置。然后填写以下信息：字段填写内容 :--- :--- API 格式 OpenAI Chat Completions 格式自定义请求地址 https://api.nonelinear.com.cn/v1 完整 URL 关闭模型 ID 例如 gpt-5.4-medium API 密钥你的 NoneLinear API Key 填写完成后点击添加模型。 !Trae 配置 NoneLinear 自定义模型 Trae 会自动把 /chat/completions 补到你填写的服务地址末尾。因此自定义请求地址填写 https://api.nonelinear.com.cn/v1 即可，不要额外拼接 /chat/completions 。不要在截图、工单、公开仓库或聊天群中暴露真实 API Key。如果怀疑 Key 泄露，请立即在 NoneLinear 控制台删除并重新生成。"},{"title":"Trae","heading":"3. 启用并测试模型","url":"/scenes/dev-tools/trae#3-启用并测试模型","text":"添加完成后，回到模型列表，在自定义分组下确认刚刚添加的模型已启用。然后回到 Trae 对话或 Agent 面板，在模型选择器中选择该 NoneLinear 模型，发送一条测试消息，例如： text 请用一句话介绍你当前模型可以做什么。如果模型正常回复，说明 Trae 已经成功接入 NoneLinear API。"},{"title":"Trae","heading":"常见问题","url":"/scenes/dev-tools/trae#常见问题","text":""},{"title":"Trae","heading":"自定义请求地址应该填 Base URL 还是完整路径？","url":"/scenes/dev-tools/trae#自定义请求地址应该填-base-url-还是完整路径？","text":"Trae 的自定义请求地址填写 Base URL： text https://api.nonelinear.com.cn/v1 不要填写： text https://api.nonelinear.com.cn/v1/chat/completions 因为 Trae 会自动拼接 /chat/completions 。"},{"title":"Trae","heading":"完整 URL 开关要打开吗？","url":"/scenes/dev-tools/trae#完整-url-开关要打开吗？","text":"通常保持关闭。关闭后，Trae 会按 OpenAI Chat Completions 格式自动补全请求路径。只有在你明确需要把请求发送到一个完整接口地址时，才考虑打开完整 URL 。"},{"title":"Trae","heading":"模型 ID 应该怎么填？","url":"/scenes/dev-tools/trae#模型-id-应该怎么填？","text":"模型 ID 必须与 NoneLinear 模型列表中展示的 ID 完全一致，包括大小写、连字符和版本号。示例： text gpt-5.4-medium gpt-5.4-mini DeepSeek-V3.2-Think"},{"title":"Trae","heading":"使用思考模型时需要额外配置 reasoning effort 吗？","url":"/scenes/dev-tools/trae#使用思考模型时需要额外配置-reasoning-effort-吗？","text":"如果使用 gpt-5.5-high 、 DeepSeek-V3.2-Think 这类模型名称中已经带有明显思考模式标识的模型，一般不需要在工具侧额外配置 reasoning effort。NoneLinear 已经根据模型命名在平台内部配置好对应的思考参数。"},{"title":"Trae","heading":"配置后调用失败怎么办？","url":"/scenes/dev-tools/trae#配置后调用失败怎么办？","text":"优先检查三项： - API Key 是否完整复制，前后不要带空格。 - 自定义请求地址是否为 https://api.nonelinear.com.cn/v1 。 - 模型 ID 是否与 NoneLinear 模型列表完全一致。"},{"title":"WorkBuddy","heading":"","url":"/scenes/productivity-tools/workbuddy","text":"WorkBuddy 支持接入 NoneLinear 的 OpenAI 兼容模型。可以根据系统选择一键脚本配置，或直接在 WorkBuddy 界面中手动添加，配置完成后即可在新建任务中选用对应模型。使用方式从这里开始 --- --- Windows，使用 PowerShell 配置 Windows 一键配置 MacBook / macOS，使用终端配置 macOS 一键配置在 WorkBuddy 界面中填写参数手动配置准备好 NoneLinear API Key。Windows 或手动配置方式需先安装并登录 WorkBuddy；macOS 一键配置会在未安装时自动下载安装。下面三种方式任选一种即可。一键配置支持一次添加或更新多个模型。同一批使用一个 API Key，每个模型分别发送一次正常计费的简短请求，全部验证成功后才备份并写入；任一模型失败，本批次不写入。"},{"title":"WorkBuddy","heading":"Windows 一键配置","url":"/scenes/productivity-tools/workbuddy#windows-一键配置","text":"开始前，等待任务结束，再从 Windows 右下角托盘退出 WorkBuddy。"},{"title":"WorkBuddy","heading":"1. 打开 PowerShell，运行命令","url":"/scenes/productivity-tools/workbuddy#1-打开-powershell，运行命令","text":"在 Windows 开始菜单搜索 PowerShell ，运行以下命令： powershell & ([scriptblock]::Create((Invoke-RestMethod -Uri 'https://docs.nonelinear.com.cn/downloads/workbuddy-setup-windows.ps1' -ErrorAction Stop))) 看到 NoneLinear WorkBuddy Setup 0.2.0 (Windows) 后，在菜单中输入 1 （ Add / update models ）并按回车。下面以同时添加 deepseek-v4.1-flash 和 gpt-6-luna 为例。 !Windows WorkBuddy 配置菜单：选择 1 添加或更新模型查看大图"},{"title":"WorkBuddy","heading":"2. 选择模型，输入 API Key","url":"/scenes/productivity-tools/workbuddy#2-选择模型，输入-api-key","text":"输入多个模型序号或完整模型 ID，用逗号或空格分隔，例如 1,3,6 。也可以混合输入，如 1,gpt-6-luna ，或直接填写列表外的完整模型 ID。重复选择会自动合并；直接按回车只选 deepseek-v4.1-flash 。默认列表如下，可同时选择多个：序号模型 ID --- --- 1 deepseek-v4.1-flash （默认） 2 gpt-6-luna 3 gpt-6.1-sol 4 gpt-5.6-terra 5 deepseek-v4-pro 6 glm-5.3 脚本会逐个检查所选模型的连通性和工具调用，显示每项“通过”或“失败”；全部通过后才统一写入。失败时会列出模型 ID，请按报错处理或移除失败项后重试。脚本会开启“工具调用”、关闭“自定义协议”；更新已有模型时，其余高级选项保持不变。如模型支持图片输入或推理模式，可在配置后进入 WorkBuddy 的设置 → 模型按需勾选。 !Windows WorkBuddy 模型菜单：可输入多个序号或完整模型 ID 查看大图出现 Paste your NoneLinear API Key (hidden) 提示时，请用鼠标右键粘贴，不要按 Ctrl+V ，粘贴后按回车（Key 不会明文显示，部分窗口会显示星号）。 !Windows PowerShell 输入 Key 前显示鼠标右键粘贴提醒查看大图"},{"title":"WorkBuddy","heading":"3. 选择模型并验证","url":"/scenes/productivity-tools/workbuddy#3-选择模型并验证","text":"每个模型显示 [PASS] ，并看到 [OK] Added / updated: 和本次所选的模型列表，表示检查通过且配置已保存。下图中，重复选择的 deepseek-v4.1-flash 已自动合并，实际检查并保存了两个模型。 !两个模型分别通过检查，WorkBuddy 配置保存成功查看大图 1. 打开 WorkBuddy（首次使用按提示登录），点击新建任务。 2. 展开输入框下方的模型选择器，在自定义模型 / Custom models 分组下选择刚配置的模型。 3. 发送一条简单消息，收到回复后核对消息底部显示的模型名称。 !Windows WorkBuddy 自定义模型分组中同时显示 deepseek-v4.1-flash 和 gpt-6-luna 查看大图 text 你好，请只回复“WorkBuddy 接入成功” 如果模型选择器仍停留在“快速”等默认档位，请先手动切换到刚添加的自定义模型（新增模型不会自动替换已有会话的模型设置）。 !Windows WorkBuddy 使用 gpt-6-luna 回复接入成功查看大图"},{"title":"WorkBuddy","heading":"更新或恢复（可选）","url":"/scenes/productivity-tools/workbuddy#更新或恢复（可选）","text":"配置成功后可直接使用，只有需要调整或撤销配置时才执行以下操作。从 Windows 右下角托盘退出 WorkBuddy，再次运行本节开头的完整 PowerShell 命令：菜单选项用途 --- --- 1 — Add / update models 添加模型或更换 Key；配置后在 WorkBuddy 中选择对应模型。 2 — Restore the original model configuration 撤销一键配置，恢复首次配置前的模型设置。配置通常保存在用户目录的 .workbuddy/models.json ，备份也在该目录下；设置了自定义目录时，以脚本显示的路径为准。配置与备份可能含 Key，请勿公开分享。"},{"title":"WorkBuddy","heading":"Windows 配置遇到问题","url":"/scenes/productivity-tools/workbuddy#windows-配置遇到问题","text":"提示或现象处理方式 --- --- 提示 WorkBuddy 仍在运行从系统托盘退出应用；只关闭窗口可能仍在后台运行。同名模型使用了其他接口脚本不会覆盖其他提供商；先到 WorkBuddy 设置中检查该模型。模型检查失败按错误信息核对 Key、模型权限、账户余额；网络或证书错误则检查终端网络。仍无法解决时，向技术支持提供系统、WorkBuddy 版本、模型 ID 和报错信息，不要发送 Key。"},{"title":"WorkBuddy","heading":"macOS 一键配置","url":"/scenes/productivity-tools/workbuddy#macos-一键配置","text":"支持 macOS 12 及以上版本，Apple 芯片和 Intel 均可使用。未安装 WorkBuddy 时会自动下载官方安装包，校验签名后安装到当前用户的 ~/Applications ；已安装时直接复用，不自动升级。"},{"title":"WorkBuddy","heading":"1. 打开终端，运行一键配置命令","url":"/scenes/productivity-tools/workbuddy#1-打开终端，运行一键配置命令","text":"如果 WorkBuddy 已在运行，先从顶部菜单栏退出；然后在终端复制并运行下面的整条命令： bash curl -fsSL https://docs.nonelinear.com.cn/downloads/nonelinear-setup-unix.sh bash -s -- --client workbuddy 命令会自动下载适合当前 Mac 的配置工具，校验后打开菜单。首次选择 1 时，如未安装 WorkBuddy，会先自动安装，再继续选择模型。添加模型、更新和恢复都从这个菜单操作。"},{"title":"WorkBuddy","heading":"2. 选择模型，输入 API Key","url":"/scenes/productivity-tools/workbuddy#2-选择模型，输入-api-key-2","text":"在操作菜单中选择 1 （添加或更新配置），再输入多个序号或完整模型 ID，用逗号或空格分隔，例如 1,3,6 或 1,gpt-6-luna 。也可填写列表外的完整模型 ID；重复选择会自动合并，直接按回车只选 deepseek-v4.1-flash 。默认列表如下，可同时选择多个：序号模型 ID --- --- 1 deepseek-v4.1-flash （默认） 2 gpt-6-luna 3 gpt-6.1-sol 4 gpt-5.6-terra 5 deepseek-v4-pro 6 glm-5.3 脚本会逐个检查所选模型的连通性和工具调用，显示每项“通过”或“失败”；全部通过后才统一写入。失败时会列出模型 ID，请按报错处理或移除失败项后重试。脚本会开启“工具调用”、关闭“自定义协议”；更新已有模型时，其余高级选项保持不变。如模型支持图片输入或推理模式，可在配置后进入 WorkBuddy 的设置 → 模型按需勾选。出现粘贴 NoneLinear API Key（隐藏输入）提示时，粘贴 Key 并按回车。终端不会显示字符或星号，无需重复粘贴。"},{"title":"WorkBuddy","heading":"3. 选择模型并验证","url":"/scenes/productivity-tools/workbuddy#3-选择模型并验证-2","text":"看到配置成功：和本次所选的模型列表后，按以下步骤验证： 1. 打开 WorkBuddy（首次使用按提示登录），点击新建任务。 2. 展开输入框下方的模型选择器，在自定义模型 / Custom models 分组下选择刚配置的模型。 3. 发送一条简单消息，收到回复后核对消息底部显示的模型名称。 text 你好，请只回复“WorkBuddy 接入成功” 如果模型选择器仍停留在“快速”等默认档位，请先手动切换到刚添加的自定义模型（新增模型不会自动替换已有会话的模型设置）。"},{"title":"WorkBuddy","heading":"更新或恢复（可选）","url":"/scenes/productivity-tools/workbuddy#更新或恢复（可选）-2","text":"退出 WorkBuddy，再次运行本节开头的完整一键配置命令，仍然会进入同一个菜单：输入操作 --- --- 1 添加或更新配置：选择模型，输入新 Key。 2 恢复原配置：撤销一键配置，回到首次配置前的模型设置。只有需要撤销配置时才选 2 ，正常使用不需要恢复。恢复配置不会卸载 WorkBuddy。配置通常位于 ~/.workbuddy/models.json ，备份也在该目录下；如果设置了 WORKBUDDY_CONFIG_DIR 或 CODEBUDDY_CONFIG_DIR ，以脚本显示的路径为准。配置与备份可能含 Key，请勿公开分享。"},{"title":"WorkBuddy","heading":"macOS 配置遇到问题","url":"/scenes/productivity-tools/workbuddy#macos-配置遇到问题","text":"提示或现象处理方式 --- --- 下载或安装校验失败检查网络后，重新运行本节开头的完整命令；不要跳过文件或应用签名校验。提示 WorkBuddy 仍在运行从顶部 WorkBuddy 菜单选择退出；点击窗口红叉不会退出应用。同名模型使用了其他接口脚本不会覆盖其他提供商；先到 WorkBuddy 设置中检查该模型。模型检查失败按错误信息核对 Key、模型权限、账户余额；网络或证书错误则检查终端网络。仍无法解决时，向技术支持提供 macOS、WorkBuddy 版本、模型 ID 和报错信息，不要发送 Key。"},{"title":"WorkBuddy","heading":"手动配置","url":"/scenes/productivity-tools/workbuddy#手动配置","text":"如果你希望在图形界面中手动添加，或想了解底层配置项，可参考以下步骤（已完成一键配置的用户可跳过；截图仅示意入口位置，模型名称以正文为准）。"},{"title":"WorkBuddy","heading":"1. 下载 WorkBuddy","url":"/scenes/productivity-tools/workbuddy#1-下载-workbuddy","text":"打开 WorkBuddy 下载页，根据电脑系统选择对应安装包。Windows 用户选择 Windows x64 ；macOS 用户根据芯片类型选择 Apple 芯片或 Intel 版本。 !WorkBuddy 下载页面"},{"title":"WorkBuddy","heading":"2. 安装并同意协议","url":"/scenes/productivity-tools/workbuddy#2-安装并同意协议","text":"运行安装包，勾选我同意此协议，点击下一步完成安装。 !WorkBuddy 安装协议"},{"title":"WorkBuddy","heading":"3. 进入模型配置","url":"/scenes/productivity-tools/workbuddy#3-进入模型配置","text":"打开 WorkBuddy，进入设置 → 模型，在自定义模型区域点击添加模型。 !WorkBuddy 添加模型入口"},{"title":"WorkBuddy","heading":"4. 选择自定义提供商","url":"/scenes/productivity-tools/workbuddy#4-选择自定义提供商","text":"在添加模型弹窗中，展开提供商下拉框，选择自定义 / Custom 。 !WorkBuddy 选择自定义提供商"},{"title":"WorkBuddy","heading":"5. 填写 NoneLinear API 信息","url":"/scenes/productivity-tools/workbuddy#5-填写-nonelinear-api-信息","text":"选择自定义提供商后，填写以下信息：字段填写内容 :--- :--- 接口地址 https://api.nonelinear.com.cn/v1 API KEY 你的 NoneLinear API Key 模型名称例如 deepseek-v4.1-flash 在高级配置中，可按模型能力勾选：选项建议 :--- :--- 工具调用支持工具调用的模型建议勾选图片输入仅在使用多模态视觉模型时勾选推理模式推理模型或需要展示思考过程时勾选自定义协议保持不勾选（默认使用 OpenAI 兼容协议）填写完成后点击保存。 !WorkBuddy 配置 NoneLinear API 请勿在截图、工单、公开仓库或聊天群中暴露真实 API Key。如果怀疑 Key 泄露，请立即前往 NoneLinear 控制台删除并重新生成。"},{"title":"WorkBuddy","heading":"6. 在对话中选择 NoneLinear 模型","url":"/scenes/productivity-tools/workbuddy#6-在对话中选择-nonelinear-模型","text":"回到 WorkBuddy 主界面，展开底部模型选择器，在自定义模型分组下选择刚添加的模型（例如 deepseek-v4.1-flash ）。发送一条测试消息，若模型能正常回复，说明接入成功。 !WorkBuddy 选择 NoneLinear 自定义模型"},{"title":"WorkBuddy","heading":"常见问题","url":"/scenes/productivity-tools/workbuddy#常见问题","text":""},{"title":"WorkBuddy","heading":"接口地址应该填 Base URL 还是完整路径？","url":"/scenes/productivity-tools/workbuddy#接口地址应该填-base-url-还是完整路径？","text":"在接口地址字段中直接填写 NoneLinear 的 Base URL 即可： text https://api.nonelinear.com.cn/v1 WorkBuddy 会自动拼接具体的接口路径，请勿在末尾额外加上 /chat/completions 。"},{"title":"WorkBuddy","heading":"模型名称应该怎么填？","url":"/scenes/productivity-tools/workbuddy#模型名称应该怎么填？","text":"模型名称必须与 NoneLinear 模型列表中的模型 ID 完全一致（注意区分大小写、连字符和版本号），例如 deepseek-v4.1-flash 。"},{"title":"WorkBuddy","heading":"配置后没有输出怎么办？","url":"/scenes/productivity-tools/workbuddy#配置后没有输出怎么办？","text":"请依次排查以下三项： - API KEY 是否完整复制，首尾有没有多余空格。 - 接口地址是否为 https://api.nonelinear.com.cn/v1 （末尾不要带 /chat/completions ）。 - 对话框底部当前选中的模型是否已切换到自定义模型分组下刚添加的模型。"},{"title":"Claude Cowork / Desktop","heading":"","url":"/scenes/dev-tools/claude-cowork","text":"Claude Desktop 的 Cowork / Code 可以通过第三方推理网关使用 NoneLinear。本文统一使用 cc-switch 本地路由配置：Claude Desktop 连接本机路由地址，cc-switch 再把 Claude 桌面应用里的模型名映射到 NoneLinear 上的真实模型 ID。关于 Cowork 与 Code 标签页 Claude Desktop 在 3P 模式下提供两个工作区： Cowork 适合资料整理、调研、长时间无人值守的代理任务； Code 是图形化的 Claude Code，可以读写本地工作目录、执行终端命令。两者共享同一份第三方推理配置。"},{"title":"Claude Cowork / Desktop","heading":"配置原理","url":"/scenes/dev-tools/claude-cowork#配置原理","text":"Claude Desktop 的第三方推理配置里， Gateway base URL 不直接填写 NoneLinear 的base url，而是填写 cc-switch 的本地路由地址： text http://127.0.0.1:18080 请求链路如下： text Claude Desktop -> cc-switch 本地路由 -> NoneLinear API 这样做的关键作用是：Claude Desktop 侧仍然使用 Claude 模型名或槽位，cc-switch 在本地把这些模型名映射为 NoneLinear 上的真实模型 ID。也就是说， Claude Desktop 里的 Gateway base URL 必须和 cc-switch 里的本地路由服务地址保持一致。"},{"title":"Claude Cowork / Desktop","heading":"准备工作","url":"/scenes/dev-tools/claude-cowork#准备工作","text":"- NoneLinear API Key ：在 NoneLinear 控制台创建。 - Claude Desktop ：从 claude.com/download 下载。 - cc-switch ：下载安装方式可参考 Claude Code 文档中的 CC-Switch 安装与配置。 - 模型 ID ：在 NoneLinear 模型列表查询，模型名需要与列表完全一致。 Windows 系统版本与虚拟化要求 Cowork 在 Windows 上仅支持 Pro / Enterprise / Education / Pro for Workstations 版本，Home 版无法使用。按 Win + R 输入 winver 可查看当前 Windows 版本。确认系统版本符合要求后，建议以管理员身份安装 Claude Desktop。首次使用 Cowork 前，如果系统提示需要启用虚拟化组件，请按提示完成安装并重启系统。"},{"title":"Claude Cowork / Desktop","heading":"1. 启用 Claude Desktop 开发者模式","url":"/scenes/dev-tools/claude-cowork#1-启用-claude-desktop-开发者模式","text":"启动 Claude Desktop 后不要登录 Anthropic 账号，先停留在登录页。在菜单栏点击 Help → Troubleshooting → Enable Developer Mode 。应用会自动重启，菜单栏会多出一个 Developer 菜单。在登录页左上角点击 ☰ 菜单 → Help → Troubleshooting → Enable Developer Mode 。应用会自动重启。 !启用 Developer Mode 重启后，在菜单栏选择 Developer → Configure third-party inference ，打开第三方推理配置面板。"},{"title":"Claude Cowork / Desktop","heading":"2. 在 cc-switch 中进入 Claude 配置页","url":"/scenes/dev-tools/claude-cowork#2-在-cc-switch-中进入-claude-配置页","text":"打开 cc-switch，点击顶部的 Claude Desktop / Cowork 对应图标，进入 Claude 桌面应用的供应商配置页。如果已经添加过 NoneLinear，可以直接使用当前供应商；如果还没有添加，点击右上角 + 新增。 !cc-switch Claude Desktop 配置入口 NoneLinear 供应商建议按下面方式配置：字段填写内容 --- --- 供应商名称 NoneLinear 官网链接 https://nonelinear.com.cn/ API Key 你的 NoneLinear API Key API 请求地址 https://api.nonelinear.com.cn/anthropic 模型映射按你的实际需求填写：左侧是 Claude Desktop 发给本地路由的模型名，右侧是 cc-switch 转发到 NoneLinear 时实际请求的模型 ID。每一行只配置一个实际请求模型；下表右侧列出的多个模型只是可选示例，不是同时填写多个。 Claude Desktop 侧模型名 NoneLinear 实际请求模型（任选一个） --- --- claude-sonnet-4.6 可以填 claude-sonnet-4.6 ，也可以改成 deepseek-v4-pro 等 claude-opus-4.7 可以填 claude-opus-4.7 ，也可以改成 kimi-k2.6 等 claude-haiku-4.5 可以填 claude-haiku-4.5 ，也可以改成 deepseek-v4-flash 等模型映射里的 NoneLinear 实际请求模型必须与模型列表完全一致，包括大小写、连字符和版本号。"},{"title":"Claude Cowork / Desktop","heading":"3. 开启 cc-switch 本地路由","url":"/scenes/dev-tools/claude-cowork#3-开启-cc-switch-本地路由","text":"进入 cc-switch 的设置 → 路由页面，确认以下开关都已打开： 1. 在主页显示本地路由开关 2. 路由总开关 3. 路由应用：Claude !cc-switch 开启 Claude 本地路由默认服务地址通常是： text http://127.0.0.1:18080 后续 Claude Desktop 的 Gateway base URL 就要填写这个地址。使用期间需要保持 cc-switch 运行；如果退出 cc-switch 或关闭本地路由，Claude Desktop 的请求就无法继续转发到 NoneLinear。"},{"title":"Claude Cowork / Desktop","heading":"4. 对齐 Claude Desktop 的 Gateway base URL","url":"/scenes/dev-tools/claude-cowork#4-对齐-claude-desktop-的-gateway-base-url","text":"回到 Claude Desktop 的 Configure third-party inference 面板，进入 Connection 分组，选择 Gateway (Anthropic-compatible) 。按下表填写：字段填写内容 --- --- Gateway base URL http://127.0.0.1:18080 Gateway API key 你的 NoneLinear API Key Gateway auth scheme bearer 这里最重要的是 Gateway base URL 要和 cc-switch 路由页里的服务地址完全一致。例如 cc-switch 显示的是 http://127.0.0.1:18080 ，Claude Desktop 里也必须填写 http://127.0.0.1:18080 。 !Claude Desktop Gateway base URL 与 cc-switch 本地路由对齐不要在 Claude Desktop 的 Gateway base URL 里填写 https://api.nonelinear.com.cn/anthropic 。本文使用的是 cc-switch 本地路由方案，Claude Desktop 要先连本机路由，再由 cc-switch 转发到 NoneLinear。"},{"title":"Claude Cowork / Desktop","heading":"5. 应用配置并进入 Cowork / Code","url":"/scenes/dev-tools/claude-cowork#5-应用配置并进入-cowork-/-code","text":"在 Claude Desktop 的第三方推理配置面板中点击 Apply locally 。保存后需要完全退出并重新打开 Claude Desktop ，让 Cowork / Code 重新读取 Gateway 和模型映射配置。只关闭 Claude Desktop 窗口不一定等于完全退出。Windows 可以在系统托盘中右键 Claude 图标选择 Quit ；macOS 可以在菜单栏选择 Claude → Quit Claude ，然后再重新打开应用。登录页出现第三方网关入口后，选择 Continue with Gateway 。进入后可以在 Cowork 或 Code 里发送测试消息，例如： text 当前文件夹里有没有py脚本啊如果可以正常回复，说明 Claude Desktop 已经通过 cc-switch 本地路由接入 NoneLinear。 !Claude Desktop 通过 cc-switch 路由验证成功"},{"title":"Claude Cowork / Desktop","heading":"常见问题","url":"/scenes/dev-tools/claude-cowork#常见问题","text":""},{"title":"Claude Cowork / Desktop","heading":"Claude Desktop 仍然连不上怎么办？","url":"/scenes/dev-tools/claude-cowork#claude-desktop-仍然连不上怎么办？","text":"优先检查三件事： 1. cc-switch 是否正在运行，并且路由总开关已开启。 2. cc-switch 路由页里 Claude 是否已开启。 3. Claude Desktop 的 Gateway base URL 是否和 cc-switch 服务地址完全一致。"},{"title":"Claude Cowork / Desktop","heading":"为什么要用本地路由？","url":"/scenes/dev-tools/claude-cowork#为什么要用本地路由？","text":"Claude Desktop 侧使用的是 Claude 模型名和第三方网关配置；cc-switch 本地路由可以在请求转发时把这些模型名映射到 NoneLinear 的真实模型 ID。这样你可以在 NoneLinear 上按需使用 Claude、DeepSeek、Kimi 等模型。"},{"title":"Claude Cowork / Desktop","heading":"修改 cc-switch 模型映射后不生效怎么办？","url":"/scenes/dev-tools/claude-cowork#修改-cc-switch-模型映射后不生效怎么办？","text":"先保存 cc-switch 配置，然后完全退出 Claude Desktop，再重新打开。Claude Desktop 读取第三方推理配置和模型信息通常需要重启当前会话。"},{"title":"Claude Cowork / Desktop","heading":"相关资源","url":"/scenes/dev-tools/claude-cowork#相关资源","text":"- NoneLinear API Key - NoneLinear 模型列表 - Claude Code 接入 NoneLinear"},{"title":"OpenClaw","heading":"概述","url":"/scenes/dev-tools/openclaw#概述","text":"本文档将指导你在服务器上安装 OpenClaw，并接入 NoneLinear 统一 API 平台。通过 NoneLinear，你可以用一个 API 接入点调用多家主流大模型厂商的模型，包括 OpenAI、Anthropic、Google、DeepSeek、字节豆包等。 NoneLinear 同时支持两种协议接入： - OpenAI 兼容协议 - Anthropic 原生协议"},{"title":"OpenClaw","heading":"前置要求","url":"/scenes/dev-tools/openclaw#前置要求","text":"- 一台 Linux 服务器（Ubuntu/CentOS/Debian 等主流发行版） - Node.js 环境（建议 v18+）及 npm - NoneLinear 平台的 API Key（获取 API Key）"},{"title":"OpenClaw","heading":"一、安装 OpenClaw","url":"/scenes/dev-tools/openclaw#一、安装-openclaw","text":""},{"title":"OpenClaw","heading":"Step 1 全局安装 OpenClaw","url":"/scenes/dev-tools/openclaw#step-1-全局安装-openclaw","text":"bash sudo npm install -g openclaw@latest"},{"title":"OpenClaw","heading":"Step 2 初始化配置","url":"/scenes/dev-tools/openclaw#step-2-初始化配置","text":"运行 quickstart 向导，完成基础配置并安装守护进程： bash openclaw onboard --install-daemon !openclaw quickstart配置界面 !openclaw quickstart配置界面 QuickStart中的 Model/auth provider 步骤，选择 Custom Provider （Any OpenAI or Anthropic compatible endpoint），然后按以下方式填写（以 Anthropic 格式为例）：字段填写内容 :--- :--- API Base URL https://api.nonelinear.com.cn/anthropic API Key 你的 NoneLinear API Key Endpoint compatibility Anthropic-compatible （OpenAI格式的就选 OpenAI-compatible ） Model ID NoneLinear 模型广场，例如 claude-haiku-4.5 注意： 1. QuickStart中的配置仅用于验证，后续配置多模型、多Agent等，会通过修改配置文件进行完整覆盖。 2. 如果 channel 部分选择飞书的，可以参考相关教程。"},{"title":"OpenClaw","heading":"Step 3 停止网关","url":"/scenes/dev-tools/openclaw#step-3-停止网关","text":"在修改配置文件前，先停止网关服务： bash openclaw gateway stop"},{"title":"OpenClaw","heading":"二、配置 NoneLinear API（OpenAI 兼容协议）","url":"/scenes/dev-tools/openclaw#二、配置-nonelinear-api（openai-兼容协议）","text":"这是最常用的接入方式，使用 OpenAI Chat Completions 兼容的协议格式。所有通过 NoneLinear 接入的模型均可使用此协议。"},{"title":"OpenClaw","heading":"方法一：编辑配置文件","url":"/scenes/dev-tools/openclaw#方法一：编辑配置文件","text":"打开配置文件： bash vim ~/.openclaw/openclaw.json 将配置修改为以下内容（核心配置示例，models 按需添加）： json openclaw.json { \"models\": { \"providers\": { \"nonelinear\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\", \"models\": [ { \"id\": \"claude-opus-4.6\", \"name\": \"NoneLinear claude-opus-4.6\" }, { \"id\": \"gpt-5.2\", \"name\": \"NoneLinear gpt-5.2\" }, { \"id\": \"DeepSeek-V3.2\", \"name\": \"NoneLinear DeepSeek-V3.2\" }, { \"id\": \"MiniMax-M2.7\", \"name\": \"NoneLinear MiniMax-M2.7\" } ] } } }, \"agents\": { \"defaults\": { \"model\": { \"primary\": \"nonelinear/MiniMax-M2.7\" }, \"models\": { \"nonelinear/claude-opus-4.6\": {}, \"nonelinear/gpt-5.2\": {}, \"nonelinear/DeepSeek-V3.2\": {} } } } } 关键字段说明： - baseUrl 设为 https://api.nonelinear.com.cn/v1 - api 字段设为 \"openai-completions\" - apiKey 使用环境变量引用 ${OPENAI_API_KEY} ：请在运行 OpenClaw 网关的环境中把 OPENAI_API_KEY 设置为你的 NoneLinear API Key，修改后重启网关；也可以直接把 ${OPENAI_API_KEY} 替换为 API Key 字符串"},{"title":"OpenClaw","heading":"方法二：命令行配置","url":"/scenes/dev-tools/openclaw#方法二：命令行配置","text":"如果你更喜欢用命令行，也可以直接运行： bash 配置 provider openclaw config set 'models.providers.nonelinear' --json '{ \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\", \"models\": [ { \"id\": \"claude-opus-4.6\", \"name\": \"NoneLinear claude-opus-4.6\" }, { \"id\": \"gpt-5.2\", \"name\": \"NoneLinear gpt-5.2\" }, { \"id\": \"DeepSeek-V3.2\", \"name\": \"NoneLinear DeepSeek-V3.2\" } ] }' 设置默认模型 openclaw config set 'agents.defaults.model' --json '{ \"primary\": \"nonelinear/MiniMax-M2.7\" }'"},{"title":"OpenClaw","heading":"三、配置 NoneLinear API（Anthropic 原生协议）","url":"/scenes/dev-tools/openclaw#三、配置-nonelinear-api（anthropic-原生协议）","text":"如果你需要使用 Anthropic 原生协议，配置方式与 OpenAI 协议几乎一模一样，只需修改两个字段：配置项 OpenAI 兼容协议 Anthropic 原生协议 :--- :--- :--- baseUrl https://api.nonelinear.com.cn/v1 https://api.nonelinear.com.cn/anthropic api openai-completions anthropic-messages 注意：除了 baseUrl 和 api 字段之外，其余配置（apiKey、models 列表等）一致。"},{"title":"OpenClaw","heading":"配置文件示例","url":"/scenes/dev-tools/openclaw#配置文件示例","text":"json openclaw.json { \"models\": { \"providers\": { \"nonelinear\": { \"baseUrl\": \"https://api.nonelinear.com.cn/anthropic\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"anthropic-messages\", \"models\": [ { \"id\": \"claude-opus-4.6\", \"name\": \"NoneLinear claude-opus-4.6\" }, { \"id\": \"claude-opus-4.6-thinking\", \"name\": \"NoneLinear claude-opus-4.6-thinking\" }, { \"id\": \"claude-haiku-4.5\", \"name\": \"NoneLinear claude-haiku-4.5\" } ] } } } }"},{"title":"OpenClaw","heading":"命令行方式","url":"/scenes/dev-tools/openclaw#命令行方式","text":"bash openclaw config set 'models.providers.nonelinear' --json '{ \"baseUrl\": \"https://api.nonelinear.com.cn/anthropic\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"anthropic-messages\", \"models\": [ { \"id\": \"claude-opus-4.6\", \"name\": \"NoneLinear claude-opus-4.6\" }, { \"id\": \"claude-opus-4.6-thinking\", \"name\": \"NoneLinear claude-opus-4.6-thinking\" }, { \"id\": \"claude-haiku-4.5\", \"name\": \"NoneLinear claude-haiku-4.5\" } ] }'"},{"title":"OpenClaw","heading":"四、启动与验证","url":"/scenes/dev-tools/openclaw#四、启动与验证","text":""},{"title":"OpenClaw","heading":"Step 1 重启网关","url":"/scenes/dev-tools/openclaw#step-1-重启网关","text":"bash openclaw gateway restart"},{"title":"OpenClaw","heading":"Step 2 探测模型可用性","url":"/scenes/dev-tools/openclaw#step-2-探测模型可用性","text":"bash openclaw models status --probe"},{"title":"OpenClaw","heading":"Step 3 查看整体状态","url":"/scenes/dev-tools/openclaw#step-3-查看整体状态","text":"bash openclaw models status ✅ 成功标志：如果以上命令均正常返回模型列表和状态信息，说明 OpenClaw 已成功接入 NoneLinear 平台！ ---"},{"title":"OpenClaw","heading":"五、多模态能力扩展","url":"/scenes/dev-tools/openclaw#五、多模态能力扩展","text":"完成上述基础接入后，OpenClaw 已经具备文本对话能力。如果你需要让 agent 能\"看图、画图、生视频\"，本节将逐步介绍如何在前面配置的基础上启用三类多模态能力：视觉理解、图像生成、视频生成。 OpenClaw 多模态架构提示： OpenClaw 通过四个独立字段控制多模态路由： - agents.defaults.imageModel — 视觉理解（看图） - agents.defaults.pdfModel — PDF 理解 - agents.defaults.imageGenerationModel — 图像生成（画图） - agents.defaults.videoGenerationModel — 视频生成这些字段独立于 agents.defaults.model ，允许\"主聊天用便宜模型，多模态调用切到能力更强的模型\"。"},{"title":"OpenClaw","heading":"1. 视觉理解（看图）","url":"/scenes/dev-tools/openclaw#1-视觉理解（看图）","text":"视觉理解是最简单的多模态能力，只需在模型声明中加一个 input 字段即可启用。"},{"title":"OpenClaw","heading":"工作机制","url":"/scenes/dev-tools/openclaw#工作机制","text":"当用户发送图片时，OpenClaw 检查当前会话使用的模型是否在 models[].input 中声明了 \"image\" ： - 声明了 → 直接把原图作为原生输入传给该模型 - 没声明 → 路由到 agents.defaults.imageModel.primary 指定的视觉专用模型处理"},{"title":"OpenClaw","heading":"配置示例","url":"/scenes/dev-tools/openclaw#配置示例","text":"在前面接入配置的基础上，给模型加 input 字段，并配置 imageModel ： json openclaw.json { \"models\": { \"providers\": { \"nonelinear\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\", \"models\": [ { \"id\": \"claude-opus-4.6\", \"name\": \"NoneLinear claude-opus-4.6\", \"input\": [\"text\", \"image\"], \"contextWindow\": 200000, \"maxTokens\": 16384 }, { \"id\": \"Qwen3-VL-235B\", \"name\": \"NoneLinear Qwen3-VL-235B\", \"input\": [\"text\", \"image\"] }, { \"id\": \"DeepSeek-V3.2\", \"name\": \"NoneLinear DeepSeek-V3.2\", \"input\": [\"text\"] } ] } } }, \"agents\": { \"defaults\": { \"model\": { \"primary\": \"nonelinear/DeepSeek-V3.2\" }, \"imageModel\": { \"primary\": \"nonelinear/Qwen3-VL-235B\", \"fallbacks\": [\"nonelinear/claude-opus-4.6\"] }, \"pdfModel\": { \"primary\": \"nonelinear/Qwen3-VL-235B\" }, \"imageMaxDimensionPx\": 1200, \"models\": { \"nonelinear/claude-opus-4.6\": {}, \"nonelinear/Qwen3-VL-235B\": {}, \"nonelinear/DeepSeek-V3.2\": {} } } } } 关键字段说明： - input 数组合法值： \"text\" / \"image\" / \"audio\" / \"video\" - imageModel.primary 仅在主模型不支持视觉时才会被使用 - pdfModel 未配置时自动 fallback 到 imageModel - imageMaxDimensionPx （默认 1200）控制传入模型前的等比下采样上限"},{"title":"OpenClaw","heading":"验证视觉理解","url":"/scenes/dev-tools/openclaw#验证视觉理解","text":"bash openclaw infer image describe \\ --file ./test.jpg \\ --model nonelinear/Qwen3-VL-235B 或直接在已连通的 channel（飞书、Telegram 等）发一张图片给 agent。"},{"title":"OpenClaw","heading":"2. 图像生成（画图）","url":"/scenes/dev-tools/openclaw#2-图像生成（画图）","text":"OpenClaw 的图像生成走 image_generate 工具，由 agents.defaults.imageGenerationModel 字段控制。重要前提： image_generate 工具仅在至少一个图像生成 Provider 已注册时才会出现在 agent 的 tools 列表中。 OpenClaw 官方文档明确说明：显式覆写 models.providers.openai.baseUrl 指向自定义端点，OpenClaw 会把图像生成请求直接发到该端点。这是 NoneLinear 接入图像生成的官方推荐路径。"},{"title":"OpenClaw","heading":"接入方式：覆写 openai provider id","url":"/scenes/dev-tools/openclaw#接入方式：覆写-openai-provider-id","text":"json openclaw.json { \"models\": { \"providers\": { \"openai\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\", \"timeoutSeconds\": 600 }, \"nonelinear\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\", \"models\": [ { \"id\": \"claude-opus-4.6\", \"name\": \"NoneLinear claude-opus-4.6\", \"input\": [\"text\", \"image\"] } ] } } }, \"agents\": { \"defaults\": { \"model\": { \"primary\": \"nonelinear/claude-opus-4.6\" }, \"imageGenerationModel\": { \"primary\": \"openai/gpt-image-2\", \"timeoutMs\": 180000 }, \"models\": { \"nonelinear/claude-opus-4.6\": {} } } } } 配置说明： - imageGenerationModel.primary 写成 openai/gpt-image-2 —— 此处 openai 是 OpenClaw 内部的 provider id （已被 baseUrl 覆写指向 NoneLinear），不是字面 OpenAI； gpt-image-2 是 NoneLinear 上架的模型 ID。 - 模型 ID 必须与 NoneLinear 模型广场上架的名称完全一致。 - timeoutMs 默认 60 秒，建议提到 180000（3 分钟）以覆盖大尺寸图像生成。"},{"title":"OpenClaw","heading":"配置多 Provider fallback 链","url":"/scenes/dev-tools/openclaw#配置多-provider-fallback-链","text":"NoneLinear 模型超市同时上架了多家图像生成模型，可通过 fallback 链实现自动容错： json openclaw.json { \"agents\": { \"defaults\": { \"imageGenerationModel\": { \"primary\": \"openai/gpt-image-2\", \"timeoutMs\": 180000, \"fallbacks\": [ \"openrouter/google/gemini-3.1-flash-image-preview\", \"google/gemini-3.1-flash-image-preview\", \"fal/fal-ai/flux/dev\" ] }, \"mediaGenerationAutoProviderFallback\": false } } } mediaGenerationAutoProviderFallback: false 表示只用显式声明的 primary 和 fallbacks ，关闭基于鉴权自动嗅探的 provider 候选。生产环境推荐关闭，避免不可预期的请求路由。要让 google / openrouter / fal 都路由到 NoneLinear，需要分别覆写它们的 baseUrl ，参考\"覆写 openai provider id\"的写法。"},{"title":"OpenClaw","heading":"工具参数清单","url":"/scenes/dev-tools/openclaw#工具参数清单","text":"agent 调用 image_generate 时可用以下参数（绝大多数由 LLM 自动决定）：参数说明 :--- :--- prompt 图像描述提示词 model 单次调用覆盖默认模型 image / images 编辑参考图（最多 5 张） size 1024x1024 … 3840x2160 aspectRatio 1:1 / 16:9 / 9:16 等 resolution 1K / 2K / 4K outputFormat png / jpeg / webp count 1-4 张 timeoutMs 单次调用覆盖超时"},{"title":"OpenClaw","heading":"验证图像生成","url":"/scenes/dev-tools/openclaw#验证图像生成","text":"bash 列出已注册的图像生成 provider openclaw image_generate --action list 文生图 openclaw infer image generate \\ --prompt \"a friendly robot mascot, watercolor style\" \\ --model openai/gpt-image-2 编辑参考图 openclaw infer image edit \\ --prompt \"make this photo look like a watercolor painting\" \\ --image ./photo.jpg \\ --model openai/gpt-image-2"},{"title":"OpenClaw","heading":"3. 视频生成（生视频）","url":"/scenes/dev-tools/openclaw#3-视频生成（生视频）","text":"视频生成走 video_generate 工具，由 agents.defaults.videoGenerationModel 字段控制。视频生成与图像生成的关键区别：视频 Provider 不能从鉴权自动推断，必须显式指定 provider/model ，且必须是 OpenClaw 已注册视频生成能力的 Provider。"},{"title":"OpenClaw","heading":"配置示例","url":"/scenes/dev-tools/openclaw#配置示例-2","text":"json openclaw.json { \"models\": { \"providers\": { \"openai\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\", \"timeoutSeconds\": 600 } } }, \"agents\": { \"defaults\": { \"videoGenerationModel\": { \"primary\": \"openai/sora-2\", \"timeoutMs\": 600000 } } } } timeoutMs 设置为 600000（10 分钟）是因为视频生成普遍较慢，Sora 通常需要 2-5 分钟。"},{"title":"OpenClaw","heading":"三种生成模式","url":"/scenes/dev-tools/openclaw#三种生成模式","text":"agent 调用时支持三种模式：模式输入用途 :--- :--- :--- generate prompt 文生视频（T2V） imageToVideo prompt + images[] 图生视频（I2V） videoToVideo prompt + videos[] 视频续写/风格化其余参数： aspectRatio 、 resolution （480P/720P/1080P）、 durationSeconds 、 audio （是否生成音轨）、 watermark 、 providerOptions （如 seed ）。"},{"title":"OpenClaw","heading":"异步任务总线","url":"/scenes/dev-tools/openclaw#异步任务总线","text":"视频生成是异步的，OpenClaw 内部走\"后台任务 + 会话 wake event\"模型： 1. agent 调 video_generate → 立即返回 task_id ，状态 queued 或 running 2. Provider 在后台跑（30 秒到 5 分钟） 3. 完成时 OpenClaw 注入 internal completion event，唤醒同一会话，agent 在新一轮对话以附件形式 post 视频 4. 状态机： queued → running → succeeded / failed CLI 查看任务： bash openclaw tasks list 列出所有后台任务 openclaw tasks show 查看具体任务状态"},{"title":"OpenClaw","heading":"多视频模型 fallback","url":"/scenes/dev-tools/openclaw#多视频模型-fallback","text":"如果 NoneLinear 同时上架了 Sora、Kling、Wan、Veo 等多家视频模型： json openclaw.json { \"models\": { \"providers\": { \"openai\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\" }, \"google\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\" }, \"minimax\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\" } } }, \"agents\": { \"defaults\": { \"videoGenerationModel\": { \"primary\": \"openai/sora-2\", \"timeoutMs\": 600000, \"fallbacks\": [ \"google/veo-3.1-fast-generate-preview\", \"minimax/MiniMax-Hailuo-2.3\" ] }, \"mediaGenerationAutoProviderFallback\": false } } }"},{"title":"OpenClaw","heading":"验证视频生成","url":"/scenes/dev-tools/openclaw#验证视频生成","text":"bash 文生视频 openclaw infer video generate \\ --prompt \"a cat playing piano in a jazz bar, cinematic\" \\ --model openai/sora-2 \\ --aspectRatio 16:9 \\ --durationSeconds 5 图生视频 openclaw infer video generate \\ --prompt \"the character starts walking forward\" \\ --image ./first_frame.jpg \\ --model openai/sora-2"},{"title":"OpenClaw","heading":"六、多模态完整配置示例","url":"/scenes/dev-tools/openclaw#六、多模态完整配置示例","text":"下面是一份生产级完整配置，集成基础接入 + 视觉理解 + 图像生成 + 视频生成，全部路由到 NoneLinear： json openclaw.json { \"models\": { \"providers\": { \"openai\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\", \"timeoutSeconds\": 600 }, \"nonelinear\": { \"baseUrl\": \"https://api.nonelinear.com.cn/v1\", \"apiKey\": \"${OPENAI_API_KEY}\", \"api\": \"openai-completions\", \"timeoutSeconds\": 300, \"models\": [ { \"id\": \"claude-opus-4.6\", \"name\": \"NoneLinear claude-opus-4.6\", \"input\": [\"text\", \"image\"], \"contextWindow\": 200000, \"maxTokens\": 16384 }, { \"id\": \"Qwen3-VL-235B\", \"name\": \"NoneLinear Qwen3-VL-235B\", \"input\": [\"text\", \"image\"] }, { \"id\": \"DeepSeek-V3.2\", \"name\": \"NoneLinear DeepSeek-V3.2\", \"input\": [\"text\"] }, { \"id\": \"MiniMax-M2.7\", \"name\": \"NoneLinear MiniMax-M2.7\", \"input\": [\"text\"] } ] } } }, \"agents\": { \"defaults\": { \"model\": { \"primary\": \"nonelinear/MiniMax-M2.7\", \"fallbacks\": [\"nonelinear/claude-opus-4.6\"] }, \"imageModel\": { \"primary\": \"nonelinear/Qwen3-VL-235B\", \"fallbacks\": [\"nonelinear/claude-opus-4.6\"] }, \"pdfModel\": { \"primary\": \"nonelinear/Qwen3-VL-235B\" }, \"imageGenerationModel\": { \"primary\": \"openai/gpt-image-2\", \"timeoutMs\": 180000 }, \"videoGenerationModel\": { \"primary\": \"openai/sora-2\", \"timeoutMs\": 600000 }, \"mediaGenerationAutoProviderFallback\": false, \"imageMaxDimensionPx\": 1200, \"models\": { \"nonelinear/claude-opus-4.6\": {}, \"nonelinear/Qwen3-VL-235B\": {}, \"nonelinear/DeepSeek-V3.2\": {}, \"nonelinear/MiniMax-M2.7\": {} } } } } 部署步骤： 1. 把上面 JSON 写入 ~/.openclaw/openclaw.json （先备份原文件） 2. 运行 openclaw doctor 检查配置语法与连通性 3. 运行 openclaw gateway restart 重启网关 4. 运行 openclaw models status 确认所有 provider 鉴权通过 5. 在已连通的 channel 测试四类调用： - 文本：直接发文字消息 - 视觉理解：发一张图 + \"描述这张图\" - 图像生成：\"生成一张赛博朋克风格的城市夜景\" - 视频生成：\"生成一段 5 秒的猫弹钢琴视频\""},{"title":"OpenClaw","heading":"七、多模态故障排查","url":"/scenes/dev-tools/openclaw#七、多模态故障排查","text":""},{"title":"OpenClaw","heading":"Q1：Model \"nonelinear/xxx\" is not allowed","url":"/scenes/dev-tools/openclaw#q1：model-nonelinear/xxx-is-not-allowed","text":"原因：模型未加入 agents.defaults.models 白名单。解决：在 agents.defaults.models 中显式添加该 key： bash openclaw config set agents.defaults.models \\ '{\"nonelinear/xxx\":{}}' --strict-json --merge"},{"title":"OpenClaw","heading":"Q2：image_generate 工具未出现在 agent tools 中","url":"/scenes/dev-tools/openclaw#q2：image_generate-工具未出现在-agent-tools-中","text":"原因：OpenClaw 没检测到任何已注册的图像生成 Provider。解决：检查三件事： 1. agents.defaults.imageGenerationModel.primary 已配置 2. 对应 Provider 的 baseUrl 和 apiKey 已设置 3. openclaw doctor 未报鉴权错误"},{"title":"OpenClaw","heading":"Q3：图像/视频请求成功但模型返回错误","url":"/scenes/dev-tools/openclaw#q3：图像/视频请求成功但模型返回错误","text":"原因：NoneLinear 上架的模型 ID 与 OpenClaw 内部协议预期的 ID 不一致。解决：用 curl 直测 NoneLinear API，确认实际模型名： bash curl https://api.nonelinear.com.cn/v1/models \\ -H \"Authorization: Bearer $OPENAI_API_KEY\" 然后把返回的精确 ID 填到 imageGenerationModel.primary 或 videoGenerationModel.primary 。"},{"title":"OpenClaw","heading":"Q4：自定义 baseUrl 似乎没生效","url":"/scenes/dev-tools/openclaw#q4：自定义-baseurl-似乎没生效","text":"原因：OpenClaw 在 ~/.openclaw/agents/ /models.json 维护 per-agent provider 覆盖。如果该文件中已有非空的 apiKey / baseUrl ，会优先于全局 ~/.openclaw/openclaw.json 。解决： bash openclaw config show models.providers.openai 查看运行时实际配置 openclaw doctor --fix 修复历史 auth-profiles 残留 cat ~/.openclaw/agents/ /models.json 检查 per-agent 覆盖文件 openclaw gateway restart 强制重启当前未覆盖的能力： OpenClaw 的 TTS（语音合成）、STT（语音识别）、音乐生成属于\"插件能力槽\"，由 OpenClaw 的 Speech Provider / Media Understanding Provider 插件管理，纯配置无法接入。如需让 NoneLinear 的 MiniMax Speech、Whisper 等模型接入这些能力槽，需通过 OpenClaw 的 Plugin SDK 编写插件注册。该能力将在 NoneLinear 官方插件发布后开放。 ---"},{"title":"Hermes Agent","heading":"概述","url":"/scenes/dev-tools/hermes-agent#概述","text":"Hermes Agent 是一个开源的通用智能体框架（CLI + 多平台网关），结构上与 OpenClaw、Claude Code 等产品类似：统一的工具箱（终端、文件、浏览器、Web 搜索、图片生成、TTS、技能、MCP 等）+ 可插拔的推理后端。本文档将指导你如何将 Nonelinear API接入 Hermes Agent。"},{"title":"Hermes Agent","heading":"前置条件","url":"/scenes/dev-tools/hermes-agent#前置条件","text":"1. 获取 API Key ：准备一个 NoneLinear API Key（获取 API Key）。后面需要填入配置文件 2. 安装 Hermes Agent ： - macOS / Linux / WSL2 / Termux: bash curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh bash - Windows (PowerShell): powershell irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 iex 安装完成后，会进入初始化向导，按照提示完成配置（也可之后通过 hermes setup 随时开启），其中： - Select provider : 在菜单中选择 Custom endpoint (enter URL manually) 。 - API base URL : 输入 https://api.nonelinear.com.cn/v1 。 - API key : 填入你的 NoneLinear API Key。也可先跳过，后续在 ~/.hermes/.env 中设置。 - Model name : 输入默认模型 ID（例如 DeepSeek-V3.2 ，需与模型列表中的大小写一致）。 3. 配置文件说明：Hermes 的配置存储在 ~/.hermes/ 目录： - ~/.hermes/config.yaml — 核心配置文件（模型、工具、后端等） - ~/.hermes/.env — API Key 等敏感环境变量 ---"},{"title":"Hermes Agent","heading":"Hermes Agent 接入方式：OpenAI 兼容协议","url":"/scenes/dev-tools/hermes-agent#hermes-agent-接入方式：openai-兼容协议","text":"NoneLinear 的 https://api.nonelinear.com.cn/v1 完全兼容 OpenAI SDK 格式，支持文本对话、图片生成、视频生成等所有场景。如果你在安装阶段跳过了配置，或后续需要更换模型、重新配置，可以通过以下两种方式进行设置。"},{"title":"Hermes Agent","heading":"方式一：交互式配置（最简单）","url":"/scenes/dev-tools/hermes-agent#方式一：交互式配置（最简单）","text":"bash hermes model 在菜单中选择 \"Custom endpoint (enter URL manually)\" API base URL: https://api.nonelinear.com.cn/v1 API key: 直接粘贴你的 NoneLinear API Key Model name: 输入默认模型 ID，例如 claude-sonnet-4.6、gpt-5.4-high"},{"title":"Hermes Agent","heading":"方式二：手动修改 config.yaml","url":"/scenes/dev-tools/hermes-agent#方式二：手动修改-config-yaml","text":"编辑 ~/.hermes/config.yaml ，找到 model: 段并修改为： yaml model: default: claude-sonnet-4.6 你要用的默认模型 ID provider: custom 固定为 custom base_url: https://api.nonelinear.com.cn/v1 在 ~/.hermes/.env 中写入 API Key： env Hermes 对 provider: custom 的 endpoint 默认读取 OPENAI_API_KEY OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx 替换为你的 NoneLinear API Key > 提示： config.yaml 里已有 Hermes 自动生成的大量默认配置，只修改 model: 这一段即可，其它段落保持不动。 ---"},{"title":"Hermes Agent","heading":"配置多个 NoneLinear 大模型并随时切换","url":"/scenes/dev-tools/hermes-agent#配置多个-nonelinear-大模型并随时切换","text":"NoneLinear 模型广场里有多个模型，Hermes 支持在同一个对话里随时切换 ——切换后对话历史、记忆、正在执行的任务都不会丢。 \"配置多个模型\"在 Hermes 里有两种做法，推荐按需组合使用。"},{"title":"Hermes Agent","heading":"方式一：对话中直接切换（零配置）","url":"/scenes/dev-tools/hermes-agent#方式一：对话中直接切换（零配置）","text":"只要你按上一节接好了 NoneLinear，对话里直接输入裸模型名（不加任何前缀）就能切到任意 NoneLinear 模型： /model claude-opus-4.6 /model gpt-5.4-high /model Kimi-K2.5-Thinking /model MiniMax-M2.7 /model GLM-5.1 /model qwen3.5-plus > 重要：不要加 custom: 前缀。 /model custom:xxx 这种写法是从其他 provider 切换到 custom 时才用的；你当前 model.provider 已经是 custom ，直接写模型名即可。如果误加了 custom: 前缀，Hermes 会把整串（例如 custom:qwen3.5-plus ）当成模型 ID 发给 NoneLinear，NoneLinear 会返回 HTTP 422: model_id错误或不支持。"},{"title":"Hermes Agent","heading":"方式二：给常用模型起短别名（推荐）","url":"/scenes/dev-tools/hermes-agent#方式二：给常用模型起短别名（推荐）","text":"如果不想每次打全模型 ID，在 ~/.hermes/config.yaml 末尾追加下面这段 model_aliases: （其它内容一个字都不要动）： yaml model_aliases: opus: model: claude-opus-4.6 provider: custom base_url: https://api.nonelinear.com.cn/v1 sonnet: model: claude-sonnet-4.6 provider: custom base_url: https://api.nonelinear.com.cn/v1 gpt: model: gpt-5.4-high provider: custom base_url: https://api.nonelinear.com.cn/v1 kimi: model: Kimi-K2.5-Thinking provider: custom base_url: https://api.nonelinear.com.cn/v1 minimax: model: MiniMax-M2.7 provider: custom base_url: https://api.nonelinear.com.cn/v1 glm: model: GLM-5.1 provider: custom base_url: https://api.nonelinear.com.cn/v1 qwen: model: qwen3.5-plus provider: custom base_url: https://api.nonelinear.com.cn/v1 保存文件，重启 hermes 。之后在对话里就可以用一个单词切换： /model opus 切到 Claude Opus 4.6（处理复杂任务） /model gpt 切到 GPT-5.4 High /model kimi 切到 Kimi K2.5 Thinking（长思考） /model qwen 切到 qwen3.5-plus（便宜快，用于简单问题）"},{"title":"Hermes Agent","heading":"验证是否切换成功","url":"/scenes/dev-tools/hermes-agent#验证是否切换成功","text":"对话里直接输入 /model （不带参数），Hermes 会打印当前使用的模型： /model 输出示例： Current model: claude-opus-4.6 Provider: custom (https://api.nonelinear.com.cn/v1) 完整模型列表请见 NoneLinear 模型广场。 ---"},{"title":"Hermes Agent","heading":"相关链接","url":"/scenes/dev-tools/hermes-agent#相关链接","text":"- Hermes Agent 仓库：github.com/nousresearch/hermes-agent - Hermes Agent 官方文档：hermes-agent.nousresearch.com/docs"},{"title":"Cherry Studio","heading":"","url":"/scenes/chat-assistants/cherry-studio","text":"Cherry Studio 支持添加 OpenAI 兼容服务商。将服务商类型设为 OpenAI，并把 API 地址配置为 NoneLinear 的 OpenAI 兼容端点后，即可在 Cherry Studio 中调用 NoneLinear 模型。 Cherry Studio Agent 模式兼容性说明本文介绍的 OpenAI 兼容协议配置适用于 Cherry Studio 的普通聊天模式。Cherry Studio 当前的 Agent 模式要求服务商使用 Anthropic 类型，并且接口支持 Anthropic Messages API。因此，通过 OpenAI 类型服务商添加的模型即使可以正常聊天，也不会出现在创建智能体时的模型列表中。这属于 Cherry Studio 当前的协议兼容性限制，并非模型 ID 填写错误或模型获取失败。如需在 Agent 模式中使用 NoneLinear 模型，请另外添加一个服务商：配置项填写内容 :--- :--- 提供商名称非线智能 Agent 提供商类型 Anthropic API 密钥你的 NoneLinear API Key API 地址 https://api.nonelinear.com.cn/anthropic 模型 ID 从 NoneLinear 模型列表中选择原有的 OpenAI 类型服务商无需删除，可以继续用于普通聊天；Anthropic 类型服务商用于 Agent 模式。更多信息请参考 Cherry Studio Agent 使用教程。"},{"title":"Cherry Studio","heading":"前置要求","url":"/scenes/chat-assistants/cherry-studio#前置要求","text":"- 已安装 Cherry Studio。 - 已获取 NoneLinear API Key：获取 API Key。 - 已确认要使用的模型 ID：模型列表。"},{"title":"Cherry Studio","heading":"配置步骤","url":"/scenes/chat-assistants/cherry-studio#配置步骤","text":""},{"title":"Cherry Studio","heading":"1. 选择其他服务商","url":"/scenes/chat-assistants/cherry-studio#1-选择其他服务商","text":"首次打开 Cherry Studio 时，在引导页点击选择其他服务商。 !Cherry Studio 选择其他服务商如果已经进入主界面，也可以从右上角设置进入模型服务商配置页。"},{"title":"Cherry Studio","heading":"2. 添加 NoneLinear 服务商","url":"/scenes/chat-assistants/cherry-studio#2-添加-nonelinear-服务商","text":"在服务商列表底部点击添加，新建一个服务商：字段填写内容 :--- :--- 提供商名称非线智能提供商类型 OpenAI 填写完成后点击确定。 !Cherry Studio 添加 NoneLinear 服务商"},{"title":"Cherry Studio","heading":"3. 填写 API Key 和 API 地址","url":"/scenes/chat-assistants/cherry-studio#3-填写-api-key-和-api-地址","text":"选中刚刚添加的非线智能服务商，打开右侧配置页并填写：字段填写内容 :--- :--- API 密钥你的 NoneLinear API Key API 地址 https://api.nonelinear.com.cn/v1 Cherry Studio 会预览完整请求地址为 https://api.nonelinear.com.cn/v1/chat/completions 。填写完成后可以点击检测验证连接。 !Cherry Studio 配置 NoneLinear API Key 和 API 地址不要在截图、工单、公开仓库或聊天群中暴露真实 API Key。如果怀疑 Key 泄露，请立即在 NoneLinear 控制台删除并重新生成。"},{"title":"Cherry Studio","heading":"4. 添加模型","url":"/scenes/chat-assistants/cherry-studio#4-添加模型","text":"在模型区域点击 + 添加模型。模型 ID 必须与 NoneLinear 模型列表中的 ID 保持一致。示例填写：字段示例 :--- :--- 模型 ID deepseek-v4-flash 模型名称 deepseek-v4-flash 分组名称 deepseek-v4 !Cherry Studio 添加 NoneLinear 模型你也可以使用其他 NoneLinear 模型，例如 GPT、Claude、Qwen、GLM、豆包等系列模型。以模型列表中展示的模型 ID 为准。"},{"title":"Cherry Studio","heading":"5. 选择默认模型","url":"/scenes/chat-assistants/cherry-studio#5-选择默认模型","text":"返回引导流程，在默认助手模型下拉框中选择刚刚添加的模型，例如 deepseek-v4-flash 非线智能，然后点击开始使用。 !Cherry Studio 选择 NoneLinear 默认模型"},{"title":"Cherry Studio","heading":"6. 发送消息验证","url":"/scenes/chat-assistants/cherry-studio#6-发送消息验证","text":"进入对话界面后，确认顶部模型显示为 deepseek-v4-flash 非线智能或你配置的其他 NoneLinear 模型。发送一条测试消息，如果模型正常回复，说明接入成功。 !Cherry Studio 使用 NoneLinear 模型对话"},{"title":"Cherry Studio","heading":"常见问题","url":"/scenes/chat-assistants/cherry-studio#常见问题","text":""},{"title":"Cherry Studio","heading":"检测失败怎么办？","url":"/scenes/chat-assistants/cherry-studio#检测失败怎么办？","text":"优先检查三项配置： - API 地址是否为 https://api.nonelinear.com.cn/v1 ，不要填写到 /chat/completions 。 - API Key 是否完整复制，前后不要带空格。 - 当前网络是否可以访问 NoneLinear API。"},{"title":"Cherry Studio","heading":"模型报错怎么办？","url":"/scenes/chat-assistants/cherry-studio#模型报错怎么办？","text":"检查模型 ID 是否与 NoneLinear 模型列表完全一致，包括大小写、连字符和版本号。模型 ID 不一致时，Cherry Studio 能保存配置，但调用时会失败。"},{"title":"Cherry Studio","heading":"可以配置多个模型吗？","url":"/scenes/chat-assistants/cherry-studio#可以配置多个模型吗？","text":"可以。重复添加模型步骤，把常用模型分别加入同一个非线智能服务商下即可。之后可以在对话顶部的模型选择器中切换。"},{"title":"Chatbox","heading":"","url":"/scenes/chat-assistants/chatbox","text":"Chatbox 支持添加 OpenAI API 兼容的模型提供方。把提供方配置为 NoneLinear，并填写 NoneLinear 的 API Key、API 主机和模型 ID 后，即可在 Chatbox 中调用 NoneLinear 模型。"},{"title":"Chatbox","heading":"前置要求","url":"/scenes/chat-assistants/chatbox#前置要求","text":"- 已安装 Chatbox。客户端下载地址：https://chatboxai.app/zh download。 - 已获取 NoneLinear API Key：获取 API Key。 - 已确认要使用的模型 ID：模型列表。"},{"title":"Chatbox","heading":"配置步骤","url":"/scenes/chat-assistants/chatbox#配置步骤","text":""},{"title":"Chatbox","heading":"1. 添加模型提供方","url":"/scenes/chat-assistants/chatbox#1-添加模型提供方","text":"打开 Chatbox，进入设置 → 模型提供方，点击底部添加，新建一个模型提供方。在弹窗中填写：字段填写内容 :--- :--- 名称 NoneLinear 或非线智能 API 模式 OpenAI API 兼容填写完成后点击添加。 !Chatbox 添加 NoneLinear 模型提供方"},{"title":"Chatbox","heading":"2. 选中 NoneLinear 提供方","url":"/scenes/chat-assistants/chatbox#2-选中-nonelinear-提供方","text":"添加完成后，在模型提供方列表中选中刚刚创建的 NoneLinear 。右侧会出现 NoneLinear 的配置面板。 !Chatbox 选中 NoneLinear 模型提供方"},{"title":"Chatbox","heading":"3. 填写 API Key 和 API 主机","url":"/scenes/chat-assistants/chatbox#3-填写-api-key-和-api-主机","text":"在 NoneLinear 配置面板中填写：字段填写内容 :--- :--- API 密钥你的 NoneLinear API Key API 主机 https://api.nonelinear.com.cn/v1 API 路径保持默认 /chat/completions Chatbox 会在下方预览完整请求地址： https://api.nonelinear.com.cn/v1/chat/completions 。 !Chatbox 配置 NoneLinear API Key 和 API 主机不要在截图、工单、公开仓库或聊天群中暴露真实 API Key。如果怀疑 Key 泄露，请立即在 NoneLinear 控制台删除并重新生成。"},{"title":"Chatbox","heading":"4. 新建模型并测试","url":"/scenes/chat-assistants/chatbox#4-新建模型并测试","text":"在模型区域点击新建，添加要使用的 NoneLinear 模型。模型 ID 必须与 NoneLinear 模型列表中的 ID 完全一致。示例填写：字段示例 :--- :--- 模型 ID deepseek-v4-flash 显示名称 deepseek-v4-flash 模型类型聊天如果该模型支持推理或工具调用，可以按需勾选推理、工具使用等能力。填写完成后点击测试模型，看到测试成功后点击保存。 !Chatbox 添加并测试 NoneLinear 模型你也可以配置其他 NoneLinear 模型，例如 GPT、Claude、Qwen、GLM、豆包等系列模型。以模型列表中展示的模型 ID 为准。"},{"title":"Chatbox","heading":"5. 切换到 NoneLinear 模型","url":"/scenes/chat-assistants/chatbox#5-切换到-nonelinear-模型","text":"回到 Chatbox 对话界面，在模型选择器中选择刚刚添加的 NoneLinear 模型，然后发送一条测试消息。如果模型正常回复，说明接入成功。"},{"title":"Chatbox","heading":"常见问题","url":"/scenes/chat-assistants/chatbox#常见问题","text":""},{"title":"Chatbox","heading":"为什么点击检查时提示需要先添加模型？","url":"/scenes/chat-assistants/chatbox#为什么点击检查时提示需要先添加模型？","text":"Chatbox 的连接检查依赖模型列表。如果当前提供方下还没有任何模型，可能会提示添加至少一个模型以检查连接。先完成新建模型并测试，再回到提供方配置页检查连接。"},{"title":"Chatbox","heading":"API 主机应该填到哪里？","url":"/scenes/chat-assistants/chatbox#api-主机应该填到哪里？","text":"API 主机填写 https://api.nonelinear.com.cn/v1 ，不要把 /chat/completions 一起填进去。 /chat/completions 保持在 API 路径字段即可。"},{"title":"Chatbox","heading":"模型测试失败怎么办？","url":"/scenes/chat-assistants/chatbox#模型测试失败怎么办？","text":"优先检查三项： - API Key 是否完整复制，前后不要带空格。 - API 主机是否为 https://api.nonelinear.com.cn/v1 。 - 模型 ID 是否与 NoneLinear 模型列表完全一致，包括大小写、连字符和版本号。"},{"title":"RikkaHub","heading":"","url":"/scenes/chat-assistants/rikkahub","text":"RikkaHub 是一款 Android 原生 LLM 聊天客户端，支持添加 OpenAI 兼容接口。将提供商类型设为 OpenAI，并把 API Base URL 配置为 NoneLinear 的 OpenAI 兼容端点后，即可在 RikkaHub 中调用 NoneLinear 模型。"},{"title":"RikkaHub","heading":"前置要求","url":"/scenes/chat-assistants/rikkahub#前置要求","text":"- 已安装 RikkaHub Android 客户端。 - 已获取 NoneLinear API Key：获取 API Key。 - 已确认要使用的模型 ID：模型列表。"},{"title":"RikkaHub","heading":"下载与安装","url":"/scenes/chat-assistants/rikkahub#下载与安装","text":""},{"title":"RikkaHub","heading":"1. 下载 RikkaHub","url":"/scenes/chat-assistants/rikkahub#1-下载-rikkahub","text":"访问 RikkaHub 下载页面，在 Download 区域选择 Download from Website 、 Download from Google Play 或 Android APK。 !RikkaHub 下载页面"},{"title":"RikkaHub","heading":"2. 安装 Android APK","url":"/scenes/chat-assistants/rikkahub#2-安装-android-apk","text":"如果选择 APK 安装包，下载完成后在手机上打开 APK 并按系统提示完成安装。 !RikkaHub 下载 APK"},{"title":"RikkaHub","heading":"配置步骤","url":"/scenes/chat-assistants/rikkahub#配置步骤","text":""},{"title":"RikkaHub","heading":"1. 进入设置","url":"/scenes/chat-assistants/rikkahub#1-进入设置","text":"打开 RikkaHub 后，点击左上角菜单按钮打开侧边栏。 !RikkaHub 打开侧边栏在侧边栏底部点击齿轮图标，进入设置页面。 !RikkaHub 进入设置"},{"title":"RikkaHub","heading":"2. 添加提供商","url":"/scenes/chat-assistants/rikkahub#2-添加提供商","text":"在提供商管理页面，点击右上角 + ，添加新的接口提供商。 !RikkaHub 添加提供商在添加提供商弹窗中填写：字段填写内容 :--- :--- 类型 OpenAI 名称 NoneLinear 或非线智能 API Key 你的 NoneLinear API Key API Base Url https://api.nonelinear.com.cn/v1 填写完成后点击添加。 !RikkaHub 填写提供商配置 !RikkaHub 完成提供商配置不要在截图、工单、公开仓库或聊天群中暴露真实 API Key。如果怀疑 Key 泄露，请立即在 NoneLinear 控制台删除并重新生成。"},{"title":"RikkaHub","heading":"3. 同步模型列表","url":"/scenes/chat-assistants/rikkahub#3-同步模型列表","text":"添加提供商后，进入该提供商详情页，切换到底部模型选项卡。 !RikkaHub 进入模型管理点击底部的同步模型图标，拉取当前 API Key 可用的模型列表。 !RikkaHub 同步模型"},{"title":"RikkaHub","heading":"4. 添加要使用的模型","url":"/scenes/chat-assistants/rikkahub#4-添加要使用的模型","text":"在可用模型列表底部的搜索框中输入模型关键词，例如 deepseek 。 !RikkaHub 搜索模型找到要使用的模型，例如 deepseek-v4-flash ，点击右侧 + 添加。 !RikkaHub 添加模型关闭弹窗后，如果模型出现在列表中，说明添加成功。 !RikkaHub 模型添加成功你也可以选择其他 NoneLinear 模型，例如 GPT、Claude、Qwen、GLM、豆包等系列模型。以模型列表中展示的模型 ID 为准。"},{"title":"RikkaHub","heading":"5. 切换模型并开始对话","url":"/scenes/chat-assistants/rikkahub#5-切换模型并开始对话","text":"返回聊天主页，点击输入框左下角的模型选择入口。 !RikkaHub 打开模型选择在模型选择面板中，找到刚刚创建的 NoneLinear 提供商，并选择已添加的模型。 !RikkaHub 选择模型发送一条测试消息，如果模型正常回复，说明接入成功。 !RikkaHub 对话测试"},{"title":"RikkaHub","heading":"常见问题","url":"/scenes/chat-assistants/rikkahub#常见问题","text":""},{"title":"RikkaHub","heading":"网络错误或请求失败怎么办？","url":"/scenes/chat-assistants/rikkahub#网络错误或请求失败怎么办？","text":"优先检查三项配置： - API Base Url 是否为 https://api.nonelinear.com.cn/v1 。 - API Key 是否完整复制，前后不要带空格。 - 当前手机网络是否可以访问 NoneLinear API。"},{"title":"RikkaHub","heading":"模型列表为空怎么办？","url":"/scenes/chat-assistants/rikkahub#模型列表为空怎么办？","text":"确认 API Key 有可用模型权限后，回到提供商详情页的模型选项卡，重新点击同步模型图标。"},{"title":"RikkaHub","heading":"找不到想用的模型怎么办？","url":"/scenes/chat-assistants/rikkahub#找不到想用的模型怎么办？","text":"检查模型 ID 是否与 NoneLinear 模型列表完全一致，包括大小写、连字符和版本号。也可以在可用模型列表中输入模型关键词进行搜索。"},{"title":"Dify","heading":"1. 获取 API Key","url":"/scenes/dev-tools/dify#1-获取-api-key","text":"1. 登录 NoneLinear 控制台（支持 GitHub 一键登录）。 2. 进入 API Key 页面，创建并复制您的 API Key。"},{"title":"Dify","heading":"2. 在 Dify 中集成 NoneLinear","url":"/scenes/dev-tools/dify#2-在-dify-中集成-nonelinear","text":"由于 NoneLinear API 完全兼容 OpenAI 协议，您可以直接以 \"OpenAI-compatible\" 模式将其添加到 Dify 中。"},{"title":"Dify","heading":"配置步骤","url":"/scenes/dev-tools/dify#配置步骤","text":"1. 在 Dify 首页，点击右上角的设置 (Settings) 。 2. 在左侧菜单中选择模型供应商 (Model Provider) 。 3. 找到 OpenAI-compatible （或自定义供应商），点击添加。 4. 在弹出的配置窗口中填写以下信息： - 模型类型 : 选择 LLM 或 Text Generation 。 - 模型名称 : 填写您想使用的模型 ID（例如 DeepSeek-V3.2 ，需与模型列表中的大小写一致）。完整列表请参考模型列表。 - API Key : 粘贴您在第一步获取的 API Key。 - API 基础 URL : 填写 https://api.nonelinear.com.cn/v1 。 5. 点击保存。"},{"title":"Dify","heading":"批量模型配置（进阶）","url":"/scenes/dev-tools/dify#批量模型配置（进阶）","text":"如果您需要同时使用多个模型，建议在 Dify 中多次添加对应的 OpenAI-compatible 配置，或使用 Dify 的模型映射功能。"},{"title":"Dify","heading":"3. 常见问题","url":"/scenes/dev-tools/dify#3-常见问题","text":"- 余额不足 : 请在 NoneLinear 充值页面进行充值，以确保服务连续性。 - 请求超时 : 如果遇到响应较慢，请检查 Dify 部署环境的网络连通性。"},{"title":"LangBot","heading":"1. 获取 API Key","url":"/scenes/dev-tools/langbot#1-获取-api-key","text":"1. 登录 NoneLinear 控制台（支持 GitHub 一键登录）。 2. 进入 API Key 页面，创建并复制您的 API Key。 3. 您可以在模型列表中查看支持的模型 ID（如 DeepSeek-V3.2 ）。"},{"title":"LangBot","heading":"2. 部署与配置 LangBot","url":"/scenes/dev-tools/langbot#2-部署与配置-langbot","text":"LangBot 支持多种部署方式，推荐使用 Docker 快速部署。更多部署方式可查看 LangBot 文档。"},{"title":"LangBot","heading":"使用 Docker 部署","url":"/scenes/dev-tools/langbot#使用-docker-部署","text":"1. 克隆项目仓库： bash git clone https://github.com/langbot-app/LangBot cd LangBot 2. 启动服务： bash docker compose up -d 如果在中国大陆使用，可将 docker-compose.yaml 中的镜像替换为： docker.langbot.app/langbot-public/rockchin/langbot:latest 3. 访问 WebUI：在浏览器中打开 http://localhost:5300 。如果部署在云服务器上，需要将 localhost 替换为服务器公网IP。"},{"title":"LangBot","heading":"3. 配置 NoneLinear 对话模型","url":"/scenes/dev-tools/langbot#3-配置-nonelinear-对话模型","text":"由于 NoneLinear API 完全兼容 OpenAI 协议，您可以直接在 LangBot 中配置为 OpenAI 类型供应商。"},{"title":"LangBot","heading":"配置步骤","url":"/scenes/dev-tools/langbot#配置步骤","text":"!LangBot 界面 1. 登录 LangBot WebUI，进入模型配置页面。 2. 添加新模型，选择供应商类型为 OpenAI ，并手动配置： - 提供商名称 : NoneLinear - API 密钥 (API Key) : 粘贴您在第一步获取的 API Key。 - API 基础 URL (Base URL) : https://api.nonelinear.com.cn/v1 - 模型名称 (Model ID) : 输入想要使用的模型 ID，如 DeepSeek-V3.2 。 3. 点击保存并测试连接。 !LangBot 配置界面 !LangBot 测试成功"},{"title":"LangBot","heading":"4. LangBot 接入平台","url":"/scenes/dev-tools/langbot#4-langbot-接入平台","text":"企业微信、飞书、Discord、Telegram、QQ、微信等更多平台，请参考LangBot 文档"},{"title":"NoneLinear 生图 Skill","heading":"","url":"/skills/nonelinear-image","text":"NoneLinear 生图 Skill 可以让 Claude Code、Codex 等 Agent 工具通过自然语言生成图片、编辑本地图片或融合多张参考图，无需手动编写 API 请求。当前版本： 0.4.2"},{"title":"NoneLinear 生图 Skill","heading":"支持能力","url":"/skills/nonelinear-image#支持能力","text":"- 文生图 - 单图编辑 - 多图融合 - 本地图片安全上传 - 自动处理不同模型的参数差异 - 返回可直接访问的图片 URL - 阻止 base64 图片进入 Agent 上下文"},{"title":"NoneLinear 生图 Skill","heading":"下载","url":"/skills/nonelinear-image#下载","text":"推荐下载 Universal ZIP： - 下载 nonelinear-image-0.4.2.zip - GitHub Releases v0.4.2"},{"title":"NoneLinear 生图 Skill","heading":"环境要求","url":"/skills/nonelinear-image#环境要求","text":"- Node.js 18 或更高版本 - Agent 可以执行本地 Node.js 命令 - 拥有可用的 NoneLinear API Key Skill 自带无第三方依赖的脚本，不需要安装 NoneLinear CLI，也不需要运行 npm install 。"},{"title":"NoneLinear 生图 Skill","heading":"API Key 自动复用","url":"/skills/nonelinear-image#api-key-自动复用","text":"如果 Claude Code、Codex 或 cc-switch 已经配置并正在使用 NoneLinear API，生图 Skill 通常可以直接复用当前 Agent 进程中的 API Key，不需要重复配置。 Skill 按以下顺序读取凭据：优先级环境变量使用条件 ---: --- --- 1 NONELINEAR_API_KEY 直接作为 NoneLinear API Key 使用 2 OPENAI_API_KEY OPENAI_BASE_URL 必须指向 api.nonelinear.com.cn 3 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY ANTHROPIC_BASE_URL 必须指向 api.nonelinear.com.cn 因此： - Codex 已通过 OPENAI_API_KEY 和 NoneLinear Base URL 接入时，Skill 可以复用该凭据。 - Claude Code 已通过 Anthropic 环境变量和 NoneLinear Base URL 接入时，Skill 可以复用该凭据。 - cc-switch 将当前配置注入 Agent 子进程时，Skill 也可以直接复用。出于安全考虑，只有 Base URL 的 HTTPS 主机名严格等于 api.nonelinear.com.cn 时，Skill 才会复用 OpenAI 或 Anthropic 凭据，避免把其他平台的 API Key 用于生图请求。 Skill 不会读取 Claude Code、Codex 或 cc-switch 的配置文件和数据库。如果宿主没有把凭据传入 Skill 子进程，会返回： text missing_api_key 只有出现该错误时，才需要单独配置 NONELINEAR_API_KEY 。"},{"title":"NoneLinear 生图 Skill","heading":"手动配置备用凭据","url":"/skills/nonelinear-image#手动配置备用凭据","text":"macOS / Linux： bash export NONELINEAR_API_KEY=\"nl-xxx\" Windows PowerShell： powershell $env:NONELINEAR_API_KEY=\"nl-xxx\" Windows CMD： bat set \"NONELINEAR_API_KEY=nl-xxx\" 配置后需要重新启动 Agent 或新建会话。不要把真实 API Key 写入 Skill 文件、项目文件或聊天消息。"},{"title":"NoneLinear 生图 Skill","heading":"安装到 Claude Code","url":"/skills/nonelinear-image#安装到-claude-code","text":"macOS / Linux： bash mkdir -p ~/.claude/skills unzip nonelinear-image-0.4.2.zip -d ~/.claude/skills Windows PowerShell： powershell New-Item -ItemType Directory -Force -Path \"$HOME\\.claude\\skills\" Out-Null Expand-Archive .\\nonelinear-image-0.4.2.zip -DestinationPath \"$HOME\\.claude\\skills\" -Force 安装后新建 Claude Code 会话： text /nonelinear-image 生成一张 1:1 产品图：白色陶瓷马克杯放在胡桃木桌面上，清晨自然光，真实摄影风格。"},{"title":"NoneLinear 生图 Skill","heading":"安装到 Codex","url":"/skills/nonelinear-image#安装到-codex","text":"macOS / Linux： bash mkdir -p ~/.agents/skills unzip nonelinear-image-0.4.2.zip -d ~/.agents/skills Windows PowerShell： powershell New-Item -ItemType Directory -Force -Path \"$HOME\\.agents\\skills\" Out-Null Expand-Archive .\\nonelinear-image-0.4.2.zip -DestinationPath \"$HOME\\.agents\\skills\" -Force 安装后新建 Codex 会话： text 使用 $nonelinear-image 生成一张 16:9 图片：雨后的上海街道，霓虹灯倒映在路面，电影摄影风格。"},{"title":"NoneLinear 生图 Skill","heading":"其他工具","url":"/skills/nonelinear-image#其他工具","text":"TRAE 可以将 Skill 放到项目目录： text /.trae/skills/nonelinear-image/SKILL.md Cherry Studio、WorkBuddy 等支持 Skills 管理的工具，可以直接导入 nonelinear-image-0.4.2.zip 。 TRAE、Cherry Studio、WorkBuddy 的不同版本可能存在导入入口、环境变量继承和本地命令权限差异。"},{"title":"NoneLinear 生图 Skill","heading":"图片编辑","url":"/skills/nonelinear-image#图片编辑","text":"编辑公开图片： text 使用 nonelinear-image 编辑 https://example.com/product.png，把背景替换成浅灰色摄影棚，保留产品外观。编辑本地图片： text 使用 nonelinear-image 编辑本地图片 /home/user/images/product.png，把背景替换成浅灰色摄影棚。不要读取或附加图片，直接把路径交给 Skill。 Windows 示例： text 使用 nonelinear-image 编辑本地图片 C:\\Users\\user\\Pictures\\product.png，把背景替换成浅灰色摄影棚。不要读取或附加图片，直接把路径交给 Skill。"},{"title":"NoneLinear 生图 Skill","heading":"多图融合","url":"/skills/nonelinear-image#多图融合","text":"text 使用 nonelinear-image 融合 /home/user/product.png 和 /home/user/scene.png，把第一张图的产品自然放入第二张图的场景，保持产品外观和比例。本地路径和公开 HTTPS URL 可以混合使用，参考图顺序会被保留。"},{"title":"NoneLinear 生图 Skill","heading":"安全与计费","url":"/skills/nonelinear-image#安全与计费","text":"- 图片生成请求发送到 https://api.nonelinear.com.cn/v1/images/generations 。 - 本地图片只会上传到固定的 https://nonelinear.com.cn/api/upload-file 。 - API Key、Authorization Header、base64 和完整请求体不会出现在 Agent 回复中。 - 每次生成请求都可能产生费用。 - Skill 不会在失败后自动重新生成，避免重复计费。 - 用户指定模型时，Skill 不会静默切换到其他模型。"},{"title":"NoneLinear 生图 Skill","heading":"常见问题","url":"/skills/nonelinear-image#常见问题","text":""},{"title":"NoneLinear 生图 Skill","heading":"Skill 没有被识别","url":"/skills/nonelinear-image#skill-没有被识别","text":"确认解压后的目录结构为： text nonelinear-image/ ├── SKILL.md ├── agents/ ├── references/ └── scripts/ 安装后需要新建 Claude Code 或 Codex 会话。"},{"title":"NoneLinear 生图 Skill","heading":"返回 missing_api_key","url":"/skills/nonelinear-image#返回-missing_api_key","text":"说明宿主没有把现有 NoneLinear 凭据传给 Skill 子进程。此时可以单独设置 NONELINEAR_API_KEY ，然后重新打开 Agent。"},{"title":"NoneLinear 生图 Skill","heading":"返回 Node.js 版本错误","url":"/skills/nonelinear-image#返回-node-js-版本错误","text":"执行： bash node --version 需要 Node.js 18 或更高版本。"},{"title":"NoneLinear 生图 Skill","heading":"请求成功但没有图片","url":"/skills/nonelinear-image#请求成功但没有图片","text":"部分模型可能返回文本结果、空图片数组或内容策略错误。Skill 会将其视为失败，不会自动重试。可以修改 Prompt 后再次主动发起请求。 > 凭据兼容说明：复用宿主环境变量中的 Key 时，也接受旧域名 api.nonelinear.com ，但必须是 HTTPS 且主机名精确匹配。生图、文件上传和 Key 验证请求均使用 .com.cn 新域名；兼容旧凭据配置不会将请求发往旧域名。"},{"title":"API 概览","heading":"协议与鉴权","url":"/api/intro#协议与鉴权","text":"使用方式 Base URL 鉴权 --- --- --- OpenAI SDK / 兼容客户端 https://api.nonelinear.com.cn/v1 Authorization: Bearer Anthropic SDK / Claude Code https://api.nonelinear.com.cn/anthropic x-api-key: ，请求版本头见接口文档 SDK 会拼接具体端点，Base URL 不要包含 /chat/completions 或 /messages 。软件中的地址字段可能有不同规则，请以对应工具教程为准。"},{"title":"API 概览","heading":"模型接口","url":"/api/intro#模型接口","text":"我想做什么接口文档请求路径 --- --- --- 文本对话、流式、多模态 OpenAI 兼容对话 POST /v1/chat/completions Anthropic 格式对话 Messages POST /anthropic/v1/messages 文生图、改图、多图融合图像生成 POST /v1/images/generations 生成视频视频任务创建与查询路径见视频文档将文本转换为向量 Embeddings POST /v1/embeddings 查询可用模型模型列表 GET /v1/models"},{"title":"API 概览","heading":"平台管理","url":"/api/intro#平台管理","text":"查询调用费用和账户余额。创建、查询和管理业务 Key。按业务组织密钥。限制允许调用的公网出口。管理接口与模型调用的权限要求不同，请查看对应页面；不要把默认管理 Key 分发给所有业务。"},{"title":"API 概览","heading":"响应与错误","url":"/api/intro#响应与错误","text":"不同协议、模型接口和管理接口的响应结构不同，以具体端点的示例为准。不能把一个统一的 code / data / message 外壳套用到全部响应。首次调用见快速开始，遇到错误见错误处理。"},{"title":"创建对话请求 (OpenAI)","heading":"接口说明","url":"/api/chat-openai#接口说明","text":"本接口兼容 OpenAI Chat Completions 协议，可以直接使用 OpenAI 官方 SDK 调用。除文本对话外，具备相应能力的模型也支持多模态输入，例如 Gemini 的视频与音轨理解。"},{"title":"创建对话请求 (OpenAI)","heading":"请求地址","url":"/api/chat-openai#请求地址","text":"用途地址 --- --- Base URL（填入 SDK 或客户端） https://api.nonelinear.com.cn/v1 完整请求地址（cURL 等直接发 HTTP 请求时使用） POST https://api.nonelinear.com.cn/v1/chat/completions 使用 SDK 时只填 Base URL，SDK 会自动拼接 /chat/completions ；不要把完整请求地址填进 Base URL。"},{"title":"创建对话请求 (OpenAI)","heading":"鉴权","url":"/api/chat-openai#鉴权","text":"在请求头中携带 API Key： Authorization: Bearer 。API Key 在 API Key 页面获取。示例从环境变量 NONELINEAR_API_KEY 读取 API Key，运行前先在终端设置： bash macOS / Linux export NONELINEAR_API_KEY=\"你的 API Key\" powershell Windows PowerShell $env:NONELINEAR_API_KEY=\"你的 API Key\""},{"title":"创建对话请求 (OpenAI)","heading":"示例代码 (OpenAI SDK)","url":"/api/chat-openai#示例代码-openai-sdk","text":"先安装 SDK： pip install --upgrade openai python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], ) response = client.chat.completions.create( model=\"gpt-6-luna\", messages=[ {\"role\": \"user\", \"content\": \"你好，请谈谈 AI 的未来。\"} ] ) print(response.choices[0].message.content)"},{"title":"创建对话请求 (OpenAI)","heading":"cURL 调用示例","url":"/api/chat-openai#curl-调用示例","text":"以下命令适用于 macOS / Linux 终端。Windows 用户可在 Git Bash 或 WSL 中运行，或使用 Python 示例。 bash curl -sS https://api.nonelinear.com.cn/v1/chat/completions \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"deepseek-v4.1-flash\", \"messages\": [ { \"role\": \"user\", \"content\": \"只回复 OK\" } ], \"stream\": false }' 成功时返回 JSON，模型的回答在 choices[0].message.content 中，本次消耗的 token 数在 usage 中。错误码说明见错误处理。如果使用 GPT-5.4 系列模型时遇到 usage 有 token 消耗但 message.content 为空，请参考错误处理：GPT-5.4 空输出。"},{"title":"创建对话请求 (OpenAI)","heading":"Gemini 视频与音轨理解","url":"/api/chat-openai#gemini-视频与音轨理解","text":"使用 gemini-4-argon 等gemini系列模型，可以分析视频画面的变化和视频中的音轨。请求发送至 POST /v1/chat/completions ，将完整 MP4 文件编码为 Base64，放入 messages[].content[] 中的 image_url.url ，格式为 data:video/mp4;base64,... 。音轨随视频文件一起传入，无需单独提取上传。这里的内容类型 type 和字段名都使用 image_url ，不要写成 video_url 。虽然字段名包含 image，传入的视频仍应使用 video/mp4 MIME 类型。"},{"title":"创建对话请求 (OpenAI)","heading":"Python 示例","url":"/api/chat-openai#python-示例","text":"先安装 SDK（ pip install --upgrade openai ），设置上文的 NONELINEAR_API_KEY 环境变量，并将 video.mp4 替换为你的本地视频文件路径。 python import base64 import os from pathlib import Path from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], ) video_base64 = base64.b64encode(Path(\"video.mp4\").read_bytes()).decode(\"utf-8\") response = client.chat.completions.create( model=\"gemini-4-argon\", stream=False, max_tokens=2048, messages=[ { \"role\": \"user\", \"content\": [ {\"type\": \"text\", \"text\": \"画面里有什么变化？音轨里有什么？\"}, { \"type\": \"image_url\", \"image_url\": {\"url\": f\"data:video/mp4;base64,{video_base64}\"}, }, ], } ], ) print(response.choices[0].message.content)"},{"title":"创建对话请求 (OpenAI)","heading":"JSON 请求体","url":"/api/chat-openai#json-请求体","text":"直接发送 HTTP 请求时，使用以下 JSON 结构，并将替换为视频文件的实际 Base64 编码。 max_tokens: 2048 是本示例设置的输出 token 上限，可按需调整。 json { \"model\": \"gemini-4-argon\", \"stream\": false, \"max_tokens\": 2048, \"messages\": [ { \"role\": \"user\", \"content\": [ {\"type\": \"text\", \"text\": \"画面里有什么变化？音轨里有什么？\"}, { \"type\": \"image_url\", \"image_url\": { \"url\": \"data:video/mp4;base64, \" } } ] } ] }"},{"title":"创建对话请求 (Anthropic)","heading":"接口说明","url":"/api/chat-anthropic#接口说明","text":"文本系列接口，兼容 Anthropic Messages 协议，可以直接使用 Anthropic 官方 SDK 调用。"},{"title":"创建对话请求 (Anthropic)","heading":"请求地址","url":"/api/chat-anthropic#请求地址","text":"用途地址 --- --- Base URL（填入 SDK 或 Claude Code 等客户端） https://api.nonelinear.com.cn/anthropic 完整请求地址（cURL 等直接发 HTTP 请求时使用） POST https://api.nonelinear.com.cn/anthropic/v1/messages 使用 SDK 时只填 Base URL，SDK 会自动拼接 /v1/messages ；不要把完整请求地址填进 Base URL。注意 Base URL 末尾没有 /v1 ，与 OpenAI 兼容接口不同。"},{"title":"创建对话请求 (Anthropic)","heading":"鉴权","url":"/api/chat-anthropic#鉴权","text":"在请求头中携带 API Key： x-api-key: ，同时携带 anthropic-version: 2023-06-01 。使用 Anthropic SDK 时这两个请求头会自动添加。API Key 在 API Key 页面获取。示例从环境变量 NONELINEAR_API_KEY 读取 API Key，运行前先在终端设置： bash macOS / Linux export NONELINEAR_API_KEY=\"你的 API Key\" powershell Windows PowerShell $env:NONELINEAR_API_KEY=\"你的 API Key\""},{"title":"创建对话请求 (Anthropic)","heading":"示例代码 (Anthropic SDK)","url":"/api/chat-anthropic#示例代码-anthropic-sdk","text":"先安装 SDK： pip install --upgrade anthropic python import os import anthropic client = anthropic.Anthropic( base_url=\"https://api.nonelinear.com.cn/anthropic\", api_key=os.environ[\"NONELINEAR_API_KEY\"], ) message = client.messages.create( model=\"claude-haiku-5.5\", max_tokens=1024, 必填：本次回答最多生成的 token 数 messages=[ {\"role\": \"user\", \"content\": \"你好，请介绍一下你自己。\"} ] ) print(message.content)"},{"title":"创建对话请求 (Anthropic)","heading":"cURL 调用示例","url":"/api/chat-anthropic#curl-调用示例","text":"以下命令适用于 macOS / Linux 终端。Windows 用户可在 Git Bash 或 WSL 中运行，或使用 Python 示例。 bash curl -sS https://api.nonelinear.com.cn/anthropic/v1/messages \\ -H \"x-api-key: $NONELINEAR_API_KEY\" \\ -H \"anthropic-version: 2023-06-01\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"claude-haiku-5.5\", \"max_tokens\": 32, \"messages\": [ { \"role\": \"user\", \"content\": \"只回复 OK\" } ] }' 成功时返回 JSON，本次消耗的 token 数在 usage 中。错误码说明见错误处理。"},{"title":"图像生成 API","heading":"","url":"/api/images","text":"希望在 Claude Code、Codex 等 Agent 工具中通过自然语言生图、编辑图片或融合多张参考图，可以使用 NoneLinear 生图 Skill。"},{"title":"图像生成 API","heading":"快速开始","url":"/api/images#快速开始","text":"所有生图模型都使用同一个接口： text POST https://api.nonelinear.com.cn/v1/images/generations - 鉴权：请求头 Authorization: Bearer ，在 API Key 页面获取。 - 同步返回：服务端等待图片生成完成后才返回，耗时可能达到数分钟，请把客户端超时设为 300 秒以上。 - 切换模型：只需修改 model ，并按模型参数调整尺寸参数。本页示例从环境变量 NONELINEAR_API_KEY 读取 API Key，运行前先在终端设置： bash export NONELINEAR_API_KEY=\"你的 API Key\" Windows PowerShell 的环境变量写法见快速开始。Python 示例使用 OpenAI SDK（ pip install openai ）。 bash cURL curl -sS --max-time 300 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"gpt-image-2\", \"prompt\": \"A clean product photo of a white ceramic coffee cup on a walnut desk, soft morning light, realistic style\", \"response_format\": \"url\", \"size\": \"1024x1024\", \"n\": 1 }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, 关闭自动重试，避免超时后重复生成、重复计费 ) response = client.images.generate( model=\"gpt-image-2\", prompt=\"A clean product photo of a white ceramic coffee cup on a walnut desk, soft morning light, realistic style\", response_format=\"url\", size=\"1024x1024\", n=1, ) for image in response.data or []: print(image.url or image.b64_json) HTTP 状态码为 200 并不代表一定出图。请以 data 中是否存在 url 或 b64_json 判断是否成功； data 为空或只有 text 时，按未出图处理。详见 Gemini 未出图说明。"},{"title":"图像生成 API","heading":"请求参数","url":"/api/images#请求参数","text":"参数类型用法 --- --- --- model string，必填精确模型 ID，见模型目录。 prompt string，必填描述要生成的画面，编辑时说明修改目标。 size string，按模型选填像素或尺寸档位；各系列允许值不同。 aspect_ratio string，按模型选填画面比例；并非所有模型支持。 n integer，按模型选填请求图片数量；省略时的默认值和实际返回数量因模型而异。 image string[]，按任务填写参考图 URL，需模型支持；不传本地路径。 response_format string，按模型填写示例使用 url ；实际返回请同时检查 url 与 b64_json 。扩展参数如 image 、 aspect_ratio 在 Python SDK 中放入 extra_body ；cURL 中放在 JSON 顶层。 quality 、 watermark 等系列独有参数见对应模型页。"},{"title":"图像生成 API","heading":"模型参数","url":"/api/images#模型参数","text":"OpenAI GPT Image / DALL·E ↗ 查询模型 ID、支持任务及尺寸参数。 Google Gemini（Nano Banana）/ Imagen ↗ 查询模型 ID、支持任务及尺寸参数。豆包 Seedream ↗ 查询模型 ID、支持任务及尺寸参数。阿里 Qwen（通义千问） ↗ 查询模型 ID、支持任务及尺寸参数。查看全部 15 个系列 →"},{"title":"图像生成 API","heading":"调用示例","url":"/api/images#调用示例","text":"文生图 ↗ 查看完整请求与结果处理。图片编辑 ↗ 查看完整请求与结果处理。多图融合 ↗ 查看完整请求与结果处理。透明背景 ↗ 查看完整请求与结果处理。组图 ↗ 查看完整请求与结果处理。"},{"title":"图像生成 API","heading":"常见问题","url":"/api/images#常见问题","text":""},{"title":"图像生成 API","heading":"本地图片怎么传","url":"/api/images#本地图片怎么传","text":"image 只接受公网可直接访问的 HTTPS 图片地址，不能传本地文件路径。本地图片可以： - 先上传到自己的对象存储（OSS / S3 / CDN），再传入图片地址； - 使用平台提供的文件上传 API 上传后获取地址； - 在 Claude Code、Codex 等工具中使用 NoneLinear 生图 Skill，它会自动处理本地图片上传。参考图地址需要免登录可访问、没有防盗链，且在生成期间保持有效。返回 404 或 Image unreachable 时，见参考图无法访问的排查。"},{"title":"图像生成 API","heading":"请求超时怎么办","url":"/api/images#请求超时怎么办","text":"生图耗时通常在 1~3 分钟，部分模型更久。请把 SDK、反向代理和后端 Worker 的超时都设为 300 秒以上；网页应用建议采用异步任务方式，避免前端等待超时，见耗时较长的处理建议。超时不代表生成失败，服务端可能仍在继续生成。请勿在超时后立即自动重试，以免重复生成、重复扣费。本页 Python 示例已通过 max_retries=0 关闭 SDK 自动重试。"},{"title":"图像生成 API","heading":"返回的图片地址能保存多久","url":"/api/images#返回的图片地址能保存多久","text":"返回的图片 URL 是临时地址，请在收到响应后尽快下载并转存到自己的存储中，见结果保存。更多错误码说明见错误处理。"},{"title":"创建视频生成请求","heading":"快速开始","url":"/api/videos#快速开始","text":"如需分析已有视频的画面和音轨，请参阅 Gemini 视频与音轨理解。视频生成是异步接口，一次完整调用分三步：步骤请求说明 --- --- --- 1. 创建任务 POST https://api.nonelinear.com.cn/v1/videos 以表单（multipart/form-data）提交，返回任务 id 2. 查询状态 GET https://api.nonelinear.com.cn/v1/videos/{video_id} 重复查询，直到 status 为 succeeded 或 completed 3. 获取视频 GET https://api.nonelinear.com.cn/v1/videos/{video_id}/content 响应 JSON 中的 url 即为视频下载地址 - 鉴权：请求头 Authorization: Bearer ，在 API Key 页面获取。 - 切换模型：修改 model ，并按模型参数调整 seconds 、 size 等参数。本页示例从环境变量 NONELINEAR_API_KEY 读取 API Key，运行前先在终端设置： bash macOS / Linux export NONELINEAR_API_KEY=\"你的 API Key\" powershell Windows PowerShell $env:NONELINEAR_API_KEY=\"你的 API Key\" cURL 示例使用 \\ 换行，适用于 macOS / Linux 终端；Windows 用户可在 Git Bash 或 WSL 中运行，或直接使用 Python 示例。 Python 示例使用 OpenAI SDK（ pip install openai ），都使用以下方式创建客户端： python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], )"},{"title":"创建视频生成请求","heading":"1. 创建任务","url":"/api/videos#1-创建任务","text":"bash cURL curl -sS https://api.nonelinear.com.cn/v1/videos \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -F \"model=wan2.7-t2v-720p\" \\ -F \"prompt=A cat playing a piano on stage\" \\ -F \"seconds=5\" python Python video = client.videos.create( model=\"wan2.7-t2v-720p\", prompt=\"A cat playing a piano on stage\", seconds=\"5\", extra_headers={\"Content-Type\": \"multipart/form-data\"}, ) print(video.id) 记下响应中的 id ，后两步都要用到。"},{"title":"创建视频生成请求","heading":"2. 查询状态","url":"/api/videos#2-查询状态","text":"将 VIDEO_ID 替换为创建任务时返回的完整 id ，后续查询和获取视频都使用这个值。不要用查询响应里的 id 覆盖它：部分模型在查询时返回的 ID 不包含模型前缀。生成需要一段时间，请间隔一段时间重复查询。不同模型的状态值大小写可能不同；判断时先转为小写，再检查是否为 succeeded 或 completed 。 bash cURL curl -sS https://api.nonelinear.com.cn/v1/videos/VIDEO_ID \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" python Python video = client.videos.retrieve(\"VIDEO_ID\") print(video.status)"},{"title":"创建视频生成请求","heading":"3. 获取视频下载地址","url":"/api/videos#3-获取视频下载地址","text":"任务完成后调用。响应 JSON 中的 url 即为视频下载地址。 bash cURL curl -sS https://api.nonelinear.com.cn/v1/videos/VIDEO_ID/content \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" python Python response = client.videos.download_content(\"VIDEO_ID\") print(response.json()[\"url\"]) python import os import time from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], ) video = client.videos.create( model=\"wan2.7-t2v-720p\", prompt=\"A cat playing a piano on stage\", seconds=\"5\", extra_headers={\"Content-Type\": \"multipart/form-data\"}, ) task_id = video.id 保留创建时的完整 ID，不能用查询响应里的 ID 替换 print(\"任务 ID：\", task_id) for _ in range(90): 每 10 秒查询一次，最多等待约 15 分钟 video = client.videos.retrieve(task_id) status = (video.status or \"\").lower() print(\"当前状态：\", video.status) if video.error: raise RuntimeError(f\"视频生成失败：{video.error}\") if status in (\"succeeded\", \"completed\"): break time.sleep(10) else: raise TimeoutError(f\"等待超时，可稍后用任务 ID {task_id} 继续查询\") response = client.videos.download_content(task_id) print(\"视频下载地址：\", response.json()[\"url\"])"},{"title":"创建视频生成请求","heading":"返回结果","url":"/api/videos#返回结果","text":"以下为 wan2.7-t2v-720p 的实际 HTTP 响应，任务 ID 已替换为示例值。创建任务与查询状态的响应字段不同，不应按同一个固定结构读取。创建任务：本次请求只返回 id ，不包含状态或进度。 json { \"id\": \"wan2.7-t2v-720p----00000000-0000-4000-8000-000000000000\" } 查询状态：生成中的响应如下。 json { \"err_code\": null, \"error\": null, \"id\": \"00000000-0000-4000-8000-000000000000\", \"model\": \"wan2.7-t2v-720p\", \"seconds\": null, \"size\": null, \"status\": \"RUNNING\" } 同一任务完成后，查询响应变为： json { \"err_code\": null, \"error\": null, \"id\": \"00000000-0000-4000-8000-000000000000\", \"model\": \"wan2.7-t2v-720p\", \"seconds\": 5, \"size\": 720, \"status\": \"completed\" } 字段说明 --- --- 创建响应的 id 后续请求使用的完整任务 ID，需原样保存，包括模型前缀。查询响应的 id 本例只返回任务标识部分，不能替换创建时的完整 ID。 status 本次任务生成中为 RUNNING ，完成后为 completed ，注意大小写不同。 model 本次任务使用的模型。 err_code 、 error 错误码与错误信息；本次成功任务的响应均为 null 。 seconds 本例生成中为 null ，完成后为整数 5 ，单位为秒。 size 本例生成中为 null ，完成后为整数 720 ，不是宽高字符串。用 status 判断任务是否完成。生成期间 seconds 、 size 为空时，继续等待即可。获取下载地址：任务完成后，使用创建时保存的完整 ID 请求 /v1/videos/{video_id}/content ，返回 JSON 中的 url 。下方地址为占位示例，请使用实际响应中的地址。 json { \"url\": \"https://example.com/generated-video.mp4\" }"},{"title":"创建视频生成请求","heading":"模型参数","url":"/api/videos#模型参数","text":"先找到所用模型，再按表中的写法原样传值，注意大小写，以及宽高之间用 x 还是。 - 参考图：“必须”表示该模型只能图生视频，创建任务时必须传入图片；“不支持”表示只能文生视频。 - 首尾帧、自定义音频：用法见调用示例中对应小节。 - 表中“不支持”的参数，调用时省略即可。 - 可以通过右侧目录按系列跳转，或按 Ctrl+F / ⌘+F 搜索模型 ID。 Python SDK 参数放在哪里？ model 、 prompt 、 seconds 、 size 、 input_reference 直接作为关键字传入； aspect_ratio 、 last_image_url 、 audio_url 等其他参数放进 extra_body={...} 。"},{"title":"创建视频生成请求","heading":"OpenAI Sora","url":"/api/videos#openai-sora","text":"模型 ID 参考图首尾帧自定义音频 seconds size aspect_ratio --- --- --- --- --- --- --- sora-2 支持不支持不支持 4 （默认）、 8 、 12 720x1280 （默认）、 1280x720 、 1024x1792 、 1792x1024 不支持"},{"title":"创建视频生成请求","heading":"豆包 Seedance","url":"/api/videos#豆包-seedance","text":"模型 ID 参考图首尾帧自定义音频 seconds size --- --- --- --- --- --- Doubao-Seedance-1.5-pro Doubao-Seedance-1.5-pro-noaudio 支持支持不支持 4~12 的整数，默认 5 480P 、 720P 、 1080P Doubao-Seedance-1.0-pro-fast 支持不支持不支持 2~12 的整数，默认 5 480P 、 720P 、 1080P Doubao-Seedance-1.0-pro 支持支持不支持 2~12 的整数，默认 5 480P 、 720P 、 1080P Doubao-Seedance-1.0-lite-i2v 必须支持不支持 2~12 的整数，默认 5 480P 、 720P 、 1080P Doubao-Seedance-1.0-lite-t2v 不支持不支持不支持 2~12 的整数，默认 5 480P 、 720P 、 1080P aspect_ratio 可选 16:9 、 4:3 、 1:1 、 3:4 、 9:16 、 21:9 、 adaptive ，其中 adaptive 有以下限制： - Doubao-Seedance-1.0-pro-fast 、 Doubao-Seedance-1.0-pro ：文生视频场景不支持 adaptive ； - Doubao-Seedance-1.0-lite-i2v 、 Doubao-Seedance-1.0-lite-t2v ：参考图和文生视频场景不支持 adaptive 。"},{"title":"创建视频生成请求","heading":"Google Veo","url":"/api/videos#google-veo","text":"模型 ID 参考图首尾帧自定义音频 seconds size --- --- --- --- --- --- veo-3.1-generate-preview veo-3.1-fast-generate-preview 支持支持不支持 4 、 6 、 8 ，默认 8 720p （默认）、 1080p veo-3.1-generate-preview-4k veo-3.1-fast-generate-preview-4k 支持支持不支持 8 4k veo-3.0-generate-001 veo-3.0-fast-generate-001 支持不支持不支持 4 、 6 、 8 ，默认 8 720p （默认）、 1080p 、 4k veo-2.0-generate-001 支持不支持不支持 5 、 6 、 8 ，默认 8 不支持 - aspect_ratio 可选 16:9 （默认）、 9:16 。 - Veo 3.1 / 3.0 使用扩展、参考图片，或使用 1080p 、 4k 分辨率时， seconds 必须为 8 。"},{"title":"创建视频生成请求","heading":"Vidu","url":"/api/videos#vidu","text":"模型 ID 参考图首尾帧自定义音频 seconds size --- --- --- --- --- --- viduq3-pro-1080p viduq3-turbo-1080p 支持支持不支持 1~16 的整数，默认 5 1080p viduq3-pro-720p viduq3-turbo-720p 支持支持不支持 1~16 的整数，默认 5 720p viduq3-pro-540p viduq3-turbo-540p 支持支持不支持 1~16 的整数，默认 5 540p aspect_ratio 可选 16:9 （默认）、 9:16 、 3:4 、 4:3 、 1:1 。"},{"title":"创建视频生成请求","heading":"可灵 Kling","url":"/api/videos#可灵-kling","text":"模型 ID 参考图首尾帧自定义音频 seconds --- --- --- --- --- Kling-v3-omni-std Kling-v3-omni-std-sound Kling-v3-omni-std-ref-video Kling-v3-omni-pro Kling-v3-omni-pro-sound Kling-v3-omni-pro-ref-video Kling-V3-std Kling-V3-std-sound Kling-V3-pro Kling-V3-pro-sound 支持支持不支持 3~15 的整数，默认 5 kling-video-o1-std kling-video-o1-std-ref-video kling-video-o1-pro kling-video-o1-pro-ref-video 支持支持不支持 3~10 的整数，默认 5 ；不传图片时只支持 5 、 10 Kling-V2-6-pro 支持支持不支持 5 （默认）、 10 Kling-V2-6-std Kling-V2-6-pro-sound Kling-V2-6-pro-sound-voiceid Kling-V2-6-std-actioncontrol Kling-V2-6-pro-actioncontrol 支持不支持不支持 5 （默认）、 10 - 本系列不支持 size 。 - aspect_ratio 可选 16:9 （默认）、 9:16 、 1:1 。"},{"title":"创建视频生成请求","heading":"阿里万相 Wan","url":"/api/videos#阿里万相-wan","text":"快速开始使用的 wan2.7-t2v-720p 已验证可用 seconds=\"5\" 、不传 size 创建任务。以下参数表仍按各型号分别列出，不应直接套用到新版本。下表型号不支持 aspect_ratio 。按任务分为以下几类。文生视频：不支持传入图片。模型 ID 自定义音频 seconds size --- --- --- --- wan2.6-t2v-720p 支持 2~15 的整数，默认 5 1280 720 （默认）、 720 1280 、 960 960 、 1088 832 、 832 1088 wan2.6-t2v-1080p 支持 2~15 的整数，默认 5 1920 1080 （默认）、 1080 1920 、 1440 1440 、 1632 1248 、 1248 1632 wan2.5-t2v-preview-480p 支持 5 （默认）、 10 832 480 （默认）、 480 832 、 624 624 wan2.5-t2v-preview-720p 支持 5 （默认）、 10 1280 720 （默认）、 720 1280 、 960 960 、 1088 832 、 832 1088 wan2.5-t2v-preview-1080p 支持 5 （默认）、 10 1920 1080 （默认）、 1080 1920 、 1440 1440 、 1632 1248 、 1248 1632 wan2.2-t2v-plus-480p 不支持固定为 5 ，不支持修改 832 480 （默认）、 480 832 、 624 624 wan2.2-t2v-plus-1080p 不支持固定为 5 ，不支持修改 1920 1080 （默认）、 1080 1920 、 1440 1440 、 1632 1248 、 1248 1632 图生视频：必须传入图片。模型 ID 自定义音频 seconds size --- --- --- --- wan2.6-i2v-flash-720p wan2.6-i2v-flash-720p-noaudio wan2.6-i2v-720p 支持 2~15 的整数，默认 5 720P wan2.6-i2v-flash-1080p wan2.6-i2v-flash-1080p-noaudio wan2.6-i2v-1080p 支持 2~15 的整数，默认 5 1080P wan2.5-i2v-preview-480p 支持 5 （默认）、 10 480P wan2.5-i2v-preview-720p 支持 5 （默认）、 10 720P wan2.5-i2v-preview-1080p 支持 5 （默认）、 10 1080P wan2.2-i2v-plus-480p 不支持固定为 5 ，不支持修改 480P wan2.2-i2v-plus-1080p 不支持固定为 5 ，不支持修改 1080P 首尾帧：必须传入首帧图片，不支持自定义音频。模型 ID seconds size --- --- --- wan2.2-kf2v-flash-480p 固定为 5 ，不支持修改 480P wan2.2-kf2v-flash-720p 固定为 5 ，不支持修改 720P wan2.2-kf2v-flash-1080p 固定为 5 ，不支持修改 1080P 图生动作、视频换人：必须传入图片，并通过 video_url 传入参考视频（见图生动作、视频换人示例）。不支持 seconds 、 size 和自定义音频。任务模型 ID --- --- 图生动作 wan2.2-animate-move-std 、 wan2.2-animate-move-pro 视频换人 wan2.2-animate-mix-std 、 wan2.2-animate-mix-pro 指定多角色：支持传入参考视频和图片，不支持自定义音频。模型 ID seconds size --- --- --- wan2.6-r2v-flash-720p wan2.6-r2v-flash-720p-noaudio wan2.6-r2v-720p 2~10 的整数，默认 5 1280 720 （默认）、 720 1280 、 960 960 、 1088 832 、 832 1088 wan2.6-r2v-flash-1080p wan2.6-r2v-flash-1080p-noaudio wan2.6-r2v-1080p 2~10 的整数，默认 5 1920 1080 （默认）、 1080 1920 、 1440 1440 、 1632 1248 、 1248 1632"},{"title":"创建视频生成请求","heading":"调用示例","url":"/api/videos#调用示例","text":"以下示例只展示创建任务这一步，每段代码只创建一个任务； client 的创建方式见快速开始。拿到任务 id 后，按查询状态和获取视频下载地址获取结果。示例中的本地图片路径（如 cat.jpg ）请替换为你自己的图片。"},{"title":"创建视频生成请求","heading":"文生视频","url":"/api/videos#文生视频","text":"python video = client.videos.create( model=\"wan2.7-t2v-720p\", prompt=\"A cat playing a piano on stage\", seconds=\"5\", extra_headers={\"Content-Type\": \"multipart/form-data\"}, ) print(video)"},{"title":"创建视频生成请求","heading":"图生视频","url":"/api/videos#图生视频","text":"通过 input_reference 上传本地图片。 python from pathlib import Path video = client.videos.create( model=\"sora-2\", prompt=\"A cat playing a piano on stage\", input_reference=Path(\"cat.jpg\"), 本地图片路径 extra_headers={\"Content-Type\": \"multipart/form-data\"}, ) print(video)"},{"title":"创建视频生成请求","heading":"首尾帧","url":"/api/videos#首尾帧","text":"支持首尾帧的模型： - Doubao-Seedance-1.5-pro 、 Doubao-Seedance-1.5-pro-noaudio 、 Doubao-Seedance-1.0-pro 、 Doubao-Seedance-1.0-lite-i2v - veo-3.1-generate-preview 、 veo-3.1-generate-preview-4k 、 veo-3.1-fast-generate-preview 、 veo-3.1-fast-generate-preview-4k - viduq3-pro-1080p 、 viduq3-pro-720p 、 viduq3-pro-540p 、 viduq3-turbo-1080p 、 viduq3-turbo-720p 、 viduq3-turbo-540p - Kling-v3-omni-std 、 Kling-v3-omni-std-sound 、 Kling-v3-omni-std-ref-video 、 Kling-v3-omni-pro 、 Kling-v3-omni-pro-sound 、 Kling-v3-omni-pro-ref-video 、 Kling-V3-std 、 Kling-V3-std-sound 、 Kling-V3-pro 、 Kling-V3-pro-sound 、 kling-video-o1-std 、 kling-video-o1-std-ref-video 、 kling-video-o1-pro 、 kling-video-o1-pro-ref-video 、 Kling-V2-6-pro - wan2.2-kf2v-flash-480p 、 wan2.2-kf2v-flash-720p 、 wan2.2-kf2v-flash-1080p 以 wan2.2-kf2v-flash-720p 为例：首帧通过 input_reference 上传本地图片，尾帧通过 extra_body 中的 last_image_url 传入图片地址。 python from pathlib import Path video = client.videos.create( model=\"wan2.2-kf2v-flash-720p\", prompt=\"写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。\", input_reference=Path(\"first_frame_wan.png\"), 首帧：本地图片路径 extra_headers={\"Content-Type\": \"multipart/form-data\"}, extra_body={\"last_image_url\": \"https://wanx.alicdn.com/material/20250318/last_frame.png\"}, ) print(video)"},{"title":"创建视频生成请求","heading":"图生动作","url":"/api/videos#图生动作","text":"支持的模型： wan2.2-animate-move-std 、 wan2.2-animate-move-pro 。上传人物图片，并通过 video_url 传入参考视频，无需 prompt 。 python from pathlib import Path video = client.videos.create( model=\"wan2.2-animate-move-std\", 或 wan2.2-animate-move-pro prompt=None, input_reference=Path(\"move_input_image.jpeg\"), 本地图片路径 extra_headers={\"Content-Type\": \"multipart/form-data\"}, extra_body={\"video_url\": \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4\"}, ) print(video)"},{"title":"创建视频生成请求","heading":"视频换人","url":"/api/videos#视频换人","text":"支持的模型： wan2.2-animate-mix-std 、 wan2.2-animate-mix-pro 。上传人物图片，并通过 video_url 传入参考视频，无需 prompt 。 python from pathlib import Path video = client.videos.create( model=\"wan2.2-animate-mix-std\", 或 wan2.2-animate-mix-pro prompt=None, input_reference=Path(\"mix_input_image.jpeg\"), 本地图片路径 extra_headers={\"Content-Type\": \"multipart/form-data\"}, extra_body={\"video_url\": \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4\"}, ) print(video)"},{"title":"创建视频生成请求","heading":"输入自定义音频","url":"/api/videos#输入自定义音频","text":"通过 extra_body 中的 audio_url 传入音频地址。支持的模型： - 文生视频： wan2.6-t2v-720p 、 wan2.6-t2v-1080p 、 wan2.5-t2v-preview-480p 、 wan2.5-t2v-preview-720p 、 wan2.5-t2v-preview-1080p - 图生视频（需同时传入图片）： wan2.6-i2v-flash-720p 、 wan2.6-i2v-flash-1080p 、 wan2.6-i2v-flash-1080p-noaudio 、 wan2.6-i2v-flash-720p-noaudio 、 wan2.6-i2v-720p 、 wan2.6-i2v-1080p 、 wan2.5-i2v-preview-480p 、 wan2.5-i2v-preview-720p 、 wan2.5-i2v-preview-1080p python video = client.videos.create( model=\"wan2.6-t2v-720p\", prompt=\"一幅史诗级可爱的场景。一只小巧可爱的卡通小猫将军，身穿细节精致的金色盔甲，头戴一个稍大的头盔，勇敢地站在悬崖上。他骑着一匹虽小但英勇的战马，说：”青海长云暗雪山，孤城遥望玉门关。黄沙百战穿金甲，不破楼兰终不还。“。悬崖下方，一支由老鼠组成的、数量庞大、无穷无尽的军队正带着临时制作的武器向前冲锋。这是一个戏剧性的、大规模的战斗场景，灵感来自中国古代的战争史诗。远处的雪山上空，天空乌云密布。整体氛围是“可爱”与“霸气”的搞笑和史诗般的融合。\", extra_headers={\"Content-Type\": \"multipart/form-data\"}, extra_body={\"audio_url\": \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250923/hbiayh/%E4%BB%8E%E5%86%9B%E8%A1%8C.mp3\"}, ) print(video)"},{"title":"创建视频生成请求","heading":"指定多角色","url":"/api/videos#指定多角色","text":"支持的模型： wan2.6-r2v-flash-720p 、 wan2.6-r2v-flash-1080p 、 wan2.6-r2v-flash-1080p-noaudio 、 wan2.6-r2v-flash-720p-noaudio 、 wan2.6-r2v-720p 、 wan2.6-r2v-1080p 。通过 extra_body 中的 reference_urls 传入多个参考视频或图片地址，模型会从中提取角色形象与音色。数组顺序即角色顺序：第 1 个地址对应 prompt 中的 character1，第 2 个对应 character2，以此类推。每个参考文件只包含一个主体角色，例如 character1 为小女孩，character2 为闹钟。 python video = client.videos.create( model=\"wan2.6-r2v-720p\", prompt=\"Character2 坐在靠窗的椅子上，手持 character3，在 character4 旁演奏一首舒缓的美国乡村民谣。Character1 对Character2开口说道：“听起来不错”\", extra_headers={\"Content-Type\": \"multipart/form-data\"}, extra_body={ \"reference_urls\": [ \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/hfugmr/wan-r2v-role1.mp4\", \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4\", \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png\", \"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png\", ] }, ) print(video)"},{"title":"文本嵌入 (Embedding)","heading":"1. 简介","url":"/api/embeddings#1-简介","text":"NoneLinear 提供与 OpenAI 接口完全兼容的 Embedding 服务。您只需修改 base_url 和 api_key ，即可将现有的 OpenAI Embedding 集成无缝迁移至 NoneLinear。"},{"title":"文本嵌入 (Embedding)","heading":"2. 获取 API Key","url":"/api/embeddings#2-获取-api-key","text":"1. 登录 NoneLinear 控制台。 2. 在 API Key 页面创建并获取您的 Key。"},{"title":"文本嵌入 (Embedding)","heading":"3. 调用示例","url":"/api/embeddings#3-调用示例","text":""},{"title":"文本嵌入 (Embedding)","heading":"使用 OpenAI Python SDK","url":"/api/embeddings#使用-openai-python-sdk","text":"示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python from openai import OpenAI import os 初始化客户端 client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ) def create_embedding(model=\"Qwen3-Embedding-8B\"): response = client.embeddings.create( model=model, input=\"你的文本内容，将转换为向量。\", encoding_format=\"float\" 可选：返回格式，float 或 base64 ) 提取向量数据 embedding = response.data[0].embedding print(f\"向量维度: {len(embedding)}\") print(f\"向量前5位: {embedding[:5]}\") 获取 Token 使用情况 usage = response.usage print(f\"消耗 Tokens: {usage}\") if __name__ == \"__main__\": create_embedding()"},{"title":"文本嵌入 (Embedding)","heading":"使用 cURL","url":"/api/embeddings#使用-curl","text":"bash curl -sS https://api.nonelinear.com.cn/v1/embeddings \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"Qwen3-Embedding-8B\", \"input\": \"你好，NoneLinear\", \"encoding_format\": \"float\" }' --- 更多支持 Embedding 的模型及其维度信息，请查看模型列表。"},{"title":"获取模型列表","heading":"接口说明","url":"/api/models#接口说明","text":"GET /v1/models 用于获取当前 API Key 可访问的模型列表。你可以用它确认模型 ID 是否可用，也可以在接入工具、模型选择器或后台配置页中动态展示模型。模型列表可能会随账号权限、模型上下架和服务配置变化。业务侧应以接口实时返回为准，不建议在客户端长期写死模型清单。"},{"title":"获取模型列表","heading":"请求地址","url":"/api/models#请求地址","text":"http GET https://api.nonelinear.com.cn/v1/models"},{"title":"获取模型列表","heading":"鉴权","url":"/api/models#鉴权","text":"在请求头中传入 API Key： http Authorization: Bearer"},{"title":"获取模型列表","heading":"查询参数","url":"/api/models#查询参数","text":"当前接口不需要传查询参数，会返回当前 API Key 可访问的全部模型。如果业务侧需要按文本、图像、视频、Embedding 等类型展示模型，建议先拉取完整列表，再结合平台模型列表或业务自己的模型分类表进行筛选。不要依赖客户端长期写死模型清单。"},{"title":"获取模型列表","heading":"cURL 示例","url":"/api/models#curl-示例","text":""},{"title":"获取模型列表","heading":"获取全部模型","url":"/api/models#获取全部模型","text":"bash curl --request GET \\ --url \"https://api.nonelinear.com.cn/v1/models\" \\ --header \"Authorization: Bearer $NONELINEAR_API_KEY\""},{"title":"获取模型列表","heading":"Python 示例","url":"/api/models#python-示例","text":""},{"title":"获取模型列表","heading":"使用 requests","url":"/api/models#使用-requests","text":"python import os import requests api_key = os.getenv(\"NONELINEAR_API_KEY\") response = requests.get( \"https://api.nonelinear.com.cn/v1/models\", headers={\"Authorization\": f\"Bearer {api_key}\"}, timeout=30, ) response.raise_for_status() models = response.json()[\"data\"] for model in models: print(model[\"id\"])"},{"title":"获取模型列表","heading":"使用 OpenAI Python SDK","url":"/api/models#使用-openai-python-sdk","text":"python import os from openai import OpenAI client = OpenAI( api_key=os.getenv(\"NONELINEAR_API_KEY\"), base_url=\"https://api.nonelinear.com.cn/v1\", ) models = client.models.list() for model in models.data: print(model.id)"},{"title":"获取模型列表","heading":"响应示例","url":"/api/models#响应示例","text":"json { \"object\": \"list\", \"data\": [ { \"id\": \"deepseek-v4-flash\", \"object\": \"model\", \"created\": 0, \"owned_by\": \"nonelinear\" }, { \"id\": \"gemini-2.5-flash-image\", \"object\": \"model\", \"created\": 0, \"owned_by\": \"nonelinear\" } ] }"},{"title":"获取模型列表","heading":"响应字段","url":"/api/models#响应字段","text":"字段类型说明 --- --- --- object string 固定为 list ，表示返回的是列表对象。 data array 模型对象数组。 data[].id string 模型 ID。调用对话、图像、视频等接口时填入 model 字段。 data[].object string 对象类型，通常为 model 。 data[].created integer 模型创建时间或占位时间戳，以接口返回为准。 data[].owned_by string 模型归属方或提供方，以接口返回为准。"},{"title":"获取模型列表","heading":"常见用途","url":"/api/models#常见用途","text":"1. 接入前确认模型 ID 是否存在，例如 deepseek-v4-flash 、 gpt-5.4-mini 、 gemini-2.5-flash-image 。 2. 在工具配置页里动态拉取模型列表，避免模型上下架后仍展示旧模型。 3. 配合业务侧模型分类表生成模型选择器，减少客户把文本模型误填到图像、视频或 Embedding 接口的概率。"},{"title":"获取模型列表","heading":"错误排查","url":"/api/models#错误排查","text":"状态码常见原因处理建议 --- --- --- 401 API Key 缺失或无效。确认 Authorization: Bearer 是否正确。 403 当前账号无权限访问。检查账号权限或联系管理员开通。 404 接口路径错误。确认请求地址为 /v1/models 。 429 请求过于频繁。降低请求频率并重试。 503 / 504 服务暂时不可用或超时。稍后重试，必要时记录请求时间并反馈给技术支持。"},{"title":"余额 & API Key 费用查询","heading":"1. 查询账户余额","url":"/api/billing#1-查询账户余额","text":"GET /v1/balance 查询当前账号的账户余额。"},{"title":"余额 & API Key 费用查询","heading":"鉴权方式","url":"/api/billing#鉴权方式","text":"Authorization: Bearer > ⚠️ 仅允许使用该账号的默认 API Key ，其他 Key 将返回 403 Forbidden 。"},{"title":"余额 & API Key 费用查询","heading":"请求示例","url":"/api/billing#请求示例","text":"bash curl -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ https://api.nonelinear.com.cn/v1/balance"},{"title":"余额 & API Key 费用查询","heading":"成功响应 (200)","url":"/api/billing#成功响应-200","text":"json { \"object\": \"balance\", \"balance\": 50.0000, \"currency\": \"RMB\", \"note\": \"元（人民币）\" } 字段类型说明 ------ ------ ------ object string 固定值 \"balance\" balance number 账户余额（元），保留 4 位小数 currency string 货币单位， \"RMB\" note string 备注说明"},{"title":"余额 & API Key 费用查询","heading":"错误响应","url":"/api/billing#错误响应","text":"状态码说明 -------- ------ 401 API Key 缺失或无效 403 API Key 有效但不是默认 Key ---"},{"title":"余额 & API Key 费用查询","heading":"2. 查询 API Key 费用信息","url":"/api/billing#2-查询-api-key-费用信息","text":"GET /v1/costofapikey 查询当前账号下所有 API Key 的费用明细，包含累计费用、预算限额、有效期、每日/每月限额等信息。"},{"title":"余额 & API Key 费用查询","heading":"鉴权方式","url":"/api/billing#鉴权方式-2","text":"Authorization: Bearer > ⚠️ 仅允许使用该账号的默认 API Key ，其他 Key 将返回 403 Forbidden 。"},{"title":"余额 & API Key 费用查询","heading":"请求示例","url":"/api/billing#请求示例-2","text":"bash curl -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ https://api.nonelinear.com.cn/v1/costofapikey"},{"title":"余额 & API Key 费用查询","heading":"成功响应 (200)","url":"/api/billing#成功响应-200-2","text":"json { \"object\": \"list\", \"data\": [ { \"apikey\": \"sk-f23118d4b \", \"name\": \"默认 API Key\", \"cost\": 0.000235, \"budget\": 0, \"created_at\": 1774081270, \"expiry_date\": null, \"daily_limit\": 0, \"monthly_limit\": 0, \"cost_today\": 0, \"cost_this_month\": 0, \"input_price_limit\": 0, \"output_price_limit\": 0, \"group_id\": \"6a06f7db38b3bf1609a9c200\", \"group_name\": \"生产环境\" } ] } 字段类型说明 ------ ------ ------ object string 固定值 \"list\" data array API Key 费用信息列表"},{"title":"余额 & API Key 费用查询","heading":"data 数组中的字段","url":"/api/billing#data-数组中的字段","text":"字段类型说明 ------ ------ ------ apikey string API Key，仅显示前 10 位，其余用掩盖 name string API Key 名称 cost number 累计费用（元） budget number 预算限额（0 表示无限制） created_at number 创建时间（Unix 时间戳） expiry_date string / null 有效期截止日期（ YYYY-MM-DD ）， null 表示永不过期 daily_limit number 每日消费限额（元），0 表示无限制 monthly_limit number 每月消费限额（元），0 表示无限制 cost_today number 今日已消费金额。 cost_this_month number 本月已消费金额。 input_price_limit number 模型输入价格限额（元/M token），0 表示无限制 output_price_limit number 模型输出价格限额（元/M token），0 表示无限制 group_id string / null 该 API Key 所属分组的 ID， null 表示未分组 group_name string / null 该 API Key 所属分组的名称， null 表示未分组，空字符串表示分组已被删除"},{"title":"余额 & API Key 费用查询","heading":"错误响应","url":"/api/billing#错误响应-2","text":"状态码说明 -------- ------ 401 API Key 缺失或无效 403 API Key 有效但不是默认 Key ---"},{"title":"余额 & API Key 费用查询","heading":"Python 调用示例","url":"/api/billing#python-调用示例","text":"python import requests BASE_URL = 'https://api.nonelinear.com.cn' def query_balance(apikey: str) -> dict: resp = requests.get( f'{BASE_URL}/v1/balance', headers={'Authorization': f'Bearer {apikey}'} ) resp.raise_for_status() return resp.json() def query_costofapikey(apikey: str) -> list: resp = requests.get( f'{BASE_URL}/v1/costofapikey', headers={'Authorization': f'Bearer {apikey}'} ) resp.raise_for_status() return resp.json()['data'] if __name__ == '__main__': API_KEY = ' ' bal = query_balance(API_KEY) print(f\"余额: {bal['balance']} {bal['currency']}\") records = query_costofapikey(API_KEY) for r in records: group = r.get('group_name') or '未分组' print(f\" Key: {r['apikey']} 分组: {group} 费用: {r.get('cost', 0)}\")"},{"title":"余额 & API Key 费用查询","heading":"相关接口","url":"/api/billing#相关接口","text":"- API Key 管理 - API Key 分组管理"},{"title":"API Key 管理","heading":"1. 创建新的 API Key","url":"/api/apikeys#1-创建新的-api-key","text":"POST /v1/apikeys 创建一个新的 API Key，可选择将其分配到指定的分组，并可同时设置各类型限额。"},{"title":"API Key 管理","heading":"鉴权方式","url":"/api/apikeys#鉴权方式","text":"Authorization: Bearer 本页接口仅允许使用账号的默认 API Key 调用。使用其他 API Key 调用会返回 403 Forbidden 。"},{"title":"API Key 管理","heading":"请求体","url":"/api/apikeys#请求体","text":"json { \"name\": \"生产环境-API-Key-001\", \"group_id\": \"6a06f7db38b3bf1609a9c200\", \"budget\": 100.0, \"expiry_date\": \"2026-12-31\", \"daily_limit\": 10.0, \"monthly_limit\": 50.0, \"input_price_limit\": 5.0, \"output_price_limit\": 15.0 } 字段类型必需说明 ------ ------ ------ ------ name string ✅ API Key 名称，不能为空、不能超过 128 个字符 group_id string ❌ 分组 ID，如果指定则将创建的 API Key 分配到该分组 budget number ❌ 总额度限额（元）， 0 表示无限制 expiry_date string ❌ 有效期截止日期，格式 YYYY-MM-DD ，不传则永不过期 daily_limit number ❌ 每日限额（元）， 0 表示无限制 monthly_limit number ❌ 每月限额（元）， 0 表示无限制 input_price_limit number ❌ 模型输入价格限额（元/M token）， 0 表示无限制 output_price_limit number ❌ 模型输出价格限额（元/M token）， 0 表示无限制"},{"title":"API Key 管理","heading":"请求示例","url":"/api/apikeys#请求示例","text":"bash curl -X POST https://api.nonelinear.com.cn/v1/apikeys \\ -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"name\": \"生产环境-API-Key-001\", \"group_id\": \"6a06f7db38b3bf1609a9c200\", \"budget\": 100.0, \"expiry_date\": \"2026-12-31\", \"daily_limit\": 10.0, \"monthly_limit\": 50.0 }'"},{"title":"API Key 管理","heading":"成功响应 (201)","url":"/api/apikeys#成功响应-201","text":"json { \"success\": true, \"message\": \"API Key 创建成功\", \"apikey\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\", \"name\": \"生产环境-API-Key-001\", \"group_id\": \"6a06f7db38b3bf1609a9c200\", \"budget\": 100.0, \"expiry_date\": \"2026-12-31\", \"daily_limit\": 10.0, \"monthly_limit\": 50.0, \"input_price_limit\": null, \"output_price_limit\": null } 字段类型说明 ------ ------ ------ success boolean 是否成功 message string 操作提示信息 apikey string 新创建的 API Key name string API Key 名称 group_id string / null 分配的分组 ID，未指定则为 null budget number / null 总额度限额（元），未传则为 null expiry_date string / null 有效期截止日期，未传则为 null daily_limit number / null 每日限额（元），未传则为 null monthly_limit number / null 每月限额（元），未传则为 null input_price_limit number / null 输入价格限额（元/M token），未传则为 null output_price_limit number / null 输出价格限额（元/M token），未传则为 null"},{"title":"API Key 管理","heading":"错误响应","url":"/api/apikeys#错误响应","text":"状态码说明示例 -------- ------ ------ 400 请求参数错误缺少名称、名称过长、分组不存在、类型错误、限额为负数等 401 API Key 缺失或无效 - 403 API Key 有效但不是默认 Key \"仅允许使用默认 API Key 创建 API Key\" 500 服务器内部错误 {\"success\": false, \"error\": \"创建 API Key 失败\"}"},{"title":"API Key 管理","heading":"常见错误响应","url":"/api/apikeys#常见错误响应","text":"json { \"success\": false, \"error\": \"API Key 名称不能为空\" } json { \"success\": false, \"error\": \"API Key 名称长度不能超过 128 个字符\" } json { \"success\": false, \"error\": \"参数 name 类型错误，期望 str，实际收到 int\" } json { \"success\": false, \"error\": \"指定的分组不存在\" } json { \"success\": false, \"error\": \"分组 ID 格式错误\" } json { \"success\": false, \"error\": \"budget 不能为负数\" } json { \"success\": false, \"error\": \"daily_limit 格式不正确，期望数字\" } json { \"success\": false, \"error\": \"expiry_date 格式不正确，期望 YYYY-MM-DD\" }"},{"title":"API Key 管理","heading":"参数验证规则","url":"/api/apikeys#参数验证规则","text":""},{"title":"API Key 管理","heading":"API Key 名称 (name)","url":"/api/apikeys#api-key-名称-name","text":"- 必需：是 - 类型： string - 长度：1-128 个字符 - 说明：用于标识和区分不同的 API Key - 示例： - ✅ \"生产环境-Key-001\" - ✅ \"测试环境\" - ❌ \"\" (空字符串) - ❌ \"x\" 129 (超过 128 字符)"},{"title":"API Key 管理","heading":"分组 ID (group_id)","url":"/api/apikeys#分组-id-group_id","text":"- 必需：否（可选） - 类型： string - 格式：MongoDB ObjectId 格式 - 说明：指定 API Key 所属的分组，如不指定则创建未分组的 API Key - 示例： - ✅ \"6a06f7db38b3bf1609a9c200\" - ❌ 123 (应为字符串) - ❌ \"invalid-id\" (无效的 ObjectId 格式) - ❌ 引用不存在的分组"},{"title":"API Key 管理","heading":"总额度限额 (budget)","url":"/api/apikeys#总额度限额-budget","text":"- 必需：否（可选） - 类型： number - 约束：不能为负数， 0 表示无限制 - 说明：API Key 的累计消费上限（元）"},{"title":"API Key 管理","heading":"有效期 (expiry_date)","url":"/api/apikeys#有效期-expiry_date","text":"- 必需：否（可选） - 类型： string - 格式： YYYY-MM-DD - 说明：API Key 的到期日期，不传表示永不过期 - 示例：✅ \"2026-12-31\" ，❌ \"2026/12/31\" ，❌ 20261231"},{"title":"API Key 管理","heading":"每日限额 (daily_limit)","url":"/api/apikeys#每日限额-daily_limit","text":"- 必需：否（可选） - 类型： number - 约束：不能为负数， 0 表示无限制 - 说明：API Key 单日消费上限（元）"},{"title":"API Key 管理","heading":"每月限额 (monthly_limit)","url":"/api/apikeys#每月限额-monthly_limit","text":"- 必需：否（可选） - 类型： number - 约束：不能为负数， 0 表示无限制 - 说明：API Key 单月消费上限（元）"},{"title":"API Key 管理","heading":"输入价格限额 (input_price_limit)","url":"/api/apikeys#输入价格限额-input_price_limit","text":"- 必需：否（可选） - 类型： number - 约束：不能为负数， 0 表示无限制 - 说明：允许调用的模型输入价格上限（元/M token），超出此价格的模型将被拒绝"},{"title":"API Key 管理","heading":"输出价格限额 (output_price_limit)","url":"/api/apikeys#输出价格限额-output_price_limit","text":"- 必需：否（可选） - 类型： number - 约束：不能为负数， 0 表示无限制 - 说明：允许调用的模型输出价格上限（元/M token），超出此价格的模型将被拒绝 ---"},{"title":"API Key 管理","heading":"应用场景","url":"/api/apikeys#应用场景","text":""},{"title":"API Key 管理","heading":"场景 1：创建一个未分组的 API Key","url":"/api/apikeys#场景-1：创建一个未分组的-api-key","text":"bash curl -X POST https://api.nonelinear.com.cn/v1/apikeys \\ -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ -H \"Content-Type: application/json\" \\ -d '{\"name\": \"我的第一个API Key\"}' 响应： json { \"success\": true, \"message\": \"API Key 创建成功\", \"apikey\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\", \"name\": \"我的第一个API Key\", \"group_id\": null, \"budget\": null, \"expiry_date\": null, \"daily_limit\": null, \"monthly_limit\": null, \"input_price_limit\": null, \"output_price_limit\": null }"},{"title":"API Key 管理","heading":"场景 2：创建 API Key 并分配到生产环境分组","url":"/api/apikeys#场景-2：创建-api-key-并分配到生产环境分组","text":"bash curl -X POST https://api.nonelinear.com.cn/v1/apikeys \\ -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"name\": \"生产API-002\", \"group_id\": \"6a06f7db38b3bf1609a9c200\" }' 响应： json { \"success\": true, \"message\": \"API Key 创建成功\", \"apikey\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\", \"name\": \"生产API-002\", \"group_id\": \"6a06f7db38b3bf1609a9c200\", \"budget\": null, \"expiry_date\": null, \"daily_limit\": null, \"monthly_limit\": null, \"input_price_limit\": null, \"output_price_limit\": null }"},{"title":"API Key 管理","heading":"场景 3：创建时同时设置限额","url":"/api/apikeys#场景-3：创建时同时设置限额","text":"bash curl -X POST https://api.nonelinear.com.cn/v1/apikeys \\ -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"name\": \"受控API-001\", \"group_id\": \"6a06f7db38b3bf1609a9c200\", \"budget\": 200.0, \"expiry_date\": \"2026-12-31\", \"daily_limit\": 20.0, \"monthly_limit\": 100.0, \"input_price_limit\": 5.0, \"output_price_limit\": 15.0 }' 响应： json { \"success\": true, \"message\": \"API Key 创建成功\", \"apikey\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\", \"name\": \"受控API-001\", \"group_id\": \"6a06f7db38b3bf1609a9c200\", \"budget\": 200.0, \"expiry_date\": \"2026-12-31\", \"daily_limit\": 20.0, \"monthly_limit\": 100.0, \"input_price_limit\": 5.0, \"output_price_limit\": 15.0 } ---"},{"title":"API Key 管理","heading":"Python 调用示例","url":"/api/apikeys#python-调用示例","text":"python import requests import json BASE_URL = 'https://api.nonelinear.com.cn' def create_apikey( apikey: str, name: str, group_id: str = None, budget: float = None, expiry_date: str = None, daily_limit: float = None, monthly_limit: float = None, input_price_limit: float = None, output_price_limit: float = None, ) -> dict: \"\"\" 创建新的 API Key Args: apikey: 默认 API Key（用于鉴权） name: API Key 名称 group_id: 可选，分组 ID budget: 可选，总额度限额（元），0 表示无限制 expiry_date: 可选，有效期截止日期，格式 YYYY-MM-DD daily_limit: 可选，每日限额（元） monthly_limit: 可选，每月限额（元） input_price_limit: 可选，输入价格限额（元/M token） output_price_limit: 可选，输出价格限额（元/M token） Returns: dict: 包含新创建的 API Key 信息 \"\"\" payload = {'name': name} if group_id is not None: payload['group_id'] = group_id if budget is not None: payload['budget'] = budget if expiry_date is not None: payload['expiry_date'] = expiry_date if daily_limit is not None: payload['daily_limit'] = daily_limit if monthly_limit is not None: payload['monthly_limit'] = monthly_limit if input_price_limit is not None: payload['input_price_limit'] = input_price_limit if output_price_limit is not None: payload['output_price_limit'] = output_price_limit resp = requests.post( f'{BASE_URL}/v1/apikeys', headers={ 'Authorization': f'Bearer {apikey}', 'Content-Type': 'application/json' }, json=payload ) resp.raise_for_status() return resp.json() if __name__ == '__main__': DEFAULT_API_KEY = ' ' 创建未分组的 API Key result1 = create_apikey(DEFAULT_API_KEY, '测试API-001') print(\"创建未分组的 API Key:\") print(json.dumps(result1, indent=2, ensure_ascii=False)) 创建分组的 API Key 并设置限额 result2 = create_apikey( DEFAULT_API_KEY, '生产API-001', group_id='6a06f7db38b3bf1609a9c200', budget=200.0, expiry_date='2026-12-31', daily_limit=20.0, monthly_limit=100.0, ) print(\"\\n创建带限额的 API Key:\") print(json.dumps(result2, indent=2, ensure_ascii=False)) ---"},{"title":"API Key 管理","heading":"2. 设置指定 API Key 的限额","url":"/api/apikeys#2-设置指定-api-key-的限额","text":"POST /v1/apikeys/ /budget 给指定 API Key 设置各类型限额。 apikey_id 为目标 API Key 的前 10 位字符。"},{"title":"API Key 管理","heading":"鉴权方式","url":"/api/apikeys#鉴权方式-2","text":"Authorization: Bearer > ⚠️ 仅允许使用该账号的默认 API Key ，其他 Key 将返回 403 Forbidden 。"},{"title":"API Key 管理","heading":"路径参数","url":"/api/apikeys#路径参数","text":"参数说明 ------ ------ apikey_id 目标 API Key 的前 10 位，例如 sk-f23118d4"},{"title":"API Key 管理","heading":"请求体","url":"/api/apikeys#请求体-2","text":"json { \"budget\": 100.0, \"expiry_date\": \"2026-12-31\", \"daily_limit\": 10.0, \"monthly_limit\": 50.0, \"input_price_limit\": 5.0, \"output_price_limit\": 15.0 } 字段类型必需说明 ------ ------ ------ ------ budget number ❌ 总额度限额（元）， 0 表示无限制 expiry_date string ❌ 有效期截止日期，格式 YYYY-MM-DD ，不传则清除有效期 daily_limit number ❌ 每日限额（元）， 0 表示无限制 monthly_limit number ❌ 每月限额（元）， 0 表示无限制 input_price_limit number ❌ 模型输入价格限额（元/M token）， 0 表示无限制 output_price_limit number ❌ 模型输出价格限额（元/M token）， 0 表示无限制 > 至少需要传一项限额参数。"},{"title":"API Key 管理","heading":"请求示例","url":"/api/apikeys#请求示例-2","text":"bash curl -X POST https://api.nonelinear.com.cn/v1/apikeys/sk-f23118d4/budget \\ -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"budget\": 100.0, \"expiry_date\": \"2026-12-31\", \"daily_limit\": 10.0, \"monthly_limit\": 50.0 }'"},{"title":"API Key 管理","heading":"成功响应 (200)","url":"/api/apikeys#成功响应-200","text":"json { \"success\": true, \"message\": \"预算设置成功，限额为 100.0000 元，有效期至 2026-12-31，每日限额：10.0000元，每月限额：50.0000元\", \"budget\": 100.0, \"expiry_date\": \"2026-12-31\", \"daily_limit\": 10.0, \"monthly_limit\": 50.0, \"input_price_limit\": null, \"output_price_limit\": null }"},{"title":"API Key 管理","heading":"错误响应","url":"/api/apikeys#错误响应-2","text":"状态码说明 -------- ------ 400 参数错误（类型错误、负数、缺少参数、日期格式错误） 401 API Key 缺失或无效 403 API Key 有效但不是默认 Key 404 指定的 API Key 不存在"},{"title":"API Key 管理","heading":"常见错误响应","url":"/api/apikeys#常见错误响应-2","text":"json {\"success\": false, \"error\": \"至少需要指定一项限额参数\"} json {\"success\": false, \"error\": \"指定的 API Key 不存在\"} json {\"success\": false, \"error\": \"参数 budget 类型错误，期望 int 或 float，实际收到 str\"} json {\"success\": false, \"error\": \"参数 daily_limit 不能为负数\"} json {\"success\": false, \"error\": \"参数 expiry_date 格式错误，应为 YYYY-MM-DD\"} ---"},{"title":"API Key 管理","heading":"最佳实践","url":"/api/apikeys#最佳实践","text":""},{"title":"API Key 管理","heading":"1. 命名约定","url":"/api/apikeys#1-命名约定","text":"- 遵循统一的命名规范，便于后续识别和管理 - 包含环境信息：生产-xxx 、测试-xxx 、开发-xxx - 包含用途或应用：数据分析-API 、内容生成-API"},{"title":"API Key 管理","heading":"2. 分组管理","url":"/api/apikeys#2-分组管理","text":"- 新创建的 API Key 应立即分配到相应分组 - 同一分组的 API Key 可统一设置限额和有效期 - 按业务线或部门创建分组，便于成本分配"},{"title":"API Key 管理","heading":"3. 安全建议","url":"/api/apikeys#3-安全建议","text":"- 每个应用或服务使用不同的 API Key - 定期轮换 API Key - 避免在代码中硬编码 API Key，使用环境变量或密钥管理服务 - 为不同环境使用不同的分组和 API Key"},{"title":"API Key 管理","heading":"4. 成本控制","url":"/api/apikeys#4-成本控制","text":"- 为每个 API Key 设置合理的预算限额 - 定期监控 API Key 的费用消耗 - 及时清理不使用的 API Key"},{"title":"API Key 管理","heading":"相关接口","url":"/api/apikeys#相关接口","text":"- API Key 分组管理 - 余额与 API Key 费用查询"},{"title":"API Key 分组管理","heading":"1. 创建 API Key 分组","url":"/api/apikey-groups#1-创建-api-key-分组","text":"POST /v1/apikey_groups 创建一个新的 API Key 分组，用于组织和管理多个 API Key。"},{"title":"API Key 分组管理","heading":"鉴权方式","url":"/api/apikey-groups#鉴权方式","text":"Authorization: Bearer 本页接口仅允许使用账号的默认 API Key 调用。使用其他 API Key 调用会返回 403 Forbidden 。"},{"title":"API Key 分组管理","heading":"请求体","url":"/api/apikey-groups#请求体","text":"json { \"name\": \"生产环境\", \"description\": \"用于生产环境的 API Key 分组\" } 字段类型必需说明 ------ ------ ------ ------ name string ✅ 分组名称，不能为空、不能重复、长度不能超过 128 个字符 description string ❌ 分组描述（可选）"},{"title":"API Key 分组管理","heading":"请求示例","url":"/api/apikey-groups#请求示例","text":"bash curl -X POST https://api.nonelinear.com.cn/v1/apikey_groups \\ -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"name\": \"生产环境\", \"description\": \"用于生产环境的 API Key 分组\" }'"},{"title":"API Key 分组管理","heading":"成功响应 (201)","url":"/api/apikey-groups#成功响应-201","text":"json { \"success\": true, \"message\": \"分组\\\"生产环境\\\"创建成功\", \"group_id\": \"6a06f7db38b3bf1609a9c200\", \"group_name\": \"生产环境\" } 字段类型说明 ------ ------ ------ success boolean 是否成功 message string 操作提示信息 group_id string 新创建分组的 ID group_name string 新创建分组的名称"},{"title":"API Key 分组管理","heading":"错误响应","url":"/api/apikey-groups#错误响应","text":"状态码说明示例 -------- ------ ------ 400 请求参数错误 {\"success\": false, \"error\": \"分组名称已存在\"} 或 {\"success\": false, \"error\": \"分组名称长度不能超过128个字符\"} 401 API Key 缺失或无效 - 403 API Key 有效但不是默认 Key \"仅允许使用默认 API Key 创建分组\" ---"},{"title":"API Key 分组管理","heading":"2. 查询 API Key 分组列表","url":"/api/apikey-groups#2-查询-api-key-分组列表","text":"GET /v1/apikey_groups 获取当前账号下所有的 API Key 分组信息。"},{"title":"API Key 分组管理","heading":"鉴权方式","url":"/api/apikey-groups#鉴权方式-2","text":"Authorization: Bearer 仅允许使用该账号的默认 API Key，其他 Key 将返回 403 Forbidden 。"},{"title":"API Key 分组管理","heading":"请求示例","url":"/api/apikey-groups#请求示例-2","text":"bash curl -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ https://api.nonelinear.com.cn/v1/apikey_groups"},{"title":"API Key 分组管理","heading":"成功响应 (200)","url":"/api/apikey-groups#成功响应-200","text":"json { \"object\": \"list\", \"data\": [ { \"id\": \"6a06f7db38b3bf1609a9c200\", \"name\": \"生产环境\", \"description\": \"用于生产环境的 API Key 分组\", \"created_at\": 1774081270, \"updated_at\": 1774081270, \"apikey_count\": 5 }, { \"id\": \"6a06f7db38b3bf1609a9c201\", \"name\": \"测试环境\", \"description\": \"用于测试环境的 API Key 分组\", \"created_at\": 1774081280, \"updated_at\": 1774081280, \"apikey_count\": 3 } ] }"},{"title":"API Key 分组管理","heading":"data 数组中的字段","url":"/api/apikey-groups#data-数组中的字段","text":"字段类型说明 ------ ------ ------ id string 分组 ID name string 分组名称 description string 分组描述 created_at number 创建时间（Unix 时间戳） updated_at number 最后更新时间（Unix 时间戳） apikey_count number 该分组中的 API Key 数量"},{"title":"API Key 分组管理","heading":"错误响应","url":"/api/apikey-groups#错误响应-2","text":"状态码说明 -------- ------ 401 API Key 缺失或无效 403 API Key 有效但不是默认 Key ---"},{"title":"API Key 分组管理","heading":"3. 批量设置分组内 API Key 的限额","url":"/api/apikey-groups#3-批量设置分组内-api-key-的限额","text":"POST /v1/apikey_groups/ /batch_budget 为指定分组下的所有 API Key 统一设置各类限额（预算、有效期、日限额、月限额、价格限额等）。"},{"title":"API Key 分组管理","heading":"鉴权方式","url":"/api/apikey-groups#鉴权方式-3","text":"Authorization: Bearer 仅允许使用该账号的默认 API Key，其他 Key 将返回 403 Forbidden 。"},{"title":"API Key 分组管理","heading":"URL 参数","url":"/api/apikey-groups#url-参数","text":"参数类型说明 ------ ------ ------ group_id string 分组 ID，从查询分组接口获取"},{"title":"API Key 分组管理","heading":"请求体","url":"/api/apikey-groups#请求体-2","text":"json { \"budget\": 1000.0, \"daily_limit\": 100.0, \"monthly_limit\": 500.0, \"expiry_date\": \"2026-12-31\", \"input_price_limit\": 50.0, \"output_price_limit\": 200.0 } 字段类型必需说明 ------ ------ ------ ------ budget number ❌ 预算限额（元），0 表示无限制 daily_limit number ❌ 每日消费限额（元），0 表示无限制 monthly_limit number ❌ 每月消费限额（元），0 表示无限制 expiry_date string ❌ 有效期截止日期（格式： YYYY-MM-DD ） input_price_limit number ❌ 模型输入价格限额（元/M token），0 表示无限制 output_price_limit number ❌ 模型输出价格限额（元/M token），0 表示无限制至少需要指定一项限额参数，否则返回 400 Bad Request 。"},{"title":"API Key 分组管理","heading":"请求示例","url":"/api/apikey-groups#请求示例-3","text":"bash curl -X POST https://api.nonelinear.com.cn/v1/apikey_groups/6a06f7db38b3bf1609a9c200/batch_budget \\ -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"budget\": 1000.0, \"daily_limit\": 100.0, \"monthly_limit\": 500.0, \"expiry_date\": \"2026-12-31\" }'"},{"title":"API Key 分组管理","heading":"成功响应 (200)","url":"/api/apikey-groups#成功响应-200-2","text":"json { \"success\": true, \"message\": \"批量设置限额成功，共更新 5 个API Key\", \"updated_count\": 5, \"failed_count\": 0 } 字段类型说明 ------ ------ ------ success boolean 是否成功 message string 操作提示信息 updated_count number 成功更新的 API Key 数量 failed_count number 失败的 API Key 数量"},{"title":"API Key 分组管理","heading":"错误响应","url":"/api/apikey-groups#错误响应-3","text":"状态码说明示例 -------- ------ ------ 400 请求参数错误参数类型错误、超出范围、格式错误或未找到符合条件的 API Key 401 API Key 缺失或无效 - 403 API Key 有效但不是默认 Key \"仅允许使用默认 API Key 设置限额\""},{"title":"API Key 分组管理","heading":"常见错误响应","url":"/api/apikey-groups#常见错误响应","text":"json { \"success\": false, \"error\": \"参数 budget 类型错误，期望 int 或 float，实际收到 str\" } json { \"success\": false, \"error\": \"参数 daily_limit 不能为负数\" } json { \"success\": false, \"error\": \"参数 expiry_date 格式错误，应为 YYYY-MM-DD\" } json { \"success\": false, \"error\": \"至少需要指定一项限额参数\" }"},{"title":"API Key 分组管理","heading":"参数验证规则","url":"/api/apikey-groups#参数验证规则","text":""},{"title":"API Key 分组管理","heading":"数值类型参数（budget, daily_limit, monthly_limit, input_price_limit, output_price_limit）","url":"/api/apikey-groups#数值类型参数（budget-daily_limit-monthly_limit-input_price_limit-output_price_limit）","text":"- 类型： int 或 float - 范围：≥ 0，不能为负数 - 说明： 0 表示无限制"},{"title":"API Key 分组管理","heading":"日期类型参数（expiry_date）","url":"/api/apikey-groups#日期类型参数（expiry_date）","text":"- 类型： string - 格式： YYYY-MM-DD （ISO 8601 日期格式） - 示例： \"2026-12-31\" ---"},{"title":"API Key 分组管理","heading":"Python 调用示例","url":"/api/apikey-groups#python-调用示例","text":"python import requests import json BASE_URL = 'https://api.nonelinear.com.cn' def create_apikey_group(apikey: str, name: str, description: str = '') -> dict: \"\"\"创建 API Key 分组\"\"\" resp = requests.post( f'{BASE_URL}/v1/apikey_groups', headers={ 'Authorization': f'Bearer {apikey}', 'Content-Type': 'application/json' }, json={ 'name': name, 'description': description } ) resp.raise_for_status() return resp.json() def query_apikey_groups(apikey: str) -> list: \"\"\"查询所有 API Key 分组\"\"\" resp = requests.get( f'{BASE_URL}/v1/apikey_groups', headers={'Authorization': f'Bearer {apikey}'} ) resp.raise_for_status() return resp.json()['data'] def set_group_apikey_budget(apikey: str, group_id: str, kwargs) -> dict: \"\"\" 批量设置分组内 API Key 的限额 kwargs 可包含： - budget: 预算限额 - daily_limit: 每日限额 - monthly_limit: 每月限额 - expiry_date: 有效期 - input_price_limit: 输入价格限额 - output_price_limit: 输出价格限额 \"\"\" resp = requests.post( f'{BASE_URL}/v1/apikey_groups/{group_id}/batch_budget', headers={ 'Authorization': f'Bearer {apikey}', 'Content-Type': 'application/json' }, json=kwargs ) resp.raise_for_status() return resp.json() if __name__ == '__main__': API_KEY = ' ' 创建分组 result = create_apikey_group(API_KEY, '生产环境', '用于生产环境的 API Key') print(f\"创建分组: {result}\") group_id = result.get('group_id') 查询所有分组 groups = query_apikey_groups(API_KEY) print(f\"\\n所有分组:\") for group in groups: print(f\" {group['name']}: {group['apikey_count']} 个 API Key\") 批量设置分组内 API Key 的限额 if group_id: budget_result = set_group_apikey_budget( API_KEY, group_id, budget=1000.0, daily_limit=100.0, monthly_limit=500.0, expiry_date='2026-12-31' ) print(f\"\\n批量设置限额结果: {budget_result}\") ---"},{"title":"API Key 分组管理","heading":"最佳实践","url":"/api/apikey-groups#最佳实践","text":""},{"title":"API Key 分组管理","heading":"分组命名建议","url":"/api/apikey-groups#分组命名建议","text":"- 按环境分组：生产环境、测试环境、开发环境 - 按业务分组：社交媒体、内容生成、数据分析 - 按团队分组：团队A 、团队B 、运维团队"},{"title":"API Key 分组管理","heading":"使用场景","url":"/api/apikey-groups#使用场景","text":"1. 成本中心分配 - 为不同部门/业务分配不同的 API Key，便于成本统计 2. 权限隔离 - 为敏感业务单独创建分组，便于权限管理 3. 配额管理 - 为不同的业务场景设置不同的调用限额 4. 监控告警 - 为不同的分组设置独立的监控和告警规则"},{"title":"API Key 分组管理","heading":"相关接口","url":"/api/apikey-groups#相关接口","text":"- API Key 管理 - 余额与 API Key 费用查询"},{"title":"API Key IP 白名单","heading":"概述","url":"/api/apikey-ip-whitelist#概述","text":"IP 白名单功能允许为每个 API Key 设置允许访问的来源 IP 或网段。设置白名单后，只有白名单内的 IP 才能使用该 API Key 调用 API ；未设置白名单（空）时，不限制来源 IP。"},{"title":"API Key IP 白名单","heading":"功能组成","url":"/api/apikey-ip-whitelist#功能组成","text":"项目说明 ------ ------ Web 管理界面在 apikey.html 页面为单个 Key 设置/查看 IP 白名单，或批量应用到分组/独立 Key API 管理端点通过 API 接口管理 IP 白名单（需默认 Key 鉴权）运行时拦截所有 LLM API 调用和 API Key 管理接口均会在鉴权时校验来源 IP ---"},{"title":"API Key IP 白名单","heading":"IP 格式说明","url":"/api/apikey-ip-whitelist#ip-格式说明","text":"每行一个 IP 地址或网段，支持两种写法："},{"title":"API Key IP 白名单","heading":"1. 标准 CIDR 格式","url":"/api/apikey-ip-whitelist#1-标准-cidr-格式","text":"56.78.45.0/24 65.78.0.0/16 10.0.0.1/32"},{"title":"API Key IP 白名单","heading":"2. 纯 IP 格式（自动推断网段）","url":"/api/apikey-ip-whitelist#2-纯-ip-格式（自动推断网段）","text":"当未包含 / 时，系统根据末尾连续为 0 的段数自动推断网段：示例末尾0段数推断网段覆盖范围 ------ ----------- ---------- ---------- 56.78.45.1 0 /32 （单机）仅 56.78.45.1 56.78.45.0 1 /24 56.78.45.0 ~ 56.78.45.255 65.78.0.0 2 /16 65.78.0.0 ~ 65.78.255.255 10.0.0.0 3 /8 10.0.0.0 ~ 10.255.255.255 > ⚠️ 0.0.0.0 会被视为非法条目。 ---"},{"title":"API Key IP 白名单","heading":"Web 管理界面","url":"/api/apikey-ip-whitelist#web-管理界面","text":""},{"title":"API Key IP 白名单","heading":"单个 Key 操作","url":"/api/apikey-ip-whitelist#单个-key-操作","text":"在 apikey.html 页面的每个 API Key 卡片上，点击 IP白名单图标按钮： 1. 弹出 IP 白名单弹窗，显示当前白名单规则 2. 在文本框中编辑（每行一个 IP/网段） 3. 点击\"保存IP白名单\"提交 4. 清空文本框并保存 = 清除白名单，恢复不限制来源 IP"},{"title":"API Key IP 白名单","heading":"批量操作","url":"/api/apikey-ip-whitelist#批量操作","text":"点击页面顶部的 \"批量设置IP白名单\" 按钮： 1. 勾选目标分组（分组下所有 Key 都会被应用） 2. 或勾选独立 API Key（支持多选） 3. 也可同时勾选分组和独立 Key（系统自动去重） 4. 填入白名单规则后保存 ---"},{"title":"API Key IP 白名单","heading":"API 接口","url":"/api/apikey-ip-whitelist#api-接口","text":""},{"title":"API Key IP 白名单","heading":"1. 设置单个 API Key 的 IP 白名单","url":"/api/apikey-ip-whitelist#1-设置单个-api-key-的-ip-白名单","text":"POST /apikey/set-ip-whitelist > ℹ️ 此接口为 Web UI 内部接口，需 Cookie 鉴权（用户登录态）。"},{"title":"API Key IP 白名单","heading":"请求体","url":"/api/apikey-ip-whitelist#请求体","text":"json { \"apikey\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\", \"ip_whitelist\": \"56.78.45.1\\n56.78.45.0\\n65.78.0.0\" } 字段类型必需说明 ------ ------ ------ ------ apikey string ✅ 目标 API Key（完整） ip_whitelist string ✅ 多行 IP/网段文本，空字符串 = 清除白名单"},{"title":"API Key IP 白名单","heading":"成功响应","url":"/api/apikey-ip-whitelist#成功响应","text":"json { \"success\": true, \"message\": \"IP白名单已更新，共 3 条规则\", \"ip_whitelist\": [\"56.78.45.1/32\", \"56.78.45.0/24\", \"65.78.0.0/16\"] }"},{"title":"API Key IP 白名单","heading":"错误响应","url":"/api/apikey-ip-whitelist#错误响应","text":"json { \"success\": false, \"error\": \"以下IP/网段格式不正确: \\\"999.1.1.1\\\": 无效的IP格式: 999.1.1.1、\\\"not.an.ip\\\": 无效的IP格式: not.an.ip\" } 状态码说明 -------- ------ 400 参数错误或 IP 格式非法 401 未登录 404 API Key 不存在或不属于当前用户 ---"},{"title":"API Key IP 白名单","heading":"2. 批量设置 API Key 的 IP 白名单","url":"/api/apikey-ip-whitelist#2-批量设置-api-key-的-ip-白名单","text":"POST /apikey/batch-set-ip-whitelist > ℹ️ 此接口为 Web UI 内部接口，需 Cookie 鉴权（用户登录态）。"},{"title":"API Key IP 白名单","heading":"请求体","url":"/api/apikey-ip-whitelist#请求体-2","text":"json { \"group_ids\": [\"6a06f7db38b3bf1609a9c200\", \"ungrouped\"], \"apikeys\": [\"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"], \"ip_whitelist\": \"56.78.45.0/24\\n65.78.0.0/16\" } 字段类型必需说明 ------ ------ ------ ------ group_ids string[] ❌ 分组 ID 列表，特殊值： \"all\" （全部）、 \"ungrouped\" （未分组） apikeys string[] ❌ 独立 API Key 列表 ip_whitelist string ✅ 多行 IP/网段文本，空字符串 = 清除白名单 > ⚠️ group_ids 和 apikeys 至少需要提供一项。"},{"title":"API Key IP 白名单","heading":"成功响应","url":"/api/apikey-ip-whitelist#成功响应-2","text":"json { \"success\": true, \"message\": \"批量设置IP白名单成功，共更新 5 个API Key，白名单共 2 条规则\", \"updated_count\": 5, \"failed_count\": 0, \"ip_whitelist\": [\"56.78.45.0/24\", \"65.78.0.0/16\"] } ---"},{"title":"API Key IP 白名单","heading":"运行时拦截","url":"/api/apikey-ip-whitelist#运行时拦截","text":"当通过 API Key 调用 LLM API 时，系统会自动校验请求来源 IP 是否在该 Key 的白名单内。"},{"title":"API Key IP 白名单","heading":"涉及的路由（均以 Authorization: Bearer 鉴权）","url":"/api/apikey-ip-whitelist#涉及的路由（均以-authorization-bearer--鉴权）","text":"路由说明 ------ ------ /llm LLM 生成 /v1/chat/completions OpenAI 兼容 chat /v1/embeddings 向量嵌入 /anthropic/v1/messages Anthropic 兼容 /v1/videos / /v1/videos/ 视频生成 /v1/images/generations 图片生成 /v1/images/generations/async 异步图片生成 /v1/responses Responses API /v1/balance 查询余额 /v1/costofapikey 查询费用 /v1/apikey_groups 分组管理 /v1/apikeys Key 管理 /autoeval 自动评测"},{"title":"API Key IP 白名单","heading":"白名单为空时","url":"/api/apikey-ip-whitelist#白名单为空时","text":"不做任何限制，所有来源 IP 均可正常调用。这与 budget 、 daily_limit 等字段的\"0/空 = 不限制\"约定一致。"},{"title":"API Key IP 白名单","heading":"白名单有规则时","url":"/api/apikey-ip-whitelist#白名单有规则时","text":"bash 来源 IP 不在白名单内 → 403 curl -H \"Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\ -H \"X-Forwarded-For: 1.2.3.4\" \\ https://api.nonelinear.com.cn/v1/chat/completions \\ -d '{\"model\": \"gpt-oss-20b\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]}' 响应 HTTP/1.1 403 Forbidden 该请求来源IP不在API Key允许的白名单内 ---"},{"title":"API Key IP 白名单","heading":"存储结构","url":"/api/apikey-ip-whitelist#存储结构","text":"IP 白名单存储在 user.costofapikey 集合的 ip_whitelist 字段： json { \"_id\": { \"$oid\": \"...\" }, \"apikey\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\", \"userid\": \"lijian\", \"cost\": 0.000647, \"budget\": 100, \"ip_whitelist\": [ \"56.78.45.1/32\", \"56.78.45.0/24\", \"65.78.0.0/16\" ] } > ip_whitelist 不存在或为 [] 时，表示该 Key 不限制来源 IP。 ---"},{"title":"API Key IP 白名单","heading":"最佳实践","url":"/api/apikey-ip-whitelist#最佳实践","text":""},{"title":"API Key IP 白名单","heading":"1. 安全隔离","url":"/api/apikey-ip-whitelist#1-安全隔离","text":"- 为生产环境的 Key 设置 IP 白名单，限制为公司办公网络 IP 或服务器出口 IP - 测试环境的 Key 可以不设置白名单"},{"title":"API Key IP 白名单","heading":"2. 网段规划","url":"/api/apikey-ip-whitelist#2-网段规划","text":"- 使用网段而非单个 IP，避免因 IP 更换频繁修改白名单 - 例如公司办公网络 192.168.0.0/16 或云服务器出口 10.0.0.0/8"},{"title":"API Key IP 白名单","heading":"3. 备用通道","url":"/api/apikey-ip-whitelist#3-备用通道","text":"- 建议至少保留一个不限制 IP 的 Key（或使用宽泛网段），防止因白名单配置错误导致完全无法访问"},{"title":"API Key IP 白名单","heading":"4. 来源 IP 说明","url":"/api/apikey-ip-whitelist#4-来源-ip-说明","text":"- 目前系统通过 X-Forwarded-For → X-Forwarded-For-Pound → request.remote_addr 的优先级获取来源 IP - 如果你的请求经过了反向代理，请确保代理正确设置了 X-Forwarded-For 头"},{"title":"模型与能力","heading":"","url":"/models/overview","text":"具体模型 ID、价格和可用状态请查看模型广场。文档说明调用方式与参数差异；不要根据厂商的展示名称猜测请求 ID。文本对话 ↗ 接入对话模型，生成文本与回答。图片生成与编辑 ↗ 按系列查询尺寸、比例、参考图和独有参数。视频生成 ↗ 创建任务、查询状态，获取生成结果。视觉理解 ↗ 读取图片内容，进行识别与分析。推理模型 ↗ 按模型选择思考强度和输出预算。工具调用 ↗ 让模型通过工具连接你的业务。"},{"title":"模型与能力","heading":"用代码查询可用模型","url":"/models/overview#用代码查询可用模型","text":"模型列表 API提供程序化查询入口。选择模型后，还需要确认它支持你要调用的接口及任务。"},{"title":"语言模型 (LLM)","heading":"1. 模型核心能力","url":"/userguide/features/llm#1-模型核心能力","text":""},{"title":"语言模型 (LLM)","heading":"基础功能","url":"/userguide/features/llm#基础功能","text":"NoneLinear 支持各类主流语言模型，提供以下基础能力： - 聊天对话：支持多轮对话、角色扮演等交互场景。 - 指令遵循：精准执行复杂指令，支持结构化输出。 - 常识问答：覆盖多领域知识库，提供实时准确的回答。 - 多语言翻译：支持全球数十种主流语言的高质量互译。"},{"title":"语言模型 (LLM)","heading":"2. 接口调用规范","url":"/userguide/features/llm#2-接口调用规范","text":""},{"title":"语言模型 (LLM)","heading":"2.1 基础请求结构","url":"/userguide/features/llm#2-1-基础请求结构","text":"我们完全兼容 OpenAI SDK。以下是使用 Python 调用接口的示例："},{"title":"语言模型 (LLM)","heading":"生成对话","url":"/userguide/features/llm#生成对话","text":"示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python import os from openai import OpenAI client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ) response = client.chat.completions.create( model=\"DeepSeek-V3.2\", messages=[ {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"}, {\"role\": \"user\", \"content\": \"用三句话介绍递归。\"} ], stream=True ) for chunk in response: 有些流式 chunk 可能没有 choices，比如 usage chunk、心跳、兼容层特殊事件 if not chunk.choices: continue delta = chunk.choices[0].delta 有些 chunk 有 delta，但没有 content content = getattr(delta, \"content\", None) if content: print(content, end=\"\", flush=True)"},{"title":"语言模型 (LLM)","heading":"2.2 消息体结构说明","url":"/userguide/features/llm#2-2-消息体结构说明","text":"- system : 用于设定模型的行为背景或限制（如“你是一位医生”）。 - user : 终端用户的输入内容。"},{"title":"语言模型 (LLM)","heading":"3. 模型系列选型指南","url":"/userguide/features/llm#3-模型系列选型指南","text":"您可以根据业务场景选择最适合的模型： - 模型广场：查看所有支持的模型列表及其参数。 - Playground ：免代码直接在线测试。 - API 文档：查看对话接口说明与调用示例。"},{"title":"多模态模型 (Multimodal)","heading":"1. 概述","url":"/userguide/features/multimodal#1-概述","text":"多模态模型支持处理多种媒体类型，包括： 1. 视觉理解：理解图片内容、OCR、图像描述。 2. 视频分析：提取视频帧、理解视频内容、动作识别。 3. 音频处理：语音识别、音频内容分析。 4. 多模态融合：同时处理多种媒体类型的综合分析。"},{"title":"多模态模型 (Multimodal)","heading":"2. 支持模型概览","url":"/userguide/features/multimodal#2-支持模型概览","text":"您可以访问模型广场查看所支持的多模态模型。"},{"title":"多模态模型 (Multimodal)","heading":"3. 使用方式","url":"/userguide/features/multimodal#3-使用方式","text":""},{"title":"多模态模型 (Multimodal)","heading":"3.1 基本消息格式","url":"/userguide/features/multimodal#3-1-基本消息格式","text":"多模态模型通过 messages 中的 content 字段传入多媒体内容。图片支持两种传入方式：方式一：公网 URL 公网 URL 必须是模型服务可以直接访问的图片地址。请使用真实图片直链，不要使用 https://example.com/image.jpg 这类占位地址，也不要使用需要登录、带防盗链或会跳转到 HTML 页面的地址。示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], ) image_url = ( \"https://ark-project.tos-cn-beijing.volces.com/doc_image/\" \"seedream4_imageToimage.png\" ) response = client.chat.completions.create( model=\"gpt-5.4-nano\", messages=[ { \"role\": \"user\", \"content\": [ {\"type\": \"text\", \"text\": \"请描述这张图片的内容\"}, { \"type\": \"image_url\", \"image_url\": { \"url\": image_url } } ] } ] ) print(response.choices[0].message.content) 方式二：本地图片（Base64 编码） python import os import base64 from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], ) 读取并编码本地图片 with open(\"image.jpg\", \"rb\") as f: b64_image = base64.b64encode(f.read()).decode(\"utf-8\") response = client.chat.completions.create( model=\"gpt-5.4-nano\", messages=[ { \"role\": \"user\", \"content\": [ {\"type\": \"text\", \"text\": \"请描述这张图片的内容\"}, { \"type\": \"image_url\", \"image_url\": { \"url\": f\"data:image/jpeg;base64,{b64_image}\" } } ] } ] ) print(response.choices[0].message.content)"},{"title":"多模态模型 (Multimodal)","heading":"3.2 通用参数说明","url":"/userguide/features/multimodal#3-2-通用参数说明","text":"参数类型说明 :--- :--- :--- type string 内容类型，可选值： text （文本）、 image_url （图片） text string 当 type 为 text 时，填写文本内容 image_url.url string 图片的公网 URL，或 data:{mime};base64,{base64数据} 格式的本地图片 > 提示：支持的图片格式： png 、 jpg / jpeg 、 webp 。 > 排查建议：如果返回 Error while downloading ... Upstream status code: 404 ，说明模型服务无法下载你传入的图片 URL。请先在浏览器或脚本中确认该 URL 能直接打开图片，并且响应状态码为 200 。"},{"title":"生图模型","heading":"1. 生图模型简介","url":"/userguide/features/image#1-生图模型简介","text":"生图模型允许用户通过文本提示（Prompt）直接创建图像，或基于现有图像生成变相版本。NoneLinear 支持包括 gpt-image-2、gemini-3-pro-image-preview、gemini-3.1-flash-image-preview、doubao-seedream-4-5-251128 等在内的多种主流模型。"},{"title":"生图模型","heading":"提示词（Prompt）输入技巧","url":"/userguide/features/image#提示词（prompt）输入技巧","text":"为了生成更高质量的图像，建议精心设计提示词： - 具体描述：详细描述场景细节。例如：“一个宁静的海滩上，夕阳西下，天空呈现橙红色，海浪轻拍沙滩”。 - 情感与氛围：加入风格化词汇，如“温馨的”、“神秘的”、“充满活力的”。 - 风格指定：明确艺术风格，如“印象派”、“超现实主义”、“赛博朋克”。 - 避免模糊词汇：少用“美”、“好”等抽象词，多用具体的材质、光影描述。 - 使用否定词 (Negative Prompt) ：排除不希望出现的元素，如“不要有船”。 - 分步骤输入：对于复杂场景，先生成基础图再调整细节。"},{"title":"生图模型","heading":"2. 体验地址","url":"/userguide/features/image#2-体验地址","text":"- 图像生成 Playground ：暂未开放图像的在线可视化生成。 - API 文档：查看生图接口详情。 - NoneLinear 生图 Skill ：在 Claude Code、Codex 等 Agent 工具中通过自然语言生成、编辑和融合图片。"},{"title":"生图模型","heading":"3. SDK 调用示例","url":"/userguide/features/image#3-sdk-调用示例","text":"我们兼容 OpenAI 接口规范，以下是 Python 调用示例：示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python import os from openai import OpenAI client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ) model=\"doubao-seedream-4-0-250828\" imagesResponse = client.images.generate( model=model, prompt=\"星际穿越，黑洞，黑洞里冲出一辆支离破碎的复古列车，强视觉冲击力，电影大片，末日既视感，动感，对比色，oc渲染，光线追踪，动态模糊，景深，超现实主义，深蓝，画面通过细腻的丰富的色彩层次塑造主体与场景，质感真实，暗黑风背景的光影效果营造出氛围，整体兼具艺术幻想感，夸张的广角透视效果，耀光，反射，极致的光影，强引力，吞噬\", size=\"2K\", response_format=\"url\", extra_body={\"watermark\": False}, ) print(imagesResponse.data[0].url)"},{"title":"生图模型","heading":"4. 支持模型列表","url":"/userguide/features/image#4-支持模型列表","text":"您可以访问模型广场查看完整列表。 --- 相关链接 - 视频生成模型 - 模型与能力"},{"title":"视频生成模型","heading":"1. 使用场景","url":"/userguide/features/video#1-使用场景","text":"视频生成模型能够生成动态的视觉内容，主要应用场景包括： 1. 动态内容生成：用于描述和解释信息，提升视觉表达力。 2. 多模态智能交互：结合图文输入，实现更智能、更具交互性的应用。 3. 替代传统视觉技术：增强或替代传统机器视觉，解决复杂的多模态问题。随着技术进步，视频生成将与视觉语言模型深度融合，推动智能交互与自动化内容生成的全面应用。"},{"title":"视频生成模型","heading":"2. 使用建议","url":"/userguide/features/video#2-使用建议","text":"为了获得最佳生成效果，建议在编写 Prompt 时参考以下原则： - 从主要动作开始： > 示例：一位皮肤白皙的女性，穿着蓝色夹克，戴着带面纱的黑帽子。她先低头向右看，然后说话时抬头。 - 添加动作与手势细节： > 示例：她先低头向右看，然后说话时抬头。 - 精确描述外观： > 示例：她盘着棕色头发，淡棕色眉毛，蓝色夹克里穿着白色领口衬衫。 - 包含背景环境细节： > 示例：背景虚化，可以看到树木和穿着时代服饰的人。 - 指定镜头角度与移动方式： > 示例：她说话时，摄像机固定在她的脸上。 - 描述光线与颜色效果： > 示例：场景采用写实风格，自然光线，色彩真实。 - 注意变化或突发事件： > 示例：一阵风吹过树林，导致女性的面纱轻微飘动。"},{"title":"视频生成模型","heading":"3. 体验地址","url":"/userguide/features/video#3-体验地址","text":"- Playground ：视频生成体验暂未开放在线测试。 - API 文档：查看视频提交接口详情。 --- 相关链接 - 多模态模型 (Multimodal) - 生图模型"},{"title":"生图模型目录","heading":"","url":"/models/images/overview","text":"所有系列通过 NoneLinear 图像生成接口调用，但尺寸、参考图和生成张数的规则不同。请原样复制模型 ID，实时可用性见模型广场。知道模型名称？搜索模型 ID 或 Nano Banana 等别名"},{"title":"生图模型目录","heading":"你想完成什么","url":"/models/images/overview#你想完成什么","text":"文生图 ↗ 查看输入要求与独立代码示例。图片编辑 ↗ 查看输入要求与独立代码示例。多图融合 ↗ 查看输入要求与独立代码示例。透明背景 ↗ 查看输入要求与独立代码示例。组图 ↗ 查看输入要求与独立代码示例。"},{"title":"生图模型目录","heading":"按模型系列查参数","url":"/models/images/overview#按模型系列查参数","text":"OpenAI GPT Image / DALL·E ↗ 查询模型 ID、支持任务及尺寸参数。 Google Gemini（Nano Banana）/ Imagen ↗ 查询模型 ID、支持任务及尺寸参数。豆包 Seedream ↗ 查询模型 ID、支持任务及尺寸参数。阿里 Qwen（通义千问） ↗ 查询模型 ID、支持任务及尺寸参数。阿里 Wan（通义万相） ↗ 查询模型 ID、支持任务及尺寸参数。快手 Kling（可灵）/ Kolors ↗ 查询模型 ID、支持任务及尺寸参数。智谱 GLM / CogView ↗ 查询模型 ID、支持任务及尺寸参数。 MiniMax ↗ 查询模型 ID、支持任务及尺寸参数。 FLUX ↗ 查询模型 ID、支持任务及尺寸参数。 Riverflow ↗ 查询模型 ID、支持任务及尺寸参数。 Stability（Stable Diffusion） ↗ 查询模型 ID、支持任务及尺寸参数。阶跃星辰 Step ↗ 查询模型 ID、支持任务及尺寸参数。 Vidu ↗ 查询模型 ID、支持任务及尺寸参数。 Luma（Uni） ↗ 查询模型 ID、支持任务及尺寸参数。 Reve ↗ 查询模型 ID、支持任务及尺寸参数。"},{"title":"生图模型目录","heading":"参数阅读约定","url":"/models/images/overview#参数阅读约定","text":"size 可能是像素或档位； aspect_ratio 表示画面比例。大小写及 x / 的写法按系列页原样使用。 “参考图”表示编辑或融合可传入的数量；标注必传时至少提供一张。表中的省略项和“不支持”不应自行补成默认值。调用方法见图像接口，问题见生图排障。"},{"title":"OpenAI GPT Image / DALL·E","heading":"","url":"/models/images/gpt-image","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 size n --- --- --- --- gpt-image-2 文生图、编辑、融合、透明背景参考图 0~16 张满足约束的任意尺寸，默认 auto ，见下方说明 1~10，默认 1 gpt-image-1.5-high gpt-image-1.5-medium gpt-image-1.5-low 文生图、编辑、融合参考图 0~16 张 1024x1024 、 1536x1024 、 1024x1536 、 auto 1~10，默认 1 gpt-image-1-high gpt-image-1-medium gpt-image-1-low 文生图、编辑、融合参考图 0~16 张 1024x1024 、 1536x1024 、 1024x1536 、 auto 1~10，默认 1 gpt-image-1-mini-high gpt-image-1-mini-medium gpt-image-1-mini-low 文生图、编辑、融合参考图 0~16 张 1024x1024 、 1536x1024 、 1024x1536 、 auto 1~10，默认 1 dall-e-3-hd dall-e-3-standard 文生图 1024x1024 、 1792x1024 、 1024x1792 1 dall-e-2 文生图 256x256 、 512x512 、 1024x1024 1~10，默认 1 本系列不支持 aspect_ratio 。 gpt-image-2 的尺寸 size 可传满足以下全部约束的任意分辨率，方图通常生成最快： - 宽和高都是 16 的倍数，最大边长不超过 3840 - 长边与短边之比不超过 3:1 - 总像素在 655360 到 8294400 之间常用值： 1024x1024 （方图）、 1536x1024 （横图）、 1024x1536 （竖图）、 2048x2048 （2K 方图）、 2048x1152 （2K 横图）、 3840x2160 （4K 横图）、 2160x3840 （4K 竖图）、 auto （默认）。其他可直接使用的尺寸： 832x1248 、 1248x832 、 864x1184 、 1184x864 、 896x1152 、 1152x896 、 768x1344 、 1344x768 、 1792x1024 、 1024x1792 。 gpt-image-2 独有参数以下参数只适用于 gpt-image-2 ，与 model 、 prompt 放在同一层；切换到其他模型时请删除。参数可选值说明 --- --- --- quality low 、 medium 、 high 、 auto （默认）渲染质量。 low 最快，适合草稿； high 适合成品。档位越高，耗时和费用通常越高。 background auto （默认）、 opaque 、 transparent 背景类型。 transparent 生成带透明通道的图片，用法见透明背景。 output_format 例如 png 输出格式。生成透明背景时必须使用 png 。"},{"title":"Google Gemini（Nano Banana）/ Imagen","heading":"","url":"/models/images/gemini","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 size aspect_ratio n --- --- --- --- --- gemini-3.1-flash-image-preview （Nano Banana 2）文生图、编辑、融合参考图 0~14 张（高保真最多 5 张） 512 、 1K 、 2K 、 4K 1:1 、 1:4 、 1:8 、 2:3 、 3:2 、 3:4 、 4:1 、 4:3 、 4:5 、 5:4 、 8:1 、 9:16 、 16:9 、 21:9 ，默认 1:1 — gemini-3-pro-image-preview （Nano Banana Pro）文生图、编辑、融合参考图 0~14 张（高保真最多 5 张） 1K 、 2K 、 4K 1:1 、 2:3 、 3:2 、 3:4 、 4:3 、 4:5 、 5:4 、 9:16 、 16:9 、 21:9 ，默认 1:1 — gemini-2.5-flash-image （Nano Banana）文生图、编辑、融合参考图 0~3 张不支持 1:1 、 2:3 、 3:2 、 3:4 、 4:3 、 4:5 、 5:4 、 9:16 、 16:9 、 21:9 ，默认 1:1 — imagen-4.0-ultra-generate-001 imagen-4.0-generate-001 文生图 1K 、 2K 1:1 、 3:4 、 4:3 、 9:16 、 16:9 1~4，默认 4 imagen-4.0-fast-generate-001 文生图不支持 1:1 、 3:4 、 4:3 、 9:16 、 16:9 1~4，默认 4 括号中的 Nano Banana 名称只是俗称， model 必须传模型 ID。 Imagen 系列不传 n 时默认一次生成 4 张图片。只需要 1 张时，请显式传 \"n\": 1 。 aspect_ratio 输出分辨率 :--- :--- 1:1 1024x1024 2:3 832x1248 3:2 1248x832 3:4 864x1184 4:3 1184x864 4:5 896x1152 5:4 1152x896 9:16 768x1344 16:9 1344x768 21:9 1536x672"},{"title":"Google Gemini（Nano Banana）/ Imagen","heading":"Gemini 未出图说明","url":"/models/images/gemini#gemini-未出图说明","text":"Gemini 偶尔会返回成功响应但没有图片，常见两种情况： - IMAGE_RECITATION ：生成因内容复述被中止，不会返回图片。建议调整 prompt 后重试。 - NO_IMAGE 或空结果：模型没有生成图片，可能表现为 data: [] ，或只返回一段文字。可按业务需要重试。 json { \"data\": [], \"text\": \"[ERROR]: FinishReason.IMAGE_RECITATION\" } json { \"data\": [], \"text\": \"好的，我来为你生成这张图片。\" } 请以 data[].url 或 data[].b64_json 是否存在判断是否出图。参见 Google 官方 FinishReason 说明。"},{"title":"豆包 Seedream","heading":"","url":"/models/images/seedream","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 size 默认 --- --- --- --- doubao-seedream-5-0-pro-260628 文生图、编辑、融合参考图 0~10 张 1K 、 2K 2K Doubao-Seedream-5.0-lite 文生图、编辑、融合、组图参考图 0~14 张 2K 、 3K 2K doubao-seedream-4-5-251128 文生图、编辑、融合、组图参考图 0~14 张 2K 、 4K 2K doubao-seedream-4-0-250828 文生图、编辑、融合、组图参考图 0~14 张 1K 、 2K 、 4K 2K 本系列只用 size 控制尺寸，不支持 aspect_ratio 。 size 有两种写法：传上表的档位，或传下面的像素尺寸。需要横图或竖图时，请使用像素尺寸，或在 prompt 中描述构图。 1024x1024 、 1280x720 、 2048x2048 2048x2048 、 2304x1728 、 1728x2304 、 2848x1600 、 1600x2848 、 2496x1664 、 1664x2496 、 3136x1344 、 3072x3072 、 3456x2592 、 2592x3456 、 4096x2304 、 2304x4096 、 2496x3744 、 3744x2496 、 4704x2016 2048x2048 、 2304x1728 、 1728x2304 、 2848x1600 、 1600x2848 、 2496x1664 、 1664x2496 、 3136x1344 、 4096x4096 、 3520x4704 、 4704x3520 、 5504x3040 、 3040x5504 、 3328x4992 、 4992x3328 、 6240x2656 1024x1024 、 864x1152 、 1152x864 、 1280x720 、 720x1280 、 832x1248 、 1248x832 、 1512x648 、 2048x2048 、 2304x1728 、 1728x2304 、 2848x1600 、 1600x2848 、 2496x1664 、 1664x2496 、 3136x1344 、 4096x4096 、 3520x4704 、 4704x3520 、 5504x3040 、 3040x5504 、 3328x4992 、 4992x3328 、 6240x2656 其他参数参数适用模型说明 --- --- --- watermark 全系列传 false 不添加水印。 sequential_image_generation Seedream 4.0 / 4.5 / 5.0 Lite 组图开关： auto 开启， disabled 或不传为单图。 Seedream 5.0 Pro 不支持。 sequential_image_generation_options.max_images 同上组图最多返回的张数，实际张数可能更少。 output_format Seedream 5.0 Pro png 或 jpeg 。 optimize_prompt_options.mode Seedream 5.0 Pro standard 偏重质量； fast 速度更快，适合预览。参考图要求 - 格式：jpeg、png、webp、bmp、tiff、gif - 大小不超过 10 MB，总像素不超过 6000×6000 - 宽高比（宽/高）在 1/16 到 16 之间，宽和高都大于 14 px - 数量：Seedream 5.0 Pro 最多 10 张，其余型号最多 14 张"},{"title":"阿里 Qwen（通义千问）","heading":"","url":"/models/images/qwen","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 size n --- --- --- --- qwen-image-3.0-pro qwen-image-3.0 qwen-image-2.0-pro qwen-image-2.0 文生图、编辑、融合参考图 0~3 张总像素在 512 512 到 2048 2048 之间，例如 1024 1536 。编辑时默认与输入图一致（多图时取最后一张） 1~6，默认 1 qwen-image-max qwen-image-plus 文生图 1664 928 、 1472 1104 、 1328 1328 、 1104 1472 、 928 1664 ，默认 1664 928 1 Qwen-Image 文生图 1328x1328 、 1664x928 、 928x1664 、 1472x1140 、 1140x1472 、 1584x1056 、 1056x1584 1 qwen-image-edit-max qwen-image-edit-plus 编辑、融合参考图 1~3 张宽、高均在 512~2048 px 1~6，默认 1 Qwen-Image-Edit 编辑参考图 1~3 张 — 1 qwen-mt-image 图片翻译参考图必传 — — 本系列不支持 aspect_ratio 。 - qwen-image-3.0 额外支持 prompt_extend 、 negative_prompt 、 seed 、 watermark ； qwen-image-3.0-pro 在此基础上还支持 prompt_extend_mode 、 enable_thinking 。 - qwen-mt-image 将图片中的文字翻译为目标语言，支持中文、英文与其他语种互译，不支持两种非中英语种之间直接互译（如日语译韩语），见支持的语种。 qwen-image-2.0 、 qwen-image-2.0-pro 、 qwen-image-3.0 、 qwen-image-3.0-pro 传 n 大于 1 时，可能只返回 1 张图片。请以响应中 data 的实际长度为准。"},{"title":"阿里 Wan（通义万相）","heading":"","url":"/models/images/wan","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 size n --- --- --- --- wan2.7-image-pro wan2.7-image 文生图、编辑、融合支持参考图 — — wan2.6-t2i wan2.5-t2i-preview 文生图总像素在 1280 1280 到 1440 1440 之间，宽高比 1:4 ~ 4:1。推荐 1280 1280 （默认）、 1104 1472 、 1472 1104 、 960 1696 、 1696 960 1~4，默认 4 wan2.2-t2i-plus wan2.2-t2i-flash wanx2.1-t2i-plus wanx2.1-t2i-turbo 文生图宽、高均在 512~1440，默认 1280 1280 1~4，默认 4 wan2.6-image 编辑、融合参考图 1~4 张（必传） 1280 1280 、 800 1200 、 1200 800 、 1344 576 、 1280 720 、 720 1280 、 1280 960 、 960 1280 1~4，默认 4 wan2.5-i2i-preview 编辑、融合参考图 1~3 张 1280 1280 、 1024 1024 、 800 1200 、 1200 800 、 960 1280 、 1280 960 、 720 1280 、 1280 720 、 1344 576 1~4，默认 4 wanx2.1-imageedit 编辑支持参考图 — 1~4，默认 4 wanx-v1 文生图、编辑支持参考图 1024 1024 、 720 1280 、 768 1152 、 1280 720 1~4，默认 4 z-image-turbo 文生图总像素在 512 512 到 2048 2048 之间，推荐 1024 1024 到 1536 1536 ，默认 1024 1536 1 本系列不支持 aspect_ratio 。 Wan 系列多数型号不传 n 时默认一次生成 4 张图片。只需要 1 张时，请显式传 \"n\": 1 。"},{"title":"快手 Kling（可灵）/ Kolors","heading":"","url":"/models/images/kling","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 size aspect_ratio n --- --- --- --- --- kling-image-o1 文生图、编辑、融合参考图最多 10 张 1k 、 2k 、 4k 1:1 、 3:2 、 2:3 、 4:3 、 3:4 、 16:9 、 9:16 、 21:9 、 auto 1~9，默认 1 kling-v2-new 编辑参考图必传 1k （默认）、 2k 1:1 、 3:2 、 2:3 、 4:3 、 3:4 、 16:9 、 9:16 、 21:9 ，默认 16:9 1~9，默认 1 kling-v2-1 文生图、融合支持参考图 1k （默认）、 2k 同上，默认 16:9 1~9，默认 1 kling-v2 文生图、编辑、融合支持参考图 1k （默认）、 2k 同上，默认 16:9 1~9，默认 1 kling-v1-5 kling-v1 文生图、编辑支持参考图 1k 同上，默认 16:9 1~9，默认 1 Kolors 文生图 1024x1024 、 960x1280 、 768x1024 、 720x1440 、 720x1280 不支持 — Kling 系列的 size 档位为小写 k ，与其他系列的 1K 、 2K 写法不同。"},{"title":"智谱 GLM / CogView","heading":"","url":"/models/images/glm","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 size --- --- --- glm-image 文生图 1280x1280 、 1568x1056 、 1056x1568 、 1472x1088 、 1088x1472 、 1728x960 、 960x1728 cogview-4-250304 cogview-4 cogview-3-flash 文生图 1024x1024 、 768x1344 、 864x1152 、 1344x768 、 1152x864 、 1440x720 、 720x1440 本系列不支持 aspect_ratio ，无需传 n 。"},{"title":"MiniMax","heading":"","url":"/models/images/minimax","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 aspect_ratio n --- --- --- --- minimax-image-01 文生图、编辑支持参考图 1:1 、 16:9 、 4:3 、 3:2 、 2:3 、 3:4 、 9:16 、 21:9 1~9，默认 1 minimax-image-01-live 文生图、编辑支持参考图 1:1 、 16:9 、 4:3 、 3:2 、 2:3 、 3:4 、 9:16 1~9，默认 1 本系列不支持 size 。"},{"title":"FLUX","heading":"","url":"/models/images/flux","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 aspect_ratio --- --- --- flux.2-max flux.2-pro flux.2-flex 文生图、编辑、融合参考图最多 8 张 1:1 、 2:3 、 3:2 、 3:4 、 4:3 、 4:5 、 5:4 、 9:16 、 16:9 、 21:9 flux.2-klein-4b 文生图、编辑、融合参考图最多 4 张同上本系列不支持 size ，无需传 n 。"},{"title":"Riverflow","heading":"","url":"/models/images/riverflow","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 aspect_ratio --- --- --- riverflow-v2-max-preview riverflow-v2-standard-preview riverflow-v2-fast-preview 文生图、编辑、融合参考图 0~4 张 1:1 、 2:3 、 3:2 、 3:4 、 4:3 、 4:5 、 5:4 、 9:16 、 16:9 、 21:9 本系列使用 aspect_ratio 控制比例，无需传 size 和 n 。"},{"title":"Stability（Stable Diffusion）","heading":"","url":"/models/images/stability","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 aspect_ratio --- --- --- Stable-Image-Ultra Stable-Image-Core Stable-Diffusion-3.5-Large Stable-Diffusion-3.5-Large-Turbo Stable-Diffusion-3.5-Medium Stable-Diffusion-3.5-Flash 文生图 16:9 、 1:1 、 21:9 、 2:3 、 3:2 、 4:5 、 5:4 、 9:16 、 9:21 本系列不支持 size ，无需传 n 。"},{"title":"阶跃星辰 Step","heading":"","url":"/models/images/step","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 size n --- --- --- --- step-2x-large step-1x-medium 文生图 256x256 、 512x512 、 768x768 、 1024x1024 、 1280x800 、 800x1280 1 step-1x-edit 编辑参考图 1 张（必传） 512x512 、 768x768 、 1024x1024 — 本系列不支持 aspect_ratio 。"},{"title":"Vidu","heading":"","url":"/models/images/vidu","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 size aspect_ratio --- --- --- --- viduq2 文生图、编辑、融合参考图 0~7 张 1080p 、 2K 、 4K 16:9 、 9:16 、 1:1 、 3:4 、 4:3 、 21:9 、 2:3 、 3:2 viduq1 编辑、融合参考图 1~7 张（必传） 1080p 16:9 、 9:16 、 1:1 、 3:4 、 4:3 本系列无需传 n 。"},{"title":"Luma（Uni）","heading":"","url":"/models/images/luma","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 aspect_ratio --- --- --- uni-1-max uni-1 文生图、参考图生图（ image_ref ）、融合参考图 0~8 张 3:1 、 2:1 、 16:9 、 3:2 、 1:1 、 2:3 、 9:16 、 1:2 、 1:3 uni-1-max-edit uni-1-edit 编辑参考图 1 张（必传）同上本系列不支持 size ，无需传 n 。"},{"title":"Reve","heading":"","url":"/models/images/reve","text":"← 生图模型目录 · 通用接口 · 任务示例表格可横向滚动，查看完整模型 ID 与参数。模型 ID 支持任务 / 参考图 aspect_ratio --- --- --- reve-create-latest 文生图 16:9 、 9:16 、 3:2 、 2:3 、 4:3 、 3:4 、 1:1 reve-edit-latest 编辑参考图 1 张（必传）同上 reve-remix-latest 融合参考图 1~6 张（必传）同上本系列不支持 size ，无需传 n 。"},{"title":"开发指南","heading":"","url":"/userguide/overview","text":"流式输出 ↗ 让回答逐步显示，读取流式事件。函数调用 ↗ 定义工具、读取调用请求并返回工具结果。多模态输入 ↗ 向模型传入图片，完成识图与分析。推理设置 ↗ 了解思考强度、输出预算与模型差异。缓存与上下文 ↗ 保持请求前缀稳定，核对缓存命中。错误与重试 ↗ 区分参数、鉴权、限流和服务异常。"},{"title":"开发指南","heading":"SDK 与框架","url":"/userguide/overview#sdk-与框架","text":"使用 OpenAI 兼容模型。构建有状态的 Agent 工作流。配置模型与 Agent。"},{"title":"流式输出","heading":"1. 简介","url":"/userguide/features/stream#1-简介","text":"在默认情况下，模型会在生成完整个回复后再一次性将其返回。对于长文本生成，这可能会导致数十秒的等待时间。流式输出 (Stream Mode) 允许服务器在生成内容的过程中，将一个个“字符”（Tokens）实时推送到客户端。这能极大地降低首字延迟 (TTFT, Time To First Token) ，显著提升用户体验。"},{"title":"流式输出","heading":"2. 工作原理","url":"/userguide/features/stream#2-工作原理","text":"NoneLinear 的流式输出采用标准的 Server-Sent Events (SSE) 协议。数据格式：每一行数据都以 data: 开头，紧随其后的是一个 JSON 字符串。结束标志：当模型生成结束时，服务端会发送 data: [DONE] 消息，表示流已关闭。"},{"title":"流式输出","heading":"3. 调用示例","url":"/userguide/features/stream#3-调用示例","text":"要在 NoneLinear 智能网关中开启流式输出，只需在请求 JSON 中设置 \"stream\": true 。"},{"title":"流式输出","heading":"Python 调用 (使用 OpenAI SDK)","url":"/userguide/features/stream#python-调用-使用-openai-sdk","text":"示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python import os from openai import OpenAI client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ) response = client.chat.completions.create( model=\"DeepSeek-V3.2\", messages=[{\"role\": \"user\", \"content\": \"帮我写一首关于非线性进化的诗。\"}], stream=True 开启流式输出 ) for chunk in response: 有些流式 chunk 可能没有 choices，比如 usage chunk、心跳、兼容层特殊事件 if not chunk.choices: continue delta = chunk.choices[0].delta 有些 chunk 有 delta，但没有 content content = getattr(delta, \"content\", None) if content: print(content, end=\"\", flush=True)"},{"title":"流式输出","heading":"cURL 调用","url":"/userguide/features/stream#curl-调用","text":"在命令行使用 curl 调用时，必须添加 -N 参数（或 --no-buffer ），否则 curl 会缓存输出，导致无法看到实时跳字的效果。 bash curl -N -X POST https://api.nonelinear.com.cn/v1/chat/completions \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"DeepSeek-V3.2\", \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}], \"stream\": true }'"},{"title":"Function Calling","heading":"1. 使用场景","url":"/userguide/features/function-calling#1-使用场景","text":"Function Calling（函数调用）允许模型根据用户需求调用外部工具或 API，核心价值包括： - 扩展数值计算能力：解决模型原生计算不精准的问题。 - 获取实时外部信息：通过调用搜索、天气、数据库等接口获取即时数据。 - 环境交互与控制：自动化操控智能设备、发送邮件或执行代码。"},{"title":"Function Calling","heading":"2. 使用方式","url":"/userguide/features/function-calling#2-使用方式","text":""},{"title":"Function Calling","heading":"2.1 通过 REST API 添加 tools 参数","url":"/userguide/features/function-calling#2-1-通过-rest-api-添加-tools-参数","text":"在发送请求时，通过 tools 字段定义可用的函数列表： json { \"model\": \"DeepSeek-V3.2\", \"messages\": [ { \"role\": \"user\", \"content\": \"帮我计算 123.45 乘以 67.89\" } ], \"tools\": [ { \"type\": \"function\", \"function\": { \"name\": \"calculate_mul\", \"description\": \"计算两个数字的乘积\", \"parameters\": { \"type\": \"object\", \"properties\": { \"a\": { \"type\": \"number\", \"description\": \"乘数 a\" }, \"b\": { \"type\": \"number\", \"description\": \"乘数 b\" } }, \"required\": [\"a\", \"b\"] } } } ] }"},{"title":"Function Calling","heading":"2.2 通过 OpenAI 库请求","url":"/userguide/features/function-calling#2-2-通过-openai-库请求","text":"推荐使用 OpenAI SDK 进行集成，调用方式如下：示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python import os from openai import OpenAI client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ) messages = [{\"role\": \"user\", \"content\": \"帮我查一下 AAPL 的实时股价\"}] response = client.chat.completions.create( model=\"DeepSeek-V3.2\", messages=messages, tools=[ { \"type\": \"function\", \"function\": { \"name\": \"get_stock_price\", \"description\": \"获取指定股票代码的实时价格\", \"parameters\": { \"type\": \"object\", \"properties\": { \"symbol\": { \"type\": \"string\" } }, \"required\": [\"symbol\"] } } } ] ) print(response.choices[0].message.tool_calls)"},{"title":"Function Calling","heading":"3. 支持模型列表","url":"/userguide/features/function-calling#3-支持模型列表","text":"您可以访问模型广场，查看模型是否支持工具调用。"},{"title":"Function Calling","heading":"4. 使用示例 (Python)","url":"/userguide/features/function-calling#4-使用示例-python","text":"以下展示一个完整的闭环调用示例： Function Calling 示例建议优先使用支持工具调用的普通对话模型。推理模型可能会把部分内容放在 reasoning_content 中，不适合作为新手接入的最小示例。 python import os from openai import OpenAI import json client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ) 1. 定义工具函数 def calculate_add(a, b): return a + b tools = [ { \"type\": \"function\", \"function\": { \"name\": \"calculate_add\", \"description\": \"计算两个数字之和\", \"parameters\": { \"type\": \"object\", \"properties\": { \"a\": {\"type\": \"number\"}, \"b\": {\"type\": \"number\"} }, \"required\": [\"a\", \"b\"] } } } ] 2. 发起首次请求 messages = [{\"role\": \"user\", \"content\": \"123.45 加上 67.89 等于多少？\"}] response = client.chat.completions.create( model=\"DeepSeek-V3.2\", messages=messages, tools=tools, tool_choice=\"auto\" ) 3. 处理工具调用 assistant_message = response.choices[0].message tool_calls = assistant_message.tool_calls or [] if not tool_calls: print(assistant_message.content) else: tool_call = tool_calls[0] function_name = tool_call.function.name function_args = json.loads(tool_call.function.arguments) 执行本地函数 function_response = calculate_add( function_args) 将结果反馈给模型 messages.append(assistant_message) messages.append({ \"role\": \"tool\", \"tool_call_id\": tool_call.id, \"content\": str(function_response) }) 再次请求获取自然语言回答 final_response = client.chat.completions.create( model=\"DeepSeek-V3.2\", messages=messages ) print(final_response.choices[0].message.content)"},{"title":"Function Calling","heading":"5. 特殊模型注意事项","url":"/userguide/features/function-calling#5-特殊模型注意事项","text":"不同模型厂商在工具调用上存在一些差异化要求。本节说明需要额外处理的情况，建议在接入对应模型前仔细阅读。"},{"title":"Function Calling","heading":"5.1 Gemini 3 系列：多轮工具调用必须回传 thought_signature","url":"/userguide/features/function-calling#5-1-gemini-3-系列：多轮工具调用必须回传-thought_signature","text":""},{"title":"Function Calling","heading":"5.1.1 背景","url":"/userguide/features/function-calling#5-1-1-背景","text":"Gemini 3 系列模型（如 gemini-3.1-pro-preview 、 gemini-3-flash-preview 等）引入了 Thought Signature 机制：模型在返回 tool_call 时，会附带一段加密的思考轨迹，用于在后续轮次中保持推理上下文的连续性。在多轮工具调用中，客户端必须将这段 signature 原样回传给模型，否则会收到类似如下的 400 错误： text Error code: 400 - Function call is missing a thought_signature in functionCall parts. This is required for tools to work correctly..."},{"title":"Function Calling","heading":"5.1.2 关键规则","url":"/userguide/features/function-calling#5-1-2-关键规则","text":"场景规则 --- --- 单个工具调用该 tool_call 会带有 thought_signature ，下一轮必须原样回传串行多步调用（多轮 tool_call）每一步的 tool_call 都带 signature，历史中的每一个都必须保留回传并行工具调用（一次返回多个 tool_call）只有第一个 tool_call 带 signature，其他不带；回传 message 顺序必须为 assistant(FC1+sig, FC2) → tool(FR1) → tool(FR2) ，不能交错"},{"title":"Function Calling","heading":"5.1.3 signature 在 OpenAI 兼容格式中的位置","url":"/userguide/features/function-calling#5-1-3-signature-在-openai-兼容格式中的位置","text":"通过 OpenAI SDK 调用时， thought_signature 位于每个 tool_call 的 extra_content.google.thought_signature 字段： json { \"id\": \"function-call-xxx\", \"type\": \"function\", \"function\": { \"name\": \"get_weather\", \"arguments\": \"{\\\"city\\\":\\\"北京\\\"}\" }, \"extra_content\": { \"google\": { \"thought_signature\": \"EvQBCvEBAQw51seEezqzHHepPSYOlXMl...\" } } } > 注意：OpenAI SDK 的 pydantic 模型对 extra_content 这类非标准字段的序列化行为在不同版本间可能不一致。推荐从 response.model_dump() 的原始 dict 里提取该字段，而不是依赖 message.tool_calls 的结构化对象属性访问。"},{"title":"Function Calling","heading":"5.1.4 完整示例代码","url":"/userguide/features/function-calling#5-1-4-完整示例代码","text":"以下是一个跑通 Gemini 3 多轮工具调用的完整示例，重点关注 build_assistant_message_from_raw 辅助函数——它是保证 signature 不丢失的关键。 python import os from openai import OpenAI import json import copy client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ) tools = [ { \"type\": \"function\", \"function\": { \"name\": \"get_weather\", \"description\": \"获取指定城市的天气信息\", \"parameters\": { \"type\": \"object\", \"properties\": { \"city\": {\"type\": \"string\", \"description\": \"城市名称\"} }, \"required\": [\"city\"] } } } ] def execute_tool(name, args): \"\"\"模拟工具执行\"\"\" args = json.loads(args) if isinstance(args, str) else args if name == \"get_weather\": return json.dumps( {\"city\": args[\"city\"], \"temp\": \"28°C\", \"condition\": \"晴\"}, ensure_ascii=False ) return json.dumps({\"error\": \"unknown tool\"}) def build_assistant_message_from_raw(raw_response): \"\"\" 从原始响应 dict 构造 assistant message，保留 extra_content 中的 thought_signature。这是 Gemini 3 多轮工具调用的关键步骤。 \"\"\" raw_msg = raw_response[\"choices\"][0][\"message\"] assistant_msg = { \"role\": raw_msg.get(\"role\", \"assistant\"), \"content\": raw_msg.get(\"content\"), } if raw_msg.get(\"tool_calls\"): assistant_msg[\"tool_calls\"] = [] for tc in raw_msg[\"tool_calls\"]: new_tc = { \"id\": tc[\"id\"], \"type\": tc[\"type\"], \"function\": { \"name\": tc[\"function\"][\"name\"], \"arguments\": tc[\"function\"][\"arguments\"], }, } 关键：保留 extra_content（包含 google.thought_signature） if \"extra_content\" in tc: new_tc[\"extra_content\"] = copy.deepcopy(tc[\"extra_content\"]) assistant_msg[\"tool_calls\"].append(new_tc) return assistant_msg messages = [{\"role\": \"user\", \"content\": \"北京今天天气怎么样？\"}] MAX_ROUNDS = 5 for round_num in range(1, MAX_ROUNDS + 1): response = client.chat.completions.create( model=\"gemini-3.1-pro-preview\", messages=messages, tools=tools, tool_choice=\"auto\" ) raw = response.model_dump() 使用辅助函数构造回传的 assistant message assistant_msg = build_assistant_message_from_raw(raw) messages.append(assistant_msg) raw_tool_calls = raw[\"choices\"][0][\"message\"].get(\"tool_calls\") if raw_tool_calls: for tc in raw_tool_calls: result = execute_tool(tc[\"function\"][\"name\"], tc[\"function\"][\"arguments\"]) messages.append({ \"role\": \"tool\", \"tool_call_id\": tc[\"id\"], \"content\": result }) else: print(f\"最终回复: {response.choices[0].message.content}\") break --- 相关链接 - 推理模型 (Reasoning) - API 参考：创建对话请求 - Google 官方文档：Thought Signatures"},{"title":"推理模型","heading":"1. 概述","url":"/userguide/features/reasoning#1-概述","text":"推理模型（如 deepseek-v4-pro, gpt-6-astra 等）通过结构化思维、逻辑演绎和思维链（Chain-of-Thought, CoT）来解决高度复杂的任务。这些模型在数学、编程、科学推理及复杂逻辑分析方面表现优异。"},{"title":"推理模型","heading":"核心特性","url":"/userguide/features/reasoning#核心特性","text":"- 结构化思维：模型在给出结论前会先进行内部逻辑拆解。 - 自我纠错：推理过程中能够识别并修正先前的逻辑偏差。 - 知识融合：多维度的知识关联，确保推理过程的严密性。"},{"title":"推理模型","heading":"2. 模型选择","url":"/userguide/features/reasoning#2-模型选择","text":"在 NoneLinear，推理模型可以直接调用：不做任何设置时，模型按下表中的默认思考强度工作。您只需在模型广场中选择对应的模型即可。我们的模型命名已经清晰标注了“思考型”与“非思考型”的区别，您可以根据需求直接调用。"},{"title":"推理模型","heading":"3. 思考强度（reasoning effort）","url":"/userguide/features/reasoning#3-思考强度（reasoning-effort）","text":"部分模型支持设置思考强度：强度越高，模型思考越充分，通常回答质量更好，但耗时更长、消耗的 token 更多。在客户端中设置推理强度，或为不同任务选择模型时，可参考下表。档位说明 - minimal 、 low 、 medium 、 high 、 xhigh 、 max ：思考强度依次增加。 - none 、 no_think ：不进行思考。 - 默认：不设置思考强度时模型使用的档位；“—”表示暂无默认档位信息。不同模型支持的档位不同，请只使用表中列出的值。传入模型不支持的档位时，该设置会被忽略，模型按默认档位处理。系列模型 ID 支持的思考强度默认 --- --- --- --- OpenAI GPT gpt-5.6-luna-pro gpt-5.6-luna gpt-5.6-terra-pro gpt-5.6-terra gpt-5.6-sol-pro gpt-5.6-sol gpt-6-luna gpt-6-sol none 、 low 、 medium 、 high 、 xhigh 、 max medium gpt-6-astra low 、 medium 、 high 、 xhigh 、 max — gpt-6.1-sol low 、 medium 、 high 、 xhigh 、 max medium Anthropic Claude claude-opus-4.7 claude-opus-4.8 claude-fable-5 claude-sonnet-5 claude-opus-5 claude-sonnet-5.5 low 、 medium 、 high 、 xhigh 、 max high claude-opus-5.5 claude-haiku-5.5 low 、 medium 、 high 、 xhigh 、 max medium Google Gemini gemini-3.6-flash minimal 、 low 、 medium 、 high medium gemini-3.7-flash gemini-3.8-flash gemini-4-argon low 、 medium 、 high medium DeepSeek deepseek-v4-flash deepseek-v4-pro deepseek-v4-flash-vision-exp deepseek-v4.1-flash none 、 low 、 high 、 max high 豆包 Seed doubao-seed-2-1-pro-260628 doubao-seed-2-1-turbo-260628 doubao-seed-evolving doubao-seed-2-1-pro-260915 doubao-seed-2-1-lite-260915 none 、 minimal 、 low 、 medium 、 high 、 xhigh 、 max high 阿里 Qwen qwen3.8-max qwen3.8-flash low 、 medium 、 xhigh xhigh 智谱 GLM glm-5.3 glm-5.3-flash low 、 high 、 max max 月之暗面 Kimi kimi-k3 low 、 high 、 max max MiniMax MiniMax-M3.1-Flash low 、 medium 、 high 、 xhigh 、 max max xAI Grok grok-4.5 low 、 medium 、 high high grok-4.6 grok-4.7 low 、 medium 、 high 、 xhigh high 阶跃星辰 Step step-3.7-flash step-5-preview low 、 medium 、 high medium 腾讯混元 hy4-preview no_think 、 high high 小米 MiMo mimo-v2.5 mimo-v2.5-pro mimo-v2.6-pro mimo-v2.6-flash 仅支持开启 / 关闭思考，不支持设置强度 — 表中只列出当前主流模型，不含较早的模型版本。未列出的模型请以模型广场为准。"},{"title":"推理模型","heading":"4. 使用示例 (Python SDK)","url":"/userguide/features/reasoning#4-使用示例-python-sdk","text":"推理模型支持返回内部的思维链内容。您可以通过 reasoning_content 字段获取模型的“思考过程”。"},{"title":"推理模型","heading":"流式输出 (Streaming)","url":"/userguide/features/reasoning#流式输出-streaming","text":"示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python import os from openai import OpenAI client = OpenAI( api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ) response = client.chat.completions.create( model=\"DeepSeek-V3.2-Think\", messages=[{\"role\": \"user\", \"content\": \"证明勾股定理\"}], stream=True ) for chunk in response: if not chunk.choices: continue delta = chunk.choices[0].delta 获取思维链内容 reasoning_content = getattr(delta, \"reasoning_content\", None) if reasoning_content: print(reasoning_content, end=\"\", flush=True) 获取最终回答内容 if delta.content: print(delta.content, end=\"\", flush=True) --- 相关链接 - 语言模型 (LLM) - API 快速入门"},{"title":"文生图","heading":"","url":"/guides/images/text-to-image","text":"← 生图模型目录 · 接口与鉴权先按快速开始设置 NONELINEAR_API_KEY ；Python 需安装 openai 。每个代码块可独立使用，只发送一次生成请求。图片地址请替换为您自己的公网 HTTPS 图片链接。 Python SDK 的扩展参数放在 extra_body 中；cURL 把这些字段放在 JSON 顶层。示例中的模型 ID 和参数需成套使用，不要只替换模型而保留不适用的尺寸。用 aspect_ratio 控制比例：适用于 Nano Banana、FLUX、MiniMax 等，以 gemini-2.5-flash-image 为例。 bash cURL curl -sS --max-time 300 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"gemini-2.5-flash-image\", \"prompt\": \"A cinematic wide-angle photo of a futuristic city skyline at sunset, rich details, natural lighting\", \"response_format\": \"url\", \"aspect_ratio\": \"16:9\" }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.images.generate( model=\"gemini-2.5-flash-image\", prompt=\"A cinematic wide-angle photo of a futuristic city skyline at sunset, rich details, natural lighting\", response_format=\"url\", extra_body={\"aspect_ratio\": \"16:9\"}, ) for image in response.data or []: print(image.url or image.b64_json) 同时用 aspect_ratio 和 size 控制比例与清晰度：适用于 Nano Banana 2 / Pro、Kling、Vidu 等，以 gemini-3-pro-image-preview 为例。 bash cURL curl -sS --max-time 300 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"gemini-3-pro-image-preview\", \"prompt\": \"A high fidelity studio portrait of a glass perfume bottle on black acrylic, sharp reflections, commercial photography\", \"response_format\": \"url\", \"aspect_ratio\": \"4:3\", \"size\": \"2K\" }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.images.generate( model=\"gemini-3-pro-image-preview\", prompt=\"A high fidelity studio portrait of a glass perfume bottle on black acrylic, sharp reflections, commercial photography\", response_format=\"url\", size=\"2K\", extra_body={\"aspect_ratio\": \"4:3\"}, ) for image in response.data or []: print(image.url or image.b64_json) 使用 gemini-3.1-flash-image-preview （Nano Banana 2）时写法相同，例如 \"aspect_ratio\": \"1:1\" 、 \"size\": \"1K\" 。只用 size 控制尺寸：适用于 Seedream、Qwen、Wan、GPT Image 等，以 doubao-seedream-4-0-250828 为例。 bash cURL curl -sS --max-time 300 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"doubao-seedream-4-0-250828\", \"prompt\": \"星际穿越，黑洞里冲出一辆支离破碎的复古列车，电影大片质感，强烈视觉冲击力，深蓝色调，光线追踪，景深，夸张的广角透视\", \"response_format\": \"url\", \"size\": \"2K\", \"watermark\": false }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.images.generate( model=\"doubao-seedream-4-0-250828\", prompt=\"星际穿越，黑洞里冲出一辆支离破碎的复古列车，电影大片质感，强烈视觉冲击力，深蓝色调，光线追踪，景深，夸张的广角透视\", response_format=\"url\", size=\"2K\", extra_body={\"watermark\": False}, ) for image in response.data or []: print(image.url or image.b64_json) Seedream 5.0 Pro ：可额外指定输出格式和提示词优化模式。追求速度时，把 mode 改为 fast 、 output_format 改为 jpeg 。 bash cURL curl -sS --max-time 600 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"doubao-seedream-5-0-pro-260628\", \"prompt\": \"一只透明玻璃茶壶放在深色胡桃木桌面上，壶中有琥珀色茶汤，左侧柔和晨光，背景为简洁的现代厨房，1:1构图，真实产品摄影，细节清晰\", \"response_format\": \"url\", \"size\": \"1K\", \"output_format\": \"png\", \"watermark\": false, \"optimize_prompt_options\": { \"mode\": \"standard\" } }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.with_options(timeout=600).images.generate( model=\"doubao-seedream-5-0-pro-260628\", prompt=\"一只透明玻璃茶壶放在深色胡桃木桌面上，壶中有琥珀色茶汤，左侧柔和晨光，背景为简洁的现代厨房，1:1构图，真实产品摄影，细节清晰\", response_format=\"url\", size=\"1K\", extra_body={ \"output_format\": \"png\", \"watermark\": False, \"optimize_prompt_options\": {\"mode\": \"standard\"}, }, ) for image in response.data or []: print(image.url or image.b64_json)"},{"title":"文生图","heading":"检查结果","url":"/guides/images/text-to-image#检查结果","text":"以 data 中存在 url 或 b64_json 判断出图，并及时保存。未出图、参考图不可访问或超时，见生图排障。"},{"title":"图片编辑","heading":"","url":"/guides/images/image-edit","text":"← 生图模型目录 · 接口与鉴权先按快速开始设置 NONELINEAR_API_KEY ；Python 需安装 openai 。每个代码块可独立使用，只发送一次生成请求。图片地址请替换为您自己的公网 HTTPS 图片链接。 Python SDK 的扩展参数放在 extra_body 中；cURL 把这些字段放在 JSON 顶层。示例中的模型 ID 和参数需成套使用，不要只替换模型而保留不适用的尺寸。通过 image 传入一张参考图，再用 prompt 描述要修改的内容，可用于增删元素、替换背景、转换风格等。支持编辑的模型见模型参数中的“支持任务”列。 image 必须是公网可直接访问的 HTTPS 图片地址，本地图片请先参考本地图片怎么传。以 gpt-image-2 为例 bash cURL curl -sS --max-time 300 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"gpt-image-2\", \"prompt\": \"将图片背景替换为简洁的浅灰色摄影棚背景，保留主体不变\", \"response_format\": \"url\", \"size\": \"1024x1024\", \"n\": 1, \"image\": [ \"https://imagen-nonelinear-2025.tos-cn-beijing.volces.com/others/gen-1780570031-PVCF2SwnzQCRFdkiSkON-0.png\" ] }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.images.generate( model=\"gpt-image-2\", prompt=\"将图片背景替换为简洁的浅灰色摄影棚背景，保留主体不变\", response_format=\"url\", size=\"1024x1024\", n=1, extra_body={ \"image\": [ \"https://imagen-nonelinear-2025.tos-cn-beijing.volces.com/others/gen-1780570031-PVCF2SwnzQCRFdkiSkON-0.png\" ] }, ) for image in response.data or []: print(image.url or image.b64_json) 以 doubao-seedream-5-0-pro-260628 为例 bash cURL curl -sS --max-time 600 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"doubao-seedream-5-0-pro-260628\", \"prompt\": \"保持柯基犬、草地、树林背景和原始构图不变，只给柯基犬脖子上增加一条清晰可见的红色格纹围巾，写实摄影风格\", \"response_format\": \"url\", \"size\": \"2K\", \"output_format\": \"png\", \"watermark\": false, \"image\": \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimage.png\" }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.with_options(timeout=600).images.generate( model=\"doubao-seedream-5-0-pro-260628\", prompt=\"保持柯基犬、草地、树林背景和原始构图不变，只给柯基犬脖子上增加一条清晰可见的红色格纹围巾，写实摄影风格\", response_format=\"url\", size=\"2K\", extra_body={ \"image\": \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimage.png\", \"output_format\": \"png\", \"watermark\": False, }, ) for image in response.data or []: print(image.url or image.b64_json) Seedream 5.0 Pro 还可以在 prompt 中用 x y 指定编辑位置，例如： text 保持图1的树林、草地、光照和柯基犬不变，只在图1 710 820 所指的柯基犬头顶增加一顶小巧的金色皇冠，皇冠自然贴合头部，写实摄影风格以 Qwen-Image-Edit 为例：该模型不需要传尺寸参数。 bash cURL curl -sS --max-time 300 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"Qwen-Image-Edit\", \"prompt\": \"生成狗狗趴在草地上的近景画面\", \"response_format\": \"url\", \"image\": \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimage.png\" }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.images.generate( model=\"Qwen-Image-Edit\", prompt=\"生成狗狗趴在草地上的近景画面\", response_format=\"url\", extra_body={ \"image\": \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimage.png\" }, ) for image in response.data or []: print(image.url or image.b64_json)"},{"title":"图片编辑","heading":"检查结果","url":"/guides/images/image-edit#检查结果","text":"以 data 中存在 url 或 b64_json 判断出图，并及时保存。未出图、参考图不可访问或超时，见生图排障。"},{"title":"多图融合","heading":"","url":"/guides/images/multi-image","text":"← 生图模型目录 · 接口与鉴权先按快速开始设置 NONELINEAR_API_KEY ；Python 需安装 openai 。每个代码块可独立使用，只发送一次生成请求。图片地址请替换为您自己的公网 HTTPS 图片链接。 Python SDK 的扩展参数放在 extra_body 中；cURL 把这些字段放在 JSON 顶层。示例中的模型 ID 和参数需成套使用，不要只替换模型而保留不适用的尺寸。在 image 中传入多张参考图，并在 prompt 中用“图1”“图2”指代，模型会融合它们的人物、服装、风格等特征，例如把服装与模特图合成为穿搭图。可传入的张数见模型参数中的“参考图”列。以 doubao-seedream-4-0-250828 为例 bash cURL curl -sS --max-time 300 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"doubao-seedream-4-0-250828\", \"prompt\": \"将图1的服装换为图2的服装\", \"response_format\": \"url\", \"size\": \"2K\", \"watermark\": false, \"sequential_image_generation\": \"disabled\", \"image\": [ \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_1.png\", \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_2.png\" ] }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.images.generate( model=\"doubao-seedream-4-0-250828\", prompt=\"将图1的服装换为图2的服装\", response_format=\"url\", size=\"2K\", extra_body={ \"image\": [ \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_1.png\", \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_2.png\", ], \"watermark\": False, \"sequential_image_generation\": \"disabled\", }, ) for image in response.data or []: print(image.url or image.b64_json) 使用 Seedream 4.0 / 4.5 / 5.0 Lite 做多图融合时，请将 sequential_image_generation 设为 disabled 或不传，否则可能返回多张组图。以 qwen-image-edit-max 为例 bash cURL curl -sS --max-time 300 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"qwen-image-edit-max\", \"prompt\": \"将图1的服装换为图2的服装\", \"response_format\": \"url\", \"image\": [ \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_1.png\", \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_2.png\" ] }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.images.generate( model=\"qwen-image-edit-max\", prompt=\"将图1的服装换为图2的服装\", response_format=\"url\", extra_body={ \"image\": [ \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_1.png\", \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_2.png\", ] }, ) for image in response.data or []: print(image.url or image.b64_json) Seedream 5.0 Pro 还可以在 prompt 中用 x1 y1 x2 y2 指定每张图的局部区域，例如： text 以图1 150 0 900 999 区域内的黑发人物为主体，保持图1的人物面部、发型、姿势和室内背景不变；将图2 80 150 850 850 区域内的黑色短款夹克和蓝色牛仔裤穿到图1人物身上，服装材质参考图2，写实摄影"},{"title":"多图融合","heading":"检查结果","url":"/guides/images/multi-image#检查结果","text":"以 data 中存在 url 或 b64_json 判断出图，并及时保存。未出图、参考图不可访问或超时，见生图排障。"},{"title":"透明背景","heading":"","url":"/guides/images/transparent","text":"← 生图模型目录 · 接口与鉴权先按快速开始设置 NONELINEAR_API_KEY ；Python 需安装 openai 。每个代码块可独立使用，只发送一次生成请求。图片地址请替换为您自己的公网 HTTPS 图片链接。 Python SDK 的扩展参数放在 extra_body 中；cURL 把这些字段放在 JSON 顶层。示例中的模型 ID 和参数需成套使用，不要只替换模型而保留不适用的尺寸。仅 gpt-image-2 支持。为了稳定得到真正透明的 PNG，以下三项需要同时满足： 1. 请求参数设置 \"background\": \"transparent\" ； 2. 设置 \"output_format\": \"png\" ，只有 PNG 能保存透明通道； 3. prompt 中明确写出“透明背景”，并排除白色背景、场景、地面和投影。只在 prompt 中要求透明，可能得到白色实心背景；只设置参数，也可能出现部分背景未完全透明。 bash cURL curl -sS --max-time 300 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"gpt-image-2\", \"prompt\": \"一只正面站立的小狗贴纸插画，主体完整，边缘清晰，透明背景，不要白色或纯色背景，不要场景、地面和投影\", \"response_format\": \"url\", \"output_format\": \"png\", \"background\": \"transparent\", \"size\": \"1024x1024\", \"quality\": \"high\", \"n\": 1 }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.images.generate( model=\"gpt-image-2\", prompt=\"一只正面站立的小狗贴纸插画，主体完整，边缘清晰，透明背景，不要白色或纯色背景，不要场景、地面和投影\", response_format=\"url\", size=\"1024x1024\", n=1, extra_body={ \"output_format\": \"png\", \"background\": \"transparent\", \"quality\": \"high\", }, ) for image in response.data or []: print(image.url or image.b64_json)"},{"title":"透明背景","heading":"检查结果","url":"/guides/images/transparent#检查结果","text":"以 data 中存在 url 或 b64_json 判断出图，并及时保存。未出图、参考图不可访问或超时，见生图排障。"},{"title":"组图","heading":"","url":"/guides/images/sequential","text":"← 生图模型目录 · 接口与鉴权先按快速开始设置 NONELINEAR_API_KEY ；Python 需安装 openai 。每个代码块可独立使用，只发送一次生成请求。图片地址请替换为您自己的公网 HTTPS 图片链接。 Python SDK 的扩展参数放在 extra_body 中；cURL 把这些字段放在 JSON 顶层。示例中的模型 ID 和参数需成套使用，不要只替换模型而保留不适用的尺寸。一次请求生成一组内容关联的图片，如漫画分镜、四季变化、品牌视觉套图。适用于 Seedream 4.0 / 4.5 / 5.0 Lite， Seedream 5.0 Pro 不支持。 - sequential_image_generation 设为 auto 开启组图； - sequential_image_generation_options.max_images 设置最多返回的张数，实际张数可能更少； - 返回多张图片，请遍历 data 中的全部元素。文生组图 bash cURL curl -sS --max-time 600 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"doubao-seedream-4-0-250828\", \"prompt\": \"生成一组共4张连贯插画，核心为同一庭院一角的四季变迁，以统一风格展现四季独特色彩、元素与氛围\", \"response_format\": \"url\", \"size\": \"2K\", \"watermark\": false, \"sequential_image_generation\": \"auto\", \"sequential_image_generation_options\": { \"max_images\": 4 } }' python Python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=300, max_retries=0, ) response = client.with_options(timeout=600).images.generate( model=\"doubao-seedream-4-0-250828\", prompt=\"生成一组共4张连贯插画，核心为同一庭院一角的四季变迁，以统一风格展现四季独特色彩、元素与氛围\", response_format=\"url\", size=\"2K\", extra_body={ \"watermark\": False, \"sequential_image_generation\": \"auto\", \"sequential_image_generation_options\": {\"max_images\": 4}, }, ) for image in response.data or []: print(image.url or image.b64_json) 参考图生组图：在上面的请求中加入 image 即可，单张或多张均可。 bash 单张参考图 curl -sS --max-time 600 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"doubao-seedream-4-0-250828\", \"prompt\": \"参考这个LOGO，做一套户外运动品牌视觉设计，品牌名称为GREEN，包括包装袋、帽子、纸盒、手环、挂绳等。绿色视觉主色调，趣味、简约现代风格\", \"response_format\": \"url\", \"size\": \"2K\", \"watermark\": true, \"sequential_image_generation\": \"auto\", \"sequential_image_generation_options\": { \"max_images\": 5 }, \"image\": \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimages.png\" }' bash 多张参考图 curl -sS --max-time 600 \\ https://api.nonelinear.com.cn/v1/images/generations \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"model\": \"doubao-seedream-4-0-250828\", \"prompt\": \"生成3张女孩和奶牛玩偶在游乐园开心地坐过山车的图片，涵盖早晨、中午、晚上\", \"response_format\": \"url\", \"size\": \"2K\", \"watermark\": false, \"sequential_image_generation\": \"auto\", \"sequential_image_generation_options\": { \"max_images\": 3 }, \"image\": [ \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_1.png\", \"https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_2.png\" ] }'"},{"title":"组图","heading":"检查结果","url":"/guides/images/sequential#检查结果","text":"以 data 中存在 url 或 b64_json 判断出图，并及时保存。未出图、参考图不可访问或超时，见生图排障。"},{"title":"LangChain","heading":"1. 简介","url":"/scenes/frameworks/langchain#1-简介","text":"LangChain 现已全面支持通过 langchain-openai 包接入所有兼容 OpenAI 规范的平台。NoneLinear 提供的对话模型与文本嵌入（Embedding）模型均可无缝集成。"},{"title":"LangChain","heading":"2. 前提条件","url":"/scenes/frameworks/langchain#2-前提条件","text":"- 已开通 NoneLinear 服务并获得 API Key，请参考获取 API Key。 - 建议将 API Key 配置到环境变量中。"},{"title":"LangChain","heading":"3. Chat Model","url":"/scenes/frameworks/langchain#3-chat-model","text":"使用前需要安装以下依赖： bash pip install langchain_openai 通过 ChatOpenAI 类，您可以调用 NoneLinear 平台上的模型列表中的模型。"},{"title":"LangChain","heading":"配置示例","url":"/scenes/frameworks/langchain#配置示例","text":"示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python import os from langchain_openai import ChatOpenAI 初始化对话模型 llm = ChatOpenAI( model=\"claude-sonnet-4.5\", 或其他支持的模型 ID api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ) 使用 invoke 接口发送请求 messages = [ {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"}, {\"role\": \"user\", \"content\": \"如何通过 LangChain 快速构建 AI 应用？\"}] response = llm.invoke(messages) print(response.content) 工具调用等进阶技巧请前往 LangChain 官方的 ChatOpenAI。完整的 API参考文档请前往 LangChain 官方的 ChatOpenAI API Reference。 --- 更多模型 ID 和详细参数请参考 NoneLinear 模型列表。"},{"title":"LangGraph","heading":"1. LangGraph 进阶概览","url":"/scenes/frameworks/langgraph#1-langgraph-进阶概览","text":"LangGraph 的核心优势在于构建具备“循环”能力的 Agent。相比基础的 StateGraph ，进阶模式通常结合 ToolNode 和 MessagesState 来实现自动化工具调用。"},{"title":"LangGraph","heading":"2. Agent 代码示例","url":"/scenes/frameworks/langgraph#2-agent-代码示例","text":"以下示例演示了如何创建一个可以查询实时天气并进行智能对话的 Agent。使用前先安装依赖： bash pip install -U langgraph langchain-openai 示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python import os from typing import Literal from langchain_core.tools import tool from langchain_openai import ChatOpenAI from langgraph.graph import END, StateGraph, START, MessagesState from langgraph.prebuilt import ToolNode 1. 定义工具函数（模拟外部查询） @tool def search_weather(query: str): \"\"\"查询指定城市的天气信息\"\"\" if \"北京\" in query.lower(): return \"阴天有雾，气温 25 度\" return \"天气晴朗，气温 35 度以上，注意防暑\" tools = [search_weather] tool_node = ToolNode(tools) 2. 初始化适配 NoneLinear 的模型并绑定工具 llm = ChatOpenAI( model=\"DeepSeek-V3.2\", api_key=os.environ[\"NONELINEAR_API_KEY\"], base_url=\"https://api.nonelinear.com.cn/v1\" ).bind_tools(tools) 3. 定义逻辑节点 def call_model(state: MessagesState): \"\"\"节点：调用 LLM 获取响应\"\"\" response = llm.invoke(state[\"messages\"]) return {\"messages\": [response]} def should_continue(state: MessagesState) -> Literal[\"tools\", END]: \"\"\"路由函数：判断是否需要继续调用工具\"\"\" last_message = state[\"messages\"][-1] if last_message.tool_calls: return \"tools\" return END 4. 构建图结构 workflow = StateGraph(MessagesState) workflow.add_node(\"agent\", call_model) workflow.add_node(\"tools\", tool_node) workflow.add_edge(START, \"agent\") workflow.add_conditional_edges(\"agent\", should_continue) workflow.add_edge(\"tools\", \"agent\") 工具执行完回到 Agent 5. 编译运行 app = workflow.compile() inputs = {\"messages\": [(\"user\", \"帮我查一下北京的天气，然后给出穿衣建议。\")]} for chunk in app.stream(inputs, stream_mode=\"values\"): chunk[\"messages\"][-1].pretty_print()"},{"title":"LangGraph","heading":"3. 开发规范与模式","url":"/scenes/frameworks/langgraph#3-开发规范与模式","text":"- 消息流管理：使用 MessagesState 可以自动处理消息历史的追加。 - 条件边 (Conditional Edges) ：通过 should_continue 逻辑，Agent 可以根据模型返回的 tool_calls 自主决定是继续执行工具还是结束任务。 - NoneLinear 兼容性：由于 NoneLinear 完美兼容 OpenAI 工具调用接口，您可以无缝使用 bind_tools 。 --- 进阶开发者可以结合 MemorySaver 实现具备持久化记忆的 Agent 对话系统。"},{"title":"Agno (原 Phidata)","heading":"1. Agno 简介","url":"/scenes/frameworks/agno#1-agno-简介","text":"Agno（原 Phidata）为 NoneLinear 这类 OpenAI 兼容平台提供了 OpenAILike 模型类，可以直接接入。适配重点：通过 OpenAILike 类注入 base_url 和 api_key 。"},{"title":"Agno (原 Phidata)","heading":"2. 配置示例","url":"/scenes/frameworks/agno#2-配置示例","text":"示例从环境变量 NONELINEAR_API_KEY 读取 API Key。运行前先在终端设置：macOS / Linux 执行 export NONELINEAR_API_KEY=\"你的 API Key\" ，Windows PowerShell 执行 $env:NONELINEAR_API_KEY=\"你的 API Key\" 。 python from os import getenv from agno.agent import Agent from agno.models.openai.like import OpenAILike 创建智能体 agent = Agent( model=OpenAILike( id=\"gpt-5.2\", NoneLinear 平台提供的具体模型 ID api_key=getenv(\"NONELINEAR_API_KEY\"), base_url=\"https://api.nonelinear.com.cn/v1\" ) ) 运行并打印响应 agent.print_response(\"如何通过 agno 快速构建 AI 应用？\")"},{"title":"Agno (原 Phidata)","heading":"3. 关键参数说明","url":"/scenes/frameworks/agno#3-关键参数说明","text":"参照 Agno 官方文档， OpenAILike 类支持以下核心参数：参数类型描述 :--- :--- :--- id str 模型标识符，例如 gpt-5.2 或 DeepSeek-V3.2 api_key str 您的 NoneLinear API Key base_url str 设置为 https://api.nonelinear.com.cn/v1 name str (可选) 自定义模型名称，默认为 \"OpenAILike\""},{"title":"Agno (原 Phidata)","heading":"4. 注意事项","url":"/scenes/frameworks/agno#4-注意事项","text":"- 安装/升级： OpenAILike 依赖 openai 包，请一并安装： pip install -U agno openai - 模型支持：您可以在 NoneLinear 模型列表中查看所有可用的模型 ID。"},{"title":"帮助中心","heading":"","url":"/faqs/overview","text":"输入关键词或报错原文搜索文档，例如 429、缓存、reasoning_content"},{"title":"帮助中心","heading":"按问题查找","url":"/faqs/overview#按问题查找","text":"点击问题直达答案，也可按 ⌘K / Ctrl+K 搜索文档。刚开始用 → 获取 API Key → 用代码发出第一个请求 → 模型 ID 怎么填 → 接口地址和协议怎么选在工具里使用 → Claude Code 怎么接 → Codex App / CLI 怎么接 → EasyClaw 输出到 8192 就停止 → RikkaHub 看不到 Claude 思考内容调用出错 → Claude 返回 422，模型 ID 错误 → DeepSeek 提示回传 reasoning_content → 返回 429，被限流了 → 内容安全拦截来自哪里 → 是否有过滤更宽松的 GPT 渠道费用与缓存 → 怎么计费，在哪里查看消耗 → 设置了限额，为什么仍然超额 → Claude 缓存不命中，费用变高 → 如何申请发票接口与参数 → 能否使用 Gemini 原生接口 → thinking、temperature 等参数怎么传 → 如何开启流式输出 → 上下文长度和输出上限的区别图片与视频 → GPT Image 能否生成 2K / 4K 图片 → Gemini 视频或音轨理解失败 → 参考图读取失败或没有生效 → 请求成功，却没有返回图片"},{"title":"帮助中心","heading":"其他常见问题","url":"/faqs/overview#其他常见问题","text":"遇到的问题查看说明 --- --- 401 / API Key 无效凭证与鉴权排查 402 / 余额不足账户余额与费用说明 403 / 权限不足权限与 IP 白名单请求成功但没有正文空输出排查图片请求超时先确认任务状态修改配置后仍请求旧模型客户端配置排查网络连接失败网络与代理排查"},{"title":"帮助中心","heading":"按主题浏览","url":"/faqs/overview#按主题浏览","text":"账号与 API Key · 地址与连通性 · 客户端与工具 · 图片与多模态 · 缓存与上下文 · 数据与计费 · 开具发票 · 联系与排查材料"},{"title":"帮助中心","heading":"视频任务卡住了？","url":"/faqs/overview#视频任务卡住了？","text":"先保留任务 ID，按视频接口查询现有任务。创建任务成功与生成完成是不同状态，不要因暂时没有下载地址就再次创建任务。"},{"title":"帮助中心","heading":"还需要帮助？","url":"/faqs/overview#还需要帮助？","text":"微信扫码联系客服获取接入帮助，办理发票开具或余额退款。在手机上阅读时，可保存二维码图片，再通过微信识别。保存客服二维码技术问题可先准备排查材料，开票前请查看申请说明。"},{"title":"错误处理","heading":"先看哪一部分","url":"/faqs/error-handling#先看哪一部分","text":"同时保留 HTTP 状态码和响应正文。业务错误 code 不一定等于 HTTP 状态；不同协议返回的错误结构也可能不同。下面是现有接口文档中的业务错误示例： json { \"code\": 20012, \"message\": \"Model does not exist. Please check it carefully.\", \"data\": null } 遇到这类信息，先核对模型 ID及目标接口。不要把 20012 当成 HTTP 状态码。"},{"title":"错误处理","heading":"常见 HTTP 状态","url":"/faqs/error-handling#常见-http-状态","text":"状态先检查下一步原样自动重试？ --- --- --- --- 400 / 422 JSON 格式、必填字段、模型参数按对应接口示例缩小请求先修正参数 401 Key 是否完整、当前进程是否读到、鉴权协议重新核对凭证来源，避免打印完整 Key 先修正凭证 402 账户余额及请求正文查看余额先处理额度 403 IP 白名单、管理 Key 权限、模型权限账号与 Key 先处理权限 404 地址、重复的 /v1 、模型或资源 ID 地址与连通性先修正路径 413 请求体积、Base64 附件、历史消息减小附件与上下文；URL 输入需接口支持先缩小请求 429 响应中的限制原因、并发和调用频次限流排查确认原因后退避 500 / 502 / 503 平台或上游异常、是否已有任务 ID 保留错误和时间；暂时性故障可有限重试按任务类型决定 504 / 客户端超时客户端、代理、服务端各自的等待时间先确认请求是否已被接受不立即重复生成业务正文中的 code: 300 表示现有文档记录的安全问题，不是 HTTP 300 跳转。遇到安全拒绝先核对请求内容与错误说明，无法定位时提交脱敏材料。"},{"title":"错误处理","heading":"Claude 返回 422，提示 model_id 错误、不支持或已下线，怎么办？","url":"/faqs/error-handling#claude-返回-422，提示-model_id-错误、不支持或已下线，怎么办？","text":"先从 NoneLinear 模型列表复制完整 Model ID，核对版本号、小数点、连字符及所用接口。平台的模型 ID 可能与上游命名不同。例如此前的配置更正中， claude-opus-5-5 应改为平台列表中的 claude-opus-5.5 。当前可用型号仍以平台列表为准。名称正确但仍报错时，保留请求 ID、模型 ID、调用时间和报错原文，联系技术支持核查模型状态与账号权限。这条处理适用于响应明确提示模型 ID 问题的情况；其他 422 错误应按响应中的参数说明排查。"},{"title":"错误处理","heading":"DeepSeek 提示 reasoning_content 必须传回，怎么处理？","url":"/faqs/error-handling#deepseek-提示-reasoning_content-必须传回，怎么处理？","text":"在 DeepSeek 思考模式下，携带 tools 的 Chat Completions 请求需要回传历史 assistant 消息中的 reasoning_content 。如果客户端或代码丢弃了这个字段，可能收到： text The reasoning_content in the thinking mode must be passed back to the API. - 代码调用：构建后续 messages 时，保留 assistant 消息中返回的 reasoning_content 、工具调用及对应工具结果，不要用空值替换已有思考内容。 - 第三方客户端：检查其 DeepSeek 思考模式与工具调用兼容性，使用支持该字段回传的版本。 - 切换协议：只有模型、平台和客户端均支持 Anthropic Messages 时，才考虑切换协议并新建会话；请求体也必须使用 Messages 格式。不携带 tools 的普通多轮请求不要求回传历史 reasoning_content ，不要把这项要求套用于所有对话。协议依据：DeepSeek 官方思考模式说明。"},{"title":"错误处理","heading":"GPT 返回内容安全拦截，是平台还是上游返回的？","url":"/faqs/error-handling#gpt-返回内容安全拦截，是平台还是上游返回的？","text":"如果响应明确提示上游模型的内容安全限制，该限制由上游服务执行，NoneLinear 无法直接解除。先读完整错误类型和说明，区分内容安全拦截、鉴权失败和额度限制；不能仅凭 HTTP 状态码或“请求失败”判断拦截来源。正常业务内容被误拦截，或无法确认来源时，请提供请求 ID、模型 ID、调用时间和脱敏报错，联系技术支持核查。"},{"title":"错误处理","heading":"有过滤政策更宽松的 GPT 备用渠道吗？","url":"/faqs/error-handling#有过滤政策更宽松的-gpt-备用渠道吗？","text":"目前不提供过滤政策更宽松的 GPT 备用渠道。正常业务内容被误拦截时，可补充清晰的任务说明，并保留请求 ID 和脱敏报错，联系技术支持核查。"},{"title":"错误处理","heading":"重试前先判断","url":"/faqs/error-handling#重试前先判断","text":"- 参数、凭证或权限错误：修正后再发送，等待通常不会改变结果。 - 限流与临时服务异常：控制并发，设置退避、最大次数和总超时；响应有等待提示时参考该提示。 - 生图或已创建的视频任务：超时不代表任务没有执行，重复提交可能产生新的生成与费用。先查看已有用量或任务状态。 - SDK 自带重试与业务外层重试可能叠加，配置前先核对各层。"},{"title":"错误处理","heading":"为什么消耗了 token 却没有正文？","url":"/faqs/error-handling#为什么消耗了-token-却没有正文？","text":"推理模型可能先消耗输出预算进行思考。预算过小、生成截断或仅返回工具调用时，不能仅凭空的 message.content 判断请求失败。 1. 查看响应 finish_reason 、工具调用字段与 usage 。 2. 如果因长度限制结束，核对模型允许的输出预算和推理设置。 3. 如果返回工具调用，按函数调用流程执行并回传结果。 4. 仍无法定位时，保留响应 ID 和脱敏响应，见排查材料。现有 GPT-5.4 系列示例也需要避免过低的 max_tokens ；提高预算前先结合用量和结束原因判断，重新请求可能产生额外费用。"},{"title":"错误处理","heading":"继续排查","url":"/faqs/error-handling#继续排查","text":"网络连接问题 · 图片没有返回 · 客户端配置问题 · 提交排查信息"},{"title":"限流与 429","heading":"先确认是哪一种限制","url":"/faqs/rate-limits#先确认是哪一种限制","text":"429 Too Many Requests 通常与请求频率或并发有关。请结合完整响应确认；账户余额不足通常返回 402，不要只看到调用失败就增加重试。核对项操作 --- --- 当前请求与响应记录时间、模型 ID、HTTP 状态和错误原文。 Key 的消费限额在 API Key 管理检查日/月限额及有效期。账户余额在账户余额核对可用额度。并发和调用频率检查多个任务、成员或后台工具是否同时请求。等待提示响应若包含 Retry-After 等提示，按提示等待；未返回时不要假定固定秒数。"},{"title":"限流与 429","heading":"如何处理","url":"/faqs/rate-limits#如何处理","text":"1. 暂停批量重试，降低同时进行的请求数。 2. 将突发任务排队，逐步发送。 3. 对确认可重试的请求使用指数退避，并设置最大重试次数和总等待时间。 4. 恢复后逐步增加负载，观察相同模型的错误是否再次出现。额度、限流作用范围和上限以账号实际配置及错误返回为准。需要提高吞吐时，准备模型、并发、请求规模及报错时间，通过支持渠道确认。"},{"title":"限流与 429","heading":"图片和视频不要盲目重试","url":"/faqs/rate-limits#图片和视频不要盲目重试","text":"有任务 ID 时先查询现有任务；同步生成超时先核对用量和处理状态。限流排查方法不能替代对生成是否已执行的确认。通用错误处理 · 生图超时 · 视频任务"},{"title":"报错与网络排查","heading":"返回 401 Unauthorized / Incorrect API key 如何排查？","url":"/faqs/troubleshooting#返回-401-unauthorized-/-incorrect-api-key-如何排查？","text":"1. 字符检查：检查复制的 API Key 前后是否包含多余空格、换行符或引号； 2. 变量验证：确认当前终端环境变量已正确加载该 Key； 3. 端点匹配：确认请求 Base URL 格式正确（OpenAI 兼容端点为 /v1 ，Anthropic 兼容端点为 /anthropic ），避免因路径错误导致鉴权失败。"},{"title":"报错与网络排查","heading":"返回 403 Forbidden 是什么原因？","url":"/faqs/troubleshooting#返回-403-forbidden-是什么原因？","text":"1. IP 白名单拦截：检查该 Key 是否绑定了 IP 白名单，且当前发起调用的公网出口 IP 不在允许列表中； 2. 管理接口权限限制：创建 Key、修改预算、查询全局余额等管理接口仅允许默认 API Key 调用，使用普通业务 Key 调用将返回 403； 3. 账户模型权限限制：确认当前账号或子 Key 是否具备该模型的调用权限。"},{"title":"报错与网络排查","heading":"出现 413 Request Entity Too Large 怎么处理？","url":"/faqs/troubleshooting#出现-413-request-entity-too-large-怎么处理？","text":"单次请求 Payload 体积超出网关限制。常见于对话历史超长、或将多张高分辨率图片转为 Base64 编码直接嵌入请求体中。 - 解决方案：压缩附件体积；清理多轮历史会话；对于支持 URL 传参的接口，优先使用公网可访问的 HTTPS 图片链接替代 Base64。详细规范请参考多模态输入与图像生成。"},{"title":"报错与网络排查","heading":"返回 429 Too Many Requests 如何排查？","url":"/faqs/troubleshooting#返回-429-too-many-requests-如何排查？","text":"1. 核对错误详情：速率超限通常返回 429，账户余额不足通常返回 402。请先查看响应正文明确原因； 2. 定位限制维度：确认是触发了 Key 的日/月费用上限、账号并发保护（同时在途请求数），还是瞬时请求频次（RPS/RPM/TPM）超限； 3. 实施退避重试：客户端代码中实现指数退避重试（Exponential Backoff），并设置最大重试次数与超时限制。"},{"title":"报错与网络排查","heading":"所有请求均报 ConnectionRefused 或 ProxyError？","url":"/faqs/troubleshooting#所有请求均报-connectionrefused-或-proxyerror？","text":"1. 排查代理配置：检查终端是否残留已失效的代理环境变量（如 VPN 客户端退出后残留的 HTTP_PROXY / HTTPS_PROXY ）； 2. 测试网络连通性：通过 nslookup 检查域名解析，测试到目标服务器 443 端口的 TCP/TLS 连通性； 3. 网络环境对照：切换至移动热点或备用网络进行对照，排除企业内网网关或本地防火墙拦截。"},{"title":"报错与网络排查","heading":"校园网或企业统一出口偶发连接超时，可能是什么原因？","url":"/faqs/troubleshooting#校园网或企业统一出口偶发连接超时，可能是什么原因？","text":"部分校园网与企业内网统一出口存在 NAT 端口耗尽、跨境链路拥堵或安全网关对长连接的主动重置行为。排查建议： - 使用手机热点做网络对照测试； - 将请求 Base URL 切换为国内加速入口 https://api.nonelinear.com.cn/v1 进行连通性比对。"},{"title":"报错与网络排查","heading":"为什么开启 thinking 或调整推理等级后报错？","url":"/faqs/troubleshooting#为什么开启-thinking-或调整推理等级后报错？","text":"不同大模型对思考参数的字段定义有所不同（如 budget_tokens 、 reasoning_effort ）。若当前客户端版本未兼容目标模型的思考参数，建议在客户端中关闭 thinking 模式，或使用官方推荐的标准参数调用。各模型支持的思考强度档位见推理模型：思考强度。"},{"title":"报错与网络排查","heading":"长对话进行到一半开始反复报错，怎样恢复？","url":"/faqs/troubleshooting#长对话进行到一半开始反复报错，怎样恢复？","text":"长对话中累积的未闭环工具调用或庞大历史极易引发异常。推荐将前期对话提炼为简洁的阶段性任务摘要，然后在客户端中开启全新 Session 继续执行，避免将已损坏的超长历史重复带入后续请求。"},{"title":"报错与网络排查","heading":"向技术支持团队提交排查工单时，需要提供哪些关键信息？","url":"/faqs/troubleshooting#向技术支持团队提交排查工单时，需要提供哪些关键信息？","text":"为确保快速准确定位，请一次性提供以下已脱敏信息： - 故障发生时间与时区； - 使用的客户端与版本（如 Codex CLI、Claude Code、Python SDK）； - 请求的完整 Model ID 与接口路径； - 请求 ID ：响应体中的 id 或调用明细中的请求 ID（若连接未建立请注明“无请求 ID”）； - API Key 脱敏标识； - HTTP 状态码与脱敏后的完整报错文本。"},{"title":"生图与多模态","heading":"GPT Image 可以生成 2K、4K 图片吗？","url":"/faqs/images#gpt-image-可以生成-2k、4k-图片吗？","text":"gpt-image-2 的尺寸说明包含 2K、4K 输出规格， size 需填写具体像素尺寸，而不是 2k 或 4k 。例如 2048x2048 为 2K 方图， 3840x2160 为 4K 横图， 2160x3840 为 4K 竖图。完整尺寸范围与限制统一查看GPT Image 模型参数。这里说的是生成图片的输出分辨率。输入参考图的规格另按图生图要求处理；其他 GPT Image 型号不能直接套用这些尺寸。"},{"title":"生图与多模态","heading":"Gemini 视频或音轨理解失败，先检查什么？","url":"/faqs/images#gemini-视频或音轨理解失败，先检查什么？","text":"先检查目标模型是否支持所需的视频或音频理解能力，再核对媒体文件的可访问性和请求字段。 1. 模型与接口：使用支持该能力的多模态对话接口。视频生成接口用于创建视频，不用于理解已有视频。 2. 媒体文件：通过 URL 传入时，使用服务端可直接读取的 HTTPS 直链，检查登录限制、防盗链、签名有效期及文件格式、大小。 3. 请求格式：按平台所用接口的多模态规范填写，不能直接套用 Google 原生 File API 的请求结构。视频画面可被读取，不代表音轨也一定参与处理；需要音轨理解时应单独确认支持范围。不要仅靠把 video_url 改成 image_url 判断视频和音轨都已正确传入。仍失败时，提供模型 ID、媒体格式、接口路径和脱敏报错，联系技术支持。请勿公开提交含客户隐私的原始媒体。"},{"title":"生图与多模态","heading":"生图模型可以使用 chat.completions 接口调用吗？","url":"/faqs/images#生图模型可以使用-chat-completions-接口调用吗？","text":"不能。文生图与参考图生成必须调用专用的图像生成端点： text POST https://api.nonelinear.com.cn/v1/images/generations 详细接口参数与格式规范请参考 NoneLinear 图像生成文档。"},{"title":"生图与多模态","heading":"图生图（参考图）返回 500 或 404（Image unreachable）如何解决？","url":"/faqs/images#图生图（参考图）返回-500-或-404（image-unreachable）如何解决？","text":"该报错通常是由于模型服务端无法成功拉取参考图所致（本地浏览器能打开，并不代表云端推理节点能够直接下载）。请按以下关键点排查参考图 URL： 1. 公网免密可达：必须为公网可直接访问的链接，不能使用 localhost 、局域网内网地址（如 192.168. 、 10. ）或依赖特定登录态/Cookie 的私有页面； 2. 标准 HTTPS 协议：建议使用公网对象存储（如 OSS / S3 / CDN）的标准 HTTPS 链接，避免携带非标端口号（如 :8080 、 :5000 ）或触发防盗链拦截； 3. 预签名链接有效期：若使用云存储的临时签名链接（Pre-signed URL），请设置充足的有效时长，避免因上游排队生图导致拉取时签名已过期； 4. 直链有效性核对：确保 URL 直接指向真实的图片文件（JPG/PNG/WEBP 等），而非 HTML 登录页、中转页或错误重定向页面。"},{"title":"生图与多模态","heading":"生图请求耗时较长（1~3 分钟），如何避免前端页面超时卡死？","url":"/faqs/images#生图请求耗时较长（1-3-分钟），如何避免前端页面超时卡死？","text":"NoneLinear 生图接口同步返回。网页应用可在自己的业务服务端采用 “异步任务队列” 架构： 1. 前端提交请求至业务服务端，服务端生成 Task ID 并即时返回前端； 2. 服务端工作进程异步调用生图 API； 3. 前端通过轮询 Task ID 状态或通过 WebSocket 接收完成通知； 4. 业务侧 SDK、反向代理与 Worker 的 timeout 应设置为 300 秒以上，并在确认上一请求状态前关闭自动盲目重试，防止重复生成扣费。"},{"title":"生图与多模态","heading":"平台返回的图片 URL 可以长期保存吗？","url":"/faqs/images#平台返回的图片-url-可以长期保存吗？","text":"不能。平台返回的 URL 是临时地址，不应作为长期存储。有效期需按具体模型或返回链接核对，不能统一假定为 24 小时。生产系统必须在接收到生成成功响应后，第一时间将图片下载并转存至企业自建的对象存储（OSS / S3 / CDN）中。"},{"title":"生图与多模态","heading":"在终端（如 Claude Code CLI）中如何为多模态模型提供图片输入？","url":"/faqs/images#在终端（如-claude-code-cli）中如何为多模态模型提供图片输入？","text":"在支持读取本地多模态附件的 CLI 工具中，可按工具规范传入本地文件的相对或绝对路径，由客户端本地读取并转换为多模态消息上传。直接调用 API 时，需按接口规范传入 Base64 编码或公网 HTTPS 图片链接，参考多模态输入文档。"},{"title":"生图与多模态","heading":"请求成功，但图片没有返回怎么办？","url":"/faqs/images#请求成功，但图片没有返回怎么办？","text":"HTTP 200 只说明收到成功状态，需进一步检查生成结果。 1. 遍历 data ，检查每项是否存在 url 或 b64_json ，不要只假定固定返回一种格式。 2. data 为空时查看 text 等错误说明。Gemini 的 IMAGE_RECITATION 、 NO_IMAGE 示例见模型说明。 3. 核对模型是否支持当前任务，以及尺寸、比例和参考图是否匹配，见生图模型目录。 4. 安全拒绝或参数错误先修改输入；不要对所有空结果无限重试。成功标志是取得有效图片数据并能保存。仍无结果时，提供请求时间、模型、响应 ID 和脱敏错误，见排查材料。"},{"title":"生图与多模态","heading":"为什么参考图没生效或尺寸不对？","url":"/faqs/images#为什么参考图没生效或尺寸不对？","text":"确认 image 是可访问的 HTTPS 直链数组，Python SDK 的扩展字段写在 extra_body 中。不同模型使用不同的 size 或 aspect_ratio ，请对照系列页，不要把另一个模型的参数直接套用。"},{"title":"账号与 API Key","heading":"企业多人或多台设备使用时，应该如何分配和管理 API Key？","url":"/faqs/account#企业多人或多台设备使用时，应该如何分配和管理-api-key？","text":"推荐在 API Key 管理中为团队成员及不同业务环境创建独立的 API Key： 1. 妥善保管默认 Key ：每个账号包含一个默认 API Key。部分敏感管理接口（如创建 Key、修改预算、查询账户余额与全局费用）仅允许默认 Key 调用，使用其他 Key 调用将返回 403 Forbidden 。建议由管理员单独保管，不分发给日常业务使用，亦严禁写入前端代码。 2. 按场景创建业务 Key ：为每位成员、开发环境、测试环境或独立 Agent 创建专属 API Key 并清晰命名，便于精细化追踪用量与定位异常。 3. 配置消费限额：在控制台中为每个 Key 设置合理的总额上限、日/月消费限额及有效期限。 4. 及时轮换与删除：一旦发生密钥泄露，应第一时间在业务端替换为新 Key，并在控制台中彻底删除泄露的 Key，阻断非授权调用。详细接口权限说明请参考 API Key 管理文档。"},{"title":"账号与 API Key","heading":"充值卡或体验金兑换码如何激活？","url":"/faqs/account#充值卡或体验金兑换码如何激活？","text":"1. 登录平台账户余额页面； 2. 在「兑换码充值」区域输入兑换码并点击确认； 3. 激活成功后额度即时到账，可在页面核对最新余额，并在充值记录中查看流水。若提示成功但余额未更新，请保留操作时间与脱敏截图联系技术支持核查（请勿在公开群聊中发送兑换码原文）。"},{"title":"账号与 API Key","heading":"平台是否支持 SSO 登录？如何实现企业统一身份认证？","url":"/faqs/account#平台是否支持-sso-登录？如何实现企业统一身份认证？","text":"- 控制台目前原生支持 GitHub 快捷登录与手机验证码登录。 - 针对有企业统一身份认证（如 Okta、企业微信、SAML/LDAP SSO）及多团队统一管控需求的企业客户，可直接联系商务对接。"},{"title":"账号与 API Key","heading":"IP 白名单有什么作用？适合哪些场景？","url":"/faqs/account#ip-白名单有什么作用？适合哪些场景？","text":"IP 白名单用于限制仅允许指定的公网出口 IP 调用特定 API Key，防止密钥泄露后被异地滥用。 - 推荐场景：具有固定公网出口 IP 的企业生产服务器、测试机房及固定办公网。 - 填写规范：必须填写请求实际到达平台时所使用的公网出口 IP，而非本机局域网私网地址（如 192.168. 、 10. ）。若使用代理或 VPN，需核对其实际出口 IP。 - 管理说明：清空内容并保存即可取消对应 Key 的白名单限制；批量保存会完整覆盖所选分组及独立 Key 的原有白名单，不是追加规则。处于动态出口 IP（如部分移动热点、家庭宽带）的环境请谨慎开启，避免因出口变化触发 403 Forbidden ；具体错误文本以接口响应为准。操作入口见 API Key 管理，详细规则参考 IP 白名单文档。"},{"title":"账号与 API Key","heading":"能否按模型限制独立 API Key，而不仅仅限制费用？","url":"/faqs/account#能否按模型限制独立-api-key，而不仅仅限制费用？","text":"当前 API Key 管理支持配置总额、日/月消费限额、模型输入/输出价格档位限额及有效期控制。其中，可以通过模型输入/输出价格档位限额来限制某个API Key的模型使用。"},{"title":"账号与 API Key","heading":"如何防止 API Key 意外泄露导致账单激增？","url":"/faqs/account#如何防止-api-key-意外泄露导致账单激增？","text":"请遵循以下安全开发规范： 1. 安全存储密钥：服务端优先使用环境变量（如 os.environ.get(\"NONELINEAR_API_KEY\") ）或 KMS 密钥管理服务注入；桌面端与 CLI 工具保存在本地受保护的配置文件中；严禁将密钥提交至代码仓库、嵌入前端代码或在截图中公开。 2. 设置消费限额：为业务 Key 配置合理的日/月限额，并预留请求完成后的结算余量。限额不会在生成途中截断请求，详见为什么仍可能超额。 3. 测试使用临时 Key ：测试新工具、社区开源 Agent 或实验性插件时，单独创建小额度临时 Key。 4. 定期审计用量：定期在控制台导出「调用明细」CSV，监控异常调用的 IP、时间戳及模型分布。"},{"title":"API 接入与连通性","heading":"平台支持哪些 API 协议与 Base URL 端点？","url":"/faqs/connection#平台支持哪些-api-协议与-base-url-端点？","text":"平台提供双协议端点支持，请按客户端类型匹配填写： - OpenAI 兼容端点（适用于 OpenAI Python/Node SDK、Codex、LangChain 等）： text Base URL: https://api.nonelinear.com.cn/v1 - Anthropic 兼容端点（适用于 Claude Code、Anthropic SDK 等）： text Base URL: https://api.nonelinear.com.cn/anthropic > 排坑说明：请勿将 OpenAI 端点地址填入只接受 Anthropic Messages 协议的字段中，避免因协议解析失败返回 404 或 400 。"},{"title":"API 接入与连通性","heading":"NoneLinear 提供 Gemini 原生接口吗？","url":"/faqs/connection#nonelinear-提供-gemini-原生接口吗？","text":"目前不提供 Gemini 原生端点。Gemini 对话模型请通过 OpenAI 兼容接口调用： text Base URL: https://api.nonelinear.com.cn/v1 可使用 OpenAI SDK 或向 /chat/completions 发送请求。请求体采用 OpenAI 兼容格式；Google 原生请求结构不能整份直接用于该端点。具体字段以对应模型和平台接口说明为准，见多模态输入。"},{"title":"API 接入与连通性","heading":"文档没列出 thinking、temperature 等参数，还能传吗？","url":"/faqs/connection#文档没列出-thinking、temperature-等参数，还能传吗？","text":"可以传入所选模型和接入协议支持的参数；文档未逐项列出，不代表都不支持，也不代表任意原生字段都能直接使用。 - 模型限制：参数取值和组合以对应模型规范为准。部分模型开启思考后，采样参数会被忽略或受到限制。 - 协议格式：Chat Completions、Responses 和 Messages 的参数名称、层级各有规定，不能混用。 - SDK 扩展字段：SDK 未直接声明的参数，通过其提供的扩展请求体机制传入，并检查实际发送的 JSON。不确定某个参数是否生效时，从最小请求开始逐个添加，再核对响应；思考能力的用法见推理模型。"},{"title":"API 接入与连通性","heading":"模型名称（Model ID）该如何确认？","url":"/faqs/connection#模型名称（model-id）该如何确认？","text":"请以模型列表中展示的完整 Model ID 为准（严格区分大小写及后缀，例如 gpt-5.6-luna 、 claude-haiku-4.5 、 deepseek-v4-flash 等），并确认该模型支持目标接口。请勿根据第三方官网名称自行猜测路由名。"},{"title":"API 接入与连通性","heading":"如何用 Python / cURL 快速验证文本模型连通性？","url":"/faqs/connection#如何用-python-/-curl-快速验证文本模型连通性？","text":"推荐选择当前账号可用的轻量模型，发送单次短文本测试。运行准备：Python 环境需安装 openai （ python -m pip install openai ）。Python 与 cURL 均从当前进程环境读取 NONELINEAR_API_KEY ，请先在同一终端通过安全方式设置并导出有效密钥。仅把密钥写入 .env 不会自动加载到下面的示例中。 Python SDK 验证示例： python import os from openai import OpenAI client = OpenAI( base_url=\"https://api.nonelinear.com.cn/v1\", api_key=os.environ[\"NONELINEAR_API_KEY\"], timeout=120.0, max_retries=0, ) res = client.chat.completions.create( model=\"deepseek-v4-flash\", 请替换为控制台模型列表中账号可用的 Model ID messages=[{\"role\": \"user\", \"content\": \"请只回复：连接正常\"}], ) print(\"响应 ID:\", res.id) if not res.choices or not (res.choices[0].message.content or \"\").strip(): raise RuntimeError(\"已收到响应但没有可见正文，请结合响应 ID、结束原因及用量排查\") print(\"结束原因:\", res.choices[0].finish_reason) print(\"返回内容:\", res.choices[0].message.content) print(\"用量明细:\", res.usage) cURL 命令行验证： bash : \"${NONELINEAR_API_KEY:?请先设置并导出 NONELINEAR_API_KEY}\" curl --silent --show-error --connect-timeout 15 --max-time 120 \\ --write-out '\\nHTTP 状态码: %{http_code}\\n' \\ https://api.nonelinear.com.cn/v1/chat/completions \\ -H \"Content-Type: application/json\" \\ -H \"Authorization: Bearer $NONELINEAR_API_KEY\" \\ -d '{ \"model\": \"deepseek-v4-flash\", \"messages\": [{\"role\": \"user\", \"content\": \"请只回复：连接正常\"}] }' 成功时应收到 HTTP 200，且 choices[0].message.content 包含可见正文；仅收到 HTTP 响应不能证明文本生成成功。示例不设置过低的输出 Token 上限，Python 关闭自动重试，cURL 未启用重试；实际费用可查看响应 usage 中的费用字段。"},{"title":"API 接入与连通性","heading":"API Base URL 在浏览器中打不开，是否代表服务故障？","url":"/faqs/connection#api-base-url-在浏览器中打不开，是否代表服务故障？","text":"不是。Base URL 是用于客户端拼接具体接口的基础地址。大模型文本生成接口为 HTTP POST 方法，直接在浏览器中通过 GET 方式访问根路径或 /v1 返回 404 属于正常 HTTP 表现。验证服务可用性应通过带有有效 Authorization 请求头的标准 SDK 或 cURL 命令发起测试。"},{"title":"API 接入与连通性","heading":"进行连通性测试时，为什么强烈建议使用轻量低价模型？","url":"/faqs/connection#进行连通性测试时，为什么强烈建议使用轻量低价模型？","text":"连通测试的核心目标是验证网络路由、API Key 鉴权及客户端参数解析。选用价格低、响应快的轻量模型（如 deepseek-v4-flash ）并配合简短输入，能以极低成本快速确认链路状态。 - 注意：若测试包含思考机制的推理模型，请勿在请求中设置过小的 max_tokens （如 max_tokens=10 ），避免因思考过程占满 Token 导致输出正文被截断。"},{"title":"客户端与开发工具","heading":"EasyClaw 的回答为什么到 8192 就停止？","url":"/faqs/clients#easyclaw-的回答为什么到-8192-就停止？","text":"先检查 EasyClaw 的最大输出 Token 设置；设为 8192 时，生成长度会受这个值限制。 1. 查看当前模型或会话配置中的最大输出 Token。 2. 在模型支持的输出上限内调大该值，保存后重新发起请求。 3. 若仍被截断，核对实际请求中的输出限制和响应结束原因，确认设置是否生效。 8192 Token 不等于 8192 个汉字。调大客户端设置也不能突破模型本身的输出上限，见上下文与最大输出长度的区别。"},{"title":"客户端与开发工具","heading":"RikkaHub 调用 Claude，为什么看不到思考内容？","url":"/faqs/clients#rikkahub-调用-claude，为什么看不到思考内容？","text":"先区分“接口没有返回思考内容”和“客户端没有显示”。是否可见取决于模型与思考参数，以及 RikkaHub 对返回字段的解析和展示支持。 1. 模型配置：确认模型支持所需思考能力，并按该模型和接入协议启用。 2. 客户端设置：检查当前版本是否提供思考内容的显示选项，以及该选项的状态。 3. 响应对比：在相同模型、协议和参数下对比直接 API 请求。若响应含思考内容而 RikkaHub 未显示，再排查客户端解析和展示。仍无法定位时，提供 RikkaHub 版本、模型 ID、协议和脱敏配置，联系技术支持。接入步骤见RikkaHub 配置。"},{"title":"客户端与开发工具","heading":"Claude Code 环境变量如何标准配置？为什么后台明细会出现 Haiku 调用记录？","url":"/faqs/clients#claude-code-环境变量如何标准配置？为什么后台明细会出现-haiku-调用记录？","text":"详细配置请参考 Claude Code 接入文档。后台 Haiku 记录说明：这是 Claude Code 官方客户端的原生机制。客户端在后台执行会话标题生成、轻量意图识别或上下文摘要等辅助任务时，会自动调用 ANTHROPIC_DEFAULT_HAIKU_MODEL 槽位对应的模型。"},{"title":"客户端与开发工具","heading":"Claude Code 出现缓存命中率偏低，应该如何优化？","url":"/faqs/clients#claude-code-出现缓存命中率偏低，应该如何优化？","text":"缓存突然失效或费用上升时，先看缓存有效期与前缀排查，再检查下面的客户端设置。 1. 关闭动态 Attribution 头部：避免客户端在请求中动态插入追踪元数据导致 Prompt Cache 前缀失效。在 ~/.claude/settings.json （Windows 为 C:\\Users\\ \\.claude\\settings.json ）已有的 env 对象中加入： json \"CLAUDE_CODE_ATTRIBUTION_HEADER\": \"0\" 详见 Claude Code 接入文档：关闭 Claude Code 动态 attribution header。 2. 保持前置指令稳定性：避免在长会话前置 System Prompt 中频繁插入动态变化的时间戳或随机标识。"},{"title":"客户端与开发工具","heading":"修改了配置文件，为什么客户端仍然请求旧地址或旧模型？","url":"/faqs/clients#修改了配置文件，为什么客户端仍然请求旧地址或旧模型？","text":"1. 排查环境变量优先级：多数 CLI 工具中终端环境变量优先级高于本地配置文件。修改文件后请重新打开全新终端窗口。 2. 彻底退出后台进程：桌面应用或部分 CLI 工具可能存在常驻后台进程，修改配置后需完全关闭进程后再重新启动。 3. 以控制台调用明细为准：客户端界面标题有时存在缓存回显，实际请求目标请登录控制台调用明细核对。"},{"title":"客户端与开发工具","heading":"为什么通过 API 接入 Codex / Chatbox 后无法使用官方的联网搜索？","url":"/faqs/clients#为什么通过-api-接入-codex-/-chatbox-后无法使用官方的联网搜索？","text":"NoneLinear API 专注于提供纯粹的高性能模型推理服务。官方订阅版客户端的联网搜索属于其应用层自建的检索服务。若需在 API 接入场景下使用联网能力，推荐在支持的客户端中配置独立的 Search MCP（Model Context Protocol）插件或联网搜索工具。"},{"title":"客户端与开发工具","heading":"Codex 桌面版响应缓慢或卡住，终端版可以作为替代吗？","url":"/faqs/clients#codex-桌面版响应缓慢或卡住，终端版可以作为替代吗？","text":"可以。Codex 桌面版在加载复杂扩展、全库代码扫描或大目录索引时本地开销较大，使用终端 CLI 版接入相同配置能够提供更纯粹稳定的执行体验。 - 优化建议：检查项目根目录，将 .git 、 node_modules 、 target 、 dist 、构建产物及大型日志目录加入忽略规则，避免扫描过多非必要上下文。"},{"title":"客户端与开发工具","heading":"Codex 提示 MCP client ... failed to start，会影响普通模型对话吗？","url":"/faqs/clients#codex-提示-mcp-client-failed-to-start，会影响普通模型对话吗？","text":"若报错的 MCP 工具并非当前任务所必需，普通文本对话通常不受影响。排查步骤： 1. 在终端执行 codex mcp list 及 codex doctor --json 查看客户端诊断详情； 2. 暂时禁用或修复异常的 MCP 服务，无需将其误判为 API Key 或模型通道故障。"},{"title":"客户端与开发工具","heading":"没有主动使用插件，为什么后台仍出现额外调用或费用？","url":"/faqs/clients#没有主动使用插件，为什么后台仍出现额外调用或费用？","text":"部分开发工具在启动扩展、后台通知程序或 Agent 辅助任务时，会在本地静默发起轻量模型调用。排查方法： 1. 在控制台导出「调用明细」CSV 查看异常调用的精确时间戳与模型 ID； 2. 对照客户端配置文件中的 plugins 、 marketplaces 与 mcp_servers ，关闭闲置或未经验证的第三方扩展。"},{"title":"缓存与上下文","heading":"Claude 缓存为什么突然不命中，费用也变高了？","url":"/faqs/cache#claude-缓存为什么突然不命中，费用也变高了？","text":"先检查缓存有效期和请求前缀。Claude 默认缓存有效期为 5 分钟，命中时会刷新；过期或前缀变化后，相关内容可能需要重新写入，费用通常高于缓存读取。 1. 核对间隔：检查两次请求是否超过所配置的缓存有效期。 2. 比较前缀：检查系统提示词、工具定义和历史消息。压缩、回退或修改历史会改变前缀，影响对应部分的缓存命中。 3. 查看用量：对比前后请求的缓存读取量、写入量和实际费用，区分缓存变化与输入、输出长度增长。模型、通道和客户端均支持时，可考虑 1 小时缓存。其写入单价更高，应结合请求间隔和命中率评估总成本，不代表开启后一定更省钱。 Claude Code 的客户端设置见缓存与费用配置；同时发起相同请求仍未命中时，继续看下方的并发缓存排查。机制参考：Claude 官方缓存说明。平台费用以模型价格和调用明细为准。"},{"title":"缓存与上下文","heading":"为什么内容完全相同的并发请求没有命中 Prompt Cache？","url":"/faqs/cache#为什么内容完全相同的并发请求没有命中-prompt-cache？","text":"核心原因是 Prompt Cache 遵循“先写入、后读取（Write-then-Read）”的机制。当多条完全相同的请求在同一瞬间高并发同时到达时： - 由于首个请求的缓存尚未完成计算与写入，此时到达的并发请求均会被判定为冷缓存（Cache Miss），从而各自执行全额输入的完整计算； - 优化建议：在执行批量或高并发任务前，先发送 1 次单请求完成缓存预热（Warm-up），待其返回后，再观察后续请求的缓存命中指标。是否命中仍受模型支持、前缀长度、缓存有效期和实际路由等条件影响，预热不能保证每次命中。排查常规 Prompt Cache 未命中的其他常见原因： 1. 前缀动态污染：System Prompt 或上下文开头动态拼接了时间戳、随机 UUID 或动态会话 ID，破坏了从首字开始的严格前缀匹配（Prefix Matching）； 2. 未达 Token 门槛：模型对缓存有最小 Token 阈值要求（通常需达到 1024 或 2048 Tokens 以上），短文本不会触发缓存； 3. 缓存 TTL 超时：两次调用间隔超过了模型的缓存保留周期； 4. 指标核对：真实命中情况以控制台调用明细记录的 cached_tokens 指标为准。"},{"title":"缓存与上下文","heading":"模型自称是其他版本，能否据此判断发生了模型降级？","url":"/faqs/cache#模型自称是其他版本，能否据此判断发生了模型降级？","text":"不能。大语言模型的“自我介绍”仅由其预训练语料和提示词决定，并不具备实时感知底层物理硬件与 API 路由的能力。真实调用的模型版本以NoneLinear 控制台调用明细中的 Model ID 记录为依据。"},{"title":"缓存与上下文","heading":"使用 Python 脚本每次独立调用，为什么多轮内容没有命中 Prompt Cache？","url":"/faqs/cache#使用-python-脚本每次独立调用，为什么多轮内容没有命中-prompt-cache？","text":"独立 Python 请求只要满足前缀一致性即可命中缓存，无需依赖持久连接。若未命中，请重点检查每次请求是否保持了完全相同的 System Prompt 和前置历史顺序。业务层多轮交互需保证 Payload 前缀稳定。"},{"title":"缓存与上下文","heading":"频繁切换模型会对 Prompt Cache 有什么影响？","url":"/faqs/cache#频繁切换模型会对-prompt-cache-有什么影响？","text":"不同大模型之间无法共享底层 Prompt Cache 缓存池。频繁在不同模型间来回切换会导致每个模型均需重新执行缓存预热。建议按任务阶段（如架构规划、常规编码）固定使用对应模型。"},{"title":"缓存与上下文","heading":"模型的“上下文上限（Context Window）”与“单次最大输出长度（Max Output Tokens）”是一回事吗？","url":"/faqs/cache#模型的“上下文上限（context-window）”与“单次最大输出长度（max-output-tokens）”是一回事吗？","text":"不是。 - 上下文上限：指单次请求中「系统提示词 + 历史输入 + 工具消息 + 本次模型输出」的总 Token 上限（如 200K / 1M）； - 最大输出长度：指模型单次推理能够生成的最大 Token 数量（如 8K / 64K）。在客户端配置中，切勿将单次输出上限配置过小，以免导致长文本生成或深度思考过程被意外截断。"},{"title":"数据与计费","heading":"设置了消费限额，为什么仍然会超额？","url":"/faqs/billing#设置了消费限额，为什么仍然会超额？","text":"限额在请求发起时校验，费用在请求完成后结算。已通过校验的请求会继续执行，不会因为生成途中达到限额而被截断；结算费用超过剩余额度时，就可能出现超额。 - 控制单次消耗：减少不必要的输入，设置合适的最大输出 Token。 - 限制模型单价：为 API Key 设置输入、输出价格档位，减少误用高单价模型。 - 预留结算余量：结合单次请求消耗和并发情况，把 Key 限额设在业务预算以内，并定期核对调用明细。限额不能代替密钥保护。怀疑 Key 泄露时，应及时更换并删除泄露的 Key，见账号与 API Key。"},{"title":"数据与计费","heading":"平台会持久化保存完整的对话正文吗？","url":"/faqs/billing#平台会持久化保存完整的对话正文吗？","text":"控制台调用明细仅展示用于计费审计与对账的元数据（包括请求时间、API Key 标识、Model ID、Token 消耗等），平台不持久化存储客户的具体业务对话正文。"},{"title":"数据与计费","heading":"平台是按量计费还是套餐制？如何查询消耗？","url":"/faqs/billing#平台是按量计费还是套餐制？如何查询消耗？","text":"平台采用透明的按量计费（Pay-as-you-go）模式，具体单价以模型列表与价格为准。 - 账单核对：管理员可随时在费用统计查看全局消耗，在账户余额查看实时余额，并在调用明细中按请求 ID 核对单次调用明细并支持按 Key 导出 CSV 对账单。"},{"title":"开具发票","heading":"","url":"/faqs/invoice","text":"微信扫码联系客服获取接入帮助，办理发票开具或余额退款。在手机上阅读时，可保存二维码图片，再通过微信识别。保存客服二维码"},{"title":"开具发票","heading":"开票主体信息","url":"/faqs/invoice#开票主体信息","text":"NoneLinear 平台的开票主体为：广州非线智能科技有限公司。"},{"title":"开具发票","heading":"什么时候申请","url":"/faqs/invoice#什么时候申请","text":"- 用户消费后可随时申请开票。 - 建议在每月月初对上一个自然月的消费进行统一申请。"},{"title":"开具发票","heading":"开票金额","url":"/faqs/invoice#开票金额","text":"- 开票金额以实际已消费金额为准。 - 充值但未消费的金额、赠送金额、活动奖励金等不可开具发票。"},{"title":"开具发票","heading":"发票类型","url":"/faqs/invoice#发票类型","text":"- 增值税电子普通发票：适用于个人或大部分企业报销。 - 增值税专用发票：适用于一般纳税人企业抵扣。"},{"title":"开具发票","heading":"申请前准备什么？","url":"/faqs/invoice#申请前准备什么？","text":"先在费用统计核对拟开票期间的实际消费，准备发票抬头、适用的纳税人识别号、发票类型、消费期间、金额和接收邮箱。通过本页微信二维码联系客服，提交申请材料并核对开票主体、金额与处理进度。具体处理时限请向客服确认。请勿在申请材料中发送 API Key 或验证码。一般故障排查材料见联系与支持。"},{"title":"开具发票","heading":"需要退款？","url":"/faqs/invoice#需要退款？","text":"通过上方微信二维码联系客服，按客服指引提交退款申请。申请时提供账号与拟退款信息，请勿发送 API Key 或验证码。"},{"title":"联系技术支持","heading":"","url":"/faqs/support","text":"微信扫码联系客服获取接入帮助，办理发票开具或余额退款。在手机上阅读时，可保存二维码图片，再通过微信识别。保存客服二维码"},{"title":"联系技术支持","heading":"先选对应入口","url":"/faqs/support#先选对应入口","text":"通用报错、网络与代理、客户端配置、生图问题通常可以先自行定位。"},{"title":"联系技术支持","heading":"提交这些信息","url":"/faqs/support#提交这些信息","text":"text 发生时间与时区：客户端名称、版本和操作系统：接口路径与完整模型 ID： HTTP 状态码：请求 ID / 视频任务 ID（没有则注明）：脱敏的错误原文：最小复现步骤：已尝试的排查：请求 ID 可从响应或调用明细查找。连接没有建立时，注明没有请求 ID，并补充代理、网络出口等相关环境信息。"},{"title":"联系技术支持","heading":"联系渠道","url":"/faqs/support#联系渠道","text":"通过本页微信二维码联系客服，发送上述排查信息。发票申请见开具发票。提交前移除完整 API Key、认证头、验证码和业务敏感内容。截图中的 Key 也需要遮挡；保留能帮助定位的模型名、时间与错误信息。"},{"title":"服务条款","heading":"1. 接受条款","url":"/legal/terms#1-接受条款","text":"欢迎使用 NoneLinear。使用本服务即表示您同意本条款。"},{"title":"服务条款","heading":"2. 服务说明","url":"/legal/terms#2-服务说明","text":"NoneLinear 提供大模型评估、诊断及网关服务。"},{"title":"隐私政策","heading":"1. 数据采集","url":"/legal/privacy#1-数据采集","text":"我们仅采集提供服务所必须的模型交互数据。"},{"title":"隐私政策","heading":"2. 数据安全","url":"/legal/privacy#2-数据安全","text":"我们采用行业标准的技术保障您的数据安全。"}]; const migrations = [{"from":"/api/images#openai-gpt-image-/-dall·e","to":"/models/images/gpt-image#openai-gpt-image-/-dall·e","title":"OpenAI GPT Image / DALL·E"},{"from":"/api/images#google-gemini（nano-banana）/-imagen","to":"/models/images/gemini#google-gemini（nano-banana）/-imagen","title":"Google Gemini（Nano Banana）/ Imagen"},{"from":"/api/images#gemini-未出图说明","to":"/models/images/gemini#gemini-未出图说明","title":"Gemini 未出图说明"},{"from":"/api/images#豆包-seedream","to":"/models/images/seedream#豆包-seedream","title":"豆包 Seedream"},{"from":"/api/images#阿里-qwen（通义千问）","to":"/models/images/qwen#阿里-qwen（通义千问）","title":"阿里 Qwen（通义千问）"},{"from":"/api/images#阿里-wan（通义万相）","to":"/models/images/wan#阿里-wan（通义万相）","title":"阿里 Wan（通义万相）"},{"from":"/api/images#快手-kling（可灵）/-kolors","to":"/models/images/kling#快手-kling（可灵）/-kolors","title":"快手 Kling（可灵）/ Kolors"},{"from":"/api/images#智谱-glm-/-cogview","to":"/models/images/glm#智谱-glm-/-cogview","title":"智谱 GLM / CogView"},{"from":"/api/images#minimax","to":"/models/images/minimax#minimax","title":"MiniMax"},{"from":"/api/images#flux","to":"/models/images/flux#flux","title":"FLUX"},{"from":"/api/images#riverflow","to":"/models/images/riverflow#riverflow","title":"Riverflow"},{"from":"/api/images#stability（stable-diffusion）","to":"/models/images/stability#stability（stable-diffusion）","title":"Stability（Stable Diffusion）"},{"from":"/api/images#阶跃星辰-step","to":"/models/images/step#阶跃星辰-step","title":"阶跃星辰 Step"},{"from":"/api/images#vidu","to":"/models/images/vidu#vidu","title":"Vidu"},{"from":"/api/images#luma（uni）","to":"/models/images/luma#luma（uni）","title":"Luma（Uni）"},{"from":"/api/images#reve","to":"/models/images/reve#reve","title":"Reve"},{"from":"/api/images#文生图","to":"/guides/images/text-to-image#文生图","title":"文生图"},{"from":"/api/images#图片编辑","to":"/guides/images/image-edit#图片编辑","title":"图片编辑"},{"from":"/api/images#多图融合","to":"/guides/images/multi-image#多图融合","title":"多图融合"},{"from":"/api/images#透明背景","to":"/guides/images/transparent#透明背景","title":"透明背景"},{"from":"/api/images#组图","to":"/guides/images/sequential#组图","title":"组图"},{"from":"/scenes/dev-tools/claude-code#一键安装与配置（推荐）","to":"/scenes/dev-tools/claude-code/quick-setup#一键安装与配置（推荐）","title":"一键安装与配置（推荐）"},{"from":"/scenes/dev-tools/claude-code#linux-一键安装与配置","to":"/scenes/dev-tools/claude-code/quick-setup#linux-一键安装与配置","title":"Linux 一键安装与配置"},{"from":"/scenes/dev-tools/claude-code#windows-一键安装与配置","to":"/scenes/dev-tools/claude-code/quick-setup#windows-一键安装与配置","title":"Windows 一键安装与配置"},{"from":"/scenes/dev-tools/claude-code#脚本写入的配置","to":"/scenes/dev-tools/claude-code/quick-setup#脚本写入的配置","title":"脚本写入的配置"},{"from":"/scenes/dev-tools/claude-code#手动配置","to":"/scenes/dev-tools/claude-code/manual#手动配置","title":"手动配置"},{"from":"/scenes/dev-tools/claude-code#安装-claude-code","to":"/scenes/dev-tools/claude-code/manual#安装-claude-code","title":"安装 Claude Code"},{"from":"/scenes/dev-tools/claude-code#macos-和-linux-手动配置","to":"/scenes/dev-tools/claude-code/manual#macos-和-linux-手动配置","title":"macOS 和 Linux 手动配置"},{"from":"/scenes/dev-tools/claude-code#windows-手动配置","to":"/scenes/dev-tools/claude-code/manual#windows-手动配置","title":"Windows 手动配置"},{"from":"/scenes/dev-tools/claude-code#通过-cc-switch-配置","to":"/scenes/dev-tools/claude-code/cc-switch#通过-cc-switch-配置","title":"通过 CC-Switch 配置"},{"from":"/scenes/dev-tools/claude-code#安装-cc-switch","to":"/scenes/dev-tools/claude-code/cc-switch#安装-cc-switch","title":"安装 CC-Switch"},{"from":"/scenes/dev-tools/claude-code#添加-nonelinear-供应商","to":"/scenes/dev-tools/claude-code/cc-switch#添加-nonelinear-供应商","title":"添加 NoneLinear 供应商"},{"from":"/scenes/dev-tools/claude-code#切换供应商","to":"/scenes/dev-tools/claude-code/cc-switch#切换供应商","title":"切换供应商"},{"from":"/scenes/dev-tools/claude-code#通过-claudecoderouter-配置","to":"/scenes/dev-tools/claude-code/router#通过-claudecoderouter-配置","title":"通过 ClaudeCodeRouter 配置"},{"from":"/scenes/dev-tools/claude-code#使用-ccr-配置界面","to":"/scenes/dev-tools/claude-code/router#使用-ccr-配置界面","title":"使用 CCR 配置界面"},{"from":"/scenes/dev-tools/claude-code#编辑-config-json","to":"/scenes/dev-tools/claude-code/router#编辑-config-json","title":"编辑 config.json"},{"from":"/scenes/dev-tools/claude-code#切换模型","to":"/scenes/dev-tools/claude-code/models#切换模型","title":"切换模型"},{"from":"/scenes/dev-tools/claude-code#费用与缓存注意事项","to":"/scenes/dev-tools/claude-code/costs#费用与缓存注意事项","title":"费用与缓存注意事项"},{"from":"/scenes/dev-tools/claude-code#为什么问一句“您好”，claude-opus-就花费几块钱","to":"/scenes/dev-tools/claude-code/costs#为什么问一句“您好”，claude-opus-就花费几块钱","title":"为什么问一句“您好”，Claude Opus 就花费几块钱"},{"from":"/scenes/dev-tools/claude-code#按任务类型选择模型","to":"/scenes/dev-tools/claude-code/costs#按任务类型选择模型","title":"按任务类型选择模型"},{"from":"/scenes/dev-tools/claude-code#claude-系列模型的缓存命中率问题","to":"/scenes/dev-tools/claude-code/costs#claude-系列模型的缓存命中率问题","title":"Claude 系列模型的缓存命中率问题"},{"from":"/scenes/dev-tools/claude-code#空槽位会使用-claude-code-默认模型名","to":"/scenes/dev-tools/claude-code/costs#空槽位会使用-claude-code-默认模型名","title":"空槽位会使用 Claude Code 默认模型名"},{"from":"/scenes/dev-tools/claude-code#闲置或结束后会出现-haiku-槽位的-recap-消耗","to":"/scenes/dev-tools/claude-code/costs#闲置或结束后会出现-haiku-槽位的-recap-消耗","title":"闲置或结束后会出现 Haiku 槽位的 recap 消耗"},{"from":"/scenes/dev-tools/claude-code#关闭-claude-code-动态-attribution-header","to":"/scenes/dev-tools/claude-code/costs#关闭-claude-code-动态-attribution-header","title":"关闭 Claude Code 动态 attribution header"},{"from":"/scenes/dev-tools/claude-code#在-ide-中使用","to":"/scenes/dev-tools/claude-code/ide#在-ide-中使用","title":"在 IDE 中使用"},{"from":"/scenes/dev-tools/claude-code#jetbrains-系列（intellij-idea、pycharm、webstorm-等）","to":"/scenes/dev-tools/claude-code/ide#jetbrains-系列（intellij-idea、pycharm、webstorm-等）","title":"JetBrains 系列（IntelliJ IDEA、PyCharm、WebStorm 等）"},{"from":"/scenes/dev-tools/claude-code#vs-code","to":"/scenes/dev-tools/claude-code/ide#vs-code","title":"VS Code"},{"from":"/scenes/dev-tools/codex-app#方式二：通过-cc-switch-配置","to":"/scenes/dev-tools/codex-app#方式三：通过-cc-switch-配置","title":"通过 cc-switch 配置"},{"from":"/scenes/dev-tools/codex-app#3-更换配置或恢复","to":"/scenes/dev-tools/codex-app#更换模型或撤销配置（可选）","title":"更换模型或撤销配置（可选）"},{"from":"/scenes/productivity-tools/workbuddy#配置步骤","to":"/scenes/productivity-tools/workbuddy#手动配置","title":"手动配置"},{"from":"/scenes/productivity-tools/workbuddy#可选模型","to":"/scenes/productivity-tools/workbuddy#2-选择模型，输入-api-key","title":"选择模型"},{"from":"/scenes/productivity-tools/workbuddy#选择模型并验证","to":"/scenes/productivity-tools/workbuddy#3-选择模型并验证","title":"选择模型并验证"},{"from":"/scenes/productivity-tools/workbuddy#3-等待配置成功","to":"/scenes/productivity-tools/workbuddy#3-选择模型并验证","title":"选择模型并验证"},{"from":"/scenes/productivity-tools/workbuddy#更换模型或-api-key","to":"/scenes/productivity-tools/workbuddy#更新或恢复（可选）","title":"更新或恢复（可选）"},{"from":"/scenes/productivity-tools/workbuddy#恢复原配置","to":"/scenes/productivity-tools/workbuddy#更新或恢复（可选）","title":"更新或恢复（可选）"},{"from":"/scenes/productivity-tools/workbuddy#提示-workbuddy-仍在运行怎么办？","to":"/scenes/productivity-tools/workbuddy#windows-配置遇到问题","title":"Windows 配置遇到问题"},{"from":"/scenes/productivity-tools/workbuddy#模型检查失败怎么办？","to":"/scenes/productivity-tools/workbuddy#windows-配置遇到问题","title":"Windows 配置遇到问题"},{"from":"/scenes/productivity-tools/workbuddy#提示-python-版本不满足要求怎么办？","to":"/scenes/productivity-tools/workbuddy#macos-配置遇到问题","title":"macOS 配置遇到问题"}]; const normalize = value => value.toLowerCase().normalize('NFKC'); const entries = data.map(entry => ({ ...entry, key: normalize(entry.title + ' ' + entry.heading + ' ' + entry.text) })); const dialog = document.createElement('dialog'); dialog.id = 'nl-search'; dialog.setAttribute('aria-label', '搜索非线智能-NoneLinear技术文档'); dialog.innerHTML = '

搜索文档

'; document.body.append(dialog); const input = dialog.querySelector('input'); const results = dialog.querySelector('ul'); const status = dialog.querySelector('[role="status"]'); let opener; function render() { const query = normalize(input.value.trim()); const words = query.split(/\s+/).filter(Boolean); const matches = words.length ? entries.filter(e => words.every(w => e.key.includes(w))) .map(e => ({ e, score: words.reduce((n, w) => n + (normalize(e.heading).includes(w) ? 8 : 0) + (normalize(e.title).includes(w) ? 5 : 0), 0) })) .sort((a, b) => b.score - a.score).map(x => x.e) : []; results.replaceChildren(); status.textContent = !query ? '输入关键词，直接跳转到相关章节。试试「429」或「Nano Banana」。' : matches.length ? `找到 ${matches.length} 个相关章节${matches.length > 30 ? '，显示前 30 个' : ''}` : '没有找到相关内容。试试模型 ID、错误码或更短的关键词。'; for (const entry of matches.slice(0, 30)) { const item = document.createElement('li'); const link = document.createElement('a'); link.href = entry.url; const title = document.createElement('strong'); title.textContent = entry.heading || entry.title; const path = document.createElement('small'); path.textContent = entry.heading ? entry.title : '文档概览'; const snippet = document.createElement('small'); const index = Math.max(0, normalize(entry.text).indexOf(words[0]) - 36); snippet.textContent = (index ? '…' : '') + entry.text.slice(index, index + 135) + (entry.text.length > index + 135 ? '…' : ''); link.append(title, path, snippet); link.addEventListener('click', () => dialog.close()); item.append(link); results.append(item); } } function open(trigger) { if (!dialog.open) { opener = trigger || document.activeElement; dialog.showModal(); } render(); input.focus(); input.select(); } dialog.querySelector('button').addEventListener('click', () => dialog.close()); dialog.addEventListener('close', () => { if (opener?.isConnected) opener.focus(); }); dialog.addEventListener('click', event => { if (event.target === dialog) { const r = dialog.getBoundingClientRect(); if (event.clientX < r.left || event.clientX > r.right || event.clientY < r.top || event.clientY > r.bottom) dialog.close(); } }); input.addEventListener('input', render); input.addEventListener('keydown', event => { if (event.key === 'ArrowDown') { event.preventDefault(); results.querySelector('a')?.focus(); } if (event.key === 'Enter') { event.preventDefault(); results.querySelector('a')?.click(); } }); window.addEventListener('keydown', event => { if (event.key === 'Escape' && dialog.open) { event.preventDefault(); event.stopImmediatePropagation(); dialog.close(); return; } if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') { event.preventDefault(); event.stopImmediatePropagation(); open(); } }, true); window.addEventListener('click', async event => { const target = event.target instanceof Element ? event.target : null; const searchButton = target?.closest('[data-doc-search], #search-bar-entry, #search-bar-entry-mobile'); if (searchButton) { event.preventDefault(); event.stopImmediatePropagation(); open(searchButton); return; } // Static exports can lose cross-page fragments in the hosted client's router. const chapterLink = target?.closest('a[href*="#"]'); if (chapterLink && !chapterLink.hasAttribute('download') && (!chapterLink.target || chapterLink.target === '_self') && event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey) { const destination = new URL(chapterLink.href, location.href); if (destination.origin === location.origin && destination.hash && destination.pathname.replace(/\/$/, '') !== location.pathname.replace(/\/$/, '')) { event.preventDefault(); event.stopImmediatePropagation(); location.assign(destination.href); return; } } const button = target?.closest('button[data-copy]'); if (button) { const label = button.textContent; try { await navigator.clipboard.writeText(button.dataset.copy); button.textContent = '已复制'; } catch { button.textContent = '请选中地址复制'; } button.setAttribute('aria-live', 'polite'); setTimeout(() => { button.textContent = label; }, 2000); } }, true); function migrate() { let current; try { current = location.pathname.replace(/\/$/, '') + decodeURIComponent(location.hash); } catch { return; } const record = migrations.find(entry => entry.from === current); if (record) location.replace(record.to); } window.addEventListener('hashchange', migrate); window.addEventListener('mintlify:navigate', migrate); migrate(); })();

模型 ID	支持任务 / 参考图	`aspect_ratio`
`flux.2-max` `flux.2-pro` `flux.2-flex`	文生图、编辑、融合参考图最多 8 张	`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`
`flux.2-klein-4b`	文生图、编辑、融合参考图最多 4 张	同上