接入排查
连接测试不通过?按本页顺序自查。绝大多数接入失败属于三类原因,每一类都有明确解法。
第一步:一条命令自检
任何客户端报“连接失败”,先用 curl 直接验证密钥与链路,把客户端配置问题和账号问题分开:
- 返回模型列表(200)→ 密钥、网络、域名全部正常,问题出在客户端配置,继续看下面的客户端速查
- 返回 401 → 密钥不对,九成是复制到了带省略号的掩码串,见下一节
- 连不上 / 超时 → base_url 写错了。必须是 https://api.qiyuanapi.cc/v1,不是主站域名 qiyuanapi.cc
自检命令
curl https://api.qiyuanapi.cc/v1/models \
-H "Authorization: Bearer sk-opc-你的完整密钥"三类最常见的失败原因
1. ① 密钥是「掩码串」,不是完整密钥
形如 sk-opc-xxxx-...xxxx、中间带省略号的是列表页的显示用掩码,粘到任何客户端都无效(必然 401)。完整密钥只在创建时完整显示一次,服务端仅保存哈希、无法找回。若当时没保存:删除该密钥并重新创建,创建弹窗里立即复制保存。
2. ② 模型名写错
模型 id 只认 /v1/models 返回的值,2026-09-12 起就是 deepseek-v4.1。老名字已全部下线:deepseek-v4、qwen3.8-flash、qwen-0810 以及生图的 qwen-image / qwen-image-edit,再调用返回 404 model_unavailable,报错里会直接列出当前可用模型 —— 把客户端里的模型名改掉即可,密钥不用换。其他常见错法:把密钥名称当模型名、写模型的 HuggingFace 全名(本站只认对外名)、沿用客户端默认模型(如 Codex 的 gpt-5.6-*、Claude Code 的 claude-*)。
3. ③ 密钥的模型白名单没勾这个模型
创建密钥时若勾选了部分模型,请求未勾选的模型会返回 403 model_not_allowed,报错里会列出该密钥已授权的模型。到控制台 →「API 密钥」→ 编辑,补勾需要的模型;或创建时不勾任何模型(等于全部允许)。
报错速查
- 401 unauthorized — 密钥无效(掩码串 / 已删除 / 拼写错)
- 402 quota_exceeded — 余额或密钥配额耗尽,充值即可,不是密钥问题
- 403 model_not_allowed — 密钥白名单没勾这个模型,编辑密钥补勾
- 403 ip_not_allowed — 密钥设了 IP 白名单,当前来源 IP 不在其中
- 403 key_expired — 密钥已过期,重新创建
- 404 model_unavailable — 模型名写错或未上线,调用 /v1/models 看可用列表
- 429 rate_limited — 触发限流,稍等重试或降低并发
- 503 backend_unavailable — 平台侧短暂不可用,可安全重试;4xx 重试无意义
- 400 ContextWindowExceededError — 会话上下文加上 max_tokens 超过模型上限(deepseek-v4.1 为 1048576,即 1M)。新开会话或精简历史;Agent 类工具务必在模型配置里把上下文上限填成 1048576,让工具提前压缩而不是堆到撞墙;另外别把 max_tokens 填成上下文长度,那会让「输入 + 输出」提前顶到上限
- 400 max_tokens cannot be greater than max_model_len — 请求的输出上限超过模型能力。检查客户端的 max_tokens 设置,曾见到客户端默认填 2000000;设为 8192 等合理值即可,不要按上下文长度顶格填
- 400 model_endpoint_mismatch — 模型类型与接口不匹配:把对话模型填到 /v1/images/* 接口,或把生图模型 seedream-5.0-pro 填到对话接口(/v1/chat/completions、/v1/responses、/v1/messages)。生图只能走 POST /v1/images/generations(prompt 写画面描述,size 填 1K 或 2K,参考图放 image 字段);对话请用 deepseek-v4.1
- 400 Input should be 'function'(param 为 body.tools.0.type)— 客户端发来了 Anthropic 原生的 web_search 工具,本站引擎只认 OpenAI 标准的 function 工具。**本站不提供服务端联网搜索**,把客户端的「服务端搜索 / 内置联网」开关关掉、改用客户端自带的网页搜索即可;各客户端开法见「联网搜索」页
- 旧版报错 No deployments available for selected model — 与上面同源。用错接口会让上游连续返回 404,网关随即熔断该模型约 30 秒,期间**其他人对同一模型的正常请求也会一起失败**。平台已改为前置返回 model_endpoint_mismatch,不再打到上游,若仍看到这句请先确认接口用对了
模型能力速查
2026-09-12 起平台只有一个对话模型:
- deepseek-v4.1 — 原生多模态(支持图片)、上下文 1,048,576(1M)、默认开思考:日常对话、编码、Agent 工作流、深度推理、带图任务全部用它。思考深浅与关闭见「思考强度设置」
- deepseek-v4 / qwen3.8-flash / qwen-0810 — 已下线,调用返回 404
- qwen-image / qwen-image-edit — 已下线;生图请用 seedream-5.0-pro(所有账号可用),接口 /v1/images/generations,参考图放 image 字段
常用客户端速查
1. 腾讯云 OpenClaw(Lighthouse Agent)
「自定义模型」选 JSON 输入,按下面模板填。两个前提:Agent 实例必须处于「运行中」状态(左上角未运行时,连接测试在腾讯侧就会失败,请求根本不会发出);密钥白名单需包含所填模型。
JSON 输入模板
{
"provider": "qiyuan-hub",
"base_url": "https://api.qiyuanapi.cc/v1",
"api_key": "sk-opc-创建时保存的完整密钥",
"api": "openai",
"model": { "id": "deepseek-v4.1", "name": "DeepSeek V4.1" }
}2. Codex Desktop
把 base URL 指到本平台后,必须同时把模型改为 deepseek-v4.1 —— Codex 默认请求自家的 gpt-5.6-* 系列,本平台没有这些模型,会返回 404。平台已支持 Codex 使用的 Responses API(/v1/responses),无需改协议;模型上下文填 1048576。
3. Trae
自定义模型配置里的「上下文长度」务必填 1048576(deepseek-v4.1 的真实上限)—— 不填的话 Trae 不知道边界,长任务会把历史一直堆到超限报 ContextWindowExceededError。模型 ID 填 deepseek-v4.1,「图片输入」可以勾上(原生多模态)。
4. WorkBuddy
模型 slug 填 deepseek-v4.1(旧文档写的 qwen3.8-flash / deepseek-v4 已下线,会返回 404)。高频坑:检查 max_tokens 设置,曾见到客户端发 max_tokens=2000000 远超模型能力导致 400,建议设为 8192 等合理值;WorkBuddy 报「自定义模型 xxx 错误,请切换模型或重试」时具体原因被吞掉了,先用本页第一步的 curl 自检。
5. OpenCode / Hermes
模型 slug 一律填 deepseek-v4.1(旧文档写的 qwen3.8-flash 已下线,会返回 404)。各工具的完整配置见左侧「外部接入」对应页面。
6. ChatBox 及其他 OpenAI 兼容客户端
API Host 填 https://api.qiyuanapi.cc/v1,API Key 填完整密钥,模型手填 deepseek-v4.1 即可。
还是不行?
联系管理员时请带上:大致发生时间、使用的客户端、完整报错文本。服务端日志可以按时间精确定位到每次请求的拒绝原因,这三样信息能让定位从几十分钟缩短到一分钟。