happy-life-star/docs/dify平台接口.md

Dify 平台接口文档

内部接口文档：本文包含可用 API Key，请勿提交到公开仓库或外部分享。

1. 基本信息

项	值
服务器端地址	http://49.232.138.53/v1
鉴权方式	Authorization: Bearer {API_KEY}
API Key	app-MqQOx09gCu9zzlKMpeLqHQHv
适用应用	短片小说生成、剧本生成

2. 通用鉴权

Service API 使用 API-Key 进行鉴权。所有 API 请求都应在 Authorization HTTP Header 中携带 API Key。

Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv

建议只在后端服务中保存和调用 API Key，避免将 Key 暴露到小程序、Web 前端或其它客户端。

3. 接口总览

方法	路径	说明
POST	/chat-messages	发送对话消息
POST	/files/upload	上传文件
GET	/files/:file_id/preview	文件预览
POST	/chat-messages/:task_id/stop	停止响应
POST	/messages/:message_id/feedbacks	消息反馈
GET	/app/feedbacks	获取 App 的消息点赞和反馈
GET	/messages/{message_id}/suggested	获取下一轮建议问题列表
GET	/messages	获取会话历史消息
GET	/conversations	获取会话列表
DELETE	/conversations/:conversation_id	删除会话
POST	/conversations/:conversation_id/name	会话重命名
GET	/conversations/:conversation_id/variables	获取对话变量
PUT	/conversations/:conversation_id/variables/:variable_id	更新对话变量
POST	/audio-to-text	语音转文字
POST	/text-to-audio	文字转语音
GET	/info	获取应用基本信息
GET	/parameters	获取应用参数
GET	/meta	获取应用 Meta 信息
GET	/site	获取应用 WebApp 设置
GET	/apps/annotations	获取标注列表
POST	/apps/annotations	创建标注
PUT	/apps/annotations/{annotation_id}	更新标注
DELETE	/apps/annotations/{annotation_id}	删除标注
POST	/apps/annotation-reply/{action}	标注回复初始设置
GET	/apps/annotation-reply/{action}/status/{job_id}	查询标注回复初始设置任务状态

4. 应用说明

4.1 短片小说生成

短片小说生成使用 Dify 对话型应用 API。接口路径、鉴权方式、请求参数和响应结构与本文后续章节一致。

4.2 剧本生成

剧本生成使用 Dify 工作流编排对话型应用 API。对话应用支持会话持久化，可将之前的聊天记录作为上下文继续回答，适用于聊天、客服 AI、脚本生成等场景。

5. 对话接口

5.1 发送对话消息

POST /chat-messages

创建会话消息。

请求体参数

参数	类型	必填	说明
query	string	是	用户输入或提问内容。
inputs	object	否	App 定义的变量值，默认为 {}。如果变量是文件类型，请按 files 中的文件结构传入。
response_mode	string	是	响应模式：streaming 为流式模式，blocking 为阻塞模式。推荐使用 streaming。
user	string	是	终端用户标识。由开发者定义，需保证在应用内唯一。
conversation_id	string	否	会话 ID。继续历史会话时传入之前响应中的 conversation_id。
files	array<object>	否	文件列表。适用于模型支持 Vision/Video 能力时的图文、多模态理解。
auto_generate_name	bool	否	是否自动生成会话标题，默认 true。
workflow_id	string	否	工作流 ID。用于指定特定已发布版本，不传则使用默认已发布版本。
trace_id	string	否	链路追踪 ID。也可通过 Header X-Trace-Id 或查询参数 trace_id 传递。优先级：Header > Query > Body。

files 参数结构

字段	类型	说明
type	string	文件类型，支持 document、image、audio、video、custom。
transfer_method	string	文件传递方式：remote_url 或 local_file。
url	string	文件地址。仅当 transfer_method 为 remote_url 时使用。
upload_file_id	string	上传文件 ID。仅当 transfer_method 为 local_file 时使用。

