Dify

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

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

不要把 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 等路径，因此推荐填写：

https://tapapi.ai/v1

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

https://tapapi.ai

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

配置步骤

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

验收方式

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

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

图片生成工作流

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

POST https://tapapi.ai/v1/images/generations
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "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 节点里单独调用：

POST https://tapapi.ai/v1/responses
Authorization: Bearer sk-xxx
Content-Type: application/json

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

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

视频工作流

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

POST /v1/videos
  -> 等待
  -> GET /v1/videos/{task_id}
  -> completed 后 GET /v1/videos/{task_id}/content
  -> 下载并转存视频文件

视频请求字段会随模型变化，不要把某个模型的 seconds、size、aspect_ratio、参考图字段直接复用到所有视频模型。更多见视频 API 和任务与输出。

日志和排障

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

{
  "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
图片生成	文生图
图片保存	输出图片保存
视频 API	视频 API
错误与重试	错误码与重试
成本控制	成本控制

官方参考

Dify Marketplace: OpenAI-API-compatible

SDK 与语言

常用工具

文本模型接入

配置步骤

验收方式

图片生成工作流

Responses 工作流

视频工作流

日志和排障

常见问题

下一步

官方参考

​文本模型接入

​配置步骤

​验收方式

​图片生成工作流

​Responses 工作流

​视频工作流

​日志和排障

​常见问题

​下一步

​官方参考

文本模型接入

配置步骤

验收方式

图片生成工作流

Responses 工作流

视频工作流

日志和排障

常见问题

下一步

官方参考