常见问题

401：没有权限

Key 缺失或无效。检查：

• PHOENIX_MODEL_KEY 已设置，且以 sk- 开头
• Key 没有在面板里被作废或删除
• 如果用的是账号 Token（PHOENIX_TOKEN），确认它没有过期；同时设置了 Key 和 Token 时，优先账号身份

403：额度不足或权限受限

• INSUFFICIENT_QUOTA（模型额度不足，请先充值）：Key 所属账户的余额不够，去面板充值。这种情况不会调用上游，也不会扣费
• MODEL_NOT_ENABLED（该模型暂未上架）：换成 phoenix models 返回的模型
• 其他 403：站点管理员限制了生成权限（WS_GENERATE_MIN_ROLE），联系管理员

默认情况下，任何有效的模型 Key 或登录账号都可以生成。完整状态码见 错误码与重试。

400：模型价格未配置

返回 MODEL_PRICE_MISSING，说明该模型暂未定价、不可用，换一个模型即可。

超时

异步生成默认等待 180 秒。超时的报错里会带上任务 id，任务仍在后台进行：

phoenix generate wait <generation_id> --json

大图或较慢的模型可先 --no-wait（MCP 里用 wait: false）。

模型 id 从哪里来？

phoenix models --json

返回里的 model 字段就是模型 id；要看某个模型的完整参数用 phoenix models --model <模型ID> --json。也可以对照工作台生图页的系列 / 模式。LLM 对话模型用 GET /v1/models 查询，见 LLM API。

MCP 在 IDE 里不生效

1. 确认 phoenixai-mcp 在 PATH 里（终端运行 which phoenixai-mcp），或配置里写绝对路径
2. 环境变量 PHOENIX_MODEL_KEY（以及可选的 PHOENIX_BASE_URL）已写进 MCP 配置的 env
3. 重启 IDE

下载到的图片链接打不开

结果文件只保留一段时间（默认约 6 小时），过期会被清理，记录还在但文件没了。生成后请及时下载保存。

限制（当前版本）

• 图像生成只支持纯文生图（CLI / MCP），编辑类模式见 HTTP API；视频功能已下线
• CLI 不负责浏览器登录，需自行提供 Key / Token
• CLI / MCP 只返回结果 URL，不会自动下载文件

协议文档

MCP 协议与各 IDE 接入格式见官方文档： https://modelcontextprotocol.io