公开文档

VProAI API

VProAI API 提供兼容 OpenAI 的文本与 Code 接口，并支持图像、视频和实时语音。客户端只保存 VProAI Key；实际供应商密钥始终留在服务端。API 调用与网页任务共用同一钱包和计费记录。

VProAI API 兼容 OpenAI SDK 的常用调用方式，但部分高级参数会因模型供应商能力不同而存在差异。请先通过 GET /v1/models 检查模型及其能力。

计费请求必须带幂等键。 所有会产生费用的 POST 请求都需带 Idempotency-Key；网络重试时保持同一个随机键，24 小时内会返回第一次的结果且不会再次扣费。更换请求内容时必须生成新键。

快速开始

注册并登录 VProAI，在左侧打开“API”。
创建 API Key；模型权限可搜索添加，留空代表允许全部可用模型，也可以切换为排除模式。
立即保存以 vpro-sk- 开头的密钥，关闭后无法再次查看明文。
把请求基础地址设置为 https://api.vproaimix.com/v1。

curl https://api.vproaimix.com/v1/models \
  -H "Authorization: Bearer vpro-sk-..."

AI 快捷配置

复制下面这段话发送给 Codex、Claude Code 或其他编程助手，它会先阅读本文档，再按当前项目和目标客户端完成接入。

请阅读 VProAI API 文档 https://www.vproaimix.com/api-docs，并检查当前项目后完成 VProAI API 接入。根据项目用途选择网页服务端、Codex、Claude Code 或其他兼容客户端的正确配置；使用我随后提供的 VProAI API Key，密钥只能保存在服务端环境变量或客户端的安全配置中，不能写入网页前端、公开仓库、日志或构建产物。先调用 GET https://api.vproaimix.com/v1/models 获取当前可用模型与 capabilities，再按文档选择文本、图像、视频、语音或 Code 接口；OpenAI 兼容接口基础地址使用 https://api.vproaimix.com/v1，Codex 使用 Responses 接口，Claude Code 的 ANTHROPIC_BASE_URL 使用 https://api.vproaimix.com 且不要追加 /v1。完成后使用最短请求验证连接、鉴权、模型权限与错误处理，并告诉我修改了哪些文件以及验证结果。

兼容与版本

API 版本策略

/v1 保持向后兼容；新增可选字段不会破坏旧客户端。需要删除字段、改变既有语义等重大不兼容变更时，将通过新的主版本（例如 /v2）发布。

Request ID

每次响应都会在 Header 返回 X-Request-ID。遇到问题时请把该值提供给客服，以便定位对应请求。

X-Request-ID: req_839201_LAX

模型列表

返回当前 API Key 实际有权调用、且供应商当前已启用的模型。同一模型可同时具备文本与 Code 等能力，接口会合并为一条记录，避免客户端看到重复模型。

GET/v1/models

{
  "object": "list",
  "data": [
    {
      "id": "grok-4.5",
      "object": "model",
      "created": 0,
      "owned_by": "vproai",
      "available": true,
      "task": "text",
      "capabilities": ["text", "code"]
    }
  ]
}

available 表示该模型当前可调用；capabilities 是 VProAI 扩展字段，列出文本、图像、视频、语音或 Code 能力。标准 OpenAI 客户端可忽略这些扩展字段。这里不返回未经供应商确认的上下文长度，避免客户端依据错误上限提交任务。

文本接口

兼容 Chat Completions。通过 GET /v1/models 获取当前 Key 实际有权使用的模型。

POST/v1/chat/completions

curl https://api.vproaimix.com/v1/chat/completions \
  -H "Authorization: Bearer vpro-sk-..." \
  -H "Idempotency-Key: 4d378671-6eab-4c91-9bcc-6711622e8e8d" \
  -H "Content-Type: application/json" \
  -d '{"model":"kimi-k3","messages":[{"role":"user","content":"你好"}],"max_tokens":64}'

{
  "id": "api_call_...",
  "object": "chat.completion",
  "model": "kimi-k3",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "你好"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 8, "completion_tokens": 2, "total_tokens": 10}
}

流式返回时加入 "stream": true。Responses API 与 Anthropic Messages API 属于 Code 权限范围，必须在 API Key 中开启对应的 Code 模型权限。

图像生成接口

Key 权限必须包含所选图像模型。接口优先接受 OpenAI 风格的 size（宽×高），服务端会按模型转换为供应商所需的长宽比；原有 aspect_ratio 仍保留兼容。生成完成后返回作品地址，作品遵循站内七天保留规则。

POST/v1/images/generations

curl https://api.vproaimix.com/v1/images/generations \
  -H "Authorization: Bearer vpro-sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-image-quality","prompt":"薄雾森林中的玻璃小屋","size":"1536x864"}'

{
  "created": 1780000000,
  "model": "grok-imagine-image-quality",
  "data": [{
    "id": "image_...",
    "url": "https://www.vproaimix.com/media/image_...",
    "size": "1536x864",
    "aspect_ratio": "16:9"
  }]
}

视频生成接口

视频是异步任务。创建后保存返回的 id，再轮询状态端点。路径与 OpenAI Videos API 保持一致；旧的 POST /v1/videos/generations 继续可用，现有客户端无需迁移。

POST/v1/videos

curl https://api.vproaimix.com/v1/videos \
  -H "Authorization: Bearer vpro-sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2-0-fast-260128","prompt":"海边日出，镜头缓慢向前推进","duration":4,"resolution":"480p","aspect_ratio":"16:9"}'

