OpenAI

OpenAI 通过 API 提供托管的 GPT 模型。应用通过稳定的 AISIX 别名调用这些模型，网关则确保 OpenAI 凭证不会出现在客户端代码中。

本指南涵盖通过同一个 OpenAI 服务提供方密钥承载的 GPT Chat 流量和 Sora 视频任务。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 从 OpenAI 平台获取的 OpenAI API Key。
• curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不带斜杠
# 本地 On-Premises 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为由 OpenAI 提供支持的路由创建服务提供方密钥、模型别名和调用方 API Key。

OpenAI 是网关原生支持的 OpenAI 兼容上游，该集成使用 openai 适配器。对于 OpenAI 规范端点，可以不设置 api_base；也可以设置该字段以指向保留 Bearer 身份认证和 OpenAI 路由形态的 OpenAI 兼容代理。

创建服务提供方密钥

创建用于存储 OpenAI 凭证的服务提供方密钥：

# 请替换为实际值
export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai-prod",
    "provider": "openai",
    "api_key": "'"${OPENAI_API_KEY}"'",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

❶ provider 为 openai。这是唯一允许 AISIX 回退到默认基础 URL https://api.openai.com/v1 的服务提供方值。

❷ api_key 存储 OpenAI API Key。该值在存储前会被加密，读取端点不会返回此值。其行为遵循服务提供方密钥中的凭证处理方式。

❸ allowed_environments 列出创建模型时可以引用该服务提供方密钥的环境。

AISIX Cloud Admin API 会从目录服务提供方派生适配器；仅 BYO 服务提供方密钥接受 adapter 字段。

对于 OpenAI，可以省略 api_base。如需指向兼容 Bearer 身份认证的代理或区域网关，请显式设置 api_base。Azure OpenAI 服务本身应使用专用的 Azure OpenAI 集成。该命令会将返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

创建调用方将在请求中发送的模型别名：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-5.6-sol-prod",
    "model_name": "gpt-5.6-sol",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是 OpenAI 模型 ID。本指南使用 OpenAI 模型目录中当前的旗舰模型 gpt-5.6-sol。如果其他当前模型的成本、延迟或模态更适合工作负载，请选择相应模型。

❸ provider_key_id 将别名关联到 OpenAI 服务提供方密钥。

创建调用方 API Key

创建可访问模型别名的调用方 API Key 资源。控制平面会生成密钥值，并仅在创建响应中返回一次明文：

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

allowed_models 值引用上一步获取的模型 ID。

请妥善保存明文密钥。控制平面仅存储哈希值；此响应之后无法再获取明文。

每次写入后，配置都会自动投射到已关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "openai-prod"
    provider: "openai"
    adapter: "openai"
    api_key: ${OPENAI_API_KEY}

models:
  - display_name: "gpt-5.6-sol-prod"
    provider: "openai"
    model_name: "gpt-5.6-sol"
    provider_key: "openai-prod"

api_keys:
  - display_name: "openai-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "gpt-5.6-sol-prod"

如果 AISIX 安装在本地，请在加载文件前进行验证：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from OpenAI."
      }
    ]
  }'

网关会返回 OpenAI 兼容响应，其中回显面向调用方的别名 gpt-5.6-sol-prod。请在 OpenAI 用量仪表板中确认该请求。如果请求因上游认证错误而失败，请检查服务提供方密钥的 api_key。

对于推理、工具调用和多轮工作流，OpenAI 建议使用 Responses API。通过同一别名发送原生 Responses 请求：

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol-prod",
    "input": "Say hello from the OpenAI Responses API."
  }'

由于模型配置的服务提供方是 openai，AISIX 会重写模型别名，并将请求转发到 OpenAI 原生 Responses 端点，而不会使用跨服务提供方的 Responses 桥接。

使用 Sora 生成视频

警告

OpenAI 已于 2026 年 3 月 24 日弃用 Videos API 和 Sora 2 系列模型，并将于 2026 年 9 月 24 日将其从 API 中移除。届时以 sora-2 或 sora-2-pro 为上游的别名将停止工作，OpenAI 也未在该 API 上给出替代模型。

同一个服务提供方密钥即可驱动网关建模的视频路由。创建第二个别名，指向 Sora 模型 sora-2 或 sora-2-pro：

在 AISIX Cloud 中创建视频别名和仅限该别名的调用方 Key：

VIDEO_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "sora-video-prod",
    "model_name": "sora-2",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$VIDEO_MODEL_ID"

VIDEO_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai-video-caller",
    "allowed_models": ["'"${VIDEO_MODEL_ID}"'"]
  }' | jq -r '.plaintext')

对于开源 AISIX 网关，请将 sora-video-prod 添加到现有 models 集合。将现有 openai-caller 条目替换为下面更新后的条目，使其允许两个模型别名。保留无关条目和集合：

resources.yaml（视频模型访问）

models:
  - display_name: "sora-video-prod"
    provider: "openai"
    model_name: "sora-2"
    provider_key: "openai-prod"

api_keys:
  - display_name: "openai-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "gpt-5.6-sol-prod"
      - "sora-video-prod"

按上文所述验证并重载或重启声明式资源文件，然后使用现有调用方 Key 发起视频请求：

export VIDEO_API_KEY="$CALLER_API_KEY"

提交任务：

curl -sS -X POST "$AISIX_PROXY/v1/videos" \
  -H "Authorization: Bearer ${VIDEO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-video-prod",
    "prompt": "A paper boat drifts down a rain-soaked street at dusk.",
    "seconds": 4,
    "size": "1280x720"
  }'

在为此路由编写脚本前，需要了解以下五项服务提供方特定行为：

• OpenAI 是唯一具有默认 Base URL 的视频服务提供方。 与本页的 Chat 别名一样，OpenAI 视频别名在未设置 api_base 时也能工作。其他视频服务提供方都要求在密钥上设置 api_base。
• seconds 和 size 由 Sora 自行校验。 OpenAI 的视频创建 schema 为 seconds 接受 4、8 或 12，为 size 列出 720x1280、1280x720、1024x1792 和 1792x1024，但各模型页面公布的分辨率范围更窄，请查阅别名所指模型的页面。AISIX 会将 seconds 以字符串形式转发，并在校验 size 的 WIDTHxHEIGHT 格式后原样转发，因此格式正确但该模型不接受的取值由服务提供方拒绝，而不是由网关拒绝。
• 已完成的视频经网关流式传输。 Sora 通过需要鉴权的内容端点交付成品文件，而不是签名 URL，因此 GET /v1/videos/{id}/content 返回 200 和 MP4 字节，而不是 302。AISIX 会使用服务提供方凭证获取文件并逐块转发，凭证不会到达调用方，大文件也不会增加网关内存用量。请据此规划网关的出口带宽：这些字节会经过网关，且不计入模型限流。
• progress 是真实百分比。 Sora 会报告任务进度，因此轮询响应会携带服务提供方自己的完成百分比。不报告进度的服务提供方在任务完成前保持 0。
• 图生视频需要透传路由。 标准化请求只建模 prompt、seconds 和 size；包括 input_reference 在内的其他字段会被忽略而不是拒绝，因此混剪或以图引导的请求会静默地只依据提示词生成。这类请求请通过 /passthrough/openai/v1/videos 发送原生 multipart 正文，原生混剪路由同理。OpenAI SDK 客户端同样只能走这条路径，但需要单独创建一个客户端：把它的 base URL 指向 ${AISIX_PROXY}/passthrough/openai/v1，而不是本页其他位置使用的 ${AISIX_PROXY}/v1，并在调用方 Key 的 allowed_routes 中授予该路由名称。其视频创建方法始终发送 multipart/form-data，而建模路由不接受该格式。透传不会返回统一的 AISIX 视频对象或网关编码的任务 ID。

完整的提交、轮询和下载工作流（包括状态语义和轮询时的限流行为）请参阅视频生成。

端点覆盖范围

OpenAI 提供多种使用不同模型类型的 API。请为应用所需的每个上游模型分别配置 AISIX 模型别名。

路由	使用 OpenAI 支持的别名时的行为
/v1/chat/completions	支持 OpenAI 请求和响应形态。仍需遵循模型特定的功能和参数限制。
/v1/responses	重写模型别名后转发到 OpenAI 原生 Responses 端点。有状态字段、托管工具、推理控制项和上游 SSE 均保留在原生路径上。
/v1/completions	转发到 OpenAI，但这是旧版端点，且所选模型必须支持该端点。
/v1/embeddings	支持使用 OpenAI Embedding 模型（例如 text-embedding-3-large）的别名。
/v1/images/generations	支持使用当前 OpenAI 图像模型的别名。
/v1/images/edits	支持使用 OpenAI 图像编辑模型（如 gpt-image-2）的别名。请求为 multipart/form-data；参见图像编辑。
/v1/videos 及其状态和内容路由	支持使用 Sora 模型别名（sora-2 或 sora-2-pro）。由于 OpenAI 通过需要鉴权的端点交付成品文件，内容路由会将 MP4 经网关流式传输，而不是重定向。参见使用 Sora 生成视频。
/v1/audio/*	支持使用适当的语音、转录或翻译模型别名。
/v1/realtime	支持以直接 Realtime 模型别名进行 WebSocket 中继。请参阅 Realtime API。
/v1/files、/v1/batches、/v1/fine_tuning/jobs	通过 OpenAI 适配器提供支持。这些任务型路由选择凭证的方式不同于普通推理调用；请参阅文件、批处理和微调。
/v1/messages	通过 OpenAI Chat 进行转换；OpenAI 不提供原生 Anthropic Messages 端点。
/v1/messages/count_tokens	拒绝，因为此路由的 Token 计数要求使用 Anthropic 支持的模型。
/v1/models	返回调用方可访问的 AISIX 模型别名，而不是 OpenAI 账户的模型清单。需要原生列表时，请使用 /passthrough/openai/v1/models。
/v1/rerank	AISIX 接受 openai 服务提供方值，但 OpenAI 公共 API 不提供 /v1/rerank，因此上游会拒绝调用。

对于 AISIX 尚未建模的 OpenAI 路由（例如内容审核或图像变体），请使用透传路由。本页的 /passthrough/openai 路径假定一条路由认领该前缀，target_url 设为 OpenAI 的 API 根地址；在调用方 Key 的 allowed_routes 上授予该路由。透传使用 OpenAI 模型 ID 而不是 AISIX 别名，并具有不同的流式传输和用量核算行为。

使用 OpenAI SDK

将 AISIX_BASE_URL 设置为 ${AISIX_PROXY}/v1，并使用调用方密钥作为 API Key。请参阅 OpenAI SDK 指南。

后续步骤

你已将 AISIX 连接到 OpenAI，并验证了模型别名。接下来可阅读以下指南：

• 模型别名：为此别名配置路由、重试行为或成本元数据。
• 使用 Chat Completions 输入和输出音频：向兼容的聊天模型发送录制音频，或保存模型生成的音频响应。
• Azure OpenAI：改为配置 Azure 托管的 OpenAI 部署。
• 服务提供方兼容性：查看受支持的代理端点和服务提供方专属边界。