工作流编排对话型应用 API

对话应用支持会话持久化，可将之前的聊天记录作为上下进行回答，可适用于聊天/客服 AI 等。

基础 URL

Code

http://ai.995120.cn/v1

鉴权

Service API 使用 API-Key 进行鉴权。强烈建议开发者将 API-Key 存储于后端，而不是分享或存储于客户端，以避免 API-Key 泄露，防止可能造成的经济损失。 所有的 API 请求都需在 Authorization HTTP 头中包含您的 API-Key，具体如下所示：

1

 Authorization: Bearer {API_KEY}

 metadata

对象元数据

usage (Usage): 模型的使用量信息。
retriever_resources (array[RetrieverResource]): 包含引用和归属信息的分段列表。

消息创建时间

created_at (int): 表示消息创建的时间戳，例如：1705395332。

流式响应结构

ChunkChatCompletionResponse: 此结构用于返回应用程序输出的流式块，其 Content-Type 为 text/event-stream。每个流式块均以 data: 开头，并且块与块之间通过进行分隔，如下所示：

data: 块内容1
 data: 块内容2
 ...
 data: [DONE]

注意: 在处理上述流式响应时，请确保按照描述的格式正确解析每个数据块。

 data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n

CopyCopied!
流式块中根据 event 不同，结构也不同：
-

 event: message

以下是LLM返回文本块事件的详细信息，内容已重新编写并结构化：

任务ID：``
消息唯一ID：``
会话ID：``
LLM返回文本块内容：``
创建时间戳：1705395332

 event: message_file

文件事件，表示有新文件需要展示。

id (string)：文件唯一ID
type (string)：文件类型，目前仅为image
belongs_to (string)：文件归属，user或assistant，该接口返回仅为 assistant
url (string)：文件访问地址
conversation_id (string)：会话ID

 event: message_end

消息结束事件，收到此事件则代表流式返回结束。

task_id (string) 任务 ID，用于请求跟踪和下方的停止响应接口
message_id (string) 消息唯一 ID
conversation_id (string) 会话 ID

 metadata

(object) 元数据

usage (Usage) 模型用量信息
retriever_resources (array[RetrieverResource]) 引用和归属分段列表

 event: tts_message

TTS 音频流事件，即：语音合成输出。内容是Mp3格式的音频块，使用 base64 编码后的字符串，播放的时候直接解码即可。(开启自动播放才有此消息)

task_id (string) 任务 ID，用于请求跟踪和下方的停止响应接口
message_id (string) 消息唯一 ID
audio (string) 语音合成之后的音频块使用 Base64 编码之后的文本内容，播放的时候直接 base64 解码送入播放器即可
created_at (int) 创建时间戳，如：1705395332

 event: tts_message_end

当接收到TTS音频流结束事件时，表示音频流已成功返回并结束。以下是该事件的相关字段信息：

任务ID（task_id）：这是一个字符串类型的任务标识符，用于请求跟踪和调用停止响应接口。
消息唯一ID（message_id）：这是一个字符串，用于标识消息的唯一性。
音频（audio）：由于是结束事件，所以这里没有音频内容，表现为一个空字符串。
创建时间戳（created_at）：这是一个整数，表示事件创建的时间戳，例如1705395332。以上信息有助于理解和处理TTS音频流结束事件。

 event: message_replace

消息内容替换事件

任务 ID (task_id): 用于请求跟踪和下方的停止响应接口的字符串标识。
消息唯一 ID (message_id): 标识每条消息的唯一字符串。
会话 ID (conversation_id): 表示会话的唯一标识符。
替换内容 (answer): 当触发审查条件时，将LLM的所有回复文本替换为此预设内容。
创建时间戳 (created_at): 记录事件创建的时间，例如：1705395332。注意: 在执行上述操作时，请确保内容的条理性和结构化，并使用Markdown格式进行编辑。

 event: workflow_started

workflow 开始执行

task_id (string) 任务 ID，用于请求跟踪和下方的停止响应接口
workflow_run_id (string) workflow 执行 ID
event (string) 固定为 workflow_started

 data

(object) 详细内容

id (string) workflow 执行 ID
workflow_id (string) 关联 Workflow ID
sequence_number (int) 自增序号，App 内自增，从 1 开始
created_at (timestamp) 开始时间

 event: node_started

node 开始执行

task_id (string) 任务 ID，用于请求跟踪和下方的停止响应接口
workflow_run_id (string) workflow 执行 ID
event (string) 固定为 node_started

 data

