灵息 AI 文档

Appearance

常见错误与排查 ​

本页汇总在使用灵息 API（OpenAI 兼容格式）时最常见的问题与排查方法。

先做这三步 ​

终极排错表：请在此处打钩

如果遇到报错，请先像刻在 DNA 里一样死记并检查以下内容：

  1. [ ] Base URL 是否完全等于 https://ask.ling.rest/api/v1？
    • ❌ 检查结尾是否有冗余斜杠 /
    • ❌ 检查是否漏了 /api/v1
    • ❌ 检查是否用了 http 而非 https
  2. [ ] Model ID 是否全小写且格式机械化？
    • ✅ 正确：gemini-3-flash-preview-vertex
    • ❌ 错误：Gemini 3 Flash (带空格/大写)
    • ❌ 错误：gemini_3_flash (下划线)
  3. [ ] API Key 是否正确携带了 Bearer 前缀？

只要保证这三点，90% 的连接问题都会消失。

  1. 确认 Base URL：https://ask.ling.rest/api/v1
  2. 通过 模型名获取器 复制 model（以工具显示为准）
  3. 确认请求头携带：Authorization: Bearer <API_KEY>

常见报错 ​

401 Unauthorized ​

  • API Key 不正确或已失效
  • 请求头未携带 Authorization 或格式错误

处理方式：到 设置 > 账号 > API 密钥 重新生成并替换。

403 Forbidden ​

  • 账号权限组不包含该模型的 API 权限

处理方式：换一个您账号可见且可调用的模型 ID。

404 / model not found ​

  • 使用了“前端展示名”，而不是模型 ID
  • 复制了别人的模型 ID（不同账号可见模型不同）

处理方式：以您自己的 /models 或 模型名获取器 返回为准。

429 Too Many Requests ​

  • 触发频率限制或并发过高

处理方式：降低并发、增加重试与指数退避；必要时切换更稳定的模型渠道。

5xx / 超时 / 空回复 ​

提示

逆向模型出现 速度慢、空回复、波动 属正常现象。请先重试或更换模型。

处理方式：

  • 先核对 API 设置：确认 Base URL、Authorization 头、model 字段均正确无误
  • 再重试 1～3 次
  • 切换到官方渠道模型（如 Vertex / AI Studio）
  • 增大客户端超时（如 60s～120s）

模型渠道说明见：模型详细介绍

推荐的重试策略 ​

  • 仅对网络错误、429、部分 5xx 做重试
  • 使用指数退避：1s、2s、4s、8s…
  • 为每次请求设置合理 timeout

下一步 ​