langgenius/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-07-22 20:36:31 -04:00
Code Issues 10 Packages Projects Releases Wiki Activity
Files
6258bbfb0f653f3caaa06fae84207c82041b0ac8
dify-docs/zh/api-reference/openapi_chatflow.json
T
Riskey 32e1b169da feat: consolidate and restructure the API reference (Phase 1) (#846) 
* docs: correct HITL API integration flow and sync translations

- Fix the claim that the resume endpoint differs per app type (same
  endpoint; only the entry endpoint differs)
- Tie workflow_run_id guidance to the human_input_required event
  (chatflow message chunks don't carry it)
- Require the same user when resuming the event stream (mismatch
  returns 404); add include_state_snapshot and continue_on_pause
  guidance
- Note at the capture step that a null form_token means Email delivery
- Soften the upload-time validation claim to file size limits
- Split long paragraphs; align zh endpoint name with the reference page

* fix: correct API references against verified backend behavior

Audit of the Service API specs against dify hotfix/1.15.0-fix.1, with
every change code-verified and the serious items adversarially
confirmed. Applies to en/zh/ja.

- Add curl samples for GET endpoints with required query params
  (Mintlify omits query params from generated snippets)
- Document 401 once in every spec's auth scheme description
- Correct wrong facts: workflow run detail returns inputs as a JSON
  string; DELETE /conversations requires a JSON body; audio-to-text
  accepts audio/{mp3,m4a,wav,amr,mpga} by MIME type; workflow log
  created_by_account filters by email; triggered_from values are
  app-run/webhook/schedule/plugin; stop endpoints' user semantics
  differ per app type
- Remove unreachable docs: phantom text_replace SSE event, annotation
  403, file preview endpoint in the workflow spec, invented
  score_threshold bounds
- Make upload user optional (DEFAULT-USER fallback), fix upload
  response example, add missing invalid_param error
- Declare text_to_speech.autoPlay in parameters responses (prose
  values, no response-field enums)

* fix: complete API reference audit for knowledge and completion specs

* feat: add API spec consolidation pipeline

Phase-1 of the API docs consolidation: tooling that merges the five per-app-type Service API specs into one openapi_service.json per language, with every divergence resolved explicitly in resolutions.json and rendering-preserving namespacing for mode-scoped schema families. Includes the audit lint and parity checks (lint taught the new language-prefixed href scheme), hand-merged mode-aware SSE documentation for POST /chat-messages in en/zh/ja, and the New Agent (Beta) virtual nav group with code-verified mode notes.

* feat: consolidate API reference into one spec per language

Emit {en,zh,ja}/api-reference/openapi_service.json (82 ops, 130 components) from the audit-fixed per-app-type specs; wire docs.json to them with explicit per-app-type endpoint lists, x-mint.href URLs (/{lang}/api-reference/{tag}/{summary} with shared English slugs for in-place language switching), 265 redirects covering the legacy en and CJK URLs, per-app-type overview pages including New Agent (Beta), and rewritten legacy API links in 21 MDX bodies. The old five specs per language stay as pipeline input; they are no longer rendered.

* fix: remove dead conversation_completed error from chat specs

ConversationCompletedError is never raised anywhere at the verified 1.15.0 ref (7a4252b3de): controllers catch it, but no service code raises it, so the documented 400 conversation_completed can never fire. Remove the bullet and example from the chat and chatflow /chat-messages docs in en/zh/ja. Found and adversarially confirmed during the New Agent (PR #836) verification; filed on the upstream bug list.

* feat: add membership matrix and restructure nav config

* feat: rename resource tags and update all references

* feat: stamp per-operation availability lines

* feat: wire three-group API navigation

* feat: add app-type page coverage lint

* docs: rewrite chatflow overview as app-type API guide

* docs: polish chatflow overview zh and ja wording

* docs: rewrite workflow overview as app-type API guide

* docs: align workflow overview details across languages

* docs: expand new agent overview into app-type API guide

* docs: use task-oriented heading on new agent overview

* docs: rewrite chatbot and agent overview as app-type API guide

* docs: rewrite text generator overview as app-type API guide

* docs: match end user link text to merged spec summary

* docs: rewrite knowledge overview as app-type API guide

* docs: move knowledge api guide into api reference

* docs: localize ui labels on knowledge overview

* docs: refresh pipeline readme for restructure modes

* docs: name app-type pages in the guides sidebar

* feat: rename zh completion messages tag to match resource framing

* docs: prototype endpoints-first layout on chatflow overview

* docs: correct detail accuracy on chatflow overview

* docs: move human input flow guide into api reference

Move the shared HITL API integration walkthrough from its six per-product
copies into {en,zh,ja}/api-reference/guides/human-input-flow as the first
task guide in the API docs. Guides gains an App Types subgroup (expanded
by default) with the flow guide after it; six redirects cover the old
paths; the Human Input node docs and the chatflow overview link to the
new home.

* fix: update spec links to the moved human input guide

* fix: let spec lint accept mdx guide pages under api-reference

* docs: align chatflow zh and ja overviews to endpoints-first layout

* docs: polish chatflow zh and ja mode terms and hitl wording

* docs: align workflow overviews to endpoints-first layout

* docs: document form expiry path in human input flow guide

* docs: align new agent overviews to endpoints-first layout

* docs: align chatbot and agent overviews to endpoints-first layout

* docs: align text generator overviews to endpoints-first layout

* docs: align knowledge overviews to endpoints-first layout

* docs: correct built-in metadata examples and agent heading

* docs: flatten app-type pages directly under guides

* docs: make guide pages self-contained and trim reference detail

* docs: add get started guide and retire developing-with-apis

* docs: update new agent api behavior for latest main

New Agent behavior re-verified against dify origin/main (f3ba2846):
agent_thought events now stream through the Service API carrying the
model's reasoning steps and tool calls; a new agent_not_published 400
fires on Send Chat Message and Get App Parameters; the files claim is
softened to contents-not-processed (raw references now reach the prompt;
runtime confirmation pending). Streaming-only, message_end metadata, and
the endpoint surface are unchanged.

* docs: audit fixes for get started and human input flow guides

* docs: fix em dash spacing and ja sentence length in get started

* docs: move message_end note to the send endpoint line

* docs: update writing guides and API skill for app-type naming

- Glossary and zh/ja translation guides: Workflow and Chatflow app types stay English (Workflow 应用 / Chatflow アプリ); lowercase workflow localizes to 工作流 / ワークフロー.
- formatting-guide: API reference links use the language prefix with English slugs.
- dify-docs-api-reference skill: Spec Structure documents source specs merged into openapi_service.json by the pipeline.

* feat: add operation sidebar titles and simplify API redirects

- merge_specs stamps x-mint.metadata.sidebarTitle per operation so translated summaries show in the sidebar.
- Redirects reduced to a catch-all to the English API home plus three knowledge-base exceptions.
- memberships, strings, and SSE overrides carry app-type labels (Workflow/Chatflow English, New Agent, API Overviews group).

* docs: correct app-type naming and translations across API specs

- English mode enum labels Chatflow and Workflow apps.
- zh/ja app references use Workflow/Chatflow; New Agent is 新 Agent / 新しい Agent.
- ja knowledge tag データセット becomes ナレッジベース; zh 模型提供商 becomes 模型供应商.
- Regenerate merged openapi_service.json with per-operation sidebar titles.

* docs: add streaming, errors, and end-user identity API guides

- Consume Streaming Responses: response modes, SSE parsing, event dispatch, and reconnect.
- Handle Errors and Rate Limits: the error envelope, status classes, and retry guidance.
- End User Identity: what the user field scopes and why it stays consistent.
- English source with zh and ja translations.

* docs: reconcile API guides and apply app-type naming

- Reader-test fixes and content audit on get-started and the app-type overview pages.
- zh/ja reconciled to the English source.
- Workflow/Chatflow and New Agent naming applied in prose.

* feat: wire API nav and redirects for consolidated guides

- Rename the guides group to API Overviews and register the new guide pages.
- Redirects: catch-all to the English API home plus three product-embedded knowledge-base links to the Knowledge guide.

* fix: normalize zh model-provider term to 模型供应商

Aligns the POSITION_PROVIDER_* descriptions with the canonical glossary term.

* docs: use Info callouts for guide forward-link notes

Wrap the authentication, base URL, and `user` field forward-reference in each app-type guide (agent, chat, chatflow, completion, workflow; en/zh/ja) in an `<Info>` callout.

* refactor: remove one-time analyze mode and verification compose

- Drop the `analyze` mode (design-time spec-overlap analysis) and its helpers; the merge is stable and nothing invokes it.
- Delete `compose.swagger.yml`, the throwaway local code-vs-spec verification stack (flagged in review for inline credentials).
- README: drop the analyze entry and correct the redirect description.

* fix: correct Chatflow naming and reasoning wording in SSE overrides

- Use "Chatflow" (English) for the app type in the `/chat-messages` SSE tables instead of 对话流/チャットフロー, and fix the legacy zh chatflow "对话流工作流" description. Standalone table cells were missed by the earlier app-type rename.
- Describe `reasoning_chunk` as "reasoning content" in en/ja (matching the `reasoning` field and the zh wording) instead of "chain-of-thought".

* docs: refine API guide wording and simplify the human-input example

* docs: standardize Workflow and Chatflow app-type capitalization

Capitalize Chatflow and Workflow when they name an app type; keep "workflow" lowercase for the general engine, graph, or run sense.

* fix: use 供应商 for model provider in the zh Knowledge spec

* fix: rename the Knowledge API nav group to "Knowledge APIs"

* fix: un-deprecate Update Document by Text in the Knowledge spec

* translate: un-deprecate Update Document by Text in zh/ja specs

Mirror the en fix (6802d5eb) into the zh and ja Knowledge specs, source and merged: drop the deprecated flag and the leading Deprecated notice from the update-by-text operation. It is the canonical text-update route; only Update Document by File stays deprecated.
2026-07-09 16:40:54 +08:00

6831 lines
250 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"openapi": "3.0.1",
"info": {
"title": "工作流编排对话型应用 API (对话流 API)",
"description": "Chatflow 应用支持会话持久化，允许将之前的聊天记录作为响应的上下文。Chatflow 应用使用 `advanced-chat` 模式，提供工作流级别的流式事件，用于详细的执行追踪，包括节点开始、完成、迭代和工作流生命周期。",
"version": "1.0.0"
},
"servers": [
{
"url": "https://{api_base_url}",
"description": "工作流编排对话型应用 API 的基础 URL。自部署时，替换为你的 API 基础 URL。",
"variables": {
"api_base_url": {
"default": "api.dify.ai/v1",
"description": "API 基础 URL 的主机与路径，不含 `https://` 前缀。"
}
}
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"paths": {
"/chat-messages": {
"post": {
"summary": "发送对话消息",
"description": "向对话型应用发送请求。",
"operationId": "sendChatMessageCn",
"tags": [
"对话流"
],
"requestBody": {
"description": "发送对话消息的请求体。",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatRequest"
},
"examples": {
"streaming_example": {
"summary": "请求示例 - 流式模式",
"value": {
"inputs": {
"city": "San Francisco"
},
"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"
}
]
}
},
"blocking_example": {
"summary": "请求示例 - 阻塞模式",
"value": {
"inputs": {},
"query": "What are the specs of the iPhone 13 Pro Max?",
"response_mode": "blocking",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `ChatCompletionResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和服务器发送事件流。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionResponse"
},
"examples": {
"blockingResponse": {
"summary": "响应示例 - 阻塞模式",
"value": {
"event": "message",
"task_id": "c3800678-a077-43df-a102-53f23ed20b88",
"id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"mode": "advanced-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\" \"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
}
}
}
},
"text/event-stream": {
"schema": {
"type": "string",
"description": "服务器发送事件 (SSE) 流。\n\n**解析**：每个事件是一行以 `data: ` 为前缀的 JSON 对象，以 `\\n\\n` 终止。解析 JSON 前先去除 `data: ` 前缀，再读取 `event` 字段确定事件类型。忽略 `ping` 事件，它以 `event: ping` 行的形式（无 `data:` 载荷）每 10 秒发送一次以保持连接活跃。\n\n**流生命周期**：工作流进度以 `workflow_started`、节点事件（`node_started` 和 `node_finished`，以及迭代和循环的相应变体）流式返回，回复则以 `message` 事件返回（设置 `reasoning_format: separated` 的 LLM 节点还会同时发送 `reasoning_chunk` 事件，承载模型的推理内容）。结束序列取决于运行结果：\n- **成功**：`message_end`，随后 `workflow_finished`\n- **失败**：`workflow_finished`（状态为 `failed`），随后 `error`；不发送 `message_end`\n- **暂停**：`human_input_required`，随后 `workflow_paused`（流到此结束，运行将另行恢复）\n\n开启文本转语音（TTS）自动播放时，`tts_message_end` 跟随在结束事件之后。\n\n**事件**：除 `ping` 外，每个事件都包含 `conversation_id`、`message_id` 和 `created_at`（Unix 纪元秒）；除 `error` 外，其余事件还包含 `task_id`。工作流、节点和人工介入事件还将载荷嵌套在 `data` 中，且除 `agent_log` 外都带有顶层 `workflow_run_id`。\n\n**回复事件**\n\n| 事件 | 触发时机 | 关键字段 |\n|:---|:---|:---|\n| `message` | 每个回答片段（按顺序拼接） | `answer` |\n| `message_replace` | 内容审核替换已生成的回答 | `answer`、`reason` |\n| `reasoning_chunk` | 每个推理内容增量，当 LLM 节点使用 `reasoning_format: separated` 时（按顺序拼接；`is_final: true` 的事件标志推理结束，且 `reasoning` 可能为空） | `data.message_id`、`data.reasoning`、`data.node_id`、`data.is_final` |\n| `message_end` | 回答完成 | `metadata`（`usage`、`retriever_resources`） |\n| `tts_message`、`tts_message_end` | 音频片段/结束，开启 TTS 自动播放时 | `audio` |\n\n**工作流与节点事件**\n\n每个事件都将载荷嵌套在 `data` 对象中。\n\n| 事件 | 触发时机 | 关键 `data` 字段 |\n|:---|:---|:---|\n| `workflow_started` | 运行开始 | `inputs` |\n| `node_started` | 节点开始 | `node_id`、`node_type`、`title` |\n| `node_finished` | 节点结束 | `status`、`outputs`、`execution_metadata` |\n| `node_retry` | 节点失败后重试 | `retry_index` |\n| `iteration_started`、`iteration_next`、`iteration_completed` | 迭代节点进度（信息性，可不处理） | `data` |\n| `loop_started`、`loop_next`、`loop_completed` | 循环节点进度（信息性，可不处理） | `data` |\n| `agent_log` | Agent 节点步骤日志（信息性，可不处理；无 `workflow_run_id`） | `data` |\n| `workflow_finished` | 运行结束 | `status`（`succeeded`、`failed`、`partial-succeeded`、`stopped`）、`outputs`、`total_tokens` |\n| `workflow_paused` | 运行暂停 | `paused_nodes`、`reasons` |\n| `human_input_required` | 运行到达人工介入节点 | `form_token`、`form_content`、`expiration_time` |\n\n暂停后，本流在 `workflow_paused` 处结束。通过 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单) 提交表单，或等待其超时；恢复后的运行（包括从 `human_input_form_filled`/`human_input_form_timeout` 到 `workflow_finished` 的事件）由 [流式获取工作流事件](/api-reference/对话流/流式获取工作流事件) 流式返回。\n\n**传输事件**\n\n| 事件 | 触发时机 | 关键字段 |\n|:---|:---|:---|\n| `error` | 失败导致流结束；HTTP 仍为 `200` | `status`（如 `400`）、`code`（如 `invalid_param`）、`message` |\n| `ping` | 每 10 秒保持连接 | 无 |"
},
"examples": {
"streamingResponseBasic": {
"summary": "Response Example - Streaming (Basic)",
"value": "data: {\"event\": \"message\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"created_at\": 1679586595, \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}"
},
"streamingResponseWorkflow": {
"summary": "Response Example - Streaming (工作流)",
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"The user greeted me, so\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395335, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}"
},
"humanInputPause": {
"summary": "响应示例 - 人工介入暂停",
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"paused_nodes\": [\"approval_node\"], \"outputs\": {}, \"reasons\": [{\"TYPE\": \"human_input_required\", \"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"resolved_default_values\": {\"comment\": \"\"}, \"form_token\": \"tok_abc123\", \"expiration_time\": 1705494029}], \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5, \"total_tokens\": 0, \"total_steps\": 1}}"
}
}
}
}
},
"400": {
"description": "- `app_unavailable` : 应用不可用或配置错误。\n- `not_chat_app` : App mode does not match the API route.\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 文本生成失败。\n- `bad_request` : Cannot use draft 工作流 version.\n- `bad_request` : Invalid `workflow_id` format.",
"content": {
"application/json": {
"examples": {
"app_unavailable": {
"summary": "app_unavailable",
"value": {
"status": 400,
"code": "app_unavailable",
"message": "App unavailable, please check your app configurations."
}
},
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"provider_quota_exceeded": {
"summary": "provider_quota_exceeded",
"value": {
"status": 400,
"code": "provider_quota_exceeded",
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
}
},
"model_currently_not_support": {
"summary": "model_currently_not_support",
"value": {
"status": 400,
"code": "model_currently_not_support",
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
}
},
"completion_request_error": {
"summary": "completion_request_error",
"value": {
"status": 400,
"code": "completion_request_error",
"message": "Completion request failed."
}
},
"is_draft_workflow": {
"summary": "bad_request",
"value": {
"status": 400,
"code": "bad_request",
"message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. "
}
},
"workflow_id_format_error": {
"summary": "bad_request",
"value": {
"status": 400,
"code": "bad_request",
"message": "Invalid workflow_id format: 'not-a-valid-id'. "
}
}
}
}
}
},
"404": {
"description": "- `not_found` : Conversation does not exist.\n- `not_found` : 工作流 not found with the specified `workflow_id`.",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
},
"workflow_not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}
}
}
}
},
"429": {
"description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 上游模型供应商的速率限制已超出。",
"content": {
"application/json": {
"examples": {
"too_many_requests": {
"summary": "too_many_requests",
"value": {
"status": 429,
"code": "too_many_requests",
"message": "Too many requests. Please try again later."
}
},
"rate_limit_error": {
"summary": "rate_limit_error",
"value": {
"status": 429,
"code": "rate_limit_error",
"message": "Rate Limit Error"
}
}
}
}
}
},
"500": {
"description": "`internal_server_error` : 内部服务器错误。",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "internal_server_error",
"value": {
"status": 500,
"code": "internal_server_error",
"message": "Internal server error."
}
}
}
}
}
}
}
}
},
"/chat-messages/{task_id}/stop": {
"post": {
"summary": "停止响应",
"description": "停止聊天消息生成任务。仅在 `streaming` 模式下支持。",
"operationId": "stopChatMessageGenerationCn",
"tags": [
"对话流"
],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"description": "任务 ID，可以从 [发送对话消息](/api-reference/对话流/发送对话消息) API 的流式分块返回中获取。",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"user"
],
"properties": {
"user": {
"type": "string",
"description": "用户标识符，必须与发送消息时传入的 `user` 一致；不一致时停止不会生效，但响应仍返回成功。"
}
}
},
"examples": {
"example": {
"summary": "请求示例",
"value": {
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SuccessResult"
},
"400": {
"description": "`not_chat_app` : 应用模式与 API 路由不匹配。",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
}
}
}
},
"/messages/{message_id}/suggested": {
"get": {
"summary": "获取下一轮建议问题列表",
"description": "获取当前消息的下一步建议问题。",
"operationId": "getSuggestedQuestionsCn",
"tags": [
"对话流"
],
"parameters": [
{
"name": "message_id",
"in": "path",
"required": true,
"description": "消息 ID。",
"schema": {
"type": "string"
}
},
{
"name": "user",
"in": "query",
"required": true,
"description": "用户标识符。",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "成功获取建议问题。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuggestedQuestionsResponse"
},
"examples": {
"suggestedQuestions": {
"summary": "响应示例",
"value": {
"result": "success",
"data": [
"What colors does the iPhone 13 Pro Max come in?",
"How does the battery compare to iPhone 12?",
"What is the price range?"
]
}
}
}
}
}
},
"400": {
"description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `bad_request` : 建议问题功能已禁用。",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
},
"bad_request": {
"summary": "bad_request",
"value": {
"status": 400,
"code": "bad_request",
"message": "Suggested Questions Is Disabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 消息不存在。",
"content": {
"application/json": {
"examples": {
"message_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Message Not Exists."
}
}
}
}
}
},
"500": {
"description": "`internal_server_error` : 内部服务器错误。",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "internal_server_error",
"value": {
"status": 500,
"code": "internal_server_error",
"message": "Internal server error."
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages/{message_id}/suggested?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
}
]
}
},
"/files/upload": {
"post": {
"operationId": "uploadFileCn",
"tags": [
"文件操作"
],
"summary": "上传文件",
"description": "上传文件用于发送消息时使用，支持图片、文档、音频和视频的多模态理解。上传的文件仅供当前终端用户使用。",
"requestBody": {
"description": "文件上传请求。需要 multipart/form-data 格式。",
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "要上传的文件。支持的类型包括图片、文档、音频和视频。"
},
"user": {
"type": "string",
"description": "用户标识符，由开发者定义的规则生成，必须在应用内唯一。Service API 与 WebApp 的用户 ID 相互独立，即使取值相同也不指向同一用户。省略时，上传会归属到共享的 `DEFAULT-USER` 终端用户；后续请求只有携带与上传时相同的 `user` 值才能使用该文件。"
}
}
}
}
}
},
"responses": {
"201": {
"description": "文件上传成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadResponse"
},
"examples": {
"uploadSuccess": {
"summary": "响应示例",
"value": {
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"name": "product-photo.png",
"size": 204800,
"extension": "png",
"mime_type": "image/png",
"created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"created_at": 1705407629,
"preview_url": null,
"source_url": "https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI=",
"original_url": null,
"user_id": null,
"tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
"conversation_id": null,
"file_key": null
}
}
}
}
}
},
"400": {
"description": "- `no_file_uploaded` : 请求中未提供文件。\n- `too_many_files` : 每次请求仅允许上传一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。\n- `invalid_param` : 文件名包含非法字符（`/` 或 `\\`）。",
"content": {
"application/json": {
"examples": {
"no_file_uploaded": {
"summary": "no_file_uploaded",
"value": {
"status": 400,
"code": "no_file_uploaded",
"message": "Please upload your file."
}
},
"too_many_files": {
"summary": "too_many_files",
"value": {
"status": 400,
"code": "too_many_files",
"message": "Only one file is allowed."
}
},
"filename_not_exists_error": {
"summary": "filename_not_exists_error",
"value": {
"status": 400,
"code": "filename_not_exists_error",
"message": "The specified filename does not exist."
}
},
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Filename contains invalid characters"
}
}
}
}
}
},
"413": {
"description": "`file_too_large` : 文件大小超出限制。",
"content": {
"application/json": {
"examples": {
"file_too_large": {
"summary": "file_too_large",
"value": {
"status": 413,
"code": "file_too_large",
"message": "File size exceeded."
}
}
}
}
}
},
"415": {
"description": "`unsupported_file_type` : 不允许的文件类型。",
"content": {
"application/json": {
"examples": {
"unsupported_file_type": {
"summary": "unsupported_file_type",
"value": {
"status": 415,
"code": "unsupported_file_type",
"message": "File type not allowed."
}
}
}
}
}
}
}
}
},
"/files/{file_id}/preview": {
"get": {
"operationId": "previewChatFlowFileCn",
"tags": [
"文件操作"
],
"summary": "下载文件",
"description": "预览或下载之前通过[上传文件](/api-reference/文件操作/上传文件) API 上传的文件。仅可访问属于请求应用内消息的文件。",
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"description": "要预览的文件唯一标识符，从 [上传文件](/api-reference/文件操作/上传文件) API 响应中获取。",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "as_attachment",
"in": "query",
"required": false,
"description": "如果为 `true`，则强制文件以附件形式下载，而不是在浏览器中预览。",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "user",
"in": "query",
"required": false,
"description": "用户标识符，用于终端用户上下文。",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "返回原始文件内容。`Content-Type` 头设置为文件的 MIME 类型。如果 `as_attachment` 为 `true`，文件将以 `Content-Disposition: attachment` 方式作为下载返回。",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"403": {
"description": "`file_access_denied` : 拒绝访问请求的文件。",
"content": {
"application/json": {
"examples": {
"file_access_denied": {
"summary": "file_access_denied",
"value": {
"status": 403,
"code": "file_access_denied",
"message": "Access to the requested file is denied."
}
}
}
}
}
},
"404": {
"description": "`file_not_found` : 未找到请求的文件。",
"content": {
"application/json": {
"examples": {
"file_not_found": {
"summary": "file_not_found",
"value": {
"status": 404,
"code": "file_not_found",
"message": "The requested file was not found."
}
}
}
}
}
}
}
}
},
"/end-users/{end_user_id}": {
"get": {
"operationId": "getEndUserChatflowCn",
"tags": [
"终端用户"
],
"summary": "获取终端用户信息",
"description": "根据 ID 获取终端用户信息。当其他 API 返回终端用户 ID（例如[上传文件](/api-reference/文件操作/上传文件)返回的 `created_by`）时很有用。",
"parameters": [
{
"name": "end_user_id",
"in": "path",
"required": true,
"description": "终端用户 ID。",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "成功获取终端用户。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EndUserDetail"
},
"examples": {
"endUserDetail": {
"summary": "响应示例",
"value": {
"id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"type": "service_api",
"external_user_id": "abc-123",
"name": null,
"is_anonymous": false,
"session_id": "abc-123",
"created_at": "2024-01-16T12:00:29Z",
"updated_at": "2024-01-16T12:00:29Z"
}
}
}
}
}
},
"404": {
"description": "`end_user_not_found` : 未找到终端用户。",
"content": {
"application/json": {
"examples": {
"end_user_not_found": {
"summary": "end_user_not_found",
"value": {
"status": 404,
"code": "end_user_not_found",
"message": "End user not found."
}
}
}
}
}
}
}
}
},
"/messages/{message_id}/feedbacks": {
"post": {
"operationId": "postMessageFeedbackCn",
"tags": [
"消息反馈"
],
"summary": "提交消息反馈",
"description": "提交消息反馈。终端用户可以对消息评价 `like` 或 `dislike`，并可选择提供文字反馈。将 `rating` 设为 `null` 可撤销之前提交的反馈。",
"parameters": [
{
"name": "message_id",
"in": "path",
"required": true,
"description": "消息 ID。",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageFeedbackRequest"
},
"examples": {
"likeFeedback": {
"summary": "请求示例",
"value": {
"rating": "like",
"user": "abc-123",
"content": "This answer was very helpful!"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SuccessResult"
},
"404": {
"description": "`not_found` : 消息不存在。",
"content": {
"application/json": {
"examples": {
"message_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Message Not Exists."
}
}
}
}
}
}
}
}
},
"/app/feedbacks": {
"get": {
"operationId": "getAppFeedbacksCn",
"tags": [
"消息反馈"
],
"summary": "获取应用的消息反馈",
"description": "获取此应用中所有消息反馈的分页列表，包括终端用户和管理员反馈。",
"parameters": [
{
"name": "page",
"in": "query",
"description": "分页页码。",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "limit",
"in": "query",
"description": "每页记录数。",
"required": false,
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 101
}
}
],
"responses": {
"200": {
"description": "应用反馈列表。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppFeedbacksResponse"
},
"examples": {
"feedbacksList": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456",
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"rating": "like",
"content": "The response accurately answered my question about product specifications.",
"from_source": "user",
"from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"from_account_id": null,
"created_at": "2025-01-16T14:30:29Z",
"updated_at": "2025-01-16T14:30:29Z"
},
{
"id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678",
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603",
"message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1",
"rating": "dislike",
"content": "The answer was too vague and did not address the specific pricing question.",
"from_source": "user",
"from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210",
"from_account_id": null,
"created_at": "2025-01-15T09:12:45Z",
"updated_at": "2025-01-15T09:12:45Z"
}
]
}
}
}
}
}
}
}
}
},
"/conversations": {
"get": {
"summary": "获取会话列表",
"description": "获取当前用户的会话列表，按最近活跃时间排序。",
"operationId": "getConversationsListCn",
"tags": [
"会话管理"
],
"parameters": [
{
"name": "user",
"in": "query",
"required": false,
"description": "用户标识符。",
"schema": {
"type": "string"
}
},
{
"name": "last_id",
"in": "query",
"required": false,
"description": "当前页最后一条记录的 ID（用于分页）。",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "返回的记录数。",
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 100
}
},
{
"name": "sort_by",
"in": "query",
"required": false,
"description": "排序字段。使用 '-' 前缀表示降序。",
"schema": {
"type": "string",
"enum": [
"created_at",
"-created_at",
"updated_at",
"-updated_at"
],
"default": "-updated_at"
}
}
],
"responses": {
"200": {
"description": "成功获取会话列表。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationsListResponse"
},
"examples": {
"conversationsList": {
"summary": "响应示例",
"value": {
"limit": 20,
"has_more": false,
"data": [
{
"id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"name": "iPhone Specs Chat",
"inputs": {
"city": "San Francisco"
},
"status": "normal",
"introduction": "Welcome! How can I help you today?",
"created_at": 1705407629,
"updated_at": 1705411229
}
]
}
}
}
}
}
},
"400": {
"description": "`not_chat_app` : 应用模式与 API 路由不匹配。",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 上一个会话不存在（无效的 `last_id`）。",
"content": {
"application/json": {
"examples": {
"last_conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Last Conversation Not Exists."
}
}
}
}
}
}
}
}
},
"/messages": {
"get": {
"summary": "获取会话历史消息",
"description": "以滚动加载的格式返回历史聊天记录，首页返回最新的 `limit` 条消息，即按时间倒序排列。",
"operationId": "getConversationHistoryCn",
"tags": [
"会话管理"
],
"parameters": [
{
"name": "conversation_id",
"in": "query",
"required": true,
"description": "会话 ID。",
"schema": {
"type": "string"
}
},
{
"name": "user",
"in": "query",
"required": false,
"description": "用户标识符。",
"schema": {
"type": "string"
}
},
{
"name": "first_id",
"in": "query",
"required": false,
"description": "当前页第一条聊天记录的 ID。默认为 `null`（获取最新消息）。获取后续页面时，使用当前列表中第一条消息的 ID 来获取更早的消息。",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "每次请求返回的聊天历史消息数量。",
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 100
}
}
],
"responses": {
"200": {
"description": "成功获取会话历史。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationHistoryResponse"
},
"examples": {
"conversationHistory": {
"summary": "响应示例",
"value": {
"limit": 20,
"has_more": false,
"data": [
{
"id": "9da23599-e713-473b-982c-4328d4f5c78a",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"parent_message_id": null,
"inputs": {
"city": "San Francisco"
},
"query": "What are the specs of the iPhone 13 Pro Max?",
"answer": "iPhone 13 Pro Max specs are listed here:...",
"status": "normal",
"error": null,
"message_files": [],
"feedback": {
"rating": "like"
},
"retriever_resources": [],
"agent_thoughts": [],
"created_at": 1705407629
}
]
}
}
}
}
}
},
"400": {
"description": "`not_chat_app` : 应用模式与 API 路由不匹配。",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 会话不存在。\n- `not_found` : 第一条消息不存在。",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
},
"first_message_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "First Message Not Exists."
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages?conversation_id={conversation_id}&user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
}
]
}
},
"/conversations/{conversation_id}/variables": {
"get": {
"summary": "获取对话变量",
"description": "从特定会话中获取变量。",
"operationId": "getConversationVariablesCn",
"tags": [
"会话管理"
],
"parameters": [
{
"name": "conversation_id",
"in": "path",
"required": true,
"description": "会话 ID。",
"schema": {
"type": "string"
}
},
{
"name": "user",
"in": "query",
"required": false,
"description": "用户标识符。",
"schema": {
"type": "string"
}
},
{
"name": "last_id",
"in": "query",
"required": false,
"description": "当前页最后一条记录的 ID（用于分页）。",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "返回的记录数。",
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 100
}
},
{
"name": "variable_name",
"in": "query",
"required": false,
"description": "按指定名称筛选变量。",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
}
],
"responses": {
"200": {
"description": "成功获取会话变量。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationVariablesResponse"
},
"examples": {
"conversationVariables": {
"summary": "响应示例",
"value": {
"limit": 20,
"has_more": false,
"data": [
{
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"name": "user_preference",
"value_type": "string",
"value": "dark_mode",
"description": "用户偏好设置",
"created_at": 1705407629,
"updated_at": 1705411229
}
]
}
}
}
}
}
},
"400": {
"description": "`not_chat_app` : 应用模式与 API 路由不匹配。",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 会话不存在。",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
}
}
}
}
}
}
}
},
"/conversations/{conversation_id}/name": {
"post": {
"summary": "重命名会话",
"description": "重命名会话或自动生成名称。会话名称用于在支持多会话的客户端上显示。",
"operationId": "renameConversationCn",
"tags": [
"会话管理"
],
"parameters": [
{
"name": "conversation_id",
"in": "path",
"required": true,
"description": "会话 ID。",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationRenameRequest"
},
"examples": {
"renameExample": {
"summary": "请求示例",
"value": {
"name": "iPhone Specs Chat",
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "会话重命名成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationListItem"
},
"examples": {
"renamedConversation": {
"summary": "响应示例",
"value": {
"id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"name": "iPhone Specs Chat",
"inputs": {
"city": "San Francisco"
},
"status": "normal",
"introduction": "Welcome! How can I help you today?",
"created_at": 1705407629,
"updated_at": 1705411229
}
}
}
}
}
},
"400": {
"description": "`not_chat_app` : 应用模式与 API 路由不匹配。",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 会话不存在。",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
}
}
}
}
}
}
}
},
"/conversations/{conversation_id}/variables/{variable_id}": {
"put": {
"summary": "更新对话变量",
"description": "更新特定会话变量的值。值必须与预期类型匹配。",
"operationId": "updateChatflowConversationVariableZh",
"tags": [
"会话管理"
],
"parameters": [
{
"name": "conversation_id",
"in": "path",
"required": true,
"description": "会话 ID。",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "variable_id",
"in": "path",
"required": true,
"description": "Variable ID.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationVariableUpdateRequest"
},
"examples": {
"updateStringVariable": {
"summary": "请求示例",
"value": {
"value": "new value",
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "变量更新成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationVariableItem"
},
"examples": {
"updatedVariable": {
"summary": "响应示例",
"value": {
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"name": "user_preference",
"value_type": "string",
"value": "new value",
"description": "用户偏好设置",
"created_at": 1705407629,
"updated_at": 1705411229
}
}
}
}
}
},
"400": {
"description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `bad_request` : 变量值类型不匹配。",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
},
"type_mismatch": {
"summary": "bad_request",
"value": {
"status": 400,
"code": "bad_request",
"message": "Value type mismatch: expected string, got integer."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 会话不存在。\n- `not_found` : 会话变量不存在。",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
},
"variable_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Variable Not Exists."
}
}
}
}
}
}
}
}
},
"/conversations/{conversation_id}": {
"delete": {
"summary": "删除会话",
"description": "删除会话。",
"operationId": "deleteConversationCn",
"tags": [
"会话管理"
],
"parameters": [
{
"name": "conversation_id",
"in": "path",
"required": true,
"description": "会话 ID。",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "JSON 请求体始终必填；不传 `user` 时发送 `{}`。",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user": {
"type": "string",
"description": "用户标识符。"
}
}
},
"examples": {
"deleteExample": {
"value": {
"user": "abc-123"
},
"summary": "请求示例"
}
}
}
}
},
"responses": {
"204": {
"description": "会话删除成功。无返回内容。"
},
"400": {
"description": "`not_chat_app` : 应用模式与 API 路由不匹配。",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 会话不存在。",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
}
}
}
}
}
}
}
},
"/audio-to-text": {
"post": {
"operationId": "audioToTextCn",
"tags": [
"语音与文字转换"
],
"summary": "语音转文字",
"description": "将音频文件转换为文字。按上传文件的 MIME 类型校验，必须为 `audio/mp3`、`audio/m4a`、`audio/wav`、`audio/amr`、`audio/mpga` 之一；其他类型（包括常见的 `audio/mpeg`）会返回 `unsupported_audio_type` 错误。文件大小限制为 `30 MB`。",
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/AudioToTextRequest"
}
}
}
},
"responses": {
"200": {
"description": "语音转文字成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AudioToTextResponse"
},
"examples": {
"audioToTextSuccess": {
"summary": "响应示例",
"value": {
"text": "Hello, I would like to know more about the iPhone 13 Pro Max."
}
}
}
}
}
},
"400": {
"description": "- `app_unavailable` : 应用不可用或配置错误。\n- `no_audio_uploaded` : 未上传音频文件。\n- `provider_not_support_speech_to_text` : 模型供应商不支持语音转文字。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 语音识别请求失败。",
"content": {
"application/json": {
"examples": {
"app_unavailable": {
"summary": "app_unavailable",
"value": {
"status": 400,
"code": "app_unavailable",
"message": "App unavailable, please check your app configurations."
}
},
"no_audio_uploaded": {
"summary": "no_audio_uploaded",
"value": {
"status": 400,
"code": "no_audio_uploaded",
"message": "Please upload your audio."
}
},
"provider_not_support_speech_to_text": {
"summary": "provider_not_support_speech_to_text",
"value": {
"status": 400,
"code": "provider_not_support_speech_to_text",
"message": "Provider not support speech to text."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"provider_quota_exceeded": {
"summary": "provider_quota_exceeded",
"value": {
"status": 400,
"code": "provider_quota_exceeded",
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
}
},
"model_currently_not_support": {
"summary": "model_currently_not_support",
"value": {
"status": 400,
"code": "model_currently_not_support",
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
}
},
"completion_request_error": {
"summary": "completion_request_error",
"value": {
"status": 400,
"code": "completion_request_error",
"message": "Completion request failed."
}
}
}
}
}
},
"413": {
"description": "`audio_too_large` : 音频文件大小超出限制。",
"content": {
"application/json": {
"examples": {
"audio_too_large": {
"summary": "audio_too_large",
"value": {
"status": 413,
"code": "audio_too_large",
"message": "Audio size exceeded."
}
}
}
}
}
},
"415": {
"description": "`unsupported_audio_type` : 不允许的音频类型。",
"content": {
"application/json": {
"examples": {
"unsupported_audio_type": {
"summary": "unsupported_audio_type",
"value": {
"status": 415,
"code": "unsupported_audio_type",
"message": "Audio type not allowed."
}
}
}
}
}
},
"500": {
"description": "`internal_server_error` : 内部服务器错误。",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "internal_server_error",
"value": {
"status": 500,
"code": "internal_server_error",
"message": "Internal server error."
}
}
}
}
}
}
}
}
},
"/text-to-audio": {
"post": {
"operationId": "textToAudioCn",
"tags": [
"语音与文字转换"
],
"summary": "文字转语音",
"description": "将文字转换为语音。",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TextToAudioRequest"
},
"examples": {
"textToAudioExample": {
"summary": "请求示例",
"value": {
"text": "Hello, welcome to our service.",
"user": "abc-123",
"voice": "alloy",
"streaming": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "返回生成的音频文件。`Content-Type` 头设置为音频 MIME 类型（例如 `audio/wav`、`audio/mp3`）。如果 `streaming` 为 `true`，音频将以分块传输编码方式流式返回。",
"content": {
"audio/mpeg": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "- `app_unavailable` : 应用不可用或配置错误。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 文字转语音请求失败。",
"content": {
"application/json": {
"examples": {
"app_unavailable": {
"summary": "app_unavailable",
"value": {
"status": 400,
"code": "app_unavailable",
"message": "App unavailable, please check your app configurations."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"provider_quota_exceeded": {
"summary": "provider_quota_exceeded",
"value": {
"status": 400,
"code": "provider_quota_exceeded",
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
}
},
"model_currently_not_support": {
"summary": "model_currently_not_support",
"value": {
"status": 400,
"code": "model_currently_not_support",
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
}
},
"completion_request_error": {
"summary": "completion_request_error",
"value": {
"status": 400,
"code": "completion_request_error",
"message": "Completion request failed."
}
}
}
}
}
},
"500": {
"description": "`internal_server_error` : 内部服务器错误。",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "internal_server_error",
"value": {
"status": 500,
"code": "internal_server_error",
"message": "Internal server error."
}
}
}
}
}
}
}
}
},
"/info": {
"get": {
"operationId": "getAppInfoCn",
"tags": [
"应用配置"
],
"summary": "获取应用基本信息",
"description": "获取应用的基本信息，包括名称、描述、标签和模式。",
"responses": {
"200": {
"description": "应用的基本信息。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppInfoResponse"
},
"examples": {
"appInfo": {
"summary": "响应示例",
"value": {
"name": "My Chatflow App",
"description": "一个有用的客服聊天机器人。",
"tags": [
"customer-service",
"chatbot"
],
"mode": "advanced-chat",
"author_name": "Dify Team"
}
}
}
}
}
}
}
}
},
"/parameters": {
"get": {
"operationId": "getAppParametersCn",
"tags": [
"应用配置"
],
"summary": "获取应用参数",
"description": "获取应用的输入表单配置，包括功能开关、输入参数名称、类型和默认值。",
"responses": {
"200": {
"description": "应用参数信息。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAppParametersResponse"
},
"examples": {
"appParameters": {
"summary": "响应示例",
"value": {
"opening_statement": "Hello! How can I help you today?",
"suggested_questions": [
"What can you do?",
"Tell me about your features."
],
"suggested_questions_after_answer": {
"enabled": true
},
"speech_to_text": {
"enabled": false
},
"text_to_speech": {
"enabled": false,
"voice": "alloy",
"language": "en-US",
"autoPlay": "disabled"
},
"retriever_resource": {
"enabled": true
},
"annotation_reply": {
"enabled": false
},
"more_like_this": {
"enabled": false
},
"sensitive_word_avoidance": {
"enabled": false
},
"user_input_form": [
{
"text-input": {
"label": "City",
"variable": "city",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": true,
"number_limits": 3,
"detail": "high",
"transfer_methods": [
"remote_url",
"local_file"
]
}
},
"system_parameters": {
"file_size_limit": 15,
"image_file_size_limit": 10,
"audio_file_size_limit": 50,
"video_file_size_limit": 100,
"workflow_file_upload_limit": 10
}
}
}
}
}
}
},
"400": {
"description": "`app_unavailable` : 应用不可用或配置错误。",
"content": {
"application/json": {
"examples": {
"app_unavailable": {
"summary": "app_unavailable",
"value": {
"status": 400,
"code": "app_unavailable",
"message": "App unavailable, please check your app configurations."
}
}
}
}
}
}
}
}
},
"/meta": {
"get": {
"operationId": "getAppMetaCn",
"tags": [
"应用配置"
],
"summary": "获取应用元数据",
"description": "获取应用的元数据，包括工具图标和其他配置详情。",
"responses": {
"200": {
"description": "成功获取应用元数据。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppMetaResponse"
},
"examples": {
"appMeta": {
"summary": "响应示例",
"value": {
"tool_icons": {
"dalle3": "https://example.com/icons/dalle3.png",
"calculator": {
"background": "#4A90D9",
"content": "🧮"
}
}
}
}
}
}
}
}
}
}
},
"/site": {
"get": {
"operationId": "getWebAppSettingsCn",
"tags": [
"应用配置"
],
"summary": "获取应用 WebApp 设置",
"description": "获取应用的 WebApp 设置，包括站点配置、主题和自定义选项。",
"responses": {
"200": {
"description": "应用的 WebApp 设置。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAppSettingsResponse"
},
"examples": {
"webAppSettings": {
"summary": "响应示例",
"value": {
"title": "My Chat App",
"chat_color_theme": "#4A90D9",
"chat_color_theme_inverted": false,
"icon_type": "emoji",
"icon": "🤖",
"icon_background": "#FFFFFF",
"icon_url": null,
"description": "一个有用的客服聊天机器人。",
"copyright": "2025 Dify",
"privacy_policy": "https://example.com/privacy",
"custom_disclaimer": "",
"default_language": "en-US",
"show_workflow_steps": false,
"use_icon_as_answer_icon": true
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 未找到此应用的站点或工作空间已归档。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden",
"value": {
"status": 403,
"code": "forbidden",
"message": "Forbidden."
}
}
}
}
}
}
}
}
},
"/apps/annotations": {
"post": {
"summary": "创建标注",
"description": "创建新的标注。标注提供预定义的问答对，应用可以直接匹配并返回，而无需生成回复。",
"operationId": "createAnnotationCn",
"tags": [
"标注管理"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAnnotationRequest"
},
"examples": {
"createAnnotation": {
"summary": "请求示例",
"value": {
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform."
}
}
}
}
}
},
"responses": {
"201": {
"description": "标注创建成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnnotationItem"
},
"examples": {
"createdAnnotation": {
"summary": "响应示例",
"value": {
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform.",
"hit_count": 0,
"created_at": 1705407629
}
}
}
}
}
}
}
},
"get": {
"summary": "获取标注列表",
"description": "获取应用的标注分页列表。支持关键词搜索筛选。",
"operationId": "getAnnotationListCn",
"tags": [
"标注管理"
],
"parameters": [
{
"name": "page",
"in": "query",
"description": "分页页码。",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "limit",
"in": "query",
"description": "每页条目数。",
"required": false,
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "keyword",
"in": "query",
"description": "按问题或回答内容筛选标注的关键词。",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "成功获取标注列表。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnnotationListResponse"
},
"examples": {
"annotationList": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform.",
"hit_count": 5,
"created_at": 1705407629
}
],
"has_more": false,
"limit": 20,
"total": 1,
"page": 1
}
}
}
}
}
}
}
}
},
"/apps/annotations/{annotation_id}": {
"put": {
"summary": "更新标注",
"description": "更新现有标注的问题和回答。",
"operationId": "updateAnnotationCn",
"tags": [
"标注管理"
],
"parameters": [
{
"name": "annotation_id",
"in": "path",
"required": true,
"description": "要更新的标注的唯一标识符。",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAnnotationRequest"
},
"examples": {
"updateAnnotation": {
"summary": "请求示例",
"value": {
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform for building AI-powered apps."
}
}
}
}
}
},
"responses": {
"200": {
"description": "标注更新成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnnotationItem"
},
"examples": {
"updatedAnnotation": {
"summary": "响应示例",
"value": {
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform for building AI-powered apps.",
"hit_count": 5,
"created_at": 1705407629
}
}
}
}
}
},
"404": {
"description": "`not_found` : 标注不存在。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Annotation not found."
}
}
}
}
}
}
}
},
"delete": {
"summary": "删除标注",
"description": "删除标注及其关联的命中历史。",
"operationId": "deleteAnnotationCn",
"tags": [
"标注管理"
],
"parameters": [
{
"name": "annotation_id",
"in": "path",
"required": true,
"description": "要删除的标注的唯一标识符。",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "标注删除成功。"
},
"404": {
"description": "`not_found` : 标注不存在。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Annotation not found."
}
}
}
}
}
}
}
}
},
"/apps/annotation-reply/{action}": {
"post": {
"summary": "配置标注回复",
"description": "启用或禁用标注回复功能。请求体在执行操作前校验，因此无论 `enable` 还是 `disable` 都必须提供 `embedding_provider_name`、`embedding_model_name` 和 `score_threshold`。异步执行，使用 [查询标注回复配置任务状态](/api-reference/标注管理/查询标注回复配置任务状态) 跟踪进度。",
"operationId": "initialAnnotationReplySettingsCn",
"tags": [
"标注管理"
],
"parameters": [
{
"name": "action",
"in": "path",
"required": true,
"description": "要执行的操作。",
"schema": {
"type": "string",
"enum": [
"enable",
"disable"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest"
},
"examples": {
"enableAnnotationReply": {
"summary": "请求示例",
"value": {
"score_threshold": 0.9,
"embedding_provider_name": "openai",
"embedding_model_name": "text-embedding-3-small"
}
}
}
}
}
},
"responses": {
"200": {
"description": "标注回复设置任务已启动。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse"
},
"examples": {
"annotationReplyResponse": {
"summary": "响应示例",
"value": {
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"job_status": "waiting"
}
}
}
}
}
}
}
}
},
"/apps/annotation-reply/{action}/status/{job_id}": {
"get": {
"summary": "查询标注回复配置任务状态",
"description": "获取由 [配置标注回复](/api-reference/标注管理/配置标注回复) 发起的异步标注回复配置任务的状态。",
"operationId": "getInitialAnnotationReplySettingsStatusCn",
"tags": [
"标注管理"
],
"parameters": [
{
"name": "action",
"in": "path",
"required": true,
"description": "操作类型，必须与 [配置标注回复](/api-reference/标注管理/配置标注回复) 调用中的一致。",
"schema": {
"type": "string",
"enum": [
"enable",
"disable"
]
}
},
{
"name": "job_id",
"in": "path",
"required": true,
"description": "由 [配置标注回复](/api-reference/标注管理/配置标注回复) 接口返回的任务 ID。",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "成功获取任务状态。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse"
},
"examples": {
"jobStatus": {
"summary": "响应示例",
"value": {
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"job_status": "completed",
"error_msg": ""
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 指定的任务不存在。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "The job does not exist."
}
}
}
}
}
}
}
}
},
"/workflows/run/{workflow_run_id}": {
"get": {
"summary": "获取工作流执行情况",
"description": "根据工作流执行 ID 获取工作流任务的当前执行结果。",
"operationId": "getChatflowWorkflowRunDetailZh",
"tags": [
"对话流"
],
"parameters": [
{
"name": "workflow_run_id",
"in": "path",
"required": true,
"description": "工作流运行 ID，可从流式事件或消息元数据中获取。",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "成功获取工作流运行详情。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowRunDetailResponse"
},
"examples": {
"workflowRunDetail": {
"summary": "响应示例",
"value": {
"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
"workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345",
"status": "succeeded",
"inputs": "{\"query\": \"Translate this to French\"}",
"outputs": {
"result": "Traduisez ceci en francais"
},
"error": null,
"total_steps": 3,
"total_tokens": 150,
"created_at": 1705407629,
"finished_at": 1705407630,
"elapsed_time": 1.23
}
}
}
}
}
},
"400": {
"description": "`not_workflow_app` : 应用模式与 API 路由不匹配。",
"content": {
"application/json": {
"examples": {
"not_workflow_app": {
"summary": "not_workflow_app",
"value": {
"status": 400,
"code": "not_workflow_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到工作流运行记录。",
"content": {
"application/json": {
"examples": {
"workflow_run_not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Workflow run not found."
}
}
}
}
}
}
}
}
},
"/workflows/logs": {
"get": {
"summary": "获取工作流日志",
"description": "列出过往的工作流运行，支持可选筛选。每条记录是运行级摘要（状态、Token 用量、步数和耗时），而非逐节点的执行日志。\n\n如需跟踪某次运行的节点级事件，请改用流式方式：\n\n- **自行发起的运行**：以流式模式调用 [发送对话消息](/api-reference/对话流/发送对话消息)，运行执行时会发送 `node_started` 和 `node_finished` 事件。\n- **已在进行中的运行**：调用 [流式获取工作流事件](/api-reference/对话流/流式获取工作流事件) 并附带 `include_state_snapshot=true`，先重放各已执行节点的状态，再流式发送其余事件。\n\n已结束运行的节点级日志无法通过服务 API 获取。",
"operationId": "listChatflowWorkflowLogsZh",
"tags": [
"对话流"
],
"parameters": [
{
"name": "keyword",
"in": "query",
"description": "在日志中搜索的关键词。",
"schema": {
"type": "string"
}
},
{
"name": "status",
"in": "query",
"description": "按执行状态筛选。",
"schema": {
"type": "string",
"enum": [
"succeeded",
"failed",
"stopped"
]
}
},
{
"name": "page",
"in": "query",
"description": "分页页码。",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1,
"maximum": 99999
}
},
{
"name": "limit",
"in": "query",
"description": "每页条目数。",
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 100
}
},
{
"name": "created_at__before",
"in": "query",
"description": "筛选在此 ISO 8601 时间戳之前创建的日志。",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "created_at__after",
"in": "query",
"description": "筛选在此 ISO 8601 时间戳之后创建的日志。",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "created_by_end_user_session_id",
"in": "query",
"description": "按终端用户会话 ID 筛选。",
"schema": {
"type": "string"
}
},
{
"name": "created_by_account",
"in": "query",
"description": "按创建者的账户邮箱筛选（例如 `name@example.com`）。",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "成功获取工作流日志。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowLogsResponse"
},
"examples": {
"workflowLogs": {
"summary": "响应示例",
"value": {
"page": 1,
"limit": 20,
"total": 1,
"has_more": false,
"data": [
{
"id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456",
"workflow_run": {
"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
"version": "2025-01-16 12:00:00.000000",
"status": "succeeded",
"error": null,
"elapsed_time": 1.23,
"total_tokens": 150,
"total_steps": 3,
"created_at": 1705407629,
"finished_at": 1705407630,
"exceptions_count": 0
},
"created_from": "service-api",
"created_by_role": "end_user",
"created_by_account": null,
"created_by_end_user": {
"id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"type": "service_api",
"is_anonymous": false,
"session_id": "user_chatflow_123"
},
"created_at": 1705407629
}
]
}
}
}
}
}
}
}
}
},
"/form/human_input/{form_token}": {
"get": {
"tags": [
"人工介入"
],
"summary": "获取人工介入表单",
"description": "获取暂停中的人工介入表单内容。需要 WebApp 提交方式。\n\n调用人工介入接口的端到端流程，参见 [API 集成流程](/zh/api-reference/guides/human-input-flow)。",
"operationId": "getChatflowHumanInputForm",
"parameters": [
{
"name": "form_token",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "暂停表单的访问令牌，由流式模式下执行工作流或发送对话消息接口返回的 `human_input_required` 事件提供。"
}
],
"responses": {
"200": {
"description": "表单内容获取成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"form_content": {
"type": "string",
"description": "已替换工作流变量的预渲染表单正文。"
},
"inputs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "表单输入控件类型。可用值：`paragraph`（多行文本输入）、`select`（从列表中单选）、`file`（单个文件上传）和 `file-list`（多个文件上传）。"
},
"output_variable_name": {
"type": "string",
"description": "引用该输入提交值在工作流中使用的变量名。对应提交 `inputs` 对象中的键。"
},
"default": {
"type": "object",
"nullable": true,
"description": "`paragraph` 输入的原始默认值配置。客户端不应直接解析此字段，请使用 `resolved_default_values` 来展示默认值。其他输入类型或未配置默认值时为 `null`。",
"properties": {
"type": {
"type": "string",
"description": "默认值来源。`constant` 表示将 `value` 作为字面字符串；`variable` 表示 `selector` 指向工作流变量。"
},
"selector": {
"type": "array",
"items": {
"type": "string"
},
"description": "当 `type` 为 `variable` 时的变量引用路径（例如 `[\"node_id\", \"var_name\"]`）。至少包含两个元素。"
},
"value": {
"type": "string",
"description": "当 `type` 为 `constant` 时的字面默认值。始终为字符串。"
}
}
},
"option_source": {
"type": "object",
"description": "`select` 输入的选项来源。仅当 `type` 为 `select` 时出现。",
"properties": {
"type": {
"type": "string",
"enum": [
"variable",
"constant"
],
"description": "选项来源。`constant` 表示 `value` 直接列出选项；`variable` 表示 `selector` 指向提供选项的 `array[string]` 工作流变量。"
},
"selector": {
"type": "array",
"items": {
"type": "string"
},
"description": "当 `type` 为 `variable` 时的变量引用路径。"
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"description": "当 `type` 为 `constant` 时的字面选项列表。"
}
}
},
"allowed_file_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"image",
"document",
"audio",
"video",
"custom"
]
},
"description": "接收人可上传的文件类别。`file` 和 `file-list` 输入会包含此字段。可用值：`image`、`document`、`audio`、`video`、`custom`。"
},
"allowed_file_extensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "当 `allowed_file_types` 包含 `custom` 时允许的文件扩展名。每个扩展名都需要包含前导 `.`，例如 `.md`。`file` 和 `file-list` 输入会包含此字段。"
},
"allowed_file_upload_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"local_file",
"remote_url"
]
},
"description": "接收人可使用的上传方式。可用值：`local_file`、`remote_url`。`file` 和 `file-list` 输入会包含此字段。"
},
"number_limits": {
"type": "integer",
"description": "接收人可上传的最大文件数。仅 `file-list` 输入会包含此字段。"
}
}
},
"description": "表单输入字段定义。"
},
"resolved_default_values": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "用于在表单中展示的预渲染默认值，按输入的 `output_variable_name` 分组。仅当 `paragraph` 输入的默认值可由工作流变量解析时填充；无可解析默认值的输入为空。客户端请直接展示这些值，无需在前端再次解析 `default`。所有值均为字符串。"
},
"user_actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"maxLength": 20,
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
"description": "操作按钮的标识。当接收人选择该按钮时，作为 `action` 传入 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单)。"
},
"title": {
"type": "string",
"maxLength": 100,
"description": "显示给接收人的按钮文本。"
},
"button_style": {
"type": "string",
"description": "按钮的视觉样式。可用值：`primary`、`default`、`accent`、`ghost`。"
}
}
},
"description": "可用的提交操作。"
},
"expiration_time": {
"type": "integer",
"format": "int64",
"description": "Unix 时间戳（秒），超过该时间后表单将不可提交。",
"nullable": true
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"form_content": "Please review the draft, set a priority, and confirm or request changes.",
"inputs": [
{
"type": "paragraph",
"output_variable_name": "feedback",
"default": {
"type": "constant",
"selector": [],
"value": ""
}
},
{
"type": "select",
"output_variable_name": "priority",
"option_source": {
"type": "constant",
"selector": [],
"value": [
"low",
"medium",
"high"
]
}
},
{
"type": "file",
"output_variable_name": "attachment",
"allowed_file_types": [
"image",
"document"
],
"allowed_file_extensions": [],
"allowed_file_upload_methods": [
"local_file",
"remote_url"
]
},
{
"type": "file-list",
"output_variable_name": "attachments",
"allowed_file_types": [
"image",
"document"
],
"allowed_file_extensions": [],
"allowed_file_upload_methods": [
"local_file",
"remote_url"
],
"number_limits": 5
}
],
"resolved_default_values": {
"feedback": ""
},
"user_actions": [
{
"id": "approve",
"title": "Approve",
"button_style": "primary"
},
{
"id": "reject",
"title": "Request changes",
"button_style": "default"
}
],
"expiration_time": 1745510400
}
}
}
}
}
},
"404": {
"description": "`not_found`：未找到表单。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "未找到表单"
}
}
}
}
}
},
"412": {
"description": "- `human_input_form_submitted`：表单已被提交。表单为一次性使用；无论由哪位用户提交，首个响应即生效。\n- `human_input_form_expired`：在提交到达之前表单已过期。",
"content": {
"application/json": {
"examples": {
"human_input_form_submitted": {
"summary": "human_input_form_submitted",
"value": {
"status": 412,
"code": "human_input_form_submitted",
"message": "该表单已被其他用户提交，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
},
"human_input_form_expired": {
"summary": "human_input_form_expired",
"value": {
"status": 412,
"code": "human_input_form_expired",
"message": "该表单已过期，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
}
}
}
}
}
},
"post": {
"tags": [
"人工介入"
],
"summary": "提交人工介入表单",
"description": "向暂停中的人工介入表单提交接收人的响应。接受后工作流将继续；可通过订阅工作流事件接口跟踪后续事件。需要 WebApp 提交方式。",
"operationId": "submitChatflowHumanInputForm",
"parameters": [
{
"name": "form_token",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "暂停表单的访问令牌，由流式模式下执行工作流或发送对话消息接口返回的 `human_input_required` 事件提供。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"inputs",
"action",
"user"
],
"properties": {
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "按各输入的 `output_variable_name` 作为键提交的值。段落和下拉选项输入为字符串；`file` 输入为单个文件映射；`file-list` 输入为文件映射数组。文件映射为 `{transfer_method: local_file, upload_file_id, type}` 或 `{transfer_method: remote_url, url, type}`，其中 `type` 为该字段 `allowed_file_types` 中的一种（`image`、`document`、`audio`、`video`、`custom`）。对于 `local_file`，`upload_file_id` 为 [上传文件](/api-reference/文件操作/上传文件) 返回的 `id`。请在执行、上传和提交各次调用中使用一致的 `user`。"
},
"action": {
"type": "string",
"description": "接收人选择的操作按钮 ID。必须与表单的 `user_actions` 列表（由 [获取人工介入表单](/api-reference/人工介入/获取人工介入表单) 接口返回）中的某个 `id` 值匹配。"
},
"user": {
"type": "string",
"description": "用户标识符，由开发者定义的规则生成，必须在应用内唯一。Service API 与 WebApp 的用户 ID 相互独立，即使取值相同也不指向同一用户。"
}
}
},
"examples": {
"approve": {
"summary": "请求示例",
"value": {
"inputs": {
"feedback": "可以发布",
"priority": "high",
"attachment": {
"transfer_method": "local_file",
"upload_file_id": "3c8fa1b2-7d4e-4f9a-b0c1-d2e3f4a5b6c7",
"type": "image"
},
"attachments": [
{
"transfer_method": "local_file",
"upload_file_id": "1a77f0df-c0e6-461c-987c-e72526f341ee",
"type": "document"
},
{
"transfer_method": "remote_url",
"url": "https://example.com/report.pdf",
"type": "document"
}
]
},
"action": "approve",
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "表单提交成功。响应体为空对象。",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"success": {
"summary": "响应示例",
"value": {}
}
}
}
}
},
"400": {
"description": "- `bad_request`：表单接收人类型无效。\n- `invalid_form_data`：提交内容未通过表单定义的校验。",
"content": {
"application/json": {
"examples": {
"bad_request": {
"summary": "bad_request",
"value": {
"status": 400,
"code": "bad_request",
"message": "表单接收人类型无效"
}
},
"invalid_form_data": {
"summary": "invalid_form_data",
"value": {
"status": 400,
"code": "invalid_form_data",
"message": "缺少必填输入：feedback"
}
}
}
}
}
},
"404": {
"description": "`not_found`：未找到表单。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "未找到表单"
}
}
}
}
}
},
"412": {
"description": "- `human_input_form_submitted`：表单已被提交。表单为一次性使用；无论由哪位用户提交，首个响应即生效。\n- `human_input_form_expired`：在提交到达之前表单已过期。",
"content": {
"application/json": {
"examples": {
"human_input_form_submitted": {
"summary": "human_input_form_submitted",
"value": {
"status": 412,
"code": "human_input_form_submitted",
"message": "该表单已被其他用户提交，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
},
"human_input_form_expired": {
"summary": "human_input_form_expired",
"value": {
"status": 412,
"code": "human_input_form_expired",
"message": "该表单已过期，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
}
}
}
}
}
}
},
"/workflow/{workflow_run_id}/events": {
"get": {
"tags": [
"对话流"
],
"summary": "流式获取工作流事件",
"description": "在工作流运行暂停或原始 SSE 连接断开后恢复 Server-Sent Events 流。对于已结束的运行，流仅发送单个 `workflow_finished` 事件后关闭。\n\n如需查看进行中运行的节点级状态与进度，可在调用时附带 `include_state_snapshot=true`：流会先重放各已执行节点的状态，再流式发送新事件。",
"operationId": "streamChatflowEvents",
"parameters": [
{
"name": "workflow_run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "要恢复事件流的工作流运行 ID（取自原始 [发送对话消息](/api-reference/对话流/发送对话消息) 响应中的 `workflow_run_id`）。"
},
{
"name": "user",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "发送该对话消息的终端用户标识。必须与工作流运行的创建者一致。"
},
{
"name": "include_state_snapshot",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "为 `true` 时，从持久化状态快照重放，在流式发送新事件前附带已执行节点的状态摘要。"
},
{
"name": "continue_on_pause",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "设为 `true` 时，流会在多次 `workflow_paused` 事件之间保持打开（适用于工作流包含多个连续人工介入节点的场景）。默认在首次暂停时关闭流。"
}
],
"responses": {
"200": {
"description": "Server-Sent Events 流。每个事件以 `data: {JSON}\\n\\n` 形式送达。事件载荷结构与原始流式响应一致。",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"description": "已恢复工作流运行的事件 SSE 流，格式与 [发送对话消息](/api-reference/对话流/发送对话消息) 相同。当恢复部分运行设置 `reasoning_format: separated` 的 LLM 节点时，本流还会携带 `reasoning_chunk` 事件。"
},
"examples": {
"resumedRun": {
"summary": "响应示例 - 恢复运行",
"value": "data: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"The reviewer approved the draft.\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"answer\": \"Approved\", \"created_at\": 1705407706} data: {\"event\": \"node_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"status\": \"succeeded\", \"elapsed_time\": 1.2, \"created_at\": 1705407705, \"finished_at\": 1705407706}} data: {\"event\": \"message_end\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"metadata\": {\"usage\": {\"total_tokens\": 42, \"latency\": 1.3}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}"
}
}
}
}
},
"400": {
"description": "`not_workflow_app` : Please check if your app mode matches the right API route.",
"content": {
"application/json": {
"examples": {
"not_workflow_app": {
"summary": "not_workflow_app",
"value": {
"status": 400,
"code": "not_workflow_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : Workflow run not found.",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Workflow run not found"
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "恢复事件流",
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
},
{
"lang": "bash",
"label": "附带状态快照",
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}&include_state_snapshot=true' \\\n --header 'Authorization: Bearer {api_key}'"
}
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "API_KEY",
"description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**缺少或无效的 API Key 会返回 HTTP `401`，错误码为 `unauthorized`。"
}
},
"responses": {
"SuccessResult": {
"description": "操作成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "结果状态。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"result": "success"
}
}
}
}
}
}
},
"schemas": {
"ChatRequest": {
"type": "object",
"required": [
"inputs",
"query",
"user"
],
"properties": {
"query": {
"type": "string",
"description": "用户输入/问题内容。"
},
"inputs": {
"type": "object",
"description": "允许输入应用定义的各种变量值。包含键值对。请参阅 [获取应用参数](/api-reference/应用配置/获取应用参数) 响应中的 `user_input_form` 字段，以了解应用所需的变量名称和类型。",
"additionalProperties": true
},
"response_mode": {
"type": "string",
"enum": [
"streaming",
"blocking"
],
"description": "响应返回模式。`streaming`（推荐）使用 SSE。`blocking` 等待完成后返回（长时间处理可能会被中断）。Cloudflare 超时为 `100 s`。省略时默认为阻塞模式。"
},
"user": {
"type": "string",
"description": "用户标识符，在应用内唯一。此标识符用于限定数据访问范围——会话、消息和文件仅在使用相同的 `user` 值查询时可见。"
},
"conversation_id": {
"type": "string",
"description": "用于继续会话的会话 ID。传入上一条消息的 `conversation_id`。要开始新会话，请省略此字段或传入空字符串。响应会返回一个 `conversation_id`——在后续消息中传入该值即可继续该会话。"
},
"files": {
"type": "array",
"description": "用于多模态理解的文件列表，包括图片、文档、音频和视频。要附加本地文件，请先通过 [上传文件](/api-reference/文件操作/上传文件) 上传，然后将返回的 `id` 作为 `upload_file_id`，并设置 `transfer_method: local_file`。",
"items": {
"type": "object",
"required": [
"type",
"transfer_method"
],
"properties": {
"type": {
"type": "string",
"enum": [
"image",
"document",
"audio",
"video",
"custom"
],
"description": "文件类型。"
},
"transfer_method": {
"type": "string",
"enum": [
"remote_url",
"local_file"
],
"description": "传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。"
},
"url": {
"type": "string",
"format": "url",
"description": "文件 URL（当 `transfer_method` 为 `remote_url` 时必填）。"
},
"upload_file_id": {
"type": "string",
"description": "通过 [上传文件](/api-reference/文件操作/上传文件) API 获取的已上传文件 ID（当 `transfer_method` 为 `local_file` 时必填）。"
}
}
}
},
"auto_generate_name": {
"type": "boolean",
"description": "自动生成会话标题。如果为 `false`，请使用 [重命名会话](/api-reference/会话管理/重命名会话) API 并设置 `auto_generate: true` 来异步生成标题。",
"default": true
},
"workflow_id": {
"type": "string",
"description": "指定要执行的已发布工作流版本 ID。如果未提供，将使用最新发布的版本。"
}
}
},
"ChatCompletionResponse": {
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "事件类型，固定为 `message`。"
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "用于请求追踪和停止响应 API 的任务 ID。"
},
"id": {
"type": "string",
"format": "uuid",
"description": "该响应事件的唯一 ID。"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "唯一的消息 ID。调用反馈或推荐问题接口时，将此值作为 `message_id` 参数使用。"
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "会话 ID。"
},
"mode": {
"type": "string",
"description": "应用模式，固定为 `advanced-chat`。"
},
"answer": {
"type": "string",
"description": "完整的响应内容。"
},
"metadata": {
"type": "object",
"description": "包含用量和检索资源的元数据。",
"properties": {
"usage": {
"$ref": "#/components/schemas/Usage"
},
"retriever_resources": {
"type": "array",
"description": "使用的检索资源列表。",
"items": {
"$ref": "#/components/schemas/RetrieverResource"
}
}
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "消息创建时间戳（Unix 纪元秒）。"
}
}
},
"ChunkChatEvent": {
"type": "object",
"description": "流式模式下 Server-Sent Event 块的基础 schema。",
"properties": {
"event": {
"type": "string",
"description": "事件类型。",
"enum": [
"message",
"tts_message",
"tts_message_end",
"message_file",
"message_end",
"message_replace",
"reasoning_chunk",
"workflow_started",
"workflow_finished",
"node_started",
"node_finished",
"node_retry",
"iteration_started",
"iteration_next",
"iteration_completed",
"loop_started",
"loop_next",
"loop_completed",
"workflow_paused",
"human_input_required",
"human_input_form_filled",
"human_input_form_timeout",
"agent_log",
"text_chunk",
"error",
"ping"
]
}
},
"discriminator": {
"propertyName": "event",
"mapping": {
"message": "#/components/schemas/StreamEventChatMessage",
"tts_message": "#/components/schemas/StreamEventChatTtsMessage",
"tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd",
"message_file": "#/components/schemas/StreamEventChatMessageFile",
"message_end": "#/components/schemas/StreamEventChatMessageEnd",
"message_replace": "#/components/schemas/StreamEventChatMessageReplace",
"reasoning_chunk": "#/components/schemas/StreamEventChatReasoningChunk",
"workflow_started": "#/components/schemas/StreamEventWorkflowStarted",
"workflow_finished": "#/components/schemas/StreamEventWorkflowFinished",
"node_started": "#/components/schemas/StreamEventNodeStarted",
"node_finished": "#/components/schemas/StreamEventNodeFinished",
"node_retry": "#/components/schemas/StreamEventNodeRetry",
"iteration_started": "#/components/schemas/StreamEventIterationStarted",
"iteration_next": "#/components/schemas/StreamEventIterationNext",
"iteration_completed": "#/components/schemas/StreamEventIterationCompleted",
"loop_started": "#/components/schemas/StreamEventLoopStarted",
"loop_next": "#/components/schemas/StreamEventLoopNext",
"loop_completed": "#/components/schemas/StreamEventLoopCompleted",
"workflow_paused": "#/components/schemas/StreamEventWorkflowPaused",
"human_input_required": "#/components/schemas/StreamEventHumanInputRequired",
"human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled",
"human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout",
"agent_log": "#/components/schemas/StreamEventAgentLog",
"text_chunk": "#/components/schemas/StreamEventChatTextChunk",
"error": "#/components/schemas/StreamEventChatError",
"ping": "#/components/schemas/StreamEventChatPing"
}
}
},
"StreamEventBase": {
"type": "object",
"description": "流式事件的基础属性。",
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "任务 ID。"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "唯一消息 ID。"
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "会话 ID。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳。"
}
}
},
"StreamEventChatMessage": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"answer": {
"type": "string",
"description": "LLM 返回的文本块。"
}
}
}
]
},
"StreamEventChatTtsMessage": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "TTS 音频流事件（base64 编码的 Mp3）。自动播放启用时可用。",
"properties": {
"audio": {
"type": "string",
"format": "byte",
"description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。"
}
}
}
]
},
"StreamEventChatTtsMessageEnd": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "TTS 音频流结束事件。",
"properties": {
"audio": {
"type": "string",
"description": "空字符串。标识音频流结束。"
}
}
}
]
},
"StreamEventChatMessageFile": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "消息文件事件，由工具创建的新文件。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "文件唯一 ID。"
},
"type": {
"type": "string",
"description": "文件类型，例如 `image`。"
},
"belongs_to": {
"type": "string",
"enum": [
"assistant"
],
"description": "该文件的归属方，此处始终为 `assistant`。"
},
"url": {
"type": "string",
"format": "url",
"description": "文件的远程 URL。"
}
}
}
]
},
"StreamEventChatMessageEnd": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "消息结束事件，流式传输已结束。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "消息的唯一 ID。"
},
"metadata": {
"type": "object",
"description": "包含用量和检索资源的元数据。",
"properties": {
"usage": {
"$ref": "#/components/schemas/Usage"
},
"retriever_resources": {
"type": "array",
"description": "使用的检索资源列表。",
"items": {
"$ref": "#/components/schemas/RetrieverResource"
}
}
}
}
}
}
]
},
"StreamEventChatMessageReplace": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "消息内容替换事件（例如由于内容审核）。",
"properties": {
"answer": {
"type": "string",
"description": "替换内容。"
},
"reason": {
"type": "string",
"description": "内容替换的原因。"
}
}
}
]
},
"StreamEventChatError": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "流式输出过程中的错误事件。",
"properties": {
"status": {
"type": "integer",
"description": "HTTP 状态码。"
},
"code": {
"type": "string",
"description": "错误码。"
},
"message": {
"type": "string",
"description": "错误信息。"
}
}
}
]
},
"StreamEventChatPing": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"type": "object",
"description": "Ping 事件，用于保持连接活跃。以 `event: ping` 行的形式送达，无 `data:` 载荷。"
}
]
},
"Usage": {
"type": "object",
"description": "模型使用信息。",
"properties": {
"prompt_tokens": {
"type": "integer",
"description": "提示词中的令牌数。"
},
"prompt_unit_price": {
"type": "string",
"format": "decimal",
"description": "每个提示词令牌的单价。"
},
"prompt_price_unit": {
"type": "string",
"format": "decimal",
"description": "提示词令牌的价格单位。"
},
"prompt_price": {
"type": "string",
"format": "decimal",
"description": "提示词令牌的总价。"
},
"completion_tokens": {
"type": "integer",
"description": "补全内容中的令牌数。"
},
"completion_unit_price": {
"type": "string",
"format": "decimal",
"description": "每个补全令牌的单价。"
},
"completion_price_unit": {
"type": "string",
"format": "decimal",
"description": "补全令牌的价格单位。"
},
"completion_price": {
"type": "string",
"format": "decimal",
"description": "补全令牌的总价。"
},
"total_tokens": {
"type": "integer",
"description": "使用的令牌总数。"
},
"total_price": {
"type": "string",
"format": "decimal",
"description": "所有令牌的总价。"
},
"currency": {
"type": "string",
"description": "计价货币。"
},
"latency": {
"type": "number",
"format": "double",
"description": "延迟时间（秒）。"
}
}
},
"RetrieverResource": {
"type": "object",
"description": "检索资源的引用和归属信息。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "检索资源的唯一 ID。"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "该资源所属消息的 ID。"
},
"position": {
"type": "integer",
"description": "资源在列表中的位置。"
},
"dataset_id": {
"type": "string",
"format": "uuid",
"description": "知识库 ID。"
},
"dataset_name": {
"type": "string",
"description": "知识库名称。"
},
"document_id": {
"type": "string",
"format": "uuid",
"description": "文档 ID。"
},
"document_name": {
"type": "string",
"description": "文档名称。"
},
"data_source_type": {
"type": "string",
"description": "数据源类型。"
},
"segment_id": {
"type": "string",
"format": "uuid",
"description": "文档中特定块的 ID。"
},
"score": {
"type": "number",
"format": "float",
"description": "资源的相关性评分。"
},
"hit_count": {
"type": "integer",
"description": "该块被命中的次数。"
},
"word_count": {
"type": "integer",
"description": "块的字数。"
},
"segment_position": {
"type": "integer",
"description": "块在文档中的位置。"
},
"index_node_hash": {
"type": "string",
"description": "索引节点的哈希值。"
},
"content": {
"type": "string",
"description": "资源的内容片段。"
},
"summary": {
"type": "string",
"nullable": true,
"description": "块内容的摘要。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳（Unix 纪元秒）。"
}
}
},
"FileUploadResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "唯一文件 ID。"
},
"name": {
"type": "string",
"description": "文件名。"
},
"size": {
"type": "integer",
"description": "文件大小（字节）。"
},
"extension": {
"type": "string",
"nullable": true,
"description": "文件扩展名。"
},
"mime_type": {
"type": "string",
"nullable": true,
"description": "文件的 MIME 类型。"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "上传文件的用户 ID。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "上传时间戳（Unix 纪元秒）。"
},
"preview_url": {
"type": "string",
"nullable": true,
"description": "文件的预览 URL。"
},
"source_url": {
"type": "string",
"description": "文件的签名下载 URL。"
},
"original_url": {
"type": "string",
"nullable": true,
"description": "文件的原始 URL。"
},
"user_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "未使用，始终为 `null`。"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "关联的租户 ID。"
},
"conversation_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "关联的会话 ID。"
},
"file_key": {
"type": "string",
"nullable": true,
"description": "未使用，始终为 `null`。"
}
}
},
"EndUserDetail": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "终端用户 ID。"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "租户 ID。"
},
"app_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "应用 ID。"
},
"type": {
"type": "string",
"description": "终端用户类型。Service API 用户固定为 `service_api`。"
},
"external_user_id": {
"type": "string",
"nullable": true,
"description": "API 请求中提供的 `user` 标识符（例如 [发送对话消息](/api-reference/对话流/发送对话消息) 中的 `user` 字段）。"
},
"name": {
"type": "string",
"nullable": true,
"description": "终端用户名称。"
},
"is_anonymous": {
"type": "boolean",
"description": "用户是否为匿名用户。当原始 API 请求中未提供 `user` 标识符时，值为 `true`。"
},
"session_id": {
"type": "string",
"description": "会话标识符。默认为 `external_user_id` 的值。"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "创建时间戳。"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最后更新时间戳。"
}
}
},
"MessageFeedbackRequest": {
"type": "object",
"description": "提交消息反馈的请求体。",
"required": [
"user"
],
"properties": {
"rating": {
"type": "string",
"enum": [
"like",
"dislike",
null
],
"nullable": true,
"description": "反馈评分。设为 `null` 可撤销之前提交的反馈。"
},
"user": {
"type": "string",
"description": "用户标识符，由开发者定义，必须确保在应用内唯一。"
},
"content": {
"type": "string",
"description": "提供额外详情的可选文字反馈。"
}
}
},
"AppFeedbacksResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "反馈项列表。",
"items": {
"$ref": "#/components/schemas/FeedbackItem"
}
}
}
},
"FeedbackItem": {
"type": "object",
"description": "单条反馈项。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "反馈 ID。"
},
"app_id": {
"type": "string",
"format": "uuid",
"description": "应用 ID。"
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "会话 ID。"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "消息 ID。"
},
"rating": {
"type": "string",
"description": "反馈评分。`like` 为正面，`dislike` 为负面。"
},
"content": {
"type": "string",
"nullable": true,
"description": "可选的文字反馈。"
},
"from_source": {
"type": "string",
"description": "反馈来源。`user` 为终端用户通过 API 提交的反馈，`admin` 为从控制台提交的反馈。"
},
"from_end_user_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "提交反馈的终端用户 ID。当 `from_source` 为 `user` 时存在。"
},
"from_account_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "提交反馈的账户 ID。当 `from_source` 为 `admin` 时存在。"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "创建时间戳。"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最后更新时间戳。"
}
}
},
"SuggestedQuestionsResponse": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "结果状态。"
},
"data": {
"type": "array",
"items": {
"type": "string"
},
"description": "建议问题列表。"
}
}
},
"ConversationHistoryResponse": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "每页条目数。"
},
"has_more": {
"type": "boolean",
"description": "是否有更多消息。"
},
"data": {
"type": "array",
"description": "消息列表。",
"items": {
"$ref": "#/components/schemas/ConversationMessageItem"
}
}
}
},
"ConversationMessageItem": {
"type": "object",
"description": "会话中的单条消息。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "消息 ID。"
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "会话 ID。"
},
"parent_message_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "线程会话的父消息 ID。"
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "该消息的输入变量。"
},
"query": {
"type": "string",
"description": "用户查询文本。"
},
"answer": {
"type": "string",
"description": "助手回答文本。"
},
"status": {
"type": "string",
"description": "消息状态。成功消息为 `normal`，生成失败时为 `error`。"
},
"error": {
"type": "string",
"nullable": true,
"description": "当 `status` 为 `error` 时的错误消息。"
},
"message_files": {
"type": "array",
"description": "附加到该消息的文件。",
"items": {
"$ref": "#/components/schemas/MessageFileItem"
}
},
"feedback": {
"type": "object",
"nullable": true,
"description": "该消息的用户反馈。",
"properties": {
"rating": {
"type": "string",
"description": "反馈评分。`like` 为正面，`dislike` 为负面。"
}
}
},
"retriever_resources": {
"type": "array",
"description": "该消息使用的检索资源。",
"items": {
"$ref": "#/components/schemas/RetrieverResource"
}
},
"agent_thoughts": {
"type": "array",
"description": "该消息的 Agent 思考。",
"items": {
"$ref": "#/components/schemas/AgentThoughtItem"
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳（Unix 纪元秒）。"
},
"extra_contents": {
"type": "array",
"description": "与此消息关联的附加执行内容，例如 Chatflow 工作流中人工介入节点的表单数据。",
"items": {
"$ref": "#/components/schemas/HumanInputContent"
}
}
}
},
"MessageFileItem": {
"type": "object",
"description": "附加到消息的文件。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "File ID."
},
"filename": {
"type": "string",
"description": "原始文件名。"
},
"type": {
"type": "string",
"description": "文件类型，例如 `image`。"
},
"url": {
"type": "string",
"format": "url",
"nullable": true,
"description": "文件的预览 URL。"
},
"mime_type": {
"type": "string",
"nullable": true,
"description": "文件的 MIME 类型。"
},
"size": {
"type": "integer",
"nullable": true,
"description": "文件大小（字节）。"
},
"transfer_method": {
"type": "string",
"description": "使用的传输方式。`remote_url` 表示基于 URL 的文件，`local_file` 表示已上传的文件，`tool_file` 表示工具生成的文件。"
},
"belongs_to": {
"type": "string",
"nullable": true,
"description": "该文件的所属者。用户上传的文件为 `user`，助手生成的文件为 `assistant`。"
},
"upload_file_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "通过 `local_file` 传输时的上传文件 ID。"
}
}
},
"AgentThoughtItem": {
"type": "object",
"description": "消息中的 Agent 思考步骤。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Agent 思考 ID。"
},
"chain_id": {
"type": "string",
"nullable": true,
"description": "该思考的链 ID。"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "该思考所属的唯一消息 ID。"
},
"position": {
"type": "integer",
"description": "该思考的位置。"
},
"thought": {
"type": "string",
"description": "LLM 正在思考的内容。"
},
"tool": {
"type": "string",
"description": "调用的工具，以 `;` 分隔。"
},
"tool_labels": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "已使用工具的标签。"
},
"tool_input": {
"type": "string",
"description": "工具输入（JSON 格式）。"
},
"observation": {
"type": "string",
"description": "工具调用的响应。"
},
"files": {
"type": "array",
"items": {
"type": "string"
},
"description": "与该思考相关的文件 ID。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳。"
}
}
},
"ConversationsListResponse": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "每页条目数。"
},
"has_more": {
"type": "boolean",
"description": "是否有更多会话。"
},
"data": {
"type": "array",
"description": "会话列表。",
"items": {
"$ref": "#/components/schemas/ConversationListItem"
}
}
}
},
"ConversationListItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "会话 ID。"
},
"name": {
"type": "string",
"description": "会话名称。"
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "会话的输入变量。"
},
"status": {
"type": "string",
"description": "会话状态。活跃会话为 `normal`。"
},
"introduction": {
"type": "string",
"description": "会话介绍。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳。"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "最后更新时间戳。"
}
}
},
"ConversationRenameRequest": {
"type": "object",
"description": "重命名会话的请求体。",
"required": [
"user"
],
"properties": {
"name": {
"type": "string",
"description": "会话名称。当 `auto_generate` 为 `false` 时必填。"
},
"auto_generate": {
"type": "boolean",
"default": false,
"description": "自动生成会话名称。当为 `true` 时，`name` 字段将被忽略。"
},
"user": {
"type": "string",
"description": "用户标识符。"
}
}
},
"ConversationVariablesResponse": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "每页条目数。"
},
"has_more": {
"type": "boolean",
"description": "是否有下一页。"
},
"data": {
"type": "array",
"description": "会话变量列表。",
"items": {
"$ref": "#/components/schemas/ConversationVariableItem"
}
}
}
},
"ConversationVariableItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Variable ID."
},
"name": {
"type": "string",
"description": "变量名称。"
},
"value_type": {
"type": "string",
"description": "变量值类型。可选值：`string`、`number`、`object`、`secret`、`file`、`boolean`、`array[any]`、`array[string]`、`array[number]`、`array[object]`、`array[file]`、`array[boolean]`。"
},
"value": {
"type": "string",
"description": "变量值（复杂类型可以是 JSON 字符串）。"
},
"description": {
"type": "string",
"description": "变量描述。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳。"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "最后更新时间戳。"
}
}
},
"ConversationVariableUpdateRequest": {
"type": "object",
"description": "更新会话变量的请求体。",
"required": [
"value"
],
"properties": {
"value": {
"description": "变量的新值。必须与变量的预期类型匹配。"
},
"user": {
"type": "string",
"description": "用户标识符。"
}
}
},
"AudioToTextRequest": {
"type": "object",
"description": "语音转文字的请求体。",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "音频文件。按 MIME 类型校验，必须为 `audio/mp3`、`audio/m4a`、`audio/wav`、`audio/amr`、`audio/mpga` 之一。大小限制：`30 MB`。"
},
"user": {
"type": "string",
"description": "用户标识符。"
}
}
},
"AudioToTextResponse": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "语音识别输出的文字。"
}
}
},
"TextToAudioRequest": {
"type": "object",
"description": "文字转语音的请求体。提供 `message_id` 或 `text` 其中之一。",
"properties": {
"message_id": {
"type": "string",
"format": "uuid",
"description": "消息 ID。当同时提供 `text` 时，优先使用消息 ID。"
},
"text": {
"type": "string",
"description": "要转换的语音内容。"
},
"user": {
"type": "string",
"description": "用户标识符。"
},
"voice": {
"type": "string",
"description": "文字转语音使用的声音。可用声音取决于为此应用配置的 TTS 提供商。使用[获取应用参数](/api-reference/应用配置/获取应用参数) → `text_to_speech.voice` 中的 `voice` 值作为默认值。"
},
"streaming": {
"type": "boolean",
"description": "是否启用流式响应。"
}
}
},
"AppInfoResponse": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "应用名称。"
},
"description": {
"type": "string",
"description": "应用描述。"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "应用标签。"
},
"mode": {
"type": "string",
"description": "应用模式。`completion` 为文本生成应用，`chat` 为基础对话应用，`agent-chat` 为 Agent 应用，`advanced-chat` 为 Chatflow 应用，`workflow` 为 Workflow 应用。"
},
"author_name": {
"type": "string",
"description": "应用作者名称。"
}
}
},
"ChatAppParametersResponse": {
"type": "object",
"properties": {
"opening_statement": {
"type": "string",
"description": "会话开始时显示的开场白。"
},
"suggested_questions": {
"type": "array",
"items": {
"type": "string"
},
"description": "建议的初始问题列表。"
},
"suggested_questions_after_answer": {
"type": "object",
"description": "回答后建议问题的配置。",
"properties": {
"enabled": {
"type": "boolean",
"description": "是否启用此功能。"
}
}
},
"speech_to_text": {
"type": "object",
"description": "语音转文字配置。",
"properties": {
"enabled": {
"type": "boolean",
"description": "是否启用此功能。"
}
}
},
"text_to_speech": {
"type": "object",
"description": "文字转语音配置。",
"properties": {
"enabled": {
"type": "boolean",
"description": "是否启用此功能。"
},
"voice": {
"type": "string",
"description": "TTS 的声音标识符。"
},
"language": {
"type": "string",
"description": "TTS 的语言。"
},
"autoPlay": {
"type": "string",
"description": "自动播放设置。`enabled` 为自动播放音频，`disabled` 为需要手动播放。"
}
}
},
"retriever_resource": {
"type": "object",
"description": "检索资源配置。",
"properties": {
"enabled": {
"type": "boolean",
"description": "是否启用此功能。"
}
}
},
"annotation_reply": {
"type": "object",
"description": "标注回复配置。",
"properties": {
"enabled": {
"type": "boolean",
"description": "是否启用此功能。"
}
}
},
"more_like_this": {
"type": "object",
"description": "更多类似内容配置。",
"properties": {
"enabled": {
"type": "boolean",
"description": "是否启用此功能。"
}
}
},
"sensitive_word_avoidance": {
"type": "object",
"description": "敏感词过滤配置。",
"properties": {
"enabled": {
"type": "boolean",
"description": "是否启用此功能。"
}
}
},
"user_input_form": {
"type": "array",
"description": "用户输入表单元素列表。",
"items": {
"$ref": "#/components/schemas/UserInputFormItem"
}
},
"file_upload": {
"type": "object",
"description": "文件上传配置。",
"properties": {
"image": {
"type": "object",
"description": "图片上传设置。",
"properties": {
"enabled": {
"type": "boolean",
"description": "是否启用图片上传。"
},
"number_limits": {
"type": "integer",
"description": "最大图片数量。"
},
"detail": {
"type": "string",
"description": "图片精细程度。"
},
"transfer_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "允许的传输方式。"
}
}
}
}
},
"system_parameters": {
"type": "object",
"description": "系统级参数和限制。",
"properties": {
"file_size_limit": {
"type": "integer",
"description": "最大文件大小（MB）。"
},
"image_file_size_limit": {
"type": "integer",
"description": "最大图片文件大小（MB）。"
},
"audio_file_size_limit": {
"type": "integer",
"description": "最大音频文件大小（MB）。"
},
"video_file_size_limit": {
"type": "integer",
"description": "最大视频文件大小（MB）。"
},
"workflow_file_upload_limit": {
"type": "integer",
"description": "工作流文件上传的最大文件数。"
}
}
}
}
},
"UserInputFormItem": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/TextInputControlWrapper"
},
{
"$ref": "#/components/schemas/ParagraphControlWrapper"
},
{
"$ref": "#/components/schemas/SelectControlWrapper"
}
]
},
"TextInputControlWrapper": {
"title": "Text Input",
"type": "object",
"properties": {
"text-input": {
"$ref": "#/components/schemas/TextInputControl"
}
}
},
"ParagraphControlWrapper": {
"title": "Paragraph",
"type": "object",
"properties": {
"paragraph": {
"$ref": "#/components/schemas/ParagraphControl"
}
}
},
"SelectControlWrapper": {
"title": "Select",
"type": "object",
"properties": {
"select": {
"$ref": "#/components/schemas/SelectControl"
}
}
},
"TextInputControl": {
"type": "object",
"description": "文本输入表单控件。",
"properties": {
"label": {
"type": "string",
"description": "显示标签。"
},
"variable": {
"type": "string",
"description": "变量名称。"
},
"required": {
"type": "boolean",
"description": "输入是否必填。"
},
"default": {
"type": "string",
"description": "默认值。"
}
}
},
"ParagraphControl": {
"type": "object",
"description": "段落（多行文本）表单控件。",
"properties": {
"label": {
"type": "string",
"description": "显示标签。"
},
"variable": {
"type": "string",
"description": "变量名称。"
},
"required": {
"type": "boolean",
"description": "输入是否必填。"
},
"default": {
"type": "string",
"description": "默认值。"
}
}
},
"SelectControl": {
"type": "object",
"description": "下拉选择表单控件。",
"properties": {
"label": {
"type": "string",
"description": "显示标签。"
},
"variable": {
"type": "string",
"description": "变量名称。"
},
"required": {
"type": "boolean",
"description": "是否必须选择。"
},
"default": {
"type": "string",
"description": "默认选中的值。"
},
"options": {
"type": "array",
"items": {
"type": "string"
},
"description": "此表单控件的可选值列表。"
}
}
},
"AppMetaResponse": {
"type": "object",
"properties": {
"tool_icons": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"title": "Icon URL",
"type": "string",
"format": "url",
"description": "图标的 URL。"
},
{
"$ref": "#/components/schemas/ToolIconDetail"
}
]
},
"description": "工具图标。键为工具名称。"
}
}
},
"ToolIconDetail": {
"title": "Emoji Icon",
"type": "object",
"description": "使用 emoji 的工具图标详情。",
"properties": {
"background": {
"type": "string",
"description": "十六进制格式的背景颜色。"
},
"content": {
"type": "string",
"description": "Emoji 内容。"
}
}
},
"WebAppSettingsResponse": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "WebApp 标题。"
},
"chat_color_theme": {
"type": "string",
"description": "聊天主题颜色。"
},
"chat_color_theme_inverted": {
"type": "boolean",
"description": "聊天主题颜色是否反转。"
},
"icon_type": {
"type": "string",
"description": "使用的图标类型。`emoji` 为表情图标，`image` 为上传的图片图标。"
},
"icon": {
"type": "string",
"description": "图标内容（表情或图片 ID）。"
},
"icon_background": {
"type": "string",
"description": "图标背景颜色。"
},
"icon_url": {
"type": "string",
"format": "url",
"nullable": true,
"description": "图标图片的 URL。"
},
"description": {
"type": "string",
"description": "WebApp 描述。"
},
"copyright": {
"type": "string",
"description": "版权文本。"
},
"privacy_policy": {
"type": "string",
"description": "隐私政策 URL。"
},
"custom_disclaimer": {
"type": "string",
"description": "自定义免责声明文本。"
},
"default_language": {
"type": "string",
"description": "默认语言代码。"
},
"show_workflow_steps": {
"type": "boolean",
"description": "是否显示工作流步骤。"
},
"use_icon_as_answer_icon": {
"type": "boolean",
"description": "是否使用应用图标作为回答图标。"
}
}
},
"AnnotationListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AnnotationItem"
},
"description": "当前页面的标注项列表。"
},
"has_more": {
"type": "boolean",
"description": "如果当前结果集之后还有更多页面，则为 `true`。"
},
"limit": {
"type": "integer",
"description": "每页条目数。"
},
"total": {
"type": "integer",
"description": "匹配查询条件的标注总数。"
},
"page": {
"type": "integer",
"description": "当前页码。"
}
}
},
"AnnotationItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "标注唯一标识符。"
},
"question": {
"type": "string",
"nullable": true,
"description": "触发该标注的问题文本。"
},
"answer": {
"type": "string",
"nullable": true,
"description": "标注被匹配时返回的预定义回答。"
},
"hit_count": {
"type": "integer",
"nullable": true,
"description": "该标注被匹配并作为回复返回的次数。"
},
"created_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "创建时间戳（Unix 纪元秒）。"
}
}
},
"CreateAnnotationRequest": {
"type": "object",
"description": "创建新标注的请求体。",
"required": [
"question",
"answer"
],
"properties": {
"question": {
"type": "string",
"description": "标注问题。"
},
"answer": {
"type": "string",
"description": "标注答案。"
}
}
},
"UpdateAnnotationRequest": {
"type": "object",
"description": "更新标注的请求体。",
"required": [
"question",
"answer"
],
"properties": {
"question": {
"type": "string",
"description": "更新后的标注问题。"
},
"answer": {
"type": "string",
"description": "更新后的标注答案。"
}
}
},
"InitialAnnotationReplySettingsRequest": {
"type": "object",
"description": "配置标注回复设置的请求体。",
"required": [
"score_threshold",
"embedding_provider_name",
"embedding_model_name"
],
"properties": {
"embedding_provider_name": {
"type": "string",
"description": "嵌入模型供应商名称（例如 `openai`、`cohere`）。"
},
"embedding_model_name": {
"type": "string",
"description": "用于标注匹配的嵌入模型名称（例如 `text-embedding-3-small`）。"
},
"score_threshold": {
"type": "number",
"format": "float",
"description": "标注被视为匹配的最低相似度分数。值越高，要求匹配越精确。"
}
}
},
"InitialAnnotationReplySettingsResponse": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"format": "uuid",
"description": "异步任务 ID。配合 [查询标注回复配置任务状态](/api-reference/标注管理/查询标注回复配置任务状态) 使用以跟踪进度。"
},
"job_status": {
"type": "string",
"description": "当前任务状态，仅为 `waiting`（排队中）或 `processing`（处理中）；`completed` 和 `error` 仅由 [查询标注回复配置任务状态](/api-reference/标注管理/查询标注回复配置任务状态) 返回。"
}
}
},
"InitialAnnotationReplySettingsStatusResponse": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"format": "uuid",
"description": "来自 [配置标注回复](/api-reference/标注管理/配置标注回复) 调用的任务 ID。"
},
"job_status": {
"type": "string",
"description": "当前任务状态。`waiting` 表示排队中，`processing` 表示处理中，`completed` 表示已完成，`error` 表示失败。"
},
"error_msg": {
"type": "string",
"description": "描述任务失败原因的错误消息。当 `job_status` 不是 `error` 时为空字符串。"
}
}
},
"StreamEventWorkflowStarted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "工作流执行已开始。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作流运行 ID。"
},
"workflow_id": {
"type": "string",
"description": "关联的工作流 ID。"
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "本次工作流执行的输入变量。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "开始时间戳（Unix 纪元秒）。"
},
"reason": {
"type": "string",
"description": "工作流启动原因。`initial` 表示首次启动，`resumption` 表示暂停后恢复（例如人工介入后）。"
}
}
}
}
}
]
},
"StreamEventWorkflowFinished": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "工作流执行已完成。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作流运行 ID。"
},
"workflow_id": {
"type": "string",
"description": "关联的工作流 ID。"
},
"status": {
"type": "string",
"description": "执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`stopped` 表示手动停止，`partial-succeeded` 表示部分完成，`paused` 表示等待人工介入。"
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "工作流输出数据。"
},
"error": {
"type": "string",
"nullable": true,
"description": "执行失败时的错误消息。"
},
"elapsed_time": {
"type": "number",
"description": "总执行耗时（秒）。"
},
"total_tokens": {
"type": "integer",
"description": "消耗的总令牌数。"
},
"total_steps": {
"type": "integer",
"description": "已执行的总步数。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "开始时间戳（Unix 纪元秒）。"
},
"finished_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "结束时间戳（Unix 纪元秒）。"
},
"exceptions_count": {
"type": "integer",
"nullable": true,
"description": "执行期间的异常数量。"
},
"files": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": true
},
"description": "工作流执行期间生成的文件。"
}
}
}
}
}
]
},
"StreamEventNodeStarted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "节点执行已开始。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "节点执行 ID。"
},
"node_id": {
"type": "string",
"description": "工作流图中的节点 ID。"
},
"node_type": {
"type": "string",
"description": "节点类型（例如 `llm`、`knowledge-retrieval`、`code`）。"
},
"title": {
"type": "string",
"description": "Node title."
},
"index": {
"type": "integer",
"description": "执行索引。"
},
"predecessor_node_id": {
"type": "string",
"nullable": true,
"description": "前驱节点的 ID。"
},
"inputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "节点输入数据。在简化 API 响应中可能为 `null`。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "开始时间戳（Unix 纪元秒）。"
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "附加元数据。"
},
"iteration_id": {
"type": "string",
"nullable": true,
"description": "如果该节点在迭代内运行，则为迭代 ID。"
},
"loop_id": {
"type": "string",
"nullable": true,
"description": "当该节点在循环内运行时的循环 ID。"
}
}
}
}
}
]
},
"StreamEventNodeFinished": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "节点执行已完成。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "节点执行 ID。"
},
"node_id": {
"type": "string",
"description": "工作流图中的节点 ID。"
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Node title."
},
"index": {
"type": "integer",
"description": "执行索引。"
},
"predecessor_node_id": {
"type": "string",
"nullable": true,
"description": "前驱节点的 ID。"
},
"inputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "节点输入数据。在简化 API 响应中可能为 `null`。"
},
"process_data": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "节点处理数据。在简化 API 响应中可能为 `null`。"
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "节点输出数据。在简化 API 响应中可能为 `null`。"
},
"status": {
"type": "string",
"description": "节点执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。"
},
"error": {
"type": "string",
"nullable": true,
"description": "节点失败时的错误消息。"
},
"elapsed_time": {
"type": "number",
"description": "节点执行耗时（秒）。"
},
"execution_metadata": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "执行元数据（例如令牌用量、模型信息）。在简化 API 响应中可能为 `null`。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "开始时间戳（Unix 纪元秒）。"
},
"finished_at": {
"type": "integer",
"format": "int64",
"description": "结束时间戳（Unix 纪元秒）。"
},
"files": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": true
},
"description": "该节点生成的文件。"
},
"iteration_id": {
"type": "string",
"nullable": true,
"description": "如果该节点在迭代内运行，则为迭代 ID。"
},
"loop_id": {
"type": "string",
"nullable": true,
"description": "当该节点在循环内运行时的循环 ID。"
}
}
}
}
}
]
},
"StreamEventNodeRetry": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "节点重试次数。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "节点执行 ID。"
},
"node_id": {
"type": "string",
"description": "工作流图中的节点 ID。"
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Node title."
},
"index": {
"type": "integer",
"description": "执行索引。"
},
"predecessor_node_id": {
"type": "string",
"nullable": true,
"description": "前驱节点的 ID。"
},
"inputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "节点输入数据。"
},
"process_data": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "节点处理数据。"
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "节点输出数据。"
},
"status": {
"type": "string",
"description": "节点执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。"
},
"error": {
"type": "string",
"nullable": true,
"description": "本次重试的错误消息。"
},
"elapsed_time": {
"type": "number",
"description": "本次尝试的执行时间（秒）。"
},
"execution_metadata": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "执行元数据。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "开始时间戳（Unix 纪元秒）。"
},
"finished_at": {
"type": "integer",
"format": "int64",
"description": "结束时间戳（Unix 纪元秒）。"
},
"files": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": true
},
"description": "本次重试期间生成的文件。"
},
"iteration_id": {
"type": "string",
"nullable": true,
"description": "迭代 ID（如适用）。"
},
"loop_id": {
"type": "string",
"nullable": true,
"description": "循环 ID（如适用）。"
},
"retry_index": {
"type": "integer",
"description": "重试次数索引，从 `0` 开始。"
}
}
}
}
}
]
},
"StreamEventIterationStarted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "迭代循环已开始。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "迭代执行 ID。"
},
"node_id": {
"type": "string",
"description": "迭代节点 ID。"
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "迭代节点标题。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "开始时间戳（Unix 纪元秒）。"
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "附加元数据。"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "迭代元数据。"
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "迭代输入数据。"
}
}
}
}
}
]
},
"StreamEventIterationNext": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "迭代已进入下一项。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "迭代执行 ID。"
},
"node_id": {
"type": "string",
"description": "迭代节点 ID。"
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "迭代节点标题。"
},
"index": {
"type": "integer",
"description": "当前迭代索引（从 0 开始）。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "时间戳（Unix 纪元秒）。"
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "附加元数据。"
}
}
}
}
}
]
},
"StreamEventIterationCompleted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "迭代循环已完成。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "迭代执行 ID。"
},
"node_id": {
"type": "string",
"description": "迭代节点 ID。"
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "迭代节点标题。"
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "迭代输出数据。"
},
"status": {
"type": "string",
"description": "迭代执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。"
},
"error": {
"type": "string",
"nullable": true,
"description": "迭代失败时的错误消息。"
},
"elapsed_time": {
"type": "number",
"description": "迭代总耗时（秒）。"
},
"total_tokens": {
"type": "integer",
"description": "所有迭代中消耗的令牌总数。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "开始时间戳（Unix 纪元秒）。"
},
"finished_at": {
"type": "integer",
"format": "int64",
"description": "结束时间戳（Unix 纪元秒）。"
},
"steps": {
"type": "integer",
"description": "已执行的迭代步骤总数。"
}
}
}
}
}
]
},
"StreamEventLoopStarted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "循环已开始。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "循环执行 ID。"
},
"node_id": {
"type": "string",
"description": "循环节点 ID。"
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "循环节点标题。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "开始时间戳（Unix 纪元秒）。"
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "附加元数据。"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "循环元数据。"
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "循环输入数据。"
}
}
}
}
}
]
},
"StreamEventLoopNext": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "循环已进入下一次迭代。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "循环执行 ID。"
},
"node_id": {
"type": "string",
"description": "循环节点 ID。"
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "循环节点标题。"
},
"index": {
"type": "integer",
"description": "当前循环索引（从 0 开始）。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "时间戳（Unix 纪元秒）。"
},
"pre_loop_output": {
"description": "上一次循环迭代的输出。"
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "附加元数据。"
}
}
}
}
}
]
},
"StreamEventLoopCompleted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "循环已完成。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "循环执行 ID。"
},
"node_id": {
"type": "string",
"description": "循环节点 ID。"
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "循环节点标题。"
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "循环输出数据。"
},
"status": {
"type": "string",
"description": "循环执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。"
},
"error": {
"type": "string",
"nullable": true,
"description": "循环失败时的错误消息。"
},
"elapsed_time": {
"type": "number",
"description": "循环总执行耗时（秒）。"
},
"total_tokens": {
"type": "integer",
"description": "所有循环迭代中消耗的令牌总数。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "开始时间戳（Unix 纪元秒）。"
},
"finished_at": {
"type": "integer",
"format": "int64",
"description": "结束时间戳（Unix 纪元秒）。"
},
"steps": {
"type": "integer",
"description": "已执行的循环总步数。"
}
}
}
}
}
]
},
"StreamEventHumanInputRequired": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"form_id": {
"type": "string",
"description": "表单实例的标识符，会在错误消息和日志中出现。Service API 调用请使用 `form_token`。"
},
"node_id": {
"type": "string",
"description": "产生该表单的 Human Input 节点 ID。"
},
"node_title": {
"type": "string",
"description": "Human Input 节点的显示标题。"
},
"form_content": {
"type": "string",
"description": "已替换工作流变量的预渲染表单正文。"
},
"inputs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "表单输入控件类型。可用值：`paragraph`（多行文本输入）、`select`（从列表中单选）、`file`（单文件上传）和 `file-list`（多文件上传）。"
},
"output_variable_name": {
"type": "string",
"description": "引用该输入提交值在工作流中使用的变量名。对应提交 `inputs` 对象中的键。"
},
"default": {
"type": "object",
"nullable": true,
"description": "从工作流上下文解析得到的默认值。未配置默认值时为 `null`。",
"properties": {
"type": {
"type": "string",
"description": "默认值来源。`constant` 表示将 `value` 作为字面字符串；`variable` 表示 `selector` 指向工作流变量。"
},
"selector": {
"type": "array",
"items": {
"type": "string"
},
"description": "当 `type` 为 `variable` 时，变量引用路径（例如 `[\"node_id\", \"var_name\"]`）。至少包含两个元素。"
},
"value": {
"type": "string",
"description": "当 `type` 为 `constant` 时的字面默认值。始终为字符串。"
}
}
}
}
},
"description": "接收者需要填写的表单输入字段。"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"maxLength": 20,
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
"description": "操作按钮的标识。当接收者选择该按钮时，作为 `action` 传入 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单)。"
},
"title": {
"type": "string",
"maxLength": 100,
"description": "显示给接收者的按钮文本。"
},
"button_style": {
"type": "string",
"description": "按钮视觉样式。可用值：`primary`、`default`、`accent`、`ghost`。"
}
}
},
"description": "接收者提交时可选择的用户操作（按钮）。"
},
"display_in_ui": {
"type": "boolean",
"description": "表单是否也在 Dify 控制台中显示。"
},
"form_token": {
"type": "string",
"nullable": true,
"description": "[获取人工介入表单](/api-reference/人工介入/获取人工介入表单) 和 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单) 的访问令牌。当人工介入节点使用邮件或控制台送达时为 `null`（Service API 仅能处理 WebApp 送达的表单）。"
},
"resolved_default_values": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "按输入的 `output_variable_name` 分组的预填充默认值。所有值均为字符串。"
},
"expiration_time": {
"type": "integer",
"format": "int64",
"description": "Unix 时间戳（秒），超过后表单无法再被提交。"
}
}
}
}
}
]
},
"StreamEventWorkflowPaused": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/对话流/获取工作流执行情况) 使用以在执行后获取结果。"
},
"paused_nodes": {
"type": "array",
"items": {
"type": "string"
},
"description": "已暂停的节点 ID 列表。"
},
"outputs": {
"type": "object",
"additionalProperties": true,
"description": "暂停时的部分输出。"
},
"reasons": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "暂停原因。"
},
"status": {
"type": "string",
"description": "工作流执行状态。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳。"
},
"elapsed_time": {
"type": "number",
"format": "float",
"description": "总耗时（秒）。"
},
"total_tokens": {
"type": "integer",
"description": "消耗的总令牌数。"
},
"total_steps": {
"type": "integer",
"description": "已执行的总步数。"
}
}
}
}
}
]
},
"StreamEventHumanInputFormFilled": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"description": "表单被填写的 Human Input 节点 ID。"
},
"node_title": {
"type": "string",
"description": "Human Input 节点的显示标题。"
},
"rendered_content": {
"type": "string",
"description": "包含接收者提交值的渲染后表单内容（`human_input_required` 上的 `form_content` 是未填写的模板）。"
},
"action_id": {
"type": "string",
"description": "接收者所选操作的标识（与传入 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单) 的 `action` 一致）。"
},
"action_text": {
"type": "string",
"description": "所选操作的显示文本。"
}
}
}
}
}
]
},
"StreamEventHumanInputFormTimeout": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "工作流执行运行 ID。"
},
"data": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"description": "表单过期的 Human Input 节点 ID。"
},
"node_title": {
"type": "string",
"description": "Human Input 节点的显示标题。"
},
"expiration_time": {
"type": "integer",
"format": "int64",
"description": "Unix 时间戳（秒），表示表单过期时刻。"
}
}
}
}
}
]
},
"StreamEventAgentLog": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "工作流中 Agent 节点的 Agent 日志。",
"properties": {
"data": {
"type": "object",
"properties": {
"node_execution_id": {
"type": "string",
"description": "节点执行 ID。"
},
"id": {
"type": "string",
"description": "日志条目 ID。"
},
"label": {
"type": "string",
"description": "日志条目标签。"
},
"parent_id": {
"type": "string",
"nullable": true,
"description": "嵌套条目的父日志条目 ID。"
},
"error": {
"type": "string",
"nullable": true,
"description": "错误消息（如适用）。"
},
"status": {
"type": "string",
"description": "日志条目状态。"
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "日志条目数据。"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "附加元数据。"
},
"node_id": {
"type": "string",
"description": "工作流图中的节点 ID。"
}
}
}
}
}
]
},
"StreamEventChatReasoningChunk": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message_id": {
"type": "string",
"format": "uuid",
"description": "此推理内容所属消息的 ID（与顶层 `message_id` 一致）。"
},
"reasoning": {
"type": "string",
"description": "由 `reasoning_format` 为 `separated` 的 LLM 节点发送的推理内容增量。拼接连续的 `reasoning_chunk` 事件即可还原完整推理内容。本流与 `message` 并行；`message`（回答）流不含 `<think>` 标签。"
},
"node_id": {
"type": "string",
"nullable": true,
"description": "产生该推理内容的 LLM 节点 ID。当多个 LLM 节点运行时，可据此归属推理内容。"
},
"is_final": {
"type": "boolean",
"description": "`true` 标志 LLM 节点推理阶段结束（即「思考完成」信号）；该事件的 `reasoning` 可能为空。"
}
}
}
}
}
]
},
"StreamEventChatTextChunk": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "文本内容块。"
},
"from_variable_selector": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "工作流中文本变量的源路径。"
}
}
}
}
}
]
},
"WorkflowRunDetailResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "工作流运行 ID。"
},
"workflow_id": {
"type": "string",
"format": "uuid",
"description": "工作流 ID."
},
"status": {
"type": "string",
"description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。"
},
"inputs": {
"type": "string",
"nullable": true,
"description": "工作流运行的输入变量，以原始 JSON 字符串返回（例如 `{\"query\": \"...\"}`），客户端需自行解析；可能为 `null`。"
},
"outputs": {
"type": "object",
"additionalProperties": true,
"description": "工作流的输出数据。尚无输出时为空对象。"
},
"error": {
"type": "string",
"nullable": true,
"description": "工作流失败时的错误消息。"
},
"total_steps": {
"type": "integer",
"description": "已执行的工作流总步数。"
},
"total_tokens": {
"type": "integer",
"description": "消耗的总令牌数。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "工作流运行创建时的 Unix 时间戳。"
},
"finished_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "工作流运行结束时的 Unix 时间戳。"
},
"elapsed_time": {
"type": "number",
"format": "float",
"nullable": true,
"description": "总耗时（秒）。"
}
}
},
"WorkflowLogsResponse": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "当前页码。"
},
"limit": {
"type": "integer",
"description": "每页条目数。"
},
"total": {
"type": "integer",
"description": "日志条目总数。"
},
"has_more": {
"type": "boolean",
"description": "是否有更多可用页面。"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowLogItem"
},
"description": "工作流日志条目列表。"
}
}
},
"WorkflowLogItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "日志条目 ID。"
},
"workflow_run": {
"$ref": "#/components/schemas/WorkflowRunSummary"
},
"created_from": {
"type": "string",
"description": "工作流运行的来源（例如 `service-api`）。"
},
"created_by_role": {
"type": "string",
"description": "创建者的角色（例如 `end_user`、`account`）。"
},
"created_by_account": {
"type": "object",
"nullable": true,
"description": "由管理员用户创建时的账户详情。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "账户 ID。"
},
"name": {
"type": "string",
"description": "账户显示名称。"
},
"email": {
"type": "string",
"description": "账户邮箱地址。"
}
}
},
"created_by_end_user": {
"$ref": "#/components/schemas/EndUserSummary"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "日志条目创建时的 Unix 时间戳。"
},
"details": {
"type": "object",
"additionalProperties": true,
"nullable": true,
"description": "日志条目的附加详情。"
}
}
},
"WorkflowRunSummary": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "工作流运行 ID。"
},
"version": {
"type": "string",
"description": "工作流版本标识符。"
},
"status": {
"type": "string",
"description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。"
},
"error": {
"type": "string",
"nullable": true,
"description": "工作流失败时的错误消息。"
},
"elapsed_time": {
"type": "number",
"format": "float",
"description": "总耗时（秒）。"
},
"total_tokens": {
"type": "integer",
"description": "消耗的总令牌数。"
},
"total_steps": {
"type": "integer",
"description": "已执行的工作流总步数。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "工作流运行创建时的 Unix 时间戳。"
},
"finished_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "工作流运行结束时的 Unix 时间戳。"
},
"exceptions_count": {
"type": "integer",
"description": "执行期间发生的异常数量。"
},
"triggered_from": {
"type": "string",
"description": "触发工作流运行的来源。`app-run` 表示从应用或 API 发起的运行，`webhook` 表示由 Webhook 触发器发起的运行，`schedule` 表示由定时触发器发起的运行，`plugin` 表示由插件触发器发起的运行。"
}
}
},
"EndUserSummary": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "终端用户 ID。"
},
"type": {
"type": "string",
"description": "终端用户类型。"
},
"is_anonymous": {
"type": "boolean",
"description": "终端用户是否为匿名。"
},
"session_id": {
"type": "string",
"description": "会话标识符。"
}
}
},
"HumanInputContent": {
"type": "object",
"description": "人工介入节点的执行内容，包括表单定义和提交数据。",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "该内容所属的工作流运行 ID。"
},
"submitted": {
"type": "boolean",
"description": "人工介入表单是否已提交。"
},
"type": {
"type": "string",
"description": "`human_input` 表示人工介入内容。"
},
"form_definition": {
"nullable": true,
"description": "人工介入节点的表单定义。当内容表示提交响应时为 `null`。",
"$ref": "#/components/schemas/HumanInputFormDefinition"
},
"form_submission_data": {
"nullable": true,
"description": "已提交的表单数据。表单尚未提交时为 `null`。",
"$ref": "#/components/schemas/HumanInputFormSubmissionData"
}
}
},
"HumanInputFormDefinition": {
"type": "object",
"description": "由人工介入节点渲染的人工介入表单定义。",
"properties": {
"form_id": {
"type": "string",
"description": "表单唯一标识符。"
},
"node_id": {
"type": "string",
"description": "生成该表单的人工介入节点 ID。"
},
"node_title": {
"type": "string",
"description": "人工介入节点的标题。"
},
"form_content": {
"type": "string",
"description": "与表单一起显示的 Markdown 或文本内容。"
},
"inputs": {
"type": "array",
"description": "表单中的输入字段。",
"items": {
"$ref": "#/components/schemas/FormInput"
}
},
"actions": {
"type": "array",
"description": "表单上可用的操作按钮。",
"items": {
"$ref": "#/components/schemas/UserAction"
}
},
"display_in_ui": {
"type": "boolean",
"description": "表单是否应在 UI 中显示。"
},
"form_token": {
"type": "string",
"nullable": true,
"description": "表单提交认证的令牌。"
},
"resolved_default_values": {
"type": "object",
"additionalProperties": true,
"description": "表单输入的已解析默认值，按输出变量名称索引。"
},
"expiration_time": {
"type": "integer",
"description": "表单过期的 Unix 时间戳。"
}
}
},
"HumanInputFormSubmissionData": {
"type": "object",
"description": "来自已提交的人工介入表单的数据。",
"properties": {
"node_id": {
"type": "string",
"description": "人工介入节点的 ID。"
},
"node_title": {
"type": "string",
"description": "人工介入节点的标题。"
},
"rendered_content": {
"type": "string",
"description": "表单提交的渲染内容。"
},
"action_id": {
"type": "string",
"description": "被点击的操作按钮的 ID。"
},
"action_text": {
"type": "string",
"description": "被点击的操作按钮的显示文本。"
}
}
},
"FormInput": {
"type": "object",
"description": "表单输入字段定义。",
"properties": {
"type": {
"type": "string",
"description": "表单输入控件类型。可用值：`paragraph`（多行文本输入）、`select`（从列表中单选）、`file`（单文件上传）和 `file-list`（多文件上传）。"
},
"output_variable_name": {
"type": "string",
"description": "存储输入值的变量名称。"
},
"default": {
"nullable": true,
"description": "该输入的默认值配置。",
"$ref": "#/components/schemas/FormInputDefault"
}
}
},
"FormInputDefault": {
"type": "object",
"description": "表单输入的默认值配置。",
"properties": {
"type": {
"type": "string",
"description": "`variable` for dynamic values from 工作流 variables, `constant` for static values."
},
"selector": {
"type": "array",
"items": {
"type": "string"
},
"description": "当 `type` 为 `variable` 时的变量选择器路径。"
},
"value": {
"type": "string",
"description": "当 `type` 为 `constant` 时的静态值。"
}
}
},
"UserAction": {
"type": "object",
"description": "人工介入表单上的操作按钮。",
"properties": {
"id": {
"type": "string",
"description": "操作唯一标识符。"
},
"title": {
"type": "string",
"description": "按钮显示文本。"
},
"button_style": {
"type": "string",
"description": "`primary`, `default`, `accent`, or `ghost`."
}
}
}
}
},
"tags": [
{
"name": "对话流",
"description": "Chatflow 应用的操作，包括对话消息、工作流执行详情和事件流。"
},
{
"name": "文件操作",
"description": "文件上传和预览操作。"
},
{
"name": "终端用户",
"description": "终端用户信息相关操作。"
},
{
"name": "消息反馈",
"description": "用户反馈操作。"
},
{
"name": "会话管理",
"description": "与管理会话相关的操作。"
},
{
"name": "语音与文字转换",
"description": "文字转语音和语音转文字操作。"
},
{
"name": "应用配置",
"description": "获取应用设置和信息的操作。"
},
{
"name": "标注管理",
"description": "与管理标注直接回复相关的操作。"
},
{
"name": "人工介入",
"description": "暂停等待人工输入的工作流恢复操作。"
}
]
}
Reference in New Issue View Git Blame Copy Permalink