详细内容：

id (string) workflow 执行 ID
node_id (string) 节点 ID
node_type (string) 节点类型
title (string) 节点名称
index (int) 执行序号，用于展示 Tracing Node 顺序
predecessor_node_id (string) 前置节点 ID，用于画布展示执行路径
inputs (array[object]) 节点中所有使用到的前置节点变量内容
created_at (timestamp) 开始时间

 event: node_finished

node 执行结束，成功失败同一事件中不同状态

task_id (string) 任务 ID，用于请求跟踪和下方的停止响应接口
workflow_run_id (string) workflow 执行 ID
event (string) 固定为 node_finished

 data

以下是对给定对象属性的详细描述，内容已重新编写并具有条理性与结构性。

ID: `` (string) 表示节点的执行ID。
节点ID: `` (string) 表示节点的唯一标识。
执行序号: index (int) 用于展示Tracing Node的顺序。
前置节点ID: predecessor_node_id (string) 可选，用于画布展示执行路径。
前置节点变量内容: inputs (array[object]) 包含节点中所有使用到的前置节点变量。
节点过程数据: process_data (json) 可选，包含节点过程数据。
输出内容: outputs (json) 可选，包含节点的输出内容。
执行状态: status (string) 表示执行状态，可能的值为running、succeeded、failed或stopped。
错误原因: error (string) 可选，包含错误发生时的原因。
耗时: elapsed_time (float) 可选，表示执行耗时，单位为秒。

 execution_metadata

(json) 元数据

total_tokens (int) optional 总使用 tokens
total_price (decimal) optional 总费用
currency (string) optional 货币，如 USD / RMB
created_at (timestamp) 开始时间

 event: workflow_finished

workflow 执行结束，成功失败同一事件中不同状态

task_id (string) 任务 ID，用于请求跟踪和下方的停止响应接口
workflow_run_id (string) workflow 执行 ID
event (string) 固定为 workflow_finished

 data

以下是关于workflow执行的详细信息，内容已按照条理性和结构性重新编写，并使用’‘代替了原有的空格：

ID：``（workflow执行ID）
Workflow ID：``（关联的Workflow ID）
Status：``（执行状态，可能为running、succeeded、failed或stopped）
Outputs：``（可选的输出内容，JSON格式）
Error：``（可选的错误原因）
Elapsed Time：``（可选的耗时，单位为秒）
Total Tokens：``（可选的总使用tokens数）
Total Steps：``（总步数，冗余字段，默认为0）
Created At：``（开始时间，时间戳格式）
Finished At：``（结束时间，时间戳格式）

 event: error

在流式输出的过程中，如果发生异常，这些异常将以stream event的形式被输出，并且一旦接收到异常事件，该过程就会终止。

task_id (string): 任务ID，用于请求跟踪以及通过下方的停止响应接口进行操作。
message_id (string): 消息的唯一标识符。
status (int): HTTP状态码，表示请求的处理结果。
code (string): 错误码，提供更具体的错误类型信息。
message (string): 错误消息，描述了错误的具体情况。另外，为了保持连接的活跃状态，每10秒将发送一个event: ping事件。

错误代码及其含义

404: 对话不存在，意味着请求的对话或资源无法找到。
400, invalid_param: 传入参数异常，表示客户端提供的参数不符合要求。
400, app_unavailable: App配置不可用，表明应用程序的设置存在问题，导致无法正常使用。
400, provider_not_initialize: 无可用模型凭据配置，意味着与服务提供商的凭证或配置没有正确设置。
400, provider_quota_exceeded: 模型调用额度不足，指用户的调用次数已经超过了限制。
400, model_currently_not_support: 当前模型不可用，表示请求的模型暂时无法提供服务。
400, completion_request_error: 文本生成失败，意味着在尝试生成文本时遇到了问题。
500: 服务内部异常，这是一个通用的错误代码，当服务器遇到未知或未预料到的问题时返回。

请求方式

方法: POST
路径: /chat-messages

curl -X POST 'http://ai.995120.cn/v1/chat-messages' \
--header 'Authorization: Bearer {api_key}' \
--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"
 }
 ]
}'

CopyCopied!

阻塞模式

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


