mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-07-24 04:25:07 -04:00
Riskey
32e1b169da
* 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.
75 lines
7.3 KiB
Plaintext
75 lines
7.3 KiB
Plaintext
---
|
||
title: Workflow アプリ API
|
||
sidebarTitle: Workflow
|
||
description: ワークフロー実行、実行制御とストリーミング、人間の入力による一時停止、実行履歴を扱う Workflow アプリ向けの API
|
||
---
|
||
|
||
> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/api-reference/guides/workflow) を参照してください。
|
||
|
||
[Workflow アプリ](/ja/cloud/use-dify/build/workflow-chatflow) は `workflow` モードで動作します。呼び出しごとに公開済みのワークフローを 1 回実行し、その出力を返します。呼び出し間で会話状態を保持しないため、各実行は独立しています。
|
||
|
||
<Info>
|
||
認証、ベース URL、エンドユーザーごとにデータを区分する `user` フィールドについては、[クイックスタート](/ja/api-reference/guides/get-started) と [エンドユーザーの識別](/ja/api-reference/guides/end-user-identity) を参照してください。
|
||
</Info>
|
||
|
||
## ワークフローの実行
|
||
|
||
- **[ワークフローを実行](/ja/api-reference/workflow-runs/run-workflow)**：指定した入力変数で、アプリの現在公開中のワークフローを実行します。
|
||
|
||
ストリーミングモードでは、ノードの実行に合わせてイベントをリアルタイムに受け取れます。ブロッキングモードでは、実行が完了してから結果を返します。
|
||
- **[ID でワークフローを実行](/ja/api-reference/workflow-runs/run-workflow-by-id)**：特定の公開バージョンを実行します。`workflow_id` は、以前の実行レスポンスや実行詳細の取得結果にあります。
|
||
|
||
## 実行の追跡と制御
|
||
|
||
どちらのモードでも、レスポンスには 2 つの ID が含まれます。`task_id` は実行中のタスクを制御し、`workflow_run_id` は実行後に保存される記録を識別します。
|
||
|
||
- **[ワークフロータスクを停止](/ja/api-reference/workflow-runs/stop-workflow-task)**：`task_id` を指定して実行中のタスクを取り消します。ストリーミングモードでのみ有効です。ブロッキングモードでは、レスポンスが返る時点で実行が完了しているため取り消せません。
|
||
- **[ワークフローイベントをストリーム](/ja/api-reference/workflow-runs/stream-workflow-events)**：接続の切断後や一時停止後に、`workflow_run_id` からイベントストリームを再開します。
|
||
|
||
`include_state_snapshot=true` を指定すると、実行済みノードの状態を先に再生します。`continue_on_pause=true` を指定すると、複数回の人間の入力による一時停止をまたいでストリームを維持できます。
|
||
|
||
## 人間の入力による一時停止
|
||
|
||
配信方法に WebApp を指定した [人間の入力](/ja/cloud/use-dify/nodes/human-input) ノードに実行が到達したら、API で一時停止を完了させます。
|
||
|
||
<Steps>
|
||
<Step title="一時停止の検知">
|
||
実行のイベントストリームが `form_token` と実行の `workflow_run_id` を含む `human_input_required` を発行します。その後、ストリームは `workflow_paused` イベントで終了します。
|
||
</Step>
|
||
<Step title="フォームの取得">
|
||
`form_token` を使い、[人間の入力フォームを取得](/ja/api-reference/human-input/get-human-input-form) でフォームの内容を読み込みます。
|
||
</Step>
|
||
<Step title="回答の送信">
|
||
[人間の入力フォームを送信](/ja/api-reference/human-input/submit-human-input-form) で受信者の入力内容を送信します。送信すると実行が再開します。
|
||
</Step>
|
||
<Step title="ストリームの再開">
|
||
一時停止したストリームの `workflow_run_id` を使い、[ワークフローイベントをストリーム](/ja/api-reference/workflow-runs/stream-workflow-events) で新しいストリームを開きます。実行完了までの残りのイベントを追跡します。
|
||
</Step>
|
||
</Steps>
|
||
|
||
ファイルを添付した送信と完全なイベントシーケンスについては、[人間の入力フロー](/ja/api-reference/guides/human-input-flow) ガイドを参照してください。
|
||
|
||
## 実行履歴の確認
|
||
|
||
- **[ワークフロー実行詳細を取得](/ja/api-reference/workflow-runs/get-workflow-run-detail)**：指定した `workflow_run_id` の実行ステータスと出力を返します。
|
||
- **[ワークフローログ一覧を取得](/ja/api-reference/workflow-runs/list-workflow-logs)**：ステータス、token 使用量、ステップ数、所要時間を含む実行単位のサマリーを返します。ノード単位の実行ログではありません。キーワード、ステータス、期間、実行を開始したユーザーで絞り込めます。
|
||
|
||
ノード単位のイベントが必要な場合は、ログではなく実行自体をストリームします。新しく開始する実行は、[ワークフローを実行](/ja/api-reference/workflow-runs/run-workflow) をストリーミングモードで呼び出します。進行中の実行には、[ワークフローイベントをストリーム](/ja/api-reference/workflow-runs/stream-workflow-events) を使用します。
|
||
|
||
## ファイルの操作
|
||
|
||
- **[ファイルをアップロード](/ja/api-reference/files/upload-file)**：画像、ドキュメント、音声、動画ファイルをアップロードします。ワークフローの実行時に、ファイル型の入力変数へ返された `id` を `upload_file_id` として渡します。ファイルはアップロードしたエンドユーザーのみが利用できます。
|
||
- **[エンドユーザー取得](/ja/api-reference/end-users/get-end-user-info)**：エンドユーザー ID（ファイルアップロードのレスポンスにある `created_by` など）から、そのユーザーの詳細を取得します。
|
||
|
||
## 音声とテキストの相互変換
|
||
|
||
- **[音声をテキストに変換](/ja/api-reference/audio/convert-audio-to-text)**：アップロードされた音声ファイル（MP3、M4A、WAV、AMR、MPGA のいずれか、最大 30 MB）を文字起こしします。エンドユーザーは入力値をタイピングの代わりに音声で入力できます。
|
||
- **[テキストを音声に変換](/ja/api-reference/audio/convert-text-to-audio)**：ワークフローのテキスト出力を音声として合成します。
|
||
|
||
## アプリ情報と設定の取得
|
||
|
||
- **[アプリケーションの基本情報を取得](/ja/api-reference/applications/get-app-info)**：アプリの名前、説明、タグ、モードを返します。
|
||
- **[アプリケーションのパラメータ情報を取得](/ja/api-reference/applications/get-app-parameters)**：呼び出し時に `inputs` で送るフィールド（名前、型、デフォルト値）と、アプリの機能スイッチを返します。リクエストやクライアント UI を構築する際の基礎になります。
|
||
- **[アプリケーションのメタ情報を取得](/ja/api-reference/applications/get-app-meta)**：ツールアイコンなどの設定メタデータを返します。
|
||
- **[アプリの WebApp 設定を取得](/ja/api-reference/applications/get-app-webapp-settings)**：WebApp のサイト設定、テーマ、カスタマイズ項目を返します。
|