OpenAI SDK Guide

OpenAI 官方 SDK 接入教程

使用 OpenAI 官方 Python 或 Node.js SDK 调用 MuxLLM 的 OpenAI 兼容端点。先从模型广场确认端点标签，再选择 Chat Completions 或 Responses 请求方式。

Python 教程 Node.js 教程

OpenAI 兼容 Base URL

https://api.muxllm.com/v1

Chat 端点标签

openai

Responses 端点标签

openai-response

Scope & Evidence

先确认协议，不根据模型名称猜测

本教程面向 OpenAI 官方 SDK。只有模型广场显示对应端点标签时，才应使用相应调用方法。模型名称包含厂商名或“Codex”并不能代替端点标签。

E1 运行态证据MuxLLM 公开模型信息提供 openai 与 openai-response 端点标签；具体模型与标签会动态调整。

E2 官方证据示例遵循 OpenAI 官方 Python 与 Node.js SDK 的 Base URL、Chat Completions 和 Responses 配置方式。

E3 接入实测本页编写过程没有使用真实 API Key，也没有向任何模型发送请求。示例需要由你使用低额度测试 Key 验证。

最后核验2026-07-18

能力边界端点标签表示可选协议，不保证每个模型支持所有可选参数、视觉、工具调用或相同上下文长度。模型能力和价格始终以实时模型广场为准。

Endpoint Selection

选择 Chat Completions 或 Responses

模型端点标签	SDK 方法	核心输入	读取文本
openai	`client.chat.completions.create()`	`messages`	`choices[0].message.content`
openai-response	`client.responses.create()`	`input`	`output_text`

两种方法的请求和响应结构不同。若模型只有 openai，不要把 Chat 示例的路径或字段机械替换为 Responses；反向也同样如此。

Credentials

通过环境变量保存凭证与模型名

先在 MuxLLM 控制台创建独立 API Key，并为测试 Key 设置合理额度。示例使用专用变量名，避免与其他站点的 Key 混用。

macOS / Linux · 当前终端会话

export MUXLLM_API_KEY="YOUR_API_KEY"
export MUXLLM_MODEL="MODEL_NAME"
export MUXLLM_BASE_URL="https://api.muxllm.com/v1"

Windows PowerShell · 当前会话

$env:MUXLLM_API_KEY = "YOUR_API_KEY"
$env:MUXLLM_MODEL = "MODEL_NAME"
$env:MUXLLM_BASE_URL = "https://api.muxllm.com/v1"

不要提交 Key把 .env、本地配置和调试日志加入忽略规则。前端网页、移动端安装包和公开仓库都不是保存长期 API Key 的安全位置。

Python

安装并发送同步请求

建议在项目虚拟环境中安装 SDK。升级依赖前先检查项目锁文件和兼容范围。

创建环境与安装

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade openai

Chat Completions 同步示例

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MUXLLM_API_KEY"],
    base_url=os.getenv("MUXLLM_BASE_URL", "https://api.muxllm.com/v1"),
)

response = client.chat.completions.create(
    model=os.environ["MUXLLM_MODEL"],
    messages=[
        {"role": "system", "content": "你是一个严谨的技术助手。"},
        {"role": "user", "content": "用三点说明 API 网关的作用。"},
    ],
)

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

若代码报缺少环境变量，先确认变量已在启动 Python 的同一终端或进程环境中设置；不要为了绕过错误而把真实 Key 硬编码进文件。

Python Streaming

逐块消费流式输出

设置 stream=True 后，返回值是可迭代流。每个块不一定都有文本，客户端必须跳过空增量，并在异常时保留“输出可能不完整”的状态。

Python · Chat 流式输出

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MUXLLM_API_KEY"],
    base_url=os.getenv("MUXLLM_BASE_URL", "https://api.muxllm.com/v1"),
)

stream = client.chat.completions.create(
    model=os.environ["MUXLLM_MODEL"],
    messages=[{"role": "user", "content": "分步骤解释指数退避。"}],
    stream=True,
)

parts = []
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta.content
    if delta:
        parts.append(delta)
        print(delta, end="", flush=True)

print()
complete_text = "".join(parts)

Node.js

安装并发送同步等待请求

以下示例使用 ESM。项目需在 package.json 中启用 "type": "module"，或把文件扩展名改为 .mjs。

安装 SDK

npm install openai

Chat Completions 示例

Node.js · ESM

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MUXLLM_API_KEY,
  baseURL: process.env.MUXLLM_BASE_URL || "https://api.muxllm.com/v1",
});

const response = await client.chat.completions.create({
  model: process.env.MUXLLM_MODEL,
  messages: [
    { role: "system", content: "你是一个严谨的技术助手。" },
    { role: "user", content: "用三点说明 API 网关的作用。" },
  ],
});

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

Node.js Streaming

使用异步迭代器读取流

不要假设一次网络块正好对应一个完整字符或句子。把增量按顺序拼接，并在界面层对异常中断、取消和重复渲染进行处理。

Node.js · Chat 流式输出

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MUXLLM_API_KEY,
  baseURL: process.env.MUXLLM_BASE_URL || "https://api.muxllm.com/v1",
});

const stream = await client.chat.completions.create({
  model: process.env.MUXLLM_MODEL,
  messages: [{ role: "user", content: "分步骤解释指数退避。" }],
  stream: true,
});

const parts = [];
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (!delta) continue;
  parts.push(delta);
  process.stdout.write(delta);
}

process.stdout.write("\n");
const completeText = parts.join("");

Responses API

仅对匹配标签的模型使用 Responses

当模型广场明确显示 openai-response 时，可使用 SDK 的 Responses 方法。它不是 Chat Completions 的别名。

语言	最小调用	文本结果
Python	`client.responses.create(model=..., input=...)`	`response.output_text`
Node.js	`client.responses.create({ model, input })`	`response.output_text`

Python Responses 示例

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MUXLLM_API_KEY"],
    base_url="https://api.muxllm.com/v1",
)

response = client.responses.create(
    model=os.environ["MUXLLM_MODEL"],
    input="列出定位 401 错误的三个检查项。",
)
print(response.output_text)

Node.js Responses 示例

Node.js

import OpenAI from "openai";

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

const response = await client.responses.create({
  model: process.env.MUXLLM_MODEL,
  input: "列出定位 401 错误的三个检查项。",
});
console.log(response.output_text);

Reliability

设置超时、明确重试上限和取消

SDK 的默认行为可能随版本调整。首次 E3 验收应显式禁用自动重试；生产环境只有在确认请求可安全重放、费用可控且有幂等策略时，才单独设定有限重试。

Python 首次验收OpenAI(..., timeout=30.0, max_retries=0)

Node.js 首次验收new OpenAI({ ..., timeout: 30_000, maxRetries: 0 })

生产重试先区分连接失败、429、5xx 和已进入业务链路的请求，再按幂等性、费用上限和总时间预算设定有限次数与随机退避。

非幂等任务图片、视频或带外部副作用的工具调用不能仅凭网络超时就直接重放，先确认任务是否已经创建。

Error Handling

记录状态码和请求上下文，不记录密钥

Python 异常分类

Python

from openai import APIConnectionError, APIStatusError, RateLimitError

try:
    response = client.chat.completions.create(
        model=os.environ["MUXLLM_MODEL"],
        messages=[{"role": "user", "content": "健康检查"}],
    )
except RateLimitError as exc:
    print("请求受限：检查余额、额度与并发", exc.status_code)
except APIConnectionError:
    print("连接失败：检查 DNS、代理、TLS 与超时")
except APIStatusError as exc:
    print("API 返回错误", exc.status_code, exc.request_id)
    raise

Node.js 异常分类

Node.js

try {
  const response = await client.chat.completions.create({
    model: process.env.MUXLLM_MODEL,
    messages: [{ role: "user", content: "健康检查" }],
  });
  console.log(response.choices[0].message.content);
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error("API 错误", {
      status: error.status,
      requestId: error.request_id,
      name: error.name,
    });
  } else {
    console.error("本地或网络错误", error);
  }
}

现象	优先检查	动作
401 / 403	Key、认证头、账户和分组权限	更换为本站独立 Key；不要无条件重试
404	Base URL、模型名、端点标签	确认没有重复拼接 `/v1`，再核对协议
400	请求字段和模型专属参数	从最小请求开始逐项恢复可选字段
429	余额、额度、并发和上游限制	降低并发并采用有上限的指数退避
连接中断	代理、DNS、TLS、超时	保留错误上下文；流式结果标记为不完整

Official Sources

按当前 SDK 与 API 手册复核

OpenAI Python SDK官方 Python SDK 的安装、Base URL、流式与异常类说明 OpenAI Node.js SDK官方 Node.js SDK 的客户端、流式和错误处理说明 Responses API Reference核对 input、请求结构与响应字段 MuxLLM 模型广场执行时重新确认 openai 或 openai-response 标签

Acceptance

最小验收顺序

01确认标签
从模型广场复制 MODEL_NAME，确认使用 openai 或 openai-response。
02限制测试 Key
创建本站专用低额度 Key，并只通过进程环境变量加载。
03运行最小同步请求
先不添加温度、工具或媒体字段，确认能读取非空文本。
04验证流和错误路径
确认流能正常结束，并对 401、429 与网络超时给出可观测错误。
05再接入业务
逐项增加可选参数、日志脱敏、重试上限和监控。

验收标准以你实际执行后的状态码、非空响应和日志记录为准。本页仅提供配置与验证方法，不构成当前模型已经实测成功的声明。

Next Guide

继续理解 Chat 请求与响应

SDK 最小示例通过后，再学习字段、SSE 事件、多轮上下文和停止原因。

Chat Completions 教程