{
 "event": "message",
 "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,
 "prompt_unit_price": "0.001",
 "prompt_price_unit": "0.001",
 "prompt_price": "0.0010330",
 "completion_tokens": 128,
 "completion_unit_price": "0.002",
 "completion_price_unit": "0.001",
 "completion_price": "0.0002560",
 "total_tokens": 1161,
 "total_price": "0.0012890",
 "currency": "USD",
 "latency": 0.7682376249867957
 },
 "retriever_resources": [
 {
 "position": 1,
 "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
 "dataset_name": "iPhone",
 "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00",
 "document_name": "iPhone List",
 "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a",
 "score": 0.98457545,
 "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""
 }
 ]
 },
 "created_at": 1705407629
}

CopyCopied!

流式模式

Response

 data: {"event": "workflow_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "sequence_number": 1, "created_at": 1679586595}}
 data: {"event": "node_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "created_at": 1679586595}}
 data: {"event": "node_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "execution_metadata": {"total_tokens": 63127864, "total_price": 2.378, "currency": "USD"}, "created_at": 1679586595}}
 data: {"event": "workflow_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "total_tokens": 63127864, "total_steps": "1", "created_at": 1679586595, "finished_at": 1679976595}}
 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", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": "'m", "created_at": 1679586595}
 data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " glad", "created_at": 1679586595}
 data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " to", "created_at": 1679586595}
 data: {"event": "message", "message_id": : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " meet", "created_at": 1679586595}
 data: {"event": "message", "message_id": : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " you", "created_at": 1679586595}
 data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548}, "retriever_resources": [{"position": 1, "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", "dataset_name": "iPhone", "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", "document_name": "iPhone List", "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", "score": 0.98457545, "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""}]}}
 data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
 data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}

文件上传接口说明

此接口用于上传文件（现阶段仅支持图片），以便在发送消息时能够结合文本与图片进行多模态的理解。支持的文件格式包括：png, jpg, jpeg, webp, gif。请注意，上传的文件仅供当前终端用户使用。

请求体

该接口需要通过 multipart/form-data 方式提交请求。

file
类型: file
描述: 需要上传的文件。
user
类型: string
描述: 用户标识符，用于确定终端用户的身份，务必保证与发送消息接口中提供的 user 参数一致。

响应

成功上传文件后，服务器将返回包含文件ID及其他相关信息的响应。

id (uuid): 文件的唯一标识符。
name (string): 文件名称。
size (int): 文件大小，以字节为单位。
extension (string): 文件的扩展名。
mime_type (string): 文件的 MIME 类型。
created_by (uuid): 上传者的唯一标识符。
created_at (timestamp): 文件的上传时间戳。

错误码

400，no_file_uploaded：请求中未提供文件。
400，too_many_files：一次请求中只能上传一个文件。
400，unsupported_preview：上传的文件类型不支持预览。
400，unsupported_estimate：上传的文件类型不支持评估。
413，file_too_large：文件体积超过允许的最大值。
415，unsupported_file_type：不支持的文件格式，目前仅接受图片类型的文件。
503，s3_connection_failed：无法建立与S3存储服务的连接。
503，s3_permission_denied：没有足够的权限将文件上传至S3。
503，s3_file_too_large：文件大小超出了S3的服务限制。

请求示例

方法: POST
URL: /files/upload 请注意，根据上述要求准备您的请求。

curl -X POST 'http://ai.995120.cn/v1/files/upload' \
--header 'Authorization: Bearer {api_key}' \
--form 'file=@localfile;type=image/[png|jpeg|jpg|webp|gif] \
--form 'user=abc-123'

CopyCopied!

Response

1
2
3
4
5
6
7
8
9


{
 "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
 "name": "example.png",
 "size": 1024,
 "extension": "png",
 "mime_type": "image/png",
 "created_by": 123,
 "created_at": 1577836800,
}

停止响应

此功能仅适用于流式模式。

路径参数

task_id (字符串) 任务 ID，该ID可从流式返回的数据块中获得。

请求体

user (字符串) 必填用户标识，用于确认终端用户的身份，必须与发送消息接口中提供的 user 参数一致。

响应

result (字符串) 响应结果为固定的 ‘success’ 表示操作成功。

示例请求

POST /chat-messages/ /stop

curl -X POST 'http://ai.995120.cn/v1/chat-messages/:task_id/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{ "user": "abc-123"}'

CopyCopied!

Response

1
2
3


{
 "result": "success"
}

消息反馈（点赞）

消息反馈（点赞）消息终端用户反馈、点赞，方便应用开发者优化输出预期。

Path Params

Name: message_id
Type: string
Description: 消息 ID

Request Body

Name: rating
Type: string
Description: 点赞 like, 点踩 dislike, 撤销点赞 null
Name: user
Type: string
Description: 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。

Response

result (string) 固定返回 success

Request

POST /messages/:message_id/feedbacks

curl -X POST 'http://ai.995120.cn/v1/messages/:message_id/feedbacks \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
 "rating": "like",
 "user": "abc-123"
}'

CopyCopied!

Response

1
2
3


{
 "result": "success"
}

CopyCopied!

GET/messages/{message_id}/suggested

获取下一轮建议问题列表

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

Path Params

- Name

message_id

Type

string

Description

Message ID

Query

- Name

user

Type

string

Description

用户标识，由开发者定义规则，需保证用户标识在应用内唯一。

Request

GET

/messages/{message_id}/suggested

curl --location --request GET 'http://ai.995120.cn/v1/messages/{message_id}/suggested?user=abc-123 \
--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
--header 'Content-Type: application/json'

CopyCopied!

Response

1
2
3
4
5
6
7
8


{
 "result": "success",
 "data": [
 "a",
 "b",
 "c"
 ]
}

获取会话历史消息接口允许用户通过指定会话ID和用户标识来检索聊天记录。该接口采用滚动加载的方式，默认每次请求返回最新的20条聊天记录。用户可以通过传递first_id参数来指定从哪条记录开始返回，从而实现分页功能。返回的消息列表包括每条消息的ID、会话ID以及用户的输入参数和提问内容。

 message_files

(array[object]) 消息文件

id (string) ID
type (string) 文件类型，image 图片
url (string) 预览图片地址
belongs_to (string) 文件归属方，user 或 assistant
answer (string) 回答消息内容
created_at (timestamp) 创建时间

 feedback

以下是对反馈信息的详细说明：

点赞与点踩：用户可以通过rating字段来表达他们对内容的喜好，其中like代表点赞，dislike代表点踩。
引用和归属分段列表：retriever_resources字段包含了一个数组，数组中的每个元素都是RetrieverResource类型，用于列出所有引用和归属的分段。
是否存在下一页：has_more字段是一个布尔值，用于指示是否存在更多的反馈信息页面。如果还有更多的页面，该字段值为true；如果没有，则为false。
返回条数限制：limit字段是一个整数，表示单次请求返回的反馈信息条数。如果传入的值超过了系统设定的限制，系统将返回限制数量的结果。

请求示例

请求方法

GET

请求路径

/messages

curl -X GET 'http://ai.995120.cn/v1/messages?user=abc-123&conversation_id=' \
--header 'Authorization: Bearer {api_key}'

CopyCopied!

Response Example

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


{
"limit": 20,
"has_more": false,
"data": [
 {
 "id": "a076a87f-31e5-48dc-b452-0061adbbc922",
 "conversation_id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce",
 "inputs": {
 "name": "dify"
 },
 "query": "iphone 13 pro",
 "answer": "The iPhone 13 Pro, released on September 24, 2021, features a 6.1-inch display with a resolution of 1170 x 2532. It is equipped with a Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard) processor, 6 GB of RAM, and offers storage options of 128 GB, 256 GB, 512 GB, and 1 TB. The camera is 12 MP, the battery capacity is 3095 mAh, and it runs on iOS 15.",
 "message_files": [],
 "feedback": null,
 "retriever_resources": [
 {
 "position": 1,
 "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
 "dataset_name": "iPhone",
 "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00",
 "document_name": "iPhone List",
 "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a",
 "score": 0.98457545,
 "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""
 }
 ],
 "created_at": 1705569239
 }
 ]
}

CopyCopied!

Response Example(智能助手)

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


{
"limit": 20,
"has_more": false,
"data": [
 {
 "id": "d35e006c-7c4d-458f-9142-be4930abdf94",
 "conversation_id": "957c068b-f258-4f89-ba10-6e8a0361c457",
 "inputs": {},
 "query": "draw a cat",
 "answer": "I have generated an image of a cat for you. Please check your messages to view the image.",
 "message_files": [
 {
 "id": "976990d2-5294-47e6-8f14-7356ba9d2d76",
 "type": "image",
 "url": "http://127.0.0.1:5001/files/tools/976990d2-5294-47e6-8f14-7356ba9d2d76.png?timestamp=1705988524&nonce=55df3f9f7311a9acd91bf074cd524092&sign=z43nMSO1L2HBvoqADLkRxr7Biz0fkjeDstnJiCK1zh8=",
 "belongs_to": "assistant"
 }
 ],
 "feedback": null,
 "retriever_resources": [],
 "created_at": 1705988187
 }
 ]
}

获取会话列表

此接口用于获取当前用户的会话列表，默认情况下将返回最近的20条记录。

请求参数

user
类型: string
描述: 用户标识，由开发者自行定义规则，确保该标识在应用内部具有唯一性。
last_id (可选)
类型: string
描述: 表示当前页面最后一条记录的ID，默认值为null。
limit (可选)
类型: int
描述: 单次请求希望返回的记录数量。
pinned (可选)
类型: bool
描述: 设置为true时仅返回置顶的会话，设置为false时仅返回非置顶的会话。

响应说明

调用成功后，API将返回与指定条件相匹配的会话列表。

 data

会话列表包含以下字段：

id (string): 会话 ID
name (string): 会话名称，默认由大语言模型生成。
inputs (array[object]): 用户输入参数。
introduction (string): 开场白
created_at (timestamp): 创建时间此外，还有两个额外的字段：
has_more (bool): 是否有更多内容
limit (int): 返回条数，若传入超过系统限制，返回系统限制数量

curl -X GET 'http://ai.995120.cn/v1/conversations?user=abc-123&last_id=&limit=20'\
--header 'Authorization: Bearer {api_key}'

CopyCopied!

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


{
 "limit": 20,
 "has_more": false,
 "data": [
 {
 "id": "10799fb8-64f7-4296-bbf7-b42bfbe0ae54",
 "name": "New chat",
 "inputs": {
 "book": "book",
 "myName": "Lucy"
 },
 "status": "normal",
 "created_at": 1679667915
 },
 {
 "id": "hSIhXBhNe8X1d8Et"
 // ...
 }
 ]
}

DELETE/conversations/:conversation_id

删除会话

此接口用于删除指定的会话。

路径参数

conversation_id (string): 会话的唯一标识符。

请求体

user: 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
类型 (Type): string
描述 (Description): 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。

响应

result (string): 操作结果，固定返回 ‘success’。

请求方法

请求类型: DELETE
路径: /conversations/:conversation_id 注意: 在使用此接口时，请确保正确替换 conversation_id 为实际的会话 ID。

curl -X DELETE 'http://ai.995120.cn/v1/conversations/:conversation_id' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
 "user": "abc-123"
}'

CopyCopied!

Response

1
2
3


{
 "result": "success"
}

对会话进行重命名，会话名称用于显示在支持多会话的客户端上。

Request Body

name (string): 名称，若 auto_generate 为 true 时，该参数可不传。
auto_generate (string): 自动生成标题，默认 false。
user (string): 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。

Response

id (string): 会话 ID
name (string): 会话名称
inputs array[object]: 用户输入参数。
introduction (string): 开场白
created_at (timestamp): 创建时间

curl -X POST 'http://ai.995120.cn/v1/conversations/name' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
 "name": "",
 "user": "abc-123"
}'

CopyCopied!

Response

1
2
3


{
 "result": "success"
}

语音转文字 API

请求方式

方法
POST
路径
/audio-to-text

请求体

该接口需要使用 multipart/form-data 格式进行请求。

参数
Name: file
Type: file
Description: 上传的语音文件。支持的格式包括：['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']。文件大小不得超过15MB。
Name: user
Type: string
Description: 用户标识符，由开发人员自行定义规则，确保此标识符在应用程序内部具有唯一性。

响应

text (string): 转换后的文本内容。

注意事项

请确保遵循上述参数要求以避免请求失败。

curl -X POST 'http://ai.995120.cn/v1/audio-to-text' \
--header 'Authorization: Bearer {api_key}' \
--form 'file=@localfile;type=audio/[mp3|mp4|mpeg|mpga|m4a|wav|webm]

CopyCopied!

Response

1
2
3


{
 "text": "hello"
}

CopyCopied!

POST/text-to-audio

文字转语音

文字转语音。

Request Body

- Name

message_id

Type

str

Description

Dify 生成的文本消息，那么直接传递生成的message-id 即可，后台会通过 message_id 查找相应的内容直接合成语音信息。如果同时传 message_id 和 text，优先使用 message_id。

- Name

text

Type

str

Description

语音生成内容。如果没有传 message-id的话，则会使用这个字段的内容

- Name

user

Type

string

Description

用户标识，由开发者定义规则，需保证用户标识在应用内唯一。

Request

POST

/text-to-audio

curl -o text-to-audio.mp3 -X POST 'http://ai.995120.cn/v1/text-to-audio' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
 "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290",
 "text": "你好Dify",
 "user": "abc-123"
}'

CopyCopied!

headers

1
2
3


{
 "Content-Type": "audio/wav"
}

获取应用配置信息

用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。

请求参数

Query参数

Name
类型: string
描述: 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。

响应内容

响应字段

opening_statement (string): 开场白
suggested_questions (array[string]): 开场推荐问题列表

 suggested_questions_after_answer

(object) 启用回答后给出推荐问题。

enabled (bool) 是否开启

 speech_to_text

(object) 语音转文本

enabled (bool) 是否开启

 retriever_resource

(object) 引用和归属

enabled (bool) 是否开启

 annotation_reply

(object) 标记回复

enabled (bool) 是否开启

 user_input_form

(array[object]) 用户输入表单配置

 text-input

(object) 文本输入控件

label (string) 控件展示标签名
variable (string) 控件 ID
required (bool) 是否必填
default (string) 默认值

 paragraph

(object) 段落文本输入控件

label (string) 控件展示标签名
variable (string) 控件 ID
required (bool) 是否必填
default (string) 默认值

 select

(object) 下拉控件

label (string) 控件展示标签名
variable (string) 控件 ID
required (bool) 是否必填
default (string) 默认值
options (array[string]) 选项值

 file_upload

(object) 文件上传配置

 image

(object) 图片设置当前仅支持图片类型：

png

jpg

 jpeg

 webp

gif

enabled (bool) 是否开启
number_limits (int) 图片数量限制，默认 3
transfer_methods (array[string]) 传递方式列表，remote_url , local_file，必选一个

 system_parameters

(object) 系统参数

image_file_size_limit (string) 图片文件上传大小限制（MB）

Request

GET

/parameters

 curl -X GET 'http://ai.995120.cn/v1/parameters'\
--header 'Authorization: Bearer {api_key}'

CopyCopied!

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


{
 "introduction": "nice to meet you",
 "user_input_form": [
 {
 "text-input": {
 "label": "a",
 "variable": "a",
 "required": true,
 "max_length": 48,
 "default": ""
 }
 },
 {
 // ...
 }
 ],
 "file_upload": {
 "image": {
 "enabled": true,
 "number_limits": 3,
 "transfer_methods": [
 "remote_url",
 "local_file"
 ]
 }
 }
}

获取应用Meta信息

此接口用于获取应用的元数据信息，例如工具图标等。

请求方法

路径 /meta
方法 GET

Query 参数

Name user
Type string
Description 用户标识，由开发者自行定义规则，确保该标识在应用内部具有唯一性。

响应

响应中将包含请求的应用元数据信息。

 tool_icons

(object[string]) 工具图标

 工具名称

(string)

 icon

(object|string)

(object) 图标
background (string) hex格式的背景色
content(string) emoji
(string) 图标URL

Request

POST

/meta

curl -X GET 'http://ai.995120.cn/v1/meta?user=abc-123' \
-H 'Authorization: Bearer {api_key}'

CopyCopied!

Response

1
2
3
4
5
6
7
8
9


{
 "tool_icons": {
 "dalle2": "https://cloud.dify.ai/console/api/workspaces/current/tool-provider/builtin/dalle/icon",
 "api_tool": {
 "background": "#252525",
 "content": "😁"
 }
 }
}

文章目录

工作流编排对话型应用 API

基础 URL

Code

鉴权

对象元数据

消息创建时间

流式响应结构

消息内容替换事件

错误代码及其含义

请求方式

阻塞模式

Response

流式模式

Response

文件上传接口说明

请求体

响应

错误码

请求示例

Response

停止响应

路径参数

请求体

响应

示例请求

Response

消息反馈（点赞）

Path Params

Request Body

Response

Request

Response

获取下一轮建议问题列表

Path Params

Query

Request

Response

请求示例

请求方法

请求路径

Response Example

Response

Response Example(智能助手)

Response

获取会话列表

请求参数

响应说明

Response

DELETE/conversations/:conversation_id

删除会话

路径参数

请求体

响应

请求方法

Response

Request Body

Response

Response

语音转文字 API

请求方式

请求体

响应

注意事项

Response

文字转语音

Request Body

Request

headers

获取应用配置信息

请求参数

Query参数

响应内容

响应字段

Request

Response

获取应用Meta信息

请求方法

Query 参数

响应