{"id":"video_...","object":"video","status":"queued","created_at":1780000000}

GET/v1/videos/{video_id}

curl https://api.vproaimix.com/v1/videos/video_... \
  -H "Authorization: Bearer vpro-sk-..."

{
  "id": "video_...",
  "object": "video",
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "completed",
  "duration": 4,
  "resolution": "480p",
  "aspect_ratio": "16:9",
  "url": "https://www.vproaimix.com/media/video_..."
}

视频接口采用异步任务，建议间隔 3–5 秒并使用指数退避。任务完成或失败后停止轮询。

实时语音接口

语音 API 使用 WebRTC 或 WebSocket 传输音频，不是普通文字聊天。创建会话前会检查并扣除未来一分钟的通话额度；通话继续时，客户端应在到期前调用续费接口。续费返回 402 时应立即结束通话。

Grok Voice（WebSocket）

POST/v1/voice/sessions

curl https://api.vproaimix.com/v1/voice/sessions \
  -H "Authorization: Bearer vpro-sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-voice-latest"}'

返回的 client_secret.value 是短期会话密钥，只用于连接返回的 websocket_url，不是供应商长期密钥。

const session = await fetch("https://api.vproaimix.com/v1/voice/sessions", {
  method: "POST",
  headers: { Authorization: `Bearer ${VPROAI_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "grok-voice-latest" })
}).then(r => r.json());

const protocol = session.client_secret.value.startsWith("xai-client-secret.")
  ? session.client_secret.value
  : `xai-client-secret.${session.client_secret.value}`;
const ws = new WebSocket(session.websocket_url, [protocol]);

GPT Realtime（WebRTC）

POST/v1/voice/calls?model=gpt-realtime-2.1-mini

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
stream.getTracks().forEach(track => pc.addTrack(track, stream));
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const answerSdp = await fetch(
  "https://api.vproaimix.com/v1/voice/calls?model=gpt-realtime-2.1-mini",
  { method: "POST", headers: { Authorization: `Bearer ${VPROAI_KEY}`, "Content-Type": "application/sdp" }, body: offer.sdp }
).then(r => { if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.text(); });
await pc.setRemoteDescription({ type: "answer", sdp: answerSdp });

每分钟续费

POST/v1/voice/renew

const renew = await fetch("https://api.vproaimix.com/v1/voice/renew", {
  method: "POST",
  headers: { Authorization: `Bearer ${VPROAI_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "grok-voice-latest" })
});
if (renew.status === 402) endCall();

Code 接口

Code 权限与普通文本权限分开管理。通用代码助手可调用专用 Chat Completions 端点；Codex 使用 Responses 端点，Claude Code 使用 Anthropic Messages 端点。只有标记为 Code 可用的模型会出现在此权限组中。

POST/v1/code/completions

curl https://api.vproaimix.com/v1/code/completions \
  -H "Authorization: Bearer vpro-sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-4.5","messages":[{"role":"user","content":"修复这个 TypeScript 函数的类型错误"}],"max_tokens":256}'

POST/v1/responses

curl https://api.vproaimix.com/v1/responses \
  -H "Authorization: Bearer vpro-sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"kimi-k2.7-code","input":"为这个项目添加一个健康检查接口"}'

POST/v1/messages

curl https://api.vproaimix.com/v1/messages \
  -H "x-api-key: vpro-sk-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":256,"messages":[{"role":"user","content":"检查并修复测试失败"}]}'

Codex、OpenAI SDK 与 Claude Code

OpenAI SDK / 通用客户端

OPENAI_API_KEY="你的 VProAI Key"
OPENAI_BASE_URL="https://api.vproaimix.com/v1"

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    api_key="你的 VProAI Key",
    base_url="https://api.vproaimix.com/v1",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "你好"}],
)

print(completion.choices[0].message.content)
print(completion._request_id)

Node.js（OpenAI SDK）

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.VPROAI_API_KEY,
  baseURL: "https://api.vproaimix.com/v1",
});

const completion = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [{ role: "user", content: "你好" }],
});

console.log(completion.choices[0].message.content);
console.log(completion._request_id);

Codex config.toml

model_provider = "vproai"

[model_providers.vproai]
base_url = "https://api.vproaimix.com/v1"
env_key = "VPROAI_API_KEY"
wire_api = "responses"

Claude Code

ANTHROPIC_API_KEY="你的 VProAI Key"
ANTHROPIC_BASE_URL="https://api.vproaimix.com"

Claude Code 的 ANTHROPIC_BASE_URL 不要添加 /v1。Anthropic 客户端会自动请求 /v1/messages，手动添加可能形成错误的 /v1/v1/messages。

状态码、安全与限制

状态码	说明
`400`	请求格式或参数错误
`401`	VProAI Key 无效
`402`	钱包余额不足
`403`	Key、团队成员或模型权限不足
`404`	模型或任务不存在
`429`	请求过于频繁
`503`	服务暂时不可用

所有开发者接口使用同一错误结构，客户端应依据 HTTP 状态码和 error.code 处理，不要依赖可读文案。钱包余额不足固定返回 402 Payment Required。

{
  "error": {
    "message": "Wallet balance is insufficient.",
    "type": "insufficient_balance",
    "code": "insufficient_balance"
  }
}

不要把 VProAI Key 写进网页前端、公开仓库或客户端安装包。
数据库只保存 Key 哈希，明文仅创建时显示一次。
个人最多创建 5 个 Key；团队最多创建 20 个 Key。
团队管理员可限制队员和模型；监控只展示当前账号或当前团队。