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

# Dify

> 在 Dify 中配置 Tapapi 的 OpenAI 兼容接口

Dify 当前建议先按 OpenAI-compatible 文本模型接入。Dify 官方市场有 `OpenAI-API-compatible` 模型供应商插件，核心配置是模型类型、模型名、API Key 和 URL；Tapapi 对外稳定入口是 `https://tapapi.ai/v1`。

<Warning>Dify 的模型供应商配置优先用于文本 / Chat 模型。图片生成如果要稳定落地，建议在 Workflow 里用 HTTP 请求调用 `POST /v1/images/generations`，不要默认假设 Dify 的 LLM Provider 会直接覆盖图片 API。</Warning>

不要把 Tapapi API Key 写进公开 Dify App、公开工作流模板、前端变量或截图里。多人工作区建议单独创建低额度、限定模型的 Tapapi Key。

## 文本模型接入

| 字段                | 值                           |
| ----------------- | --------------------------- |
| Provider / Plugin | `OpenAI-API-compatible`     |
| Model type        | LLM / Chat                  |
| Base URL / URL    | `https://tapapi.ai/v1`      |
| API Key           | Tapapi 控制台创建的 `sk-` Key     |
| Model name        | 控制台可用的文本模型，例如 `gpt-5.4`     |
| Streaming         | 聊天应用建议开启；如果流式异常，先关闭流式验证基础请求 |

大多数 OpenAI-compatible 插件会自动在 Base URL 后拼接 `/chat/completions`、`/models` 等路径，因此推荐填写：

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

如果你的 Dify 版本请求到了 `/v1/v1/chat/completions`，说明插件已经自动拼了 `/v1`，把 URL 改成：

```text theme={null}
https://tapapi.ai
```

如果请求到了 `/chat/completions` 且返回 404，说明缺少 `/v1`，改回 `https://tapapi.ai/v1`。

## 配置步骤

1. 在 Dify 后台安装或启用 `OpenAI-API-compatible` 模型供应商插件。
2. 新增模型，选择 LLM / Chat 类型。
3. 填入 `https://tapapi.ai/v1`、Tapapi API Key 和模型名。
4. 保存后新建一个 Chatbot / Chatflow，用一句简单输入测试。
5. 到 Tapapi 控制台检查是否产生调用记录和扣费记录。

## 验收方式

| 检查项   | 通过标准                                 |
| ----- | ------------------------------------ |
| 模型配置  | 模型名和 Tapapi 控制台完全一致                  |
| 非流式聊天 | 简单问题能返回 `choices[0].message.content` |
| 流式聊天  | 开启 streaming 后前端持续显示内容               |
| 用量记录  | Tapapi 控制台能看到对应调用和扣费                 |
| 错误排查  | 能拿到 HTTP 状态码和错误 message              |

如果流式输出异常，先关闭 streaming 跑通基础请求，再检查 Dify 版本、插件版本和模型是否支持流式。

## 图片生成工作流

如果 Dify 工作流需要生成图片，用 HTTP Request 节点直接调用图片 API：

```http theme={null}
POST https://tapapi.ai/v1/images/generations
Authorization: Bearer sk-xxx
Content-Type: application/json
```

```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"
}
```

返回结果通常读取 `data[0].url`；如果你传 `response_format: "b64_json"`，则读取 `data[0].b64_json`。生产环境建议把返回图片转存到自己的对象存储。

图片工作流需要额外处理：

| 情况                        | 建议                   |
| ------------------------- | -------------------- |
| `data=[]`                 | 当作失败处理，记录请求摘要和错误信息   |
| 返回 URL                    | 立刻下载并转存到自己的文件服务或对象存储 |
| 返回 `b64_json`             | 解码成文件后再上传或发送         |
| `metadata.tapapi_partial` | 按实际返回张数处理，不要假设全部成功   |
| URL 下载失败                  | 优先重试下载和转存，不要立刻重新生成图片 |

当前不要把 `image_urls` 当作 `/v1/images/generations` 的通用图生图参数。图生图、多参考图和图片编辑请先看对应图片文档，不要直接写进生产 Workflow。

## Responses 工作流

`/v1/chat/completions` 是 Dify 文本接入的默认主线。如果你确实需要 Responses API，建议在 Workflow HTTP Request 节点里单独调用：

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

```json theme={null}
{
  "model": "gpt-5.4",
  "input": "用一句话解释 Tapapi 是什么"
}
```

Responses 的返回结构和 Chat Completions 不完全一样。接入前先用真实模型测试字段，再写入 Dify 节点映射。

## 视频工作流

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

推荐流程：

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

## 日志和排障

OpenAI-compatible 接口失败时通常会返回：

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

如果 Dify 节点能读取响应头，优先保存 `X-Oneapi-Request-Id`。如果当前节点拿不到响应头，至少保存 HTTP 状态码、错误 message、模型名、输入摘要、业务用户和 Dify workflow run id。

| 状态            | 建议                        |
| ------------- | ------------------------- |
| 400           | 修请求字段，不要自动重试              |
| 401 / 403     | 检查 Tapapi Key、余额、权限和模型可见性 |
| 429           | 等待后有限重试                   |
| 临时 5xx / 网络超时 | 重试 1-2 次，仍失败则告警           |
| 504 / 524     | 先查业务状态和账单，再决定是否补跑         |

## 常见问题

| 现象                | 优先检查                                                              |
| ----------------- | ----------------------------------------------------------------- |
| `401` / `403`     | API Key 是否来自 Tapapi 控制台，是否复制完整                                    |
| `404`             | Base URL 是否写成 `https://tapapi.ai/v1`；不要把 endpoint 完整路径填到模型供应商 URL |
| `model not found` | 模型名是否和控制台完全一致                                                     |
| 流式无输出             | 先关闭 streaming 跑通，再确认模型和 Dify 版本是否支持流式                             |
| 图片不返回             | 不要走 LLM Provider 猜图片能力，改用 Workflow HTTP Request                   |
| 工作流成本异常           | 检查是否有无限重试、重复触发或批量并发过高                                             |

## 下一步

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

## 官方参考

* [Dify Marketplace: OpenAI-API-compatible](https://marketplace.dify.ai/plugins/langgenius/openai_api_compatible)