快速开始
快速开始
平台提供统一的 OpenAI 兼容 API,一个 API Key 即可访问 Claude、GPT、Gemini 等主流模型。 现有 OpenAI 代码只需更改 base_url,无需任何其他修改。
| 接入方式 | 适用场景 |
|---|---|
| OpenAI SDK | 已有 OpenAI 代码,直接替换 base_url 即可,零改动 |
| HTTP 直接请求 | 任意语言,无依赖,完全控制请求细节 |
| 第三方客户端 | Claude Code、Claude Desktop、QClaw、WorkBuddy 等,参见「客户端集成」 |
步骤一:获取 API Key
登录控制台,进入「API 密钥」页面,点击「新建密钥」。密钥只在创建时完整展示一次,请立即复制保存。
export HY_API_KEY="sk-hy-xxxxxxxxxxxx"推荐通过环境变量注入密钥,避免将 API Key 硬编码到源码中。
步骤二:使用 OpenAI SDK
安装 OpenAI 官方 SDK,将 base_url / baseURL 指向平台即可,模型名称直接使用平台的模型 ID。
pip install openaiimport os
from openai import OpenAI
client = OpenAI(
base_url="https://apiclaw.cc/v1",
api_key=os.environ["HY_API_KEY"],
)
completion = client.chat.completions.create(
model="claude-sonnet-4-6",
messages=[{"role": "user", "content": "你好,介绍一下你自己"}],
)
print(completion.choices[0].message.content)步骤三:HTTP 直接请求
无需任何 SDK,向 /v1/chat/completions 发送标准 POST 请求即可。
curl -X POST https://apiclaw.cc/v1/chat/completions \
-H "Authorization: Bearer $HY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"messages": [
{ "role": "user", "content": "你好,介绍一下你自己" }
]
}'流式响应
添加 stream=True 即可切换为 Server-Sent Events 流式输出,适合长文本生成和实时交互场景。
import os
from openai import OpenAI
client = OpenAI(
base_url="https://apiclaw.cc/v1",
api_key=os.environ["HY_API_KEY"],
)
with client.chat.completions.stream(
model="claude-sonnet-4-6",
messages=[{"role": "user", "content": "写一首关于春天的短诗"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)Base URL
不同接口格式使用不同路径前缀。OpenAI 兼容 SDK 配置到 /v1 即可。
OpenAI 兼容
https://apiclaw.cc/v1
适用于 OpenAI SDK、LangChain、LiteLLM 等生态工具。
Claude 原生
https://apiclaw.cc
适用于 Anthropic SDK 的 Messages API 原生调用。
Gemini 原生
https://apiclaw.cc
适用于 generateContent 等 Gemini 原生路径。
认证方式
平台 API Key 统一由控制台发放,不同接口沿用各供应商惯用的请求头格式。
| 接口类型 | 请求头 | 说明 |
|---|---|---|
| OpenAI 兼容 | Authorization: Bearer {API_KEY} | OpenAI SDK 默认格式,Bearer Token |
| Claude 原生 | x-api-key: {API_KEY} | Anthropic SDK 默认,无需 Bearer 前缀 |
| Gemini 原生 | x-goog-api-key: {API_KEY} | Google SDK 默认,无需 Bearer 前缀 |
常见错误排查
遇到问题时先对照下表排查。
| 状态码 | 常见原因 | 解决方式 |
|---|---|---|
| 401 Unauthorized | API Key 不存在或已失效 | 在控制台重新生成 API Key,确认 Authorization 请求头格式为 Bearer <key>。 |
| 403 Forbidden | 密钥无权访问该模型 | 检查 API Key 绑定的权限,或在控制台「模型管理」页面开放对应模型。 |
| 404 Model Not Found | 模型 ID 拼写错误或未上线 | 在控制台「模型管理」确认模型 ID 及可用状态。 |
| 429 Rate Limit | 请求频率或并发超出限制 | 降低请求频率,或联系客服申请提升配额。建议添加指数退避重试。 |
| 500 / 502 | 上游模型服务临时异常 | 通常短暂,稍后重试。持续出现请在控制台提交工单联系支持。 |

