> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sub2api.ruilinlu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python 使用 Sub2API 的代码示例

> 通过 Python openai 库使用 Sub2API，涵盖单轮对话、多轮对话、流式输出与错误处理的完整代码示例。

本页提供多个可直接运行的 Python 示例，演示如何通过 `openai` 官方 SDK 调用 Sub2API，覆盖最常见的使用场景。

## 前置条件

确保已安装 SDK：

```bash theme={null}
pip install openai
```

所有示例均假设你在环境变量中设置了 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`：

```bash theme={null}
export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://sub2api.ruilinlu.com"
```

## 1. 基本对话

最简单的单轮对话示例：

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL")
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "请用一句话介绍 Sub2API。"}
    ]
)

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

## 2. 多轮对话

通过维护 `messages` 列表实现上下文保留：

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL")
)

messages = [
    {"role": "system", "content": "你是一位 helpful 的编程助手。"},
    {"role": "user", "content": "什么是 API Gateway？"},
]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages
)

assistant_reply = response.choices[0].message.content
print(f"Assistant: {assistant_reply}")

# 将助手回复加入历史，继续下一轮
messages.append({"role": "assistant", "content": assistant_reply})
messages.append({"role": "user", "content": "它和反向代理有什么区别？"})

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages
)

print(f"Assistant: {response.choices[0].message.content}")
```

## 3. 流式输出

设置 `stream=True` 可逐字接收模型输出，适合交互式场景：

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL")
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "写一首关于 AI 的短诗。"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
print()
```

## 4. 错误处理

对 `APIStatusError` 进行捕获，优雅处理各类 HTTP 错误：

```python theme={null}
import os
from openai import OpenAI, APIStatusError

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL")
)

try:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hi"}]
    )
    print(response.choices[0].message.content)
except APIStatusError as e:
    print(f"请求失败: {e.status_code}")
    print(f"错误详情: {e.response}")
except Exception as e:
    print(f"其他异常: {e}")
```

## 5. 图片生成

调用 Images API 生成图片：

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL")
)

response = client.images.generate(
    model="dall-e-3",
    prompt="一只穿着宇航服的猫在月球上漫步，卡通风格",
    size="1024x1024",
    quality="standard",
    n=1
)

print(response.data[0].url)
```

<Warning>
  图片生成功能的可用模型与参数取决于上游供应商配置。若调用失败，请参考 [模型不可用排查](/troubleshooting/model-unavailable)。
</Warning>

## 常见问题排查

<Accordion title="APIStatusError: 401 Unauthorized">
  请检查 `OPENAI_API_KEY` 是否已正确设置，且 Key 未被吊销。详见 [401 排查](/troubleshooting/401) 与 [API Key 无效](/troubleshooting/api-key-invalid)。
</Accordion>

<Accordion title="APIStatusError: 404 model not found">
  请确认你使用的 model 名称在 Sub2API 当前可用列表中。可参考 [Model 选择指南](/models/how-to-choose)。
</Accordion>

<Accordion title="流式输出为空或中断">
  请确认你正确迭代了 `response` 对象，并检查了每个 `chunk.choices[0].delta.content` 是否存在。网络中断也可能导致流异常终止。
</Accordion>

<Accordion title="图片生成返回 400 Bad Request">
  请检查 `size`、`quality`、`n` 等参数是否与所选模型兼容。不同模型支持的参数集合不同。
</Accordion>