文件类型支持范围：

类型	支持格式
document	TXT、MD、MARKDOWN、MDX、PDF、HTML、XLSX、XLS、VTT、PROPERTIES、DOC、DOCX、CSV、EML、MSG、PPTX、PPT、XML、EPUB
image	JPG、JPEG、PNG、GIF、WEBP、SVG
audio	MP3、M4A、WAV、WEBM、MPGA
video	MP4、MOV、MPEG、WEBM
custom	其它文件类型

响应说明

当 response_mode 为 blocking 时，返回 ChatCompletionResponse。当 response_mode 为 streaming 时，返回 ChunkChatCompletionResponse 流式序列。

ChatCompletionResponse

字段	类型	说明
event	string	事件类型，固定为 message。
task_id	string	任务 ID，可用于停止响应接口。
id	string	唯一 ID。
message_id	string	消息唯一 ID。
conversation_id	string	会话 ID。
mode	string	App 模式，固定为 chat。
answer	string	完整回复内容。
metadata	object	元数据。
usage	Usage	模型用量信息。
retriever_resources	array<RetrieverResource>	引用和归属分段列表。
created_at	int	消息创建时间戳，例如 1705395332。

ChunkChatCompletionResponse

流式响应的 Content-Type 为 text/event-stream。每个流式块以 data: 开头，块之间使用两个换行符分隔。

常见事件：

事件	说明
message	LLM 文本块事件。
message_file	文件事件，表示有新文件需要展示。
message_end	消息结束事件，收到后表示流式返回结束。
tts_message	TTS 音频流事件。
tts_message_end	TTS 音频流结束事件。
message_replace	消息内容替换事件，通常用于内容审查命中后的预设回复。
workflow_started	工作流开始执行。
node_started	工作流节点开始执行。
node_finished	工作流节点执行结束。
workflow_finished	工作流执行结束。
error	流式输出过程中出现异常。
ping	每 10 秒一次的连接保活事件。

请求示例

curl -X POST 'http://49.232.138.53/v1/chat-messages' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {},
    "query": "What are the specs of the iPhone 13 Pro Max?",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "abc-123",
    "files": [
      {
        "type": "image",
        "transfer_method": "remote_url",
        "url": "https://cloud.dify.ai/logo/logo-site.png"
      }
    ]
  }'

阻塞模式响应示例

{
  "event": "message",
  "task_id": "c3800678-a077-43df-a102-53f23ed20b88",
  "id": "9da23599-e713-473b-982c-4328d4f5c78a",
  "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
  "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
  "mode": "chat",
  "answer": "iPhone 13 Pro Max specs are listed here:...",
  "metadata": {
    "usage": {
      "prompt_tokens": 1033,
      "completion_tokens": 128,
      "total_tokens": 1161,
      "total_price": "0.0012890",
      "currency": "USD",
      "latency": 0.7682376249867957
    },
    "retriever_resources": []
  },
  "created_at": 1705407629
}

流式模式响应示例

data: {"event":"message","message_id":"5ad4cb98-f0c7-4085-b384-88c403be6290","conversation_id":"45701982-8118-4bc5-8e9b-64562b4555f2","answer":"I","created_at":1679586595}

data: {"event":"message_end","conversation_id":"45701982-8118-4bc5-8e9b-64562b4555f2","metadata":{"usage":{"prompt_tokens":1033,"completion_tokens":135,"total_tokens":1168}}}

错误码

HTTP 状态码	错误码	说明
400	invalid_param	传入参数异常。
400	app_unavailable	App 配置不可用。
400	provider_not_initialize	无可用模型凭据配置。
400	provider_quota_exceeded	模型调用额度不足。
400	model_currently_not_support	当前模型不可用。
400	workflow_not_found	指定的工作流版本未找到。
400	draft_workflow_error	无法使用草稿工作流版本。
400	workflow_id_format_error	工作流 ID 格式错误，需要 UUID 格式。
400	completion_request_error	文本生成失败。
404	-	对话不存在。
500	-	服务内部异常。

