1. 接入前准备

开始前，你需要准备以下信息：

• 平台访问地址：https://api.gavinhub.online/
• 一个可用的 API 令牌
• 至少一个可调用的模型名称，例如 gpt-4o-mini、 claude-3-5-sonnet、gemini-2.5-flash

如果你还没有 API 令牌：

1. 登录平台控制台
2. 进入“令牌管理”
3. 新建一个令牌
4. 复制生成后的密钥并妥善保存

2. 基础概念

Base URL

如果你使用 OpenAI 兼容 SDK，base_url 或 baseURL 应配置为：

https://api.gavinhub.online/v1

如果你直接发 HTTP 请求，则完整地址通常是：

• 聊天接口：POST https://api.gavinhub.online/v1/chat/completions
• Responses 接口：POST https://api.gavinhub.online/v1/responses
• 模型列表：GET https://api.gavinhub.online/v1/models
• Claude Messages：POST https://api.gavinhub.online/v1/messages
• Gemini 原生格式：POST https://api.gavinhub.online/v1beta/models/{model}:generateContent

认证方式

3. 第一个请求

3.1 获取可用模型列表

curl https://api.gavinhub.online/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

成功后你会拿到当前令牌可调用的模型列表。请从返回结果中选择一个模型名继续测试。

• 使用 Authorization: Bearer ... 时，默认返回 OpenAI 兼容格式
• 使用 x-api-key 且同时携带 anthropic-version 时，返回 Claude 风格格式
• 使用 x-goog-api-key 或查询参数 key=... 时，返回 Gemini 风格格式

3.2 Chat Completions

curl https://api.gavinhub.online/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "你好，请用一句话介绍你自己。"
      }
    ]
  }'

如果返回 choices[0].message.content，说明接入已经成功。

3.3 流式响应

curl https://api.gavinhub.online/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "请写一段 50 字以内的欢迎语。"
      }
    ]
  }'

4. 主流工具接入

Claude Code

Claude Code 官方当前推荐使用原生安装方式。

curl -fsSL https://claude.ai/install.sh | bash
claude --version

接入本平台时，建议在启动前设置以下环境变量：

export ANTHROPIC_BASE_URL="https://api.gavinhub.online"
export ANTHROPIC_API_KEY="YOUR_API_KEY"

claude

说明：

• ANTHROPIC_BASE_URL 使用平台根地址，不要额外拼接 /v1/messages
• ANTHROPIC_API_KEY 会以 x-api-key 方式发送，适合本平台的 Claude 兼容接口
• 进入 Claude Code 后可执行 /status 检查当前认证方式是否生效

Codex CLI

Codex CLI 可通过 npm 或 Homebrew 安装。

npm install -g @openai/codex
codex --version

接入本平台时，建议优先使用环境变量配置：

export OPENAI_BASE_URL="https://api.gavinhub.online/v1"
export OPENAI_API_KEY="YOUR_API_KEY"

codex

说明：

• OPENAI_BASE_URL 需要带上 /v1
• OPENAI_API_KEY 填写你在平台创建的令牌即可
• Codex CLI 走的是 OpenAI 兼容接口，适合本平台的 /v1/responses 与相关 OpenAI 风格能力

其他 OpenAI 兼容工具

如果你使用的是其他支持 OpenAI 协议的客户端、插件或 IDE，通常只需要填写这两项：

• API Key：你的平台令牌
• Base URL：https://api.gavinhub.online/v1

5. 使用 OpenAI 兼容 SDK

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.gavinhub.online/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "请用一句话介绍 new-api 接入方式。"}
    ],
)

print(resp.choices[0].message.content)

JavaScript / TypeScript

const response = await fetch("https://api.gavinhub.online/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [
      {
        role: "user",
        content: "请返回一句接入成功提示。",
      },
    ],
  }),
});

const data = await response.json();
console.log(data.choices?.[0]?.message?.content);

6. 使用原生格式接入

Claude Messages

curl https://api.gavinhub.online/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet",
    "max_tokens": 256,
    "messages": [
      {
        "role": "user",
        "content": "请用一句话说明 Claude 格式已接入成功。"
      }
    ]
  }'

Gemini 原生格式

curl "https://api.gavinhub.online/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "请返回一句 Gemini 接入成功提示。"
          }
        ]
      }
    ]
  }'

7. 常用接口速查

8. 额度与用量查询

如果你想让用户自助确认当前令牌是否还有可用额度，可以调用：

curl https://api.gavinhub.online/api/usage/token/ \
  -H "Authorization: Bearer YOUR_API_KEY"

返回结果中通常会包含：

• total_granted：总额度
• total_used：已使用额度
• total_available：剩余额度
• expires_at：过期时间

9. 常见问题

401 Unauthorized / Invalid token

• API 令牌是否复制完整
• 是否把 Authorization 写成了 Bearer YOUR_API_KEY
• 令牌是否已过期、被禁用或额度耗尽
• Claude 或 Gemini 原生格式是否把密钥放到了正确的请求头

404 Not Found

• 把 base_url 配成了根域名，但 SDK 又自动补了 /v1
• 直接访问了不存在的路径，例如 /chat/completions 而不是 /v1/chat/completions

429 Too Many Requests

• 降低请求并发
• 加入指数退避重试
• 联系平台管理员确认限流策略

返回“模型不存在”或“无权限”

• 模型名称拼写错误
• 当前令牌没有该模型的调用权限
• 后端暂未给你的分组分配该模型

10. 安全建议

• 不要把 API 令牌写死在前端页面或公开仓库中
• 服务端保存令牌时，优先使用环境变量或密钥管理服务
• 如无必要，不建议把高权限令牌共享给多个应用
• 如怀疑令牌泄露，请立即在控制台删除并重新生成

11. 对接建议

1. 先用 curl 验证令牌、域名和模型名
2. 再切换到你的业务 SDK
3. 最后再开启流式输出、函数调用、多模态等高级能力