快速开始

EnHeng AI 提供兼容 OpenAI 和 Anthropic 的 API 接口,一个 sk-enheng-* Key 可同时调用 GPT、Claude、Gemini 等模型。

Base URLhttps://api.enheng.ai/v1
1
注册账号
免费注册后进入控制台
2
创建 API Key
在控制台生成专属 Key
3
开始调用
替换 base_url,无缝切换

对话补全示例

import openai

client = openai.OpenAI(
    api_key="sk-enheng-xxxxxxxx",
    base_url="https://api.enheng.ai/v1"
)

response = client.chat.completions.create(
    model="claude-4-sonnet",
    messages=[
        {"role": "user", "content": "你好,介绍一下自己"}
    ]
)

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

一个 Key 通用所有模型

控制台生成的 sk-enheng-* 是通用 Key,不需要分别创建 ChatGPT Key、Claude Key、Gemini Key。不同客户端只需要使用对应的 Base URL 和 Header 名称。

OpenAI SDK
/v1/chat/completions
Authorization: Bearer
Claude Code
/v1/messages
ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY / x-api-key
Gemini 模型
/v1/chat/completions
Authorization: Bearer
OPENAI_API_KEY=sk-enheng-xxxxxxxx
OPENAI_BASE_URL=https://api.enheng.ai/v1

# 同一个 Key 可调用 GPT、Claude、Gemini 等模型
curl https://api.enheng.ai/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role":"user","content":"你好"}]
  }'
Key 是否能调用某个模型,还会受余额、Key 限额、IP 白名单、allowed_models 和后台 provider 路由健康度影响。

认证方式

OpenAI 兼容接口建议通过 HTTP Authorization Header 传递 Bearer Token;Anthropic 兼容工具也可以使用 x-api-keyANTHROPIC_AUTH_TOKEN

HTTP Header
Authorization: Bearer sk-enheng-xxxxxxxx
⚠️ API Key 请勿提交至代码仓库,建议通过环境变量 ENHENG_API_KEY 注入。

API 端点

所有端点均兼容 OpenAI API 规范,可直接使用 openai 官方 SDK 调用。

POST/v1/chat/completions

参数

modelstring必填模型 ID,如 gpt-4o、claude-4-sonnet
messagesarray必填对话消息数组,包含 role 和 content
streamboolean可选是否启用流式输出,默认 false
temperaturenumber可选随机性,范围 0-2,默认 1
max_tokensnumber可选最大输出 Token 数
top_pnumber可选核采样概率,范围 0-1
POST/v1/messages

参数

modelstring必填Claude 模型 ID,如 claude-opus-4-7、claude-sonnet-4-6
messagesarray必填Anthropic messages 数组
streamboolean可选是否启用 Anthropic SSE 流式输出
max_tokensnumber可选最大输出 Token 数
POST/v1/messages/count_tokens

参数

modelstring必填Claude 模型 ID
messagesarray必填待估算的消息数组
GET/v1/models
GET/v1/usage

参数

start_datestring可选开始日期,格式 YYYY-MM-DD
end_datestring可选结束日期,格式 YYYY-MM-DD
POST/v1/responses
POST/v1/embeddings
POST/v1/images/generations
POST/v1/audio/speech
POST/v1/audio/transcriptions
POST/v1/rerank

智能路由参数

provider 参数兼容 OpenRouter 风格,可控制优先 provider、排序、fallback、价格上限和 ZDR 要求。响应会返回实际 provider、上游模型和 route trace;流式请求同样会在响应 header 返回。

provider.order:按顺序优先尝试 provider。
provider.sort:price / latency / throughput。
provider.only:只走指定 provider。
provider.ignore:排除指定 provider。
provider.allow_fallbacks:false 时禁用 fallback。
provider.max_price:限制输入/输出 USD / 1M tokens。
const response = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "美光会不会崩盘,为什么?" }],
  provider: {
    sort: "latency",                 // price | latency | throughput
    order: ["ai-openclaw", "aiincs"],
    allow_fallbacks: true,
    max_price: { input: 1.0, output: 6.0 }, // USD / 1M tokens
    ignore: ["unstable-provider"]
  }
});

console.log(response.provider);
console.log(response.route.trace);

多模态接口

当前已开放 embeddings、images、audio、rerank、responses 的 OpenAI 兼容代理入口。PDF 可先在客户端提取文本后走 chat/responses;图片输入通过支持 vision 的 chat 模型传入 content parts。

curl https://api.enheng.ai/v1/embeddings \
  -H "Authorization: Bearer sk-enheng-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"text-embedding-3-small","input":"EnHengAI 是一个 AI API 中转站"}'

模型列表

以下是当前支持的全部模型 ID,直接填入 model 参数即可调用。

import openai

client = openai.OpenAI(
    api_key="sk-enheng-xxxxxxxx",
    base_url="https://api.enheng.ai/v1"
)

# 列出所有可用模型
models = client.models.list()
for model in models.data:
    print(model.id)
Model ID供应商
gpt-4oOpenAI
gpt-4o-miniOpenAI
o1OpenAI
o3-miniOpenAI
claude-4-sonnetAnthropic
claude-4-opusAnthropic
claude-3.5-haikuAnthropic
gemini-2.5-proGoogle
gemini-2.5-flashGoogle
deepseek-r1DeepSeek
deepseek-v3DeepSeek
llama-4-maverickMeta
mistral-largeMistral

流式输出

设置 stream: true 即可启用服务端推送(SSE),实现打字机效果,显著改善用户体验。

import openai

client = openai.OpenAI(
    api_key="sk-enheng-xxxxxxxx",
    base_url="https://api.enheng.ai/v1"
)

with client.chat.completions.stream(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一首关于AI的诗"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

用量查询

每次 API 响应的 usage 字段包含本次请求的 Token 消耗明细。

响应示例(usage 字段)
{
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 156,
    "total_tokens": 184
  }
}

详细用量统计可在 控制台 → 使用日志 中查看,支持按时间、模型、Key 筛选。

迁移指南

改两行代码,0 成本迁移。EnHeng AI 完全兼容 OpenAI SDK,无需更换任何库。

从官方 OpenAI 迁移

之前(官方)
client = openai.OpenAI(
    api_key="sk-官方key",
    # 无需 base_url
)
之后(EnHeng AI)
client = openai.OpenAI(
    api_key="sk-enheng-xxxxxx",
    base_url="https://api.enheng.ai/v1"
)

从其他中转站迁移

同样只需替换 api_keybase_url 两个参数。模型 ID 格式与 OpenAI 标准一致。

# 替换这两行即可完成迁移
import openai
client = openai.OpenAI(
    api_key="sk-enheng-xxxxxxxx",          # 换成你的 EnHeng AI Key
    base_url="https://api.enheng.ai/v1",   # 换成 EnHeng AI 端点
)
# 其余代码完全不用改 ✓

工具集成

EnHeng AI 兼容所有支持自定义 API Endpoint 的 AI 工具,以下为常用工具的接入方式。

⌨️ Cursor

  1. 1打开 Cursor → Settings → Models
  2. 2在 OpenAI API Key 填入 sk-enheng-xxxxxxxx
  3. 3在 Override OpenAI Base URL 填入 https://api.enheng.ai/v1
  4. 4点击 Save,重启 Cursor 即可生效

Vercel AI SDK

  1. 1设置 OPENAI_API_KEY=sk-enheng-xxxxxxxx
  2. 2设置 OPENAI_BASE_URL=https://api.enheng.ai/v1
  3. 3在代码中使用 openai.chat(model) 或自定义 OpenAI provider
  4. 4生产环境建议开启 provider.allow_fallbacks 与超时重试

CLI Claude Code

  1. 1打开或创建 ~/.claude/settings.json
  2. 2在 env 中设置 ANTHROPIC_AUTH_TOKEN=sk-enheng-xxxxxxxx
  3. 3同时设置 ANTHROPIC_API_KEY=sk-enheng-xxxxxxxx 兼容不同版本
  4. 4设置 ANTHROPIC_BASE_URL=https://api.enheng.ai/v1
  5. 5模型选择 claude-opus-4-7 或 claude-sonnet-4-6
  6. 6同一个 Key 的余额、限额、IP 限制与 OpenAI 兼容接口共用

🌐 OpenWebUI

  1. 1进入 Settings → Connections → OpenAI API
  2. 2API Base URL 填写 https://api.enheng.ai/v1
  3. 3API Key 填写 sk-enheng-xxxxxxxx
  4. 4点击保存,在对话页选择模型即可

🍒 Cherry Studio

  1. 1Settings → 模型服务 → 添加 OpenAI 兼容服务
  2. 2API 地址填写 https://api.enheng.ai/v1
  3. 3填写 API Key,点击测试连接
  4. 4测试成功后在对话中选择服务商即可

💬 ChatBox

  1. 1设置 → AI 模型提供方 → OpenAI API
  2. 2API Host 填写 https://api.enheng.ai/v1
  3. 3API Key 填写 sk-enheng-xxxxxxxx
  4. 4保存后选择模型即可使用

🦜 LangChain / LlamaIndex

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="claude-4-sonnet",
    api_key="sk-enheng-xxxxxxxx",
    base_url="https://api.enheng.ai/v1",
)

response = llm.invoke("你好,介绍一下自己")
print(response.content)

BYOK 高级能力

BYOK 控制面支持用户保存自己的 OpenAI、Anthropic、Google、DeepSeek、Qwen、GLM provider key。Key 使用服务端 AES-GCM 加密保存,只展示 prefix/suffix;未配置 BYOK_ENCRYPTION_KEY 时保存接口会拒绝请求。

curl https://enheng.ai/api/user/provider-keys \
  -H "Content-Type: application/json" \
  -b "你的登录 Cookie" \
  -d '{"provider":"openai","api_key":"sk-your-upstream-key"}'
当前 BYOK 已具备安全存储与管理接口;实际路由使用 BYOK 需在后台为对应 provider 开启 BYOK 通道,避免用户 Key 被错误路由到非官方 endpoint。

错误码速查

遇到报错时,先查错误码,90% 的问题 5 分钟内可自行解决。

状态码error_code
400INVALID_REQUEST
400CONTEXT_TOO_LONG
401KEY_MISSING
401KEY_INVALID / KEY_EXPIRED / KEY_REVOKED
404MODEL_NOT_FOUND
429RATE_LIMITED_RPM
429RATE_LIMITED_TPM
429QUOTA_EXCEEDED
500INTERNAL_ERROR
502UPSTREAM_ERROR
503MODEL_UNAVAILABLE
504UPSTREAM_TIMEOUT

错误响应结构(所有接口统一)

{
  "error": {
    "request_id": "550e8400-e29b-41d4-a716-...",  // 用于工单排查
    "error_code": "RATE_LIMITED_RPM",
    "message": "请求频率超出限制(RPM)",
    "retryable": true,
    "retry_after_ms": 3000  // 仅 retryable=true 时出现
  }
}

生产环境最佳实践

为保证在高并发与不稳定网络条件下的稳定性,建议遵循以下实践。

1. 超时设置

连接超时(connect timeout)建议 3~5 秒;读取超时(read timeout)按模型和任务类型分开配置。对长文本/推理任务建议更高读取超时,并配合流式输出。

场景连接超时读取超时
轻量模型(Haiku、GPT-4o Mini)5s10s
标准模型(GPT-4o、Sonnet)5s30s
推理模型(o1、R1)5s120s
流式请求(SSE)5s首 Token 10s + 总 300s

2. 指数退避重试

只对可重试的错误重试(429/500/502/503),幂等请求才可重试。

import time, openai

def call_with_retry(client, **kwargs):
    max_retries = 3
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except openai.RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt   # 1s, 2s, 4s
            print(f"Rate limited, retrying in {wait}s...")
            time.sleep(wait)
        except openai.APIStatusError as e:
            if e.status_code in (500, 502, 503) and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise

3. 模型降级(Fallback)

主模型不可用时自动切换备用模型,保证请求成功率。

FALLBACK_CHAIN = [
    "claude-4-sonnet",   # 主模型
    "gpt-4o",            # 备选1
    "gemini-2.5-pro",    # 备选2
    "deepseek-v3",       # 备选3(成本最低)
]

def call_with_fallback(client, messages):
    last_error = None
    for model in FALLBACK_CHAIN:
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                timeout=30,
            )
        except (openai.APIStatusError, openai.APIConnectionError) as e:
            print(f"Model {model} failed: {e}, trying next...")
            last_error = e
    raise last_error

4. 熔断器模式

避免持续打压已故障的模型,让服务有时间恢复。

import time
from collections import defaultdict

class CircuitBreaker:
    def __init__(self, failure_threshold=5, recovery_timeout=60):
        self.failures = defaultdict(int)
        self.last_failure_time = {}
        self.failure_threshold = failure_threshold
        self.recovery_timeout = recovery_timeout  # seconds

    def is_open(self, model: str) -> bool:
        """True = 熔断中,不应发请求"""
        if self.failures[model] < self.failure_threshold:
            return False
        elapsed = time.time() - self.last_failure_time.get(model, 0)
        if elapsed > self.recovery_timeout:
            self.failures[model] = 0  # 半开状态,允许重试
            return False
        return True

    def record_failure(self, model: str):
        self.failures[model] += 1
        self.last_failure_time[model] = time.time()

    def record_success(self, model: str):
        self.failures[model] = 0

cb = CircuitBreaker()

def safe_call(client, model, messages):
    if cb.is_open(model):
        raise Exception(f"{model} is circuit-broken, skip")
    try:
        result = client.chat.completions.create(model=model, messages=messages)
        cb.record_success(model)
        return result
    except Exception as e:
        cb.record_failure(model)
        raise

5. 请求 ID 追踪

每次请求带上唯一 ID,方便排查问题时定位具体请求。

import uuid

request_id = str(uuid.uuid4())

response = client.chat.completions.create(
    model="claude-4-sonnet",
    messages=[{"role": "user", "content": "hello"}],
    extra_headers={"X-Request-ID": request_id},
)

# 如果出问题,把 request_id 发给支持团队
print(f"Request ID: {request_id}")

6. 错误处理规范

统一错误处理结构,前端展示遵循"用户可理解 + 可追踪"原则。

可重试状态码408, 429, 500, 502, 503, 504
不建议重试400, 401, 403, 404
错误结构必含字段request_id · status_code · error_code · message · retryable
前端展示示例请求失败(可重试),追踪 ID: req_xxxxxxxx

7. 速率限制与并发控制

客户端增加本地限流,避免突发打爆配额,对高成本模型设置并发上限与预算上限。

import threading, time

class TokenBucket:
    def __init__(self, rate=10, burst=20):  # rate: 每秒补充, burst: 最大积攒
        self.tokens = burst
        self.rate = rate
        self.burst = burst
        self.last = time.monotonic()
        self.lock = threading.Lock()

    def acquire(self):
        with self.lock:
            now = time.monotonic()
            self.tokens = min(self.burst, self.tokens + (now - self.last) * self.rate)
            self.last = now
            if self.tokens >= 1:
                self.tokens -= 1
                return True
            return False  # 被限流,调用方应等待或排队

bucket = TokenBucket(rate=10, burst=20)  # 10 RPM 客户端限流

8. 安全建议

  • API Key 只存服务端,不下发到前端或客户端代码
  • 使用环境变量管理密钥,定期轮换(建议每 90 天)
  • 为不同业务线使用不同子 Key(权限与额度隔离)
  • 对回调/Webhook 启用签名校验,防止伪造通知
  • 设置月度 Token 用量上限,防止密钥泄露导致超支

9. 观测与告警

建议至少监控以下指标,并设置告警阈值:

必监控指标

  • ·成功率(2xx 占比)
  • ·错误码分布(429 / 5xx)
  • ·P50 / P95 延迟
  • ·每模型调用量与成本
  • ·降级触发次数

推荐告警阈值

  • 5 分钟成功率 < 98%
  • P95 延迟 > 8s
  • 429 占比 > 3%
  • 单 Key 日成本超预算 80%
  • 降级触发 > 3 次/小时

10. 版本升级策略

  • 固定 SDK 版本(package.json lockfile),避免自动升级导致行为变化
  • 在灰度环境验证新版本后再全量发布(金丝雀比例 5% → 50% → 100%)
  • 记录每次升级的变更日志与回滚方案
  • 重要模型 ID 更新前订阅状态页公告,避免被动感知

📋 生产上线检查清单

  • ✅ 设置了连接超时(5s)和读取超时(按模型分类)
  • ✅ 实现了指数退避重试(408/429/5xx,含随机 jitter)
  • ✅ 配置了 Fallback 模型链(至少 2 个备选)
  • ✅ 关键请求生成 request_id,重试时保持同一 ID
  • ✅ 每条请求携带 X-Request-ID Header 便于服务端追踪
  • ✅ 客户端实现本地令牌桶限流,防止突发打爆配额
  • ✅ API Key 只在服务端,不出现在前端或版本控制
  • ✅ 订阅了状态页通知(邮件或 Webhook)
  • ✅ Key 设置了月度 Token 用量上限防超支
  • ✅ 关键指标(成功率/延迟/成本)已接入告警