5.2 停止响应

POST /chat-messages/:task_id/stop

停止正在进行的流式响应。

路径参数

参数	类型	说明
task_id	string	任务 ID，由发送对话消息接口返回。

请求体参数

参数	类型	必填	说明
user	string	是	终端用户标识，必须与发送消息时的 user 一致。

请求示例

curl -X POST 'http://49.232.138.53/v1/chat-messages/:task_id/stop' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "user": "abc-123"
  }'

响应示例

{
  "result": "success"
}

6. 文件接口

6.1 上传文件

POST /files/upload

上传文件并在发送消息时使用，可实现图文多模态理解。上传文件仅供当前终端用户使用。

请求体参数

该接口使用 multipart/form-data 请求。

参数	类型	必填	说明
file	file	是	要上传的文件。
user	string	是	终端用户标识，需和发送消息接口的 user 保持一致。

请求示例

curl -X POST 'http://49.232.138.53/v1/files/upload' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --form 'file=@localfile;type=image/png' \
  --form 'user=abc-123'

响应字段

字段	类型	说明
id	string	文件 ID。
name	string	文件名。
size	int	文件大小，单位为字节。
extension	string	文件扩展名。
mime_type	string	MIME 类型。
created_by	string	上传用户。
created_at	int	创建时间戳。

6.2 文件预览

GET /files/:file_id/preview

预览或下载已上传文件。

路径参数

参数	类型	说明
file_id	string	文件 ID。

查询参数

参数	类型	必填	说明
as_attachment	bool	否	是否作为附件下载。传 true 时触发下载。

请求示例

curl -X GET 'http://49.232.138.53/v1/files/72fa9618-8f89-4a37-9b33-7e1178a24a67/preview' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

下载示例

curl -X GET 'http://49.232.138.53/v1/files/72fa9618-8f89-4a37-9b33-7e1178a24a67/preview?as_attachment=true' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

7. 消息与反馈接口

7.1 消息反馈

POST /messages/:message_id/feedbacks

提交消息点赞、点踩或文字反馈。

路径参数

参数	类型	说明
message_id	string	消息 ID。

请求体参数

参数	类型	必填	说明
rating	string	否	反馈类型，例如 like、dislike。传 null 可取消反馈。
user	string	是	终端用户标识。
content	string	否	消息反馈的具体内容。

请求示例

curl -X POST 'http://49.232.138.53/v1/messages/:message_id/feedbacks' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "rating": "like",
    "user": "abc-123",
    "content": "message feedback information"
  }'

响应示例

{
  "result": "success"
}

7.2 获取 App 的消息点赞和反馈

GET /app/feedbacks

获取应用终端用户的反馈和点赞记录。

查询参数

参数	类型	必填	说明
page	string	否	分页页码，默认 1。
limit	string	否	每页数量，默认 20。

请求示例

curl -X GET 'http://49.232.138.53/v1/app/feedbacks?page=1&limit=20' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

7.3 获取下一轮建议问题列表

GET /messages/{message_id}/suggested

获取指定消息的下一轮建议问题列表。

路径参数

参数	类型	说明
message_id	string	消息 ID。

查询参数

参数	类型	必填	说明
user	string	是	终端用户标识。

请求示例

curl --location --request GET 'http://49.232.138.53/v1/messages/{message_id}/suggested?user=abc-123' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

7.4 获取会话历史消息

GET /messages

获取指定会话的历史消息。

查询参数

参数	类型	必填	说明
user	string	是	终端用户标识。
conversation_id	string	是	会话 ID。
first_id	string	否	当前页第一条聊天记录 ID，用于分页。
limit	int	否	一次请求返回多少条记录，默认 20。

请求示例

curl -X GET 'http://49.232.138.53/v1/messages?user=abc-123&conversation_id={conversation_id}' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

8. 会话接口

8.1 获取会话列表

GET /conversations

获取当前用户的会话列表。

查询参数

参数	类型	必填	说明
user	string	是	终端用户标识。
last_id	string	否	当前页最后一条记录 ID，用于分页。
limit	int	否	一次请求返回多少条记录，默认 20。
sort_by	string	否	排序字段，例如 created_at、updated_at。

请求示例

curl -X GET 'http://49.232.138.53/v1/conversations?user=abc-123&last_id=&limit=20' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

8.2 删除会话

DELETE /conversations/:conversation_id

删除指定会话。

路径参数

参数	类型	说明
conversation_id	string	会话 ID。

请求体参数

参数	类型	必填	说明
user	string	是	终端用户标识。

请求示例

curl -X DELETE 'http://49.232.138.53/v1/conversations/{conversation_id}' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "user": "abc-123"
  }'

8.3 会话重命名

POST /conversations/:conversation_id/name

重命名指定会话。

路径参数

参数	类型	说明
conversation_id	string	会话 ID。

请求体参数

参数	类型	必填	说明
name	string	否	新会话名称。
auto_generate	bool	否	是否自动生成标题。
user	string	是	终端用户标识。

请求示例

curl -X POST 'http://49.232.138.53/v1/conversations/{conversation_id}/name' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "新的会话名称",
    "auto_generate": false,
    "user": "abc-123"
  }'

8.4 获取对话变量

GET /conversations/:conversation_id/variables

获取指定会话中的变量列表。

路径参数

参数	类型	说明
conversation_id	string	会话 ID。

查询参数

参数	类型	必填	说明
user	string	是	终端用户标识。
last_id	string	否	当前页最后一条记录 ID。
limit	int	否	每页数量。

请求示例

curl -X GET 'http://49.232.138.53/v1/conversations/{conversation_id}/variables?user=abc-123' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

8.5 更新对话变量

PUT /conversations/:conversation_id/variables/:variable_id

更新指定会话变量。

路径参数

参数	类型	说明
conversation_id	string	会话 ID。
variable_id	string	变量 ID。

请求体参数

参数	类型	必填	说明
value	string	是	变量值。
user	string	是	终端用户标识。

请求示例

curl -X PUT 'http://49.232.138.53/v1/conversations/{conversation_id}/variables/{variable_id}' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "value": "Updated Value",
    "user": "abc-123"
  }'

9. 音频接口

9.1 语音转文字

POST /audio-to-text

将音频文件转写为文本。

请求体参数

该接口使用 multipart/form-data 请求。

参数	类型	必填	说明
file	file	是	音频文件。
user	string	是	终端用户标识。

请求示例

curl -X POST 'http://49.232.138.53/v1/audio-to-text' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --form 'file=@localfile;type=audio/mpeg' \
  --form 'user=abc-123'

9.2 文字转语音

POST /text-to-audio

将文本或消息内容转换为音频。

请求体参数

参数	类型	必填	说明
message_id	string	否	消息 ID。传入后对指定消息内容进行语音合成。
text	string	否	待转换文本。未传 message_id 时使用。
user	string	是	终端用户标识。

请求示例

curl -o text-to-audio.mp3 -X POST 'http://49.232.138.53/v1/text-to-audio' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "text": "hello",
    "user": "abc-123"
  }'

10. 应用信息接口

10.1 获取应用基本信息

GET /info

获取应用基本信息。

curl -X GET 'http://49.232.138.53/v1/info' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

10.2 获取应用参数

GET /parameters

获取应用输入参数、用户输入表单、文件上传配置、系统参数等。

curl -X GET 'http://49.232.138.53/v1/parameters' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

10.3 获取应用 Meta 信息

GET /meta

获取应用 Meta 信息，例如工具图标等。

curl -X GET 'http://49.232.138.53/v1/meta' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

10.4 获取应用 WebApp 设置

GET /site

获取应用 WebApp 设置。

curl -X GET 'http://49.232.138.53/v1/site' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

11. 标注接口

11.1 获取标注列表

GET /apps/annotations

获取应用标注列表。

查询参数

参数	类型	必填	说明
page	string	否	页码，默认 1。
limit	string	否	每页数量，默认 20。

请求示例

curl --location --request GET 'http://49.232.138.53/v1/apps/annotations?page=1&limit=20' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

11.2 创建标注

POST /apps/annotations

创建一条标注问答。

请求体参数

参数	类型	必填	说明
question	string	是	问题。
answer	string	是	答案。

请求示例

curl --location --request POST 'http://49.232.138.53/v1/apps/annotations' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "question": "What is Dify?",
    "answer": "Dify is an LLM application development platform."
  }'

11.3 更新标注

PUT /apps/annotations/{annotation_id}

更新指定标注。

路径参数

参数	类型	说明
annotation_id	string	标注 ID。

请求体参数

参数	类型	必填	说明
question	string	是	问题。
answer	string	是	答案。

请求示例

curl --location --request PUT 'http://49.232.138.53/v1/apps/annotations/{annotation_id}' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "question": "What is Dify?",
    "answer": "Dify is an LLM application development platform."
  }'

11.4 删除标注

DELETE /apps/annotations/{annotation_id}

删除指定标注。

路径参数

参数	类型	说明
annotation_id	string	标注 ID。

请求示例

curl --location --request DELETE 'http://49.232.138.53/v1/apps/annotations/{annotation_id}' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

11.5 标注回复初始设置

POST /apps/annotation-reply/{action}

启用或禁用标注回复。该接口异步执行，返回 job_id 后可通过任务状态接口查询最终结果。

路径参数

参数	类型	说明
action	string	动作，只能是 enable 或 disable。

请求体参数

参数	类型	必填	说明
score_threshold	number	是	相似度阈值。当相似度大于该阈值时，系统自动回复。
embedding_provider_name	string	是	嵌入模型提供商。
embedding_model_name	string	是	嵌入模型名称。

请求示例

curl --location --request POST 'http://49.232.138.53/v1/apps/annotation-reply/{action}' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "score_threshold": 0.9,
    "embedding_provider_name": "zhipu",
    "embedding_model_name": "embedding_3"
  }'

响应示例

{
  "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
  "job_status": "waiting"
}

11.6 查询标注回复初始设置任务状态

GET /apps/annotation-reply/{action}/status/{job_id}

查询标注回复启用或禁用任务状态。

路径参数

参数	类型	说明
action	string	动作，只能是 enable 或 disable，并且必须和标注回复初始设置接口的动作一致。
job_id	string	任务 ID，由标注回复初始设置接口返回。

请求示例

curl --location --request GET 'http://49.232.138.53/v1/apps/annotation-reply/{action}/status/{job_id}' \
  --header 'Authorization: Bearer app-MqQOx09gCu9zzlKMpeLqHQHv'

响应示例

{
  "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
  "job_status": "waiting",
  "error_msg": ""
}

12. 通用响应对象

12.1 Usage

字段	类型	说明
prompt_tokens	int	提示词 token 数。
prompt_unit_price	string	提示词单价。
prompt_price_unit	string	提示词价格单位。
prompt_price	string	提示词价格。
completion_tokens	int	补全 token 数。
completion_unit_price	string	补全单价。
completion_price_unit	string	补全价格单位。
completion_price	string	补全价格。
total_tokens	int	总 token 数。
total_price	string	总价格。
currency	string	货币。
latency	number	请求耗时。

12.2 RetrieverResource

字段	类型	说明
position	int	引用位置。
dataset_id	string	数据集 ID。
dataset_name	string	数据集名称。
document_id	string	文档 ID。
document_name	string	文档名称。
segment_id	string	分段 ID。
score	number	相关性分数。
content	string	分段内容。