快速开始

快速开始

平台提供统一的 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 openai
import 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 UnauthorizedAPI Key 不存在或已失效在控制台重新生成 API Key,确认 Authorization 请求头格式为 Bearer <key>。
403 Forbidden密钥无权访问该模型检查 API Key 绑定的权限,或在控制台「模型管理」页面开放对应模型。
404 Model Not Found模型 ID 拼写错误或未上线在控制台「模型管理」确认模型 ID 及可用状态。
429 Rate Limit请求频率或并发超出限制降低请求频率,或联系客服申请提升配额。建议添加指数退避重试。
500 / 502上游模型服务临时异常通常短暂,稍后重试。持续出现请在控制台提交工单联系支持。