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

# OpenAI SDK 迁移

> 已有 OpenAI 代码如何切到 Tapapi

如果你的项目已经使用 OpenAI SDK，优先用 OpenAI-compatible 方式接入 Tapapi。通常只需要改三处：`api_key`、`base_url` 和 `model`。

这页是迁移总入口。更完整的语言示例见 [Python](/integrations/python)、[Node.js / TypeScript](/integrations/node-typescript)、[PHP / Laravel](/integrations/php-laravel) 和 [HTTP REST](/integrations/http-rest)。

## 接入边界

| 能力            | 推荐路径                                         | 当前建议                   |
| ------------- | -------------------------------------------- | ---------------------- |
| 文本对话          | `POST /v1/chat/completions`                  | 生产主线                   |
| 文本流式          | `POST /v1/chat/completions` + `stream: true` | 生产主线                   |
| Responses API | `POST /v1/responses`                         | 可选文本协议，按模型详情和 SDK 版本确认 |
| 图片生成          | `POST /v1/images/generations`                | 生产主线                   |
| 图片编辑          | `POST /v1/images/edits`                      | 仅在模型明确支持时使用            |
| 高级图片入口        | `POST /v1/tapapi/images/advanced`            | 有边界，不作为通用 SDK 主线       |
| 视频 API        | `/v1/videos` 系列                              | 受控开放，不建议直接作为默认生产依赖     |

## 配置方式

```bash theme={null}
export TAPAPI_API_KEY="sk-xxx"
export TAPAPI_BASE_URL="https://tapapi.ai/v1"
```

<Warning>不要把 API Key 写在前端代码、公开仓库、公开截图或客户端直连配置里。浏览器项目请通过自己的后端代理调用 Tapapi。</Warning>

## 迁移检查表

| 项                      | 要检查什么                                                              |
| ---------------------- | ------------------------------------------------------------------ |
| API Key                | 换成 Tapapi 控制台创建的 `sk-` Key                                         |
| `base_url` / `baseURL` | 统一设置为 `https://tapapi.ai/v1`                                       |
| `model`                | 换成控制台可见、账号有权限、价格已确认的模型                                             |
| 运行位置                   | SDK 代码放在服务端、脚本或队列 worker，不放浏览器                                     |
| 错误日志                   | 记录 HTTP 状态码、`error.type`、`error.code`、`error.message`、`request_id` |
| 超时与重试                  | 按业务设置 timeout、最大重试次数和 429 降并发策略                                    |
| 图片输出                   | 同时兼容 `url` 和 `b64_json`，URL 结果建议转存到自有存储                            |

## Python 服务端示例

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

client = OpenAI(
    api_key=os.environ["TAPAPI_API_KEY"],
    base_url=os.getenv("TAPAPI_BASE_URL", "https://tapapi.ai/v1"),
)

resp = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "用一句话解释 Tapapi 是什么"}],
)

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

## Node.js 服务端示例

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TAPAPI_API_KEY,
  baseURL: process.env.TAPAPI_BASE_URL || "https://tapapi.ai/v1",
});

const resp = await client.chat.completions.create({
  model: "gpt-5.4",
  messages: [{ role: "user", content: "用一句话解释 Tapapi 是什么" }],
});

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

## 图片生成

OpenAI SDK 的图片生成方法可以继续使用，但生产代码不要只兼容一种返回字段。

```python theme={null}
resp = client.images.generate(
    model="nano-banana-pro",
    prompt="a clean product photo of a white mug",
    n=1,
    size="1024x1024",
    response_format="url",
)

item = resp.data[0]
print(item.url or item.b64_json)
```

生产代码不要只兼容一种返回字段。图片结果可能是 `url`，也可能是 `b64_json`。如果拿到 URL，建议后端下载后转存到自己的 COS、S3、R2 或 OSS。

## Responses 和视频怎么处理

`/v1/chat/completions` 仍然是文本迁移的默认主线。`/v1/responses` 是已存在的文本协议入口，但是否适合你的项目，要看模型详情、SDK 版本和你是否需要 Responses 特有能力。

视频能力当前按受控开放处理。公开视频主口径是：

```text theme={null}
POST /v1/videos
GET /v1/videos/{task_id}
GET /v1/videos/{task_id}/content
```

生产调用前必须确认控制台模型、价格、账号权限和任务轮询规则。没有确认前，不要把视频 API 写成默认 SDK 依赖。

## 当前不要直接照搬的接口

| 接口                                                      | 原因                    |
| ------------------------------------------------------- | --------------------- |
| `/v1/images/variations`                                 | 本地返回 not implemented  |
| `/v1/files` / `/v1/fine-tunes`                          | 本地返回 not implemented  |
| `/v1/tapapi/images/advanced` 的 `image_urls` / `webhook` | 当前会在计费前拦截，暂不开放        |
| `/v1/videos`                                            | 受控开放，需先看控制台权限、模型文档和价格 |

## 下一步

| 场景                        | 文档                                                    |
| ------------------------- | ----------------------------------------------------- |
| 文本模型接入                    | [文本 API](/text-generation/overview)                   |
| 图片模型接入                    | [图片 API](/image-generation/overview)                  |
| 视频模型接入                    | [视频 API](/video-generation/overview)                  |
| Python 完整示例               | [Python](/integrations/python)                        |
| Node.js / TypeScript 完整示例 | [Node.js / TypeScript](/integrations/node-typescript) |
| PHP / Laravel             | [PHP / Laravel](/integrations/php-laravel)            |
| 不使用 SDK                   | [HTTP REST](/integrations/http-rest)                  |
| 生产上线检查                    | [上线 Checklist](/production/launch-checklist)          |