> ## 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.

# HTTP REST

> 不使用 SDK，直接调用 Tapapi HTTP 接口

Tapapi 的主线接口可以直接用 HTTP 调用。只要你的语言能发 HTTPS 请求，就可以接入文本和图片能力；视频 API 当前按受控开放处理，生产调用前需要先确认模型、价格和账号权限。

## 基础信息

| 项目           | 值                              |
| ------------ | ------------------------------ |
| Base URL     | `https://tapapi.ai/v1`         |
| 鉴权           | `Authorization: Bearer sk-xxx` |
| 文本接口         | `POST /v1/chat/completions`    |
| Responses 接口 | `POST /v1/responses`，按模型详情确认   |
| 图片接口         | `POST /v1/images/generations`  |
| 视频接口         | `/v1/videos` 系列，受控开放           |
| 模型列表         | `GET /v1/models`               |

<Note>本地服务也兼容部分上游风格的 Key 传法，但公开文档统一主推 Bearer Token，便于排障和迁移。</Note>

## 文本请求

```bash theme={null}
curl https://tapapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "用一句话解释 Tapapi 是什么"}
    ]
  }'
```

成功后读取：

```text theme={null}
choices[0].message.content
```

## 流式文本

```bash theme={null}
curl -N https://tapapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [
      {"role": "user", "content": "写一段 100 字的产品介绍"}
    ]
  }'
```

底层响应是 SSE：

```text theme={null}
data: {...}
data: {...}
data: [DONE]
```

业务代码通常读取每个 chunk 的 `choices[0].delta.content`。生产解析时要跳过空内容、ping/keep-alive 和无内容的 delta，收到 `data: [DONE]` 后结束。

## Responses 请求

`/v1/chat/completions` 是文本 HTTP 接入的默认主线。`/v1/responses` 是可选文本协议，适合已经确认模型和字段支持的场景：

```bash theme={null}
curl https://tapapi.ai/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "用一句话解释 Tapapi 是什么"
  }'
```

Responses 的返回结构和 Chat Completions 不完全一样。接入前先用真实模型测试字段，再写入生产解析逻辑。

## 图片生成

```bash theme={null}
curl https://tapapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "a clean product photo of a white ceramic mug",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

成功后读取：

```text theme={null}
data[0].url
```

或者：

```text theme={null}
data[0].b64_json
```

生产代码需要同时兼容 `url` 和 `b64_json`。`size` 必须使用英文字母 `x`，例如 `1024x1024`，不要写成 `1024×1024`。

生产解析建议：

| 项          | 建议                                         |
| ---------- | ------------------------------------------ |
| `data=[]`  | 当作无有效结果处理，记录 `request_id` 和请求摘要            |
| 返回数量       | 记录请求 `n`、实际 `data.length` 和成功转存数量          |
| `url`      | 后端下载后转存到自有 COS、S3、R2 或 OSS                 |
| `b64_json` | 解码后写入文件或上传对象存储                             |
| 部分成功       | 如果响应包含 `metadata.tapapi_partial`，按实际返回张数处理 |

## 视频 HTTP 入口

视频 API 当前不是默认全量开放能力。只有控制台可见模型、价格已确认、账号有权限时，才适合生产调用。

推荐流程：

```text theme={null}
POST /v1/videos
  -> GET /v1/videos/{task_id}
  -> completed 后 GET /v1/videos/{task_id}/content
```

视频请求字段会随模型变化，不要把某个模型的 `seconds`、`size`、`aspect_ratio`、参考图字段直接复用到所有视频模型。更多见 [视频 API](/video-generation/overview) 和 [任务与输出](/video-generation/tasks-and-output)。

## 模型列表

```bash theme={null}
curl https://tapapi.ai/v1/models \
  -H "Authorization: Bearer sk-xxx"
```

模型是否可用、价格和权限以控制台为准。文档示例里的模型名只用于说明调用结构。

## 错误响应

OpenAI-compatible 接口的错误通常是：

```json theme={null}
{
  "error": {
    "message": "...",
    "type": "new_api_error",
    "param": "",
    "code": "invalid_request"
  }
}
```

响应头会返回请求标识，排障时优先保存：

```http theme={null}
X-Oneapi-Request-Id: 20260609...
```

任务/视频类接口的错误可能不是标准 `{ "error": ... }`，也可能返回顶层 `code`、`message`、`data`。生产日志不要只保存一段错误文本，至少记录 HTTP 状态码、`error.type`、`error.code`、`error.message`、`request_id` 和业务 `task_id`。

处理建议：

|    HTTP   | 是否重试 | 建议                 |
| :-------: | :--: | ------------------ |
|    400    |   否  | 修正请求字段             |
| 401 / 403 |   否  | 检查 API Key、账户状态和权限 |
|    429    |   是  | 指数退避，限制最大次数        |
|   临时 5xx  |   是  | 重试 1-2 次，仍失败则记录并告警 |
| 504 / 524 |  先排查 | 查业务状态和账单，再决定是否补跑   |

更多见 [错误码与重试](/errors)。

## 生产 HTTP 建议

| 项       | 建议                                       |
| ------- | ---------------------------------------- |
| API Key | 只放服务端环境变量，不放 URL query、前端代码或公开配置         |
| timeout | 文本和图片按业务设置等待时间；长任务进入队列或轮询                |
| 重试      | 只对 429、临时 5xx、网络中断做有限重试                  |
| 幂等      | 保存业务 `task_id`，避免刷新、重复点击、worker 重启造成重复请求 |
| 日志      | 保存模型、接口、请求摘要、HTTP 状态码、`request_id` 和最终用量 |
| 输出      | 图片和视频结果尽快转存，不长期依赖临时 URL                  |

## 不建议当前使用

| 路径                                                      | 原因                      |
| ------------------------------------------------------- | ----------------------- |
| `/v1/images/variations`                                 | 当前返回 not implemented    |
| `/v1/files`                                             | 当前返回 not implemented    |
| `/v1/fine-tunes`                                        | 当前返回 not implemented    |
| `/v1/tapapi/images/advanced` 的 `image_urls` / `webhook` | 代码会在计费前拦截，暂不开放          |
| `/v1/videos`                                            | 受控开放，未确认模型、价格和权限前不要生产依赖 |

## 下一步

| 场景                   | 文档                                                    |
| -------------------- | ----------------------------------------------------- |
| 已有 OpenAI SDK        | [OpenAI SDK 迁移](/integrations/openai-sdk)             |
| Python 完整示例          | [Python](/integrations/python)                        |
| Node.js / TypeScript | [Node.js / TypeScript](/integrations/node-typescript) |
| PHP / Laravel        | [PHP / Laravel](/integrations/php-laravel)            |
| 错误与重试                | [错误码与重试](/errors)                                     |
| 生产上线检查               | [上线 Checklist](/production/launch-checklist)          |