接入文档 — V需API

01开始之前

三件事就够了：接口地址、一把密钥，以及理解密钥和分组的关系。

用途	填什么
OpenAI 兼容客户端 / SDK	`https://vneedapi.com/v1`
Claude Code	`https://vneedapi.com` — 不带 `/v1`，客户端会自己补
认证头	`Authorization: Bearer sk-你的密钥`

一把密钥绑定一个分组。分组决定了这把密钥能调用哪些模型、按什么倍率计费。

所以：想用 Claude 就用 Claude 系分组的密钥，想用 Gemini 就另建一把。用 ChatGPT 分组的密钥去调 claude-opus-5 会报模型不存在 —— 这不是故障，是分组隔离。

创建密钥

注册并登录
完成邮箱验证后进入控制台。
充值
余额为 0 时无法发起调用。
新建 API 密钥，选择分组
控制台 → API 密钥 → 新建。分组列表里能看到每个分组的说明和倍率，按需要选。

02让控制台生成配置

这是最省事的办法，也最不容易填错 —— 生成的配置里会直接带上你的密钥和正确的地址。

控制台 → API 密钥 → 在密钥那一行点 「使用此密钥」 → 选择客户端和你的操作系统（macOS / Linux、Windows CMD、PowerShell）→ 复制生成的配置。

可选的客户端取决于这把密钥所属分组的平台：

分组平台	可生成的客户端配置
ChatGPT 系	Codex CLI、Codex CLI (WebSocket)、OpenCode
Claude 系	Claude Code、Codex CLI、OpenCode
Gemini 模型	以 OpenAI 兼容方式提供，控制台生成的 Codex 配置不适用，请按下文「Gemini 模型」一节配置
KIMI / DeepSeek / GLM	只提供 OpenAI 兼容方式，Claude Code 用不了，请按下文「KIMI / DeepSeek / GLM」一节配置
Grok 系	Grok CLI、Claude Code、Codex CLI、OpenCode

03各客户端手工配置

把下面的 sk-你的密钥 换成自己的密钥即可。

任何兼容 OpenAI 的客户端

Cherry Studio、ChatBox、NextChat、Dify、Open WebUI、LobeChat 以及各语言的 OpenAI SDK，都只需填两项：

字段	值
API Base URL	`https://vneedapi.com/v1`
API Key	`sk-你的密钥`

curl 验证

接客户端之前，先用这条确认密钥和地址都对。模型名请换成你的分组里实际有的。

Terminal

curl https://vneedapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"你好"}]}'

想先看看这把密钥能用哪些模型：

Terminal

curl https://vneedapi.com/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

Claude Code

需要一把 Claude 系分组的密钥。注意地址不带 /v1。

Terminal

export ANTHROPIC_BASE_URL="https://vneedapi.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

用 ChatGPT 系分组的密钥配 Claude Code 会被拒绝，报 This group does not allow /v1/messages dispatch。换 Claude 系分组的密钥即可。

Codex CLI

需要一把 ChatGPT 系分组的密钥。写入配置文件：

~/.codex/config.toml　（Windows: %userprofile%\.codex\config.toml）

model_provider = "OpenAI"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
disable_response_storage = true
network_access = "enabled"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://vneedapi.com/v1"
wire_api = "responses"
requires_openai_auth = false
experimental_bearer_token = "sk-你的密钥"

[features]
api_key_model_discovery = true

Codex 的配置项会随版本变化。控制台的「使用此密钥 → Codex CLI」会按当前版本生成完整配置，以它为准。

Gemini 模型

需要一把 Gemini 分组的密钥。Gemini 模型通过 OpenAI 兼容接口提供：在 Cherry Studio、ChatBox、NextChat 或 OpenAI SDK 里，Base URL 填 https://vneedapi.com/v1，模型名填 Gemini 的模型即可。

Terminal

curl https://vneedapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.8-flash","messages":[{"role":"user","content":"你好"}]}'

暂不支持 Gemini CLI。Gemini CLI 只走 Google 原生接口（/v1beta），目前不提供。具体有哪些 Gemini 模型，用 /v1/models 查询。

KIMI / DeepSeek / GLM

需要一把对应分组（KIMI-官KEY、DeepSeek-官KEY 或 GLM-官Key）的密钥。这三家模型只通过 OpenAI 兼容接口提供：在 Cherry Studio、ChatBox、NextChat、OpenCode 或 OpenAI SDK 里，Base URL 填 https://vneedapi.com/v1，模型名填对应的模型即可。

Terminal

curl https://vneedapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-flash","messages":[{"role":"user","content":"你好"}]}'

暂不支持在 Claude Code 里使用。Claude Code 走 Anthropic 格式（/v1/messages），这三家目前只能用 OpenAI 格式（/v1/chat/completions）调用。具体有哪些模型，用 /v1/models 查询。

Grok CLI

需要一把 Grok 系分组的密钥。

Terminal

export GROK_MODELS_BASE_URL="https://vneedapi.com/v1"
export XAI_API_KEY="sk-你的密钥"

04可用端点

根路径是 https://vneedapi.com。能否调用某个端点，取决于你的密钥属于哪个平台的分组。

端点	方法	说明
`/v1/models`	GET	列出当前密钥所属分组可用的模型
`/v1/chat/completions`	POST	OpenAI Chat Completions，兼容性最好，推荐优先用
`/v1/responses`	POST	OpenAI Responses，Codex CLI 使用
`/v1/embeddings`	POST	文本向量
`/v1/images/generations`	POST	生图，需传图像类模型
`/v1/messages`	POST	Anthropic 原生格式，需 Claude 系分组

旧版 /v1/completions（Legacy Completions）不支持，会返回 404。请改用 /v1/chat/completions。

05模型清单

公开模型目录在首页「模型目录」，按小时自动同步，不是手工维护的清单。

但请注意：首页展示的是所有公开分组的合集。你这把密钥实际能调用的，是它所属分组的那一部分。要看准确范围，用 /v1/models 查，或在控制台里看分组详情。

06计费方式

按 token 计费，从账户余额扣。公式只有一条：

实际扣费＝模型官方价 × 分组倍率

举例：某分组倍率是 0.2，那么用这个分组调模型，花的是官方价的两折。每个分组的倍率都在控制台的分组列表里写明，不同分组倍率不同 —— 便宜的分组通常在稳定性或模型范围上有取舍，分组说明里会讲清楚。

用量和消费明细在控制台 → 用量统计里按天查看，可以按模型和密钥拆分。

07常见报错

下面都是实际会返回的报错原文，照着对就行。

报错	原因	怎么办
`Model "xxx" is not supported by any configured account in this group`	这个模型不在你密钥所属的分组里	先用 `/v1/models` 看可用清单后换模型；或换一把对应分组的密钥
`This group does not allow /v1/messages dispatch`	用 Claude 格式去调了非 Claude 分组	改用 Claude 系分组的密钥
`API key group platform is not gemini`	用了 Gemini 原生接口（`/v1beta`，如 Gemini CLI），目前不提供	改用 `/v1/chat/completions` 调用 Gemini 模型，见上文「Gemini 模型」
`Upstream service temporarily unavailable`（在 Claude Code 里用 KIMI / DeepSeek / GLM 时）	这三家模型只支持 OpenAI 格式，Claude Code 发的是 Anthropic 格式	改用 OpenAI 兼容客户端调用，见上文「KIMI / DeepSeek / GLM」
`images endpoint requires an image model`	生图端点传了非图像模型	换成图像类模型，并确认分组支持生图
`No available accounts supporting model …`	该分组当前没有可用上游	稍后重试，或换一个分组
`Upstream access forbidden`	上游拒绝了这次请求	换分组重试；持续出现请联系我们
HTTP 401	密钥无效，或没带认证头	检查 `Authorization: Bearer sk-…` 是否正确、密钥是否被禁用
HTTP 429	触发了速率或并发限制	降低并发后重试

报问题时请带上响应头里的 X-Request-Id，我们可以直接定位到那一次请求。

08联系我们

遇到文档里没写到的情况，发邮件到 ai@vneedai.com，带上 X-Request-Id 和你用的分组名称。

模型接入，回到简单。返回首页 · 打开控制台