面向开发者的 OpenAI API：使用兼容接口

简短说明

大多数关于面向开发者的 openai api的指南都假设只有一家供应商和一张账单。但传输格式只是 HTTPS 上的 JSON，许多客户端代码、框架和工具都可以与实现该格式的任何服务器通信。本站托管了这样一个服务器。你保留自己的 SDK，更改 Base URL，替换来自本站的密钥，并将模型设置为uncensored。

这就是典型应用的全部迁移步骤。以下是检查清单，页面其余部分将详细说明每一步。

1. 创建账户并在API 密钥页面领取试用额度。
2. 将 Base URL 设置为https://api.openaigatewayapi.com/v1。
3. 将密钥作为Authorization: Bearer <key>发送。当你传递api_key时，SDK 会自动处理此步骤。
4. 在每个请求中使用uncensored作为模型 ID。
5. 处理 HTTP 429 错误，如页面末尾所示进行短延迟重试。

存在两个接口：POST /v1/chat/completions 和 GET /v1/models。服务仅支持文本。没有图像或音频生成、没有嵌入和微调，所以如果你的应用调用这些功能，它们需要不同的提供商。

使用 curl 检查连接

在修改应用前，先确认密钥是否有效。模型接口是成本最低的测试方式，因为它不生成 token。

Copyexport API_KEY="paste-your-key-here"

curl https://api.openaigatewayapi.com/v1/models \
  -H "Authorization: Bearer $API_KEY" | grep -o uncensored

如果列表包含该 ID，grep 会打印模型 ID uncensored；去掉 grep 即可看到完整的 JSON 列表。如果收到 401 错误，说明密钥错误或缺少 Bearer 前缀。现在发送一个真实请求：

Copycurl https://api.openaigatewayapi.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain idempotency keys in two sentences."}
    ],
    "temperature": 0.4
  }'

响应包含通常的 choices 和 usage 对象。它还包含值得记录的标头：X-Request-Id 用于支持问题，X-Balance-USD 显示你的剩余预付额度，以及显示你的请求和并发上限的两个 X-RateLimit-Limit-* 标头。

使用官方 openai 包的 Python 示例

在 Python 中，你只需处理客户端构造函数。之后的代码都是你已有的代码。

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You write short, accurate release notes."},
        {"role": "user", "content": "Summarise: added retry logic, fixed timeout bug."},
    ],
    temperature=0.5,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

在实际代码中从环境变量读取密钥。示例硬编码仅为了保持代码片段简短。max_tokens 是可选的；如果省略它，补全部分可以使用 100,000 token 上下文窗口的剩余配额（提示词和补全部分合计）。设置它也是控制失控生成成本的一种廉价方式。

流式输出

流式输出使用服务器发送事件和你知道的相同 stream=True 标志。统计信息在流结束时送达，因此最后一个块可能包含空的 choices 列表。

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "List five edge cases for a date parser."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if getattr(chunk, "usage", None):
        print("\ntokens:", chunk.usage.total_tokens)

容量规划需注意一个细节。流式请求会占用并发槽位，直到流结束，而不仅仅是第一个 token。如果客户端在未关闭流的情况下放弃，该槽位会占用比预期更长的时间。

Node.js 示例

Node SDK 使用不同的名称接受相同的两项设置。

Copyimport OpenAI from "openai";

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

const completion = await client.chat.completions.create({
  model: "uncensored",
  messages: [
    { role: "user", content: "Write a regex that matches ISO 8601 dates, and explain it." },
  ],
  temperature: 0.3,
});

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

如果你使用具有自己 OpenAI 集成的框架，请在其设置中查找名为 base URL、API base 或 endpoint 的字段。将相同的 URL 粘贴到那里通常就足够了。聊天前端、代理框架和编辑器插件大多遵循此模式。采样参数如 temperature、top_p、stop、seed 以及频率和存在惩罚将传递给模型。

工具调用和 JSON 模式

决定模型是否适用于真实应用的两个功能是：调用你的函数和返回可解析的数据。两者均受支持。

函数调用

你使用 tools 声明工具，可选地使用 tool_choice 强制选择，并使用 role: "tool" 将结果作为消息发送。流式响应以片段形式交付 tool_calls，与标准格式一样。

Copyimport json
from openai import OpenAI

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up the status of an order by its ID.",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = {"order_id": args["order_id"], "status": "shipped"}  # your real lookup here
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)

在根据参数执行操作前，务必先验证参数。模型生成的 JSON 大多时候符合你的 schema，但并非总是如此，因此请将 call.function.arguments 视为任何不可信输入来处理。

JSON 模式

对于提取和分类任务，请求 JSON 对象并在提示词中说明。在指令中提及 JSON 比仅依赖标志能获得更好的结果。

Copyfrom openai import OpenAI
import json

client = OpenAI(base_url="https://api.openaigatewayapi.com/v1", api_key="paste-your-key-here")

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with JSON only: {\"sentiment\": string, \"topics\": [string]}."},
        {"role": "user", "content": "The docs are clear but the rate limits caught me off guard."},
    ],
)
data = json.loads(resp.choices[0].message.content)
print(data)

限制、错误和重试

完整密钥允许 8 个请求进行中，每分钟 300 个请求。试用密钥允许 2 个请求进行中，每分钟 60 个请求。最大请求体为 8 MB。超过限制时，你会收到 HTTP 429 错误，错误代码会告诉你具体是哪个限制。

错误代码	含义	该做什么
rate_limited	每分钟请求过多	减慢生产者速度或将工作均匀分布在一分钟内
concurrency	同时请求过多	将 worker 数量降低至 8 或更少，或在试用密钥上降低至 2
429 且 Retry-After: 5	临时过载	等待指定的秒数后重试

SDK 已经重试某些失败。添加你自己的 429 处理逻辑，以便突发不会导致批处理作业崩溃：

Copyimport time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.openaigatewayapi.com/v1",
    api_key="paste-your-key-here",
    max_retries=0,
)

def ask(prompt, attempts=5):
    for i in range(attempts):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            wait = float(e.response.headers.get("retry-after", 2 ** i))
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

失败或被拒绝的请求不会收费，因此重试循环不会使你的账单翻倍。将信号量大小设置为匹配你的并发限制是在异步代码中保持在上限之下的最简洁方式。

迁移现有应用

如果你有正在运行的应用，不要硬编码新值。将基础 URL、密钥和模型名称放入环境变量中，以便在不部署的情况下切换环境。这也允许你对两个后端运行相同的测试套件并并排比较输出。

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.openaigatewayapi.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def complete(messages, **kw):
    return client.chat.completions.create(model=MODEL, messages=messages, **kw)

然后执行简短的迁移流程：

1. 将现有提示词集针对新接口运行，并自行读取输出。自动化检查可捕获格式错误，但无法捕获语气问题。
2. 检查任何解析 JSON 的代码在设置 response_format 时是否仍然有效，并保留一个剥离对象周围多余文本的回退机制。
3. 从 usage 测量真实的 token 计数，因为不同的模型以不同方式对文本进行分词，你之前的估算可能不准确。
4. 将 worker 池设置为 8 或更少，以便在负载下并发上限不会成为第一个失败的因素。
5. 向一小部分流量发布，观察 429 错误率和错误日志，然后扩大范围。

团队在此过程中常忽略系统提示词。旨在温和地引导易拒绝模型正常表现的提示词通常包含在此处多余且会干扰输出的修饰语。重新阅读你的提示词并删除不再起作用的部分。

切换前须知

兼容性涵盖请求和响应格式。这并不意味着它是任何模型制造商的官方 API。该服务运行一个开放权重模型，由独立提供商托管，并经过调整以在不拒绝内容的情况下回答，适用于合法的成人用途。它不是跨供应商的路由器，因此你不会在其后面找到其他模型的菜单。涉及未成年人的性内容是不允许的，且该限制不可更改。

围绕与大型多模型平台的三个实际差异进行规划：

• 一个模型。 ID 是 uncensored。如果你的代码按任务切换模型，将其折叠为一个值。
• 仅文本。 从指向此接口的路径中移除任何图像、音频或嵌入调用。
• 提示词行为不同。 不同的模型以不同方式读取指令，因此在切换后重新运行提示词和测试。如果输出偏离，请收紧系统提示词。

提示词不用于训练。完整参数列表请参阅API 文档。如果你正在估算支出，定价页面 列出了每 token 费率：输入 token 每 1M 0.15$，输出 token 每 1M 0.50$，从预付额度中计费，无订阅。充值金额从 20$ 到 500$ 不等，额度永不失效。如果你正在考虑在多个服务前设置代理层，LLM 网关 页面涵盖了何时值得增加这个额外组件。

更多指南

• 通俗易懂地解释 OpenAI Gateway API
• OpenAI Gateway API 定价：真实成本示例
• LLM 网关：成本与复杂性分析