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

# n8n / Make

> 把 Tapapi 接入自动化工作流

n8n 和 Make 适合定时生成、表格批量处理、内容生产、通知流程和图片转存。核心不是安装专用插件，而是用 HTTP 节点调用 Tapapi 的 REST API。

<Warning>不要把 Tapapi API Key 写进公开 workflow、公开场景模板、共享表格、前端页面或截图里。n8n 建议放 Credential / 环境变量，Make 建议放私有 Connection 或受限变量。</Warning>

## 适合的流程

| 场景                | 推荐接口                            |
| ----------------- | ------------------------------- |
| 批量写标题、摘要、客服回复     | `POST /v1/chat/completions`     |
| 已确认模型支持 Responses | `POST /v1/responses`            |
| 批量生图、商品图草稿、社媒配图   | `POST /v1/images/generations`   |
| 定时同步模型列表          | `GET /v1/models`                |
| 视频生成              | `/v1/videos` 系列受控开放，未确认权限前不要接生产 |

## n8n: HTTP Request 节点

n8n 官方的 HTTP Request 节点可以向任意 REST API 发请求。Tapapi 推荐这样配：

| 配置项               | 文本生成                                    | 图片生成                                      |
| ----------------- | --------------------------------------- | ----------------------------------------- |
| Method            | `POST`                                  | `POST`                                    |
| URL               | `https://tapapi.ai/v1/chat/completions` | `https://tapapi.ai/v1/images/generations` |
| Authentication    | None / 手动 Header                        | None / 手动 Header                          |
| Header            | `Authorization: Bearer sk-xxx`          | `Authorization: Bearer sk-xxx`            |
| Header            | `Content-Type: application/json`        | `Content-Type: application/json`          |
| Body Content Type | JSON                                    | JSON                                      |
| Timeout           | 60-120 秒                                | 120-180 秒                                 |

如果你的 n8n 版本支持保存完整响应或响应头，建议开启，并把 `X-Oneapi-Request-Id` 写回当前数据行。这个字段是排障时最重要的请求标识。

文本请求 Body：

```json theme={null}
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Write a short product caption for a ceramic mug."
    }
  ],
  "temperature": 0.7
}
```

图片请求 Body：

```json theme={null}
{
  "model": "z-image-turbo",
  "prompt": "a clean ecommerce product photo of a white ceramic mug",
  "n": 1,
  "size": "1024x1024",
  "response_format": "url"
}
```

Responses 请求 Body：

```json theme={null}
{
  "model": "gpt-5.4",
  "input": "Write a short product caption for a ceramic mug."
}
```

`/v1/chat/completions` 是自动化场景的默认文本主线。`/v1/responses` 是可选协议，接入前先确认模型支持和返回字段；不要用 Chat Completions 的字段路径去解析 Responses。

## n8n 结果处理

| 接口        | 读取字段                         | 后续动作                |
| --------- | ---------------------------- | ------------------- |
| 文本        | `choices[0].message.content` | 写回表格、数据库、Notion、CRM |
| Responses | `output_text`                | 写回表格、数据库、Notion、CRM |
| 图片 URL    | `data[0].url`                | 立刻下载并转存到你的对象存储      |
| 图片 base64 | `data[0].b64_json`           | 解码为文件，再上传或发送        |
| 请求标识      | 响应头 `X-Oneapi-Request-Id`    | 写回当前行，用于排障          |
| 图片部分成功    | `metadata.tapapi_partial`    | 按实际返回张数处理           |

图片生产流程需要额外处理：

| 情况                | 建议                                      |
| ----------------- | --------------------------------------- |
| `data=[]`         | 记为失败行，保存 `request_id`、模型、prompt 摘要和错误信息 |
| `data.length < n` | 按实际返回数量结算业务结果，不要假设全部成功                  |
| 返回 URL            | 立刻下载并转存到 S3、R2、OSS、COS 或自己的文件服务         |
| 返回 `b64_json`     | 解码成文件后再上传或发送                            |
| URL 下载失败          | 优先重试下载和转存，不要立刻重新生成图片                    |

批量任务建议加队列和有限重试：429、临时 5xx、网络超时可以重试 1-2 次；401、403、model not found 不要自动重试，先停下来修配置。

## 批量任务模板

每条输入数据建议至少保存这些字段：

| 字段                                            | 用途                                       |
| --------------------------------------------- | ---------------------------------------- |
| `task_id`                                     | 你的业务任务 ID，用于幂等和对账                        |
| `input_hash`                                  | 防止同一行重复提交                                |
| `model`                                       | 记录实际调用模型                                 |
| `status`                                      | `pending`、`running`、`succeeded`、`failed` |
| `request_id`                                  | Tapapi 返回的 `X-Oneapi-Request-Id`         |
| `error_type` / `error_code` / `error_message` | 失败排障                                     |
| `output_url` / `output_text`                  | 结果字段                                     |
| `saved_url`                                   | 图片或视频转存后的自有 URL                          |

放大批量前先跑 3-5 条样本；稳定后再按 10-50 条一批扩容。图片和视频任务不要无限并发，也不要无限重试。

## 错误分支

| 状态            | n8n / Make 动作                 |
| ------------- | ----------------------------- |
| 400           | 停止当前行，修请求字段                   |
| 401 / 403     | 停止整个流程，检查 API Key、余额、权限和模型可见性 |
| 429           | 等待后重试，限制最大次数                  |
| 临时 5xx / 网络超时 | 重试 1-2 次，仍失败则进入人工检查           |
| 504 / 524     | 先查业务状态和账单，再决定是否补跑             |

错误响应通常包含 `error.message`、`error.type`、`error.code`。任务/视频类接口也可能返回顶层 `code`、`message`、`data`。生产流程不要只保存一段错误文本。

## Make

Make 也按同样的 HTTP 思路接入：选择 HTTP 模块，填写 Method、URL、Headers 和 JSON Body。字段名会随 Make UI 版本变化，配置本质不变：

```text theme={null}
POST https://tapapi.ai/v1/chat/completions
Authorization: Bearer sk-xxx
Content-Type: application/json
```

需要生图时把 URL 换成：

```text theme={null}
POST https://tapapi.ai/v1/images/generations
```

Make 场景建议拆出两条 route：

| Route   | 处理                                                                               |
| ------- | -------------------------------------------------------------------------------- |
| Success | 解析 `choices[0].message.content`、`output_text`、`data[0].url` 或 `data[0].b64_json` |
| Error   | 保存 HTTP 状态码、`X-Oneapi-Request-Id`、错误字段和原始输入                                      |

如果 Make 模块拿不到响应头，至少把 HTTP 状态码、响应 body、模型、输入摘要和业务 `task_id` 写回数据源。

## 视频工作流

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

推荐流程：

```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)。

## 安全和成本

* 不要把 Tapapi Key 写在公开表格、公开场景模板或前端页面里。
* 批量流程先用 3-5 条样本测试，再放大到全量。
* 图片生成拿到 URL 后尽快转存；不要长期依赖临时返回链接。
* 给每条业务数据写入业务 `task_id`，方便失败重试和对账。
* 对高频流程设置每日预算上限和并发上限。
* 给高成本图片和视频流程加人工抽检节点，避免错误 prompt 大批量烧钱。
* 不要把失败分支重新连回同一个 HTTP 节点做无限循环。

## 下一步

| 场景         | 文档                                           |
| ---------- | -------------------------------------------- |
| 底层 HTTP 规则 | [HTTP REST](/integrations/http-rest)         |
| 图片生成       | [文生图](/image-generation/text-to-image)       |
| 图片保存       | [输出图片保存](/image-generation/output-images)    |
| 视频 API     | [视频 API](/video-generation/overview)         |
| 错误与重试      | [错误码与重试](/errors)                            |
| 成本控制       | [成本控制](/production/cost-control)             |
| 生产上线检查     | [上线 Checklist](/production/launch-checklist) |

## 官方参考

* [n8n HTTP Request node](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/)