OpenAI API 接入教程：Base URL 停在 /v1，每步有通过标准

OpenAI API 接入最稳妥的顺序是：先用一条可观察的 HTTP 请求确认地址、鉴权和模型，再接入 SDK；不要一开始就把网关、框架、代理和业务代码一起调试。

“ChatGPT 中转 API”通常指 OpenAI 风格的程序接口，不等于 ChatGPT 网页订阅。本文同时区分 OpenAI 兼容 API、官方 Responses 与 Chat Completions，避免把产品账户、协议和计费边界混在一起。

export GPTZZZ_BASE_URL="https://gptzzz.ai/v1"
export GPTZZZ_API_KEY="YOUR_GPTZZZ_API_KEY"
export GPTZZZ_MODEL="gpt-5.5"

curl --fail-with-body -sS -D /tmp/gptzzz-openai-headers.txt \
  "$GPTZZZ_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $GPTZZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$GPTZZZ_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"只回复 OPENAI_OK\"}],\"stream\":false}"

$env:GPTZZZ_BASE_URL = "https://gptzzz.ai/v1"
$env:GPTZZZ_API_KEY = "YOUR_GPTZZZ_API_KEY"
$env:GPTZZZ_MODEL = "gpt-5.5"

$body = @{
  model = $env:GPTZZZ_MODEL
  messages = @(@{ role = "user"; content = "只回复 OPENAI_OK" })
  stream = $false
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post -Uri "$env:GPTZZZ_BASE_URL/chat/completions" `
  -Headers @{ Authorization = "Bearer $env:GPTZZZ_API_KEY" } `
  -ContentType "application/json; charset=utf-8" `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

OpenAI 官方当前基线：Responses API

OpenAI 官方建议新文本项目使用 Responses API。先在官方端点完成基线，再测试中转站是否真的实现 /responses；“Chat Completions 可用”不能证明 Responses 兼容。

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

curl --fail-with-body -sS \
  "https://api.openai.com/v1/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6","input":"Reply with exactly: OPENAI_OK"}'

import os
from openai import OpenAI

official = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)
response = official.responses.create(
    model="gpt-5.6",
    input="Reply with exactly: OPENAI_OK",
)
if response.status != "completed" or not response.output_text.strip():
    raise RuntimeError(f"unexpected response status={response.status!r}")
print(response.output_text)
print(response._request_id)

Responses 的 output 可能包含 reasoning、工具调用或多个消息项，不要硬编码 output[0].content[0].text；SDK 的 output_text 会聚合文本。模型参数支持范围仍取决于具体模型。

Base URL 与完整接口路径的边界

“Base URL”和“完整 Endpoint”不是同一字段。OpenAI SDK 的 base_url 应停在版本根，调用 chat.completions.create() 后由 SDK 追加 chat/completions。若某客户端明确要求完整 Endpoint，才填资源路径。

核对 OpenAI Base URL 时，先确认客户端字段要求 API 根还是完整 Endpoint；官方 SDK 应填版本根，中转 SDK 示例同样停在 /v1。

Python SDK：请求与响应验证

安装官方 SDK，并显式传入中转站配置：

python -m pip install -U openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GPTZZZ_API_KEY"],
    base_url=os.environ.get("GPTZZZ_BASE_URL", "https://gptzzz.ai/v1"),
    timeout=90.0,
    max_retries=2,
)

response = client.chat.completions.create(
    model=os.environ["GPTZZZ_MODEL"],
    messages=[{"role": "user", "content": "只回复 OPENAI_OK"}],
)

choice = response.choices[0]
if not response.id or not response.model or not choice.message.content:
    raise RuntimeError(f"unexpected response: {response.model_dump_json()}")
if choice.finish_reason not in {"stop", "length", "tool_calls", "content_filter"}:
    raise RuntimeError(f"unexpected finish_reason={choice.finish_reason!r}")

print(choice.message.content)
print({
    "response_id": response.id,
    "request_id": response._request_id,
    "model": response.model,
    "finish_reason": choice.finish_reason,
    "total_tokens": response.usage.total_tokens if response.usage else None,
})

示例接受多个合法结束原因，是为了避免把“输出达到上限”或“模型请求工具”误判成传输错误；业务仍需按任务契约分别处理。

OpenAI 流式输出怎样验收

官方 Responses 流是 SSE，常见事件包括 response.created、response.output_text.delta、response.completed 与 error：

completed = False
for event in official.responses.create(
    model="gpt-5.6",
    input="Say hello.",
    stream=True,
):
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        completed = True
    elif event.type == "error":
        raise RuntimeError(str(event))
if not completed:
    raise RuntimeError("Responses stream did not complete")

中转站若只实现 Chat Completions，则使用下面的兼容流探针；两种事件模型不要混用：

stream = client.chat.completions.create(
    model=os.environ["GPTZZZ_MODEL"],
    messages=[{"role": "user", "content": "分三点解释 API 网关"}],
    stream=True,
    stream_options={"include_usage": True},
)

finished = False
total_tokens = None
for chunk in stream:
    if chunk.usage is not None:
        total_tokens = chunk.usage.total_tokens
    if not chunk.choices:
        continue
    choice = chunk.choices[0]
    if choice.delta.content:
        print(choice.delta.content, end="", flush=True)
    if choice.finish_reason is not None:
        finished = True
        print(f"\nfinish_reason={choice.finish_reason}")

if not finished or total_tokens is None:
    raise RuntimeError("stream ended without finish_reason or usage")
print(f"usage.total_tokens={total_tokens}")

兼容网关常使用 data-only SSE。客户端需要处理空增量、工具调用增量、正常结束、用户取消和 HTTP 200 之后的流内错误。只有消费到协议终点，结果才能记为完整。

自定义模型与 OpenAI 兼容边界

Model ID 不是营销名称。先从目标平台的模型列表或控制台复制可用 ID，再把请求模型、响应模型、日期和网关路由记录在同一条证据中。

401、404、429 与流式中断排查

迁移旧客户端前先看 OpenAI 兼容 API 迁移清单；密钥存储参考 API Key 安全指南；工具与流式语义用 兼容性测试矩阵复验；状态码分层见 API 中转站错误码排查。

验证指标与回滚

固定 20 条短请求与 5 条流式请求，记录成功率（完整结束数 ÷ 总请求数）、TTFT、总耗时、HTTP 状态、finish_reason、输入/输出 Token、重试次数和 request ID。切换前保存旧 Base URL、Key 变量名、Model ID 与 SDK 版本。

1. 停止在途请求，避免同一业务动作在两个端点重复执行。
2. 恢复旧 Base URL、旧模型与旧凭据来源，不复用中转 Key。
3. 关闭连接池并启动新进程，重新运行同一条 curl 和 Python 基线。
4. 只有完整结束率、错误语义和用量恢复后才结束回滚。

官方资料

• OpenAI API Quickstart
• OpenAI API Overview
• OpenAI Text generation / Responses
• OpenAI Streaming API responses
• OpenAI Python SDK reference
• OpenAI API error codes