跳到主要内容

常见问题

先从 API 调用和客户端配置确认基础链路，再处理具体错误。

API 调用​

如何确认 API Key 复制完整​

Key 创建后通常只完整显示一次。复制后先粘贴到本地安全位置，检查前后没有空格、换行或中文引号；后续看不到完整值时不要猜，直接停用旧 Key 并新建。

我应该先测软件，还是先测 curl​

先测 curl。curl 只包含地址、Key、模型和请求体四个变量，可以先排除客户端缓存、插件配置和环境变量继承问题。curl 成功后，再把同一组信息复制到软件。

为什么 curl 可以，软件不可以​

优先检查软件里的 Provider 类型、Base URL 层级、API Key 和 Model 字段。很多客户端保存后不会影响已经打开的旧会话，需要新建会话或重启客户端。

Base URL 和完整 Endpoint 到底差在哪​

Base URL 是协议根，客户端会继续追加路径；完整 Endpoint 已经包含具体接口路径。字段名写 Base URL、API Host 或 Server URL 时通常填协议根，只有明确要求 Request URL 或完整接口地址时才填完整路径。

模型列表为空怎么办​

很多客户端不会自动拉取第三方模型列表。只要 Key 和 Base URL 正确，可以从模型与价格页复制当前可用的 YOUR_MODEL 并手动填写，再发送一条短消息验证。

账户状态或额度不足怎么判断​

如果请求返回 403 或 429，且 Key、模型和路径都确认无误，回到主站查看账户状态、额度和当前模型可用状态。不要用公开文档里的旧截图判断。

用最小请求定位问题​

先不要直接在复杂客户端里反复重试。把地址、Key、模型和请求体固定下来，只发送一条短消息：

curl -i https://api.popgo.site/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"连接测试"}]}'

如果这个请求成功，问题通常在客户端的 Provider、Base URL、模型字段或旧会话缓存；如果这里也失败，再根据 HTTP 状态码进入“错误修复”。

客户端与本地环境​

命令找不到​

  • 现象： 软件或终端通常会显示“命令找不到”，也可能表现为配置保存了但请求仍失败。
  • 原因： 终端找不到 claude、codex 或 gemini 命令，通常是安装目录不在 PATH，或旧终端还没刷新环境。
  • 自查：
    1. 在启动软件的同一终端运行 where claude、where codex 或 where gemini，确认命令实际路径。
    2. 运行对应的 --version，如果新终端可以而旧终端不行，说明 PATH 尚未刷新。
    3. 不要从搜索结果中的未知安装包补救，优先按官方安装方式修复 PATH。
  • 处理： 重新打开终端并运行版本命令；仍失败时按官方来源重新安装，不要从未知镜像下载。
  • 验证： 重新启动客户端后发送一条短消息；能返回正常内容且地址、模型和认证均正确，才算恢复。

环境变量没有生效​

  • 现象： 软件或终端通常会显示“环境变量没有生效”，也可能表现为配置保存了但请求仍失败。
  • 原因： 变量设置在一个终端窗口里，软件却从另一个旧窗口、桌面快捷方式或后台进程启动。
  • 自查：
    1. 在同一终端打印变量名是否存在，但不要把完整 Key 粘贴到公开日志。
    2. 设置变量后关闭旧终端和旧进程，再从新终端启动软件。
    3. 桌面快捷方式启动的程序可能不会继承终端变量，改用软件支持的配置入口。
  • 处理： 在启动软件的同一个终端打印变量确认，设置后关闭旧会话并重新打开。
  • 验证： 重新启动客户端后发送一条短消息；能返回正常内容且地址、模型和认证均正确，才算恢复。

配置保存后仍请求默认服务​

  • 现象： 软件或终端通常会显示“配置保存后仍请求默认服务”，也可能表现为配置保存了但请求仍失败。
  • 原因： 客户端可能缓存了旧 Provider，或当前会话没有切换到新配置。
  • 自查：
    1. 重新打开软件的 Provider 配置，确认类型、Base URL、Key 和模型都指向 PopGo。
    2. 新建会话或完全重启软件，排除旧会话缓存。
    3. 用一条短消息查看实际请求是否命中预期模型。
  • 处理： 新建会话或重启客户端，确认当前 Provider、Base URL、Key 和模型都来自 PopGo 配置。
  • 验证： 重新启动客户端后发送一条短消息；能返回正常内容且地址、模型和认证均正确，才算恢复。

模型不可用​

  • 现象： 软件或终端通常会显示“模型不可用”，也可能表现为配置保存了但请求仍失败。
  • 原因： 模型 ID 拼写、访问范围或实时可用状态发生变化。
  • 自查：
    1. 从模型与价格页复制完整模型 ID，不要手打旧截图中的名称。
    2. 确认模型和 Key 属于同一可访问范围，并先用最小请求验证。
    3. 如果列表为空，直接手动填写模型 ID；列表为空不等于 API 不可用。
  • 处理： 从模型与价格页重新复制模型 ID，并先用最小请求验证；不要根据旧截图手打。
  • 验证： 重新启动客户端后发送一条短消息；能返回正常内容且地址、模型和认证均正确，才算恢复。

npm 全局安装权限错误​

  • 现象： 软件或终端通常会显示“npm 全局安装权限错误”，也可能表现为配置保存了但请求仍失败。
  • 原因： Windows 可能缺少安装权限，macOS/Linux 可能是 Node.js 安装方式导致全局目录不可写。
  • 自查：
    1. 运行 node --version 和 npm --version，确认 Node.js 与 npm 都在 PATH。
    2. Windows 重新打开 PowerShell；macOS/Linux 检查 npm 全局目录是否属于当前用户。
    3. 修复安装目录权限后重试，不要长期用 sudo npm install -g 掩盖目录配置问题。
  • 处理： Windows 重新打开具备安装权限的 PowerShell 后安装；macOS/Linux 优先用官方推荐方式或包管理器重装 Node.js，不要长期依赖 sudo npm install -g。
  • 验证： 重新启动客户端后发送一条短消息；能返回正常内容且地址、模型和认证均正确，才算恢复。

Claude Code 要求登录官方账号​

  • 现象： 软件或终端通常会显示“Claude Code 要求登录官方账号”，也可能表现为配置保存了但请求仍失败。
  • 原因： 环境变量没有被 Claude Code 读取到，客户端回退到了官方登录流程。
  • 自查：
    1. 在启动 Claude Code 的同一终端检查 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 是否存在。
    2. 确认 Base URL 是根地址，认证变量是 Key 本身，不要把 Key 写进命令历史或公开截图。
    3. 运行 claude doctor，再关闭旧会话并重新启动。
  • 处理： 在同一终端检查 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，关闭旧窗口后重新启动，并运行 claude doctor。
  • 验证： 重新启动客户端后发送一条短消息；能返回正常内容且地址、模型和认证均正确，才算恢复。

Codex 报认证错误​

  • 现象： 软件或终端通常会显示“Codex 报认证错误”，也可能表现为配置保存了但请求仍失败。
  • 原因： 本地配置读取不到 POPGO_API_KEY，或 config.toml 的 Provider 名称、model_provider、env_key 不一致。
  • 自查：
    1. 确认 POPGO_API_KEY 在启动 Codex 的同一终端中可见。
    2. 检查 config.toml 中 model_provider、Provider 配置块和 env_key 的名称完全一致。
    3. 先用短请求验证，成功后再恢复 Responses、工具调用或长上下文。
  • 处理： 确认环境变量名严格为 POPGO_API_KEY，再检查 model_provider = "popgo" 与 [model_providers.popgo] 是否对应。
  • 验证： 重新启动客户端后发送一条短消息；能返回正常内容且地址、模型和认证均正确，才算恢复。

Base URL 填写后 404​

  • 现象： 软件或终端通常会显示“Base URL 填写后 404”，也可能表现为配置保存了但请求仍失败。
  • 原因： 软件可能在你填写的地址后继续追加路径，导致 /v1/v1 或重复 endpoint。
  • 自查：
    1. 把软件最终发出的 URL 与快速开始页的表格逐段比较。
    2. Base URL 字段只填根或 /v1，完整 Endpoint 字段才填具体接口路径。
    3. 保存后新建会话，防止旧配置继续发送。
  • 处理： 回到快速开始页的 Base URL 层级表：Base URL 字段填协议根，完整 Endpoint 字段才填完整路径。
  • 验证： 重新启动客户端后发送一条短消息；能返回正常内容且地址、模型和认证均正确，才算恢复。

证书或 SSL 错误​

  • 现象： 软件或终端通常会显示“证书或 SSL 错误”，也可能表现为配置保存了但请求仍失败。
  • 原因： 常见原因是本地代理、公司网络拦截、系统时间错误或证书链异常。
  • 自查：
    1. 校准系统时间并暂时关闭本地代理，用另一网络做一次对照测试。
    2. 检查安全软件是否启用了 HTTPS 检查或替换证书。
    3. 不要关闭 TLS 校验；记录错误文本和发生时间供后续定位。
  • 处理： 不要关闭 TLS 校验。先校准系统时间，临时关闭本地代理或换网络验证，再检查安全软件是否劫持 HTTPS。
  • 验证： 重新启动客户端后发送一条短消息；能返回正常内容且地址、模型和认证均正确，才算恢复。

参考音频与输出声音有什么区别？​

generate_audio 控制输出音轨，不能证明模型接受参考音频。模式名按能力显示为参考视频/音频、参考视频或参考音频；参考视频模式必须有视频，纯音频模式必须有音频。

为什么 C 有参考音频却没有参考视频？​

C当前明确不支持视频输入，视频数量0不能通过留空来绕过；最多支持3个参考音频。Kling文档里的音频描述未公开参考输入字段，当前不开放参考音频；Grok也不支持。

粘贴网络图片或音频就一定是公网素材吗？​

粘贴明确的HTTP(S)直链会保留公网来源；只复制文件二进制仍是本地。生成结果仅在保留公网sourceUrl时标记公网。本地/公网标签可点击查看来源，但公网不保证服务访问成功；不支持Base64的模型需要可访问URL。

为什么有任务ID，参考素材却没有生效？​

ID只证明任务接受。检查模式、实际字段、素材抓取和最终成片。首帧与参考图片不等价；一个错误且被静默忽略的字段可能仍导致生成和费用。详见视频任务流程及对应模型页。

推荐排查顺序​

  1. 先记录完整错误：HTTP 状态码、请求路径、客户端名称和发生时间。
  2. 用快速开始页的最小 curl 请求复现，确认问题来自 Key、模型、地址还是客户端。
  3. 一次只改一个变量；修复后先验证短文本请求，再恢复流式、工具调用或媒体参数。