centersl/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-03-27 13:28:32 +07:00
Code Issues Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
Alter-xyz
2025-05-12 02:19:57 +08:00
parent 26aa7cfef3
commit d0d81e0276
13 changed files with 10162 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1192
api_access/chat.en.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

980
api_access/chat.ja.mdx Normal file
View File

@@ -0,0 +1,980 @@
---
title: チャットアプリAPI
---
チャットアプリケーションはセッションの持続性をサポートしており、以前のチャット履歴を応答のコンテキストとして使用できます。これは、チャットボットやカスタマーサービス AI などに適用できます。
### ベース URL
```text
https://api.dify.ai/v1
```
### 認証
サービス API は`API-Key`認証を使用します。
<i>
**APIキーの漏洩を防ぐため、APIキーはクライアント側で共有または保存せず、サーバー側で保存することを強くお勧めします。**
</i>
すべての API リクエストにおいて、以下のように`Authorization`HTTP ヘッダーに API キーを含めてください：
```
Authorization: Bearer {API_KEY}
```
---
## チャットメッセージを送信 `POST /chat-messages`
チャットアプリケーションにリクエストを送信します。
### リクエストボディ
- `query` (string, required): ユーザー入力/質問内容
- `inputs` (object): アプリで定義されたさまざまな変数値の入力を許可します。`inputs`パラメータには複数のキー/値ペアが含まれ、各キーは特定の変数に対応し、各値はその変数の特定の値です。デフォルトは`{}`
- `response_mode` (string, required): 応答の返却モードを指定します。サポートされているモード：
- `streaming` ストリーミングモード（推奨）、SSE（[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)）を通じてタイプライターのような出力を実装します。
- `blocking` ブロッキングモード、実行完了後に結果を返します。（プロセスが長い場合、リクエストが中断される可能性があります）
Cloudflare の制限により、100 秒後に応答がない場合、リクエストは中断されます。
<i>
注：エージェントアシスタントモードではブロッキングモードはサポートされていません
</i>
- `user` (string, required): ユーザー識別子、エンドユーザーのアイデンティティを定義するために使用されます。アプリケーション内で開発者によって一意に定義される必要があります。
- `conversation_id` (string): 会話 ID、以前のチャット記録に基づいて会話を続けるには、前のメッセージの conversation_id を渡す必要があります。
- `files` (array[object]): ファイルリスト、テキストの理解と質問への回答を組み合わせたファイル（画像）の入力に適しており、モデルがビジョン機能をサポートしている場合にのみ利用可能です。
- `type` (string): サポートされているタイプ：`image`（現在は画像タイプのみサポート）
- `transfer_method` (string): 転送方法、画像 URL の場合は`remote_url` / ファイルアップロードの場合は`local_file`
- `url` (string): 画像 URL（転送方法が`remote_url`の場合）
- `upload_file_id` (string): アップロードされたファイル ID、事前にファイルアップロード API を通じて取得する必要があります（転送方法が`local_file`の場合）
- `auto_generate_name` (bool): タイトルを自動生成します。デフォルトは`true`です。
### 応答
`response_mode`がブロッキングの場合、`ChatCompletionResponse`オブジェクトを返します。
`response_mode`がストリーミングの場合、`ChunkChatCompletionResponse`ストリームを返します。
#### ChatCompletionResponse
完全なアプリ結果を返します。`Content-Type`は`application/json`です。
- `event` (string): イベントタイプ、固定で `message`
- `task_id` (string): タスク ID、リクエスト追跡と以下の Stop Generate API に使用
- `id` (string): ユニーク ID
- `message_id` (string): 一意のメッセージ ID
- `conversation_id` (string): 会話 ID
- `mode` (string): アプリモード、`chat`として固定
- `answer` (string): 完全な応答内容
- `metadata` (object): メタデータ
- `usage` (object): モデル使用情報 (詳細は Usage オブジェクトを参照)
- `retriever_resources` (array[object]): 引用と帰属リスト (詳細は RetrieverResource オブジェクトを参照)
- `created_at` (int): メッセージ作成タイムスタンプ、例：1705395332
#### ChunkChatCompletionResponse
アプリによって出力されたストリームチャンクを返します。`Content-Type`は`text/event-stream`です。
各ストリーミングチャンクは`data:`で始まり、2 つの改行文字`\n\n`で区切られます。以下のように表示されます：
<CodeGroup>
```streaming 応答
data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n
```
</CodeGroup>
ストリーミングチャンクの構造は`event`に応じて異なります：
- `event: message`: LLMはテキストチャンクイベントを返します。つまり、完全なテキストがチャンク形式で出力されます。
- `task_id` (string): タスクID
- `message_id` (string): 一意のメッセージID
- `conversation_id` (string): 会話ID
- `answer` (string): LLMが返したテキストチャンク内容
- `created_at` (int): 作成タイムスタンプ
- `event: agent_message`: LLMはテキストチャンクイベントを返します（エージェントモードでのみサポート）。
- `task_id` (string): タスクID
- `message_id` (string): 一意のメッセージID
- `conversation_id` (string): 会話ID
- `answer` (string): LLMが返したテキストチャンク内容
- `created_at` (int): 作成タイムスタンプ
- `event: tts_message`: TTSオーディオストリームイベント。内容はMp3形式のオーディオブロックで、base64文字列としてエンコードされています。（自動再生が有効な場合のみ利用可能）
- `task_id` (string): タスクID
- `message_id` (string): 一意のメッセージID
- `audio` (string): base64エンコードされたオーディオコンテンツ
- `created_at` (int): 作成タイムスタンプ
- `event: tts_message_end`: TTSオーディオストリーム終了イベント。
- `task_id` (string): タスクID
- `message_id` (string): 一意のメッセージID
- `audio` (string): 空の文字列
- `created_at` (int): 作成タイムスタンプ
- `event: agent_thought`: エージェントの思考（エージェントモードでのみサポート）。
- `id` (string): エージェント思考ID
- `task_id` (string): タスクID
- `message_id` (string): 一意のメッセージID
- `position` (int): 現在のエージェント思考の位置
- `thought` (string): LLMが考えていること
- `observation` (string): ツール呼び出しからの応答
- `tool` (string): 呼び出されたツールのリスト（;で区切られる）
- `tool_input` (string): ツールの入力（JSON形式）
- `created_at` (int): 作成タイムスタンプ
- `message_files` (array[string]): この思考ステップに関連付けられたファイルIDのリスト。各IDは、対応する `message_file` イベントで詳細が提供されるファイルを参照します。
- `conversation_id` (string): 会話ID
- `event: message_file`: メッセージファイルイベント。ツールによって新しいファイルが作成されました。
- `id` (string): ファイル一意ID
- `type` (string): ファイルタイプ（現在は"image"のみ）
- `belongs_to` (string): 所属（ここでは'assistant'のみ）
- `url` (string): ファイルのリモートURL
- `conversation_id` (string): 会話ID
- `event: message_end`: メッセージ終了イベント。
- `task_id` (string): タスクID
- `message_id` (string): 一意のメッセージID
- `conversation_id` (string): 会話ID
- `metadata` (object): メタデータ
- `usage` (object): モデル使用情報
- `retriever_resources` (array[object]): 引用と帰属リスト
- `event: message_replace`: メッセージ内容置換イベント。
- `task_id` (string): タスクID
- `message_id` (string): 一意のメッセージID
- `conversation_id` (string): 会話ID
- `answer` (string): 置換内容
- `created_at` (int): 作成タイムスタンプ
- `event: error`: エラーイベント。
- `task_id` (string): タスクID
- `message_id` (string): 一意のメッセージID
- `status` (int): HTTPステータスコード
- `code` (string): エラーコード
- `message` (string): エラーメッセージ
- `event: ping`: 接続維持のためのpingイベント（10秒ごと）。
### エラー
- 404, 会話が存在しません
- 400, `invalid_param`, 異常なパラメータ入力
- 400, `app_unavailable`, アプリ構成が利用できません
- 400, `provider_not_initialize`, 利用可能なモデル資格情報構成がありません
- 400, `provider_quota_exceeded`, モデル呼び出しクォータが不足しています
- 400, `model_currently_not_support`, 現在のモデルは利用できません
- 400, `completion_request_error`, テキスト生成に失敗しました
- 500, 内部サーバーエラー
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/chat-messages' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"inputs": {},
"query": "What are the specs of the iPhone 13 Pro Max?",
"response_mode": "streaming",
"conversation_id": "",
"user": "abc-123",
"files": [
{
"type": "image",
"transfer_method": "remote_url",
"url": "https://cloud.dify.ai/logo/logo-site.png"
}
]
}'
```
</CodeGroup>
<CodeGroup>
```json 応答 (ブロッキングモード)
{
"event": "message",
"task_id": "c3800678-a077-43df-a102-53f23ed20b88",
"id": "9da23599-e713-473b-982c-4328d4f5c78a",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"mode": "chat",
"answer": "iPhone 13 Pro Maxの仕様は次のとおりです:...",
"metadata": {
"usage": {
"prompt_tokens": 1033,
"prompt_unit_price": "0.001",
"prompt_price_unit": "0.001",
"prompt_price": "0.0010330",
"completion_tokens": 128,
"completion_unit_price": "0.002",
"completion_price_unit": "0.001",
"completion_price": "0.0002560",
"total_tokens": 1161,
"total_price": "0.0012890",
"currency": "USD",
"latency": 0.7682376249867957
},
"retriever_resources": [
{
"position": 1,
"dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
"dataset_name": "iPhone",
"document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00",
"document_name": "iPhone List",
"segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a",
"score": 0.98457545,
"content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""
}
]
},
"created_at": 1705407629
}
```
```streaming 応答 (ストリーミングモード - 基本アシスタント)
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " I", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": "'m", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " glad", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " to", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " meet", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " you", "created_at": 1679586595}
data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548}, "retriever_resources": [{"position": 1, "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", "dataset_name": "iPhone", "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", "document_name": "iPhone List", "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", "score": 0.98457545, "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""}]}}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
```streaming 応答 (エージェントアシスタント)
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " I", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": "'m", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " glad", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " to", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " meet", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " you", "created_at": 1679586595}
data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548}, "retriever_resources": [{"position": 1, "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", "dataset_name": "iPhone", "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", "document_name": "iPhone List", "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", "score": 0.98457545, "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""}]}}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
</CodeGroup>
---
## ファイルアップロード `POST /files/upload`
メッセージ送信時に使用するためのファイルをアップロードします（現在は画像のみサポート）。画像とテキストのマルチモーダル理解を可能にします。
png、jpg、jpeg、webp、gif 形式をサポートしています。
アップロードされたファイルは現在のエンドユーザーのみが使用できます。
### リクエストボディ
このインターフェースは`multipart/form-data`リクエストを必要とします。
- `file` (File, required): アップロードするファイル。
- `user` (string, required): ユーザー識別子、開発者のルールで定義され、アプリケーション内で一意でなければなりません。
### 応答
アップロードが成功すると、サーバーはファイルの ID と関連情報を返します。
- `id` (uuid): ID
- `name` (string): ファイル名
- `size` (int): ファイルサイズ（バイト）
- `extension` (string): ファイル拡張子
- `mime_type` (string): ファイルの MIME タイプ
- `created_by` (uuid): エンドユーザー ID
- `created_at` (timestamp): 作成タイムスタンプ、例：1705395332
### エラー
- 400, `no_file_uploaded`, ファイルが提供されなければなりません
- 400, `too_many_files`, 現在は 1 つのファイルのみ受け付けます
- 400, `unsupported_preview`, ファイルはプレビューをサポートしていません
- 400, `unsupported_estimate`, ファイルは推定をサポートしていません
- 413, `file_too_large`, ファイルが大きすぎます
- 415, `unsupported_file_type`, サポートされていない拡張子、現在はドキュメントファイルのみ受け付けます
- 503, `s3_connection_failed`, S3 サービスに接続できません
- 503, `s3_permission_denied`, S3 にファイルをアップロードする権限がありません
- 503, `s3_file_too_large`, ファイルが S3 のサイズ制限を超えています
- 500, 内部サーバーエラー
<CodeGroup>
```bash cURL curl -X POST 'https://api.dify.ai/v1/files/upload' \ --header
'Authorization: Bearer {api_key}' \ --form
'file=@/path/to/your/image.png;type=image/png' \ --form 'user=abc-123' ```
</CodeGroup>
<CodeGroup>
```json 応答
{
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13",
"created_at": 1577836800
}
```
</CodeGroup>
---
## 生成停止 `POST /chat-messages/:task_id/stop`
ストリーミングモードでのみサポートされています。
### パスパラメータ
- `task_id` (string, required): タスク ID、ストリーミングチャンクの返り値から取得できます。
### リクエストボディ
- `user` (string, required): ユーザー識別子、エンドユーザーのアイデンティティを定義するために使用され、メッセージ送信インターフェースで渡されたユーザーと一致している必要があります。
### 応答
- `result` (string): 常に"success"を返します。
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/chat-messages/your_task_id/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json 応答
{
"result": "success"
}
```
</CodeGroup>
---
## メッセージフィードバック `POST /messages/:message_id/feedbacks`
エンドユーザーはフィードバックメッセージを提供でき、アプリケーション開発者が期待される出力を最適化するのに役立ちます。
### パスパラメータ
- `message_id` (string, required): メッセージ ID
### リクエストボディ
- `rating` (string): アップボートは`like`、ダウンボートは`dislike`、アップボートの取り消しは`null`。
- `user` (string, required): ユーザー識別子、開発者のルールで定義され、アプリケーション内で一意でなければなりません。
- `content` (string): メッセージのフィードバックです。
### 応答
- `result` (string): 常に"success"を返します。
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/messages/your_message_id/feedbacks' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"rating": "like",
"user": "abc-123",
"content": "message feedback information"
}'
```
</CodeGroup>
<CodeGroup>
```json 応答
{
"result": "success"
}
```
</CodeGroup>
---
## 次の推奨質問 `GET /messages/{message_id}/suggested`
現在のメッセージに対する次の質問の提案を取得します。
### パスパラメータ
- `message_id` (string, required): メッセージ ID
### クエリパラメータ
- `user` (string, required): ユーザー識別子、エンドユーザーのアイデンティティを定義するために使用され、統計のために使用されます。アプリケーション内で開発者によって一意に定義される必要があります。
<CodeGroup>
```bash cURL curl --location --request GET
'https://api.dify.ai/v1/messages/your_message_id/suggested?user=abc-123' \
--header 'Authorization: Bearer {api_key}' \ --header 'Content-Type:
application/json' ```
</CodeGroup>
<CodeGroup>
```json 応答
{
"result": "success",
"data": [
"a",
"b",
"c"
]
}
```
</CodeGroup>
---
## 会話履歴メッセージを取得 `GET /messages`
スクロールロード形式で過去のチャット記録を返し、最初のページは最新の`{limit}`メッセージを返します。つまり、逆順です。
### クエリパラメータ
- `conversation_id` (string, required): 会話 ID
- `user` (string, required): ユーザー識別子
- `first_id` (string): 現在のページの最初のチャット記録の ID、デフォルトは null です。
- `limit` (int): 1 回のリクエストで返すチャット履歴メッセージの数、デフォルトは 20 です。
### 応答
- `data` (array[object]): メッセージリスト
- `id` (string): メッセージ ID
- `conversation_id` (string): 会話 ID
- `inputs` (object): ユーザー入力パラメータ
- `query` (string): ユーザー入力/質問内容
- `message_files` (array[object]): メッセージファイル
- `id` (string): ID
- `type` (string): ファイルタイプ（例: `image`）
- `url` (string): プレビュー画像 URL
- `belongs_to` (string): 所属（`user` または `assistant`）
- `agent_thoughts` (array[object]): エージェントの思考（基本アシスタントの場合は空）
- `id` (string): エージェント思考 ID
- `message_id` (string): 一意のメッセージ ID
- `position` (int): 現在のエージェント思考の位置
- `thought` (string): LLM が考えていること
- `observation` (string): ツール呼び出しからの応答
- `tool` (string): 呼び出されたツールのリスト（;で区切られる）
- `tool_input` (string): ツールの入力（JSON 形式）
- `created_at` (int): 作成タイムスタンプ
- `message_files` (array[string]): この思考ステップに関連付けられたファイル ID のリスト。
- `answer` (string): 応答メッセージ内容
- `created_at` (timestamp): 作成タイムスタンプ
- `feedback` (object): フィードバック情報
- `rating` (string): `like` / `dislike`
- `retriever_resources` (array[object]): 引用と帰属リスト
- `has_more` (bool): 次のページがあるかどうか
- `limit` (int): 返されたアイテムの数
<CodeGroup>
```bash cURL curl -X GET
'https://api.dify.ai/v1/messages?user=abc-123&conversation_id=your_conversation_id'
\ --header 'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json 応答 (基本アシスタント)
{
"limit": 20,
"has_more": false,
"data": [
{
"id": "a076a87f-31e5-48dc-b452-0061adbbc922",
"conversation_id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce",
"inputs": {
"name": "dify"
},
"query": "iphone 13 pro",
"answer": "iPhone 13 Proは2021年9月24日に発売され、6.1インチのディスプレイと1170 x 2532の解像度を備えています。Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)プロセッサ、6 GBのRAMを搭載し、128 GB、256 GB、512 GB、1 TBのストレージオプションを提供します。カメラは12 MP、バッテリー容量は3095 mAhで、iOS 15を搭載しています。",
"message_files": [],
"feedback": null,
"retriever_resources": [
{
"position": 1,
"dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
"dataset_name": "iPhone",
"document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00",
"document_name": "iPhone List",
"segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a",
"score": 0.98457545,
"content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""
}
],
"agent_thoughts": [],
"created_at": 1705569239
}
]
}
```
```json 応答 (エージェントアシスタント)
{
"limit": 20,
"has_more": false,
"data": [
{
"id": "d35e006c-7c4d-458f-9142-be4930abdf94",
"conversation_id": "957c068b-f258-4f89-ba10-6e8a0361c457",
"inputs": {},
"query": "draw a cat",
"answer": "猫の画像を生成しました。メッセージを確認して画像を表示してください。",
"message_files": [
{
"id": "976990d2-5294-47e6-8f14-7356ba9d2d76",
"type": "image",
"url": "http://127.0.0.1:5001/files/tools/976990d2-5294-47e6-8f14-7356ba9d2d76.png?timestamp=1705988524&nonce=55df3f9f7311a9acd91bf074cd524092&sign=z43nMSO1L2HBvoqADLkRxr7Biz0fkjeDstnJiCK1zh8=",
"belongs_to": "assistant"
}
],
"feedback": null,
"retriever_resources": [],
"created_at": 1705988187,
"agent_thoughts": [
{
"id": "592c84cf-07ee-441c-9dcc-ffc66c033469",
"chain_id": null,
"message_id": "d35e006c-7c4d-458f-9142-be4930abdf94",
"position": 1,
"thought": "",
"tool": "dalle2",
"tool_input": "{\"dalle2\": {\"prompt\": \"cat\"}}",
"created_at": 1705988186,
"observation": "画像はすでに作成され、ユーザーに送信されました。今すぐユーザーに確認するように伝えてください。",
"files": [
"976990d2-5294-47e6-8f14-7356ba9d2d76"
]
},
{
"id": "73ead60d-2370-4780-b5ed-532d2762b0e5",
"chain_id": null,
"message_id": "d35e006c-7c4d-458f-9142-be4930abdf94",
"position": 2,
"thought": "猫の画像を生成しました。メッセージを確認して画像を表示してください。",
"tool": "",
"tool_input": "",
"created_at": 1705988199,
"observation": "",
"files": []
}
]
}
]
}
```
</CodeGroup>
---
## 会話を取得 `GET /conversations`
現在のユーザーの会話リストを取得し、デフォルトで最新の 20 件を返します。
### クエリパラメータ
- `user` (string, required): ユーザー識別子
- `last_id` (string, optional): 現在のページの最後のレコードの ID、デフォルトは null です。
- `limit` (int, optional): 1 回のリクエストで返すレコードの数、デフォルトは最新の 20 件です。最大 100、最小 1。
- `sort_by` (string, optional): ソートフィールド、デフォルト：`-updated_at`（更新時間で降順にソート）。利用可能な値：`created_at`, `-created_at`, `updated_at`, `-updated_at`。フィールドの前の記号は順序または逆順を表し、`-`は逆順を表します。
### 応答
- `data` (array[object]): 会話のリスト
- `id` (string): 会話 ID
- `name` (string): 会話名
- `inputs` (object): ユーザー入力パラメータ
- `introduction` (string): 紹介
- `created_at` (timestamp): 作成タイムスタンプ
- `updated_at` (timestamp): 更新タイムスタンプ
- `has_more` (bool): さらにレコードがあるか
- `limit` (int): 返されたエントリの数
<CodeGroup>
```bash cURL curl -X GET
'https://api.dify.ai/v1/conversations?user=abc-123&last_id=&limit=20' \
--header 'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json 応答
{
"limit": 20,
"has_more": false,
"data": [
{
"id": "10799fb8-64f7-4296-bbf7-b42bfbe0ae54",
"name": "新しいチャット",
"inputs": {
"book": "book",
"myName": "Lucy"
},
"status": "normal",
"created_at": 1679667915,
"updated_at": 1679667915
},
{
"id": "hSIhXBhNe8X1d8Et"
// ...
}
]
}
```
</CodeGroup>
---
## 会話を削除 `DELETE /conversations/:conversation_id`
会話を削除します。
### パスパラメータ
- `conversation_id` (string, required): 会話 ID
### リクエストボディ
- `user` (string, required): ユーザー識別子、開発者によって定義され、アプリケーション内で一意である必要があります。
### 応答
- `204 No Content`: 成功を示す HTTP ステータス。
<CodeGroup>
```bash cURL
curl -X DELETE 'https://api.dify.ai/v1/conversations/your_conversation_id' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>```text 応答 204 No Content ```</CodeGroup>
---
## 会話の名前を変更 `POST /conversations/:conversation_id/name`
セッションの名前を変更します。セッション名は、複数のセッションをサポートするクライアントでの表示に使用されます。
### パスパラメータ
- `conversation_id` (string, required): 会話 ID
### リクエストボディ
- `name` (string, optional): 会話の名前。このパラメータは、`auto_generate`が`true`に設定されている場合、省略できます。
- `auto_generate` (bool, optional): タイトルを自動生成します。デフォルトは`false`です。
- `user` (string, required): ユーザー識別子、開発者によって定義され、アプリケーション内で一意である必要があります。
### 応答
- `id` (string): 会話 ID
- `name` (string): 会話名
- `inputs` (object): ユーザー入力パラメータ
- `status` (string): 会話状態
- `introduction` (string): 紹介
- `created_at` (timestamp): 作成タイムスタンプ
- `updated_at` (timestamp): 更新タイムスタンプ
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/conversations/your_conversation_id/name' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "新しい会話名",
"auto_generate": false,
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json 応答
{
"id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce",
"name": "Chat vs AI",
"inputs": {},
"introduction": "",
"created_at": 1705569238,
"updated_at": 1705569238
}
```
</CodeGroup>
---
## 会話変数の取得 `GET /conversations/:conversation_id/variables`
特定の会話から変数を取得します。このエンドポイントは、会話中に取得された構造化データを抽出するのに役立ちます。
### パスパラメータ
- `conversation_id` (string, required): 変数を取得する会話の ID。
### クエリパラメータ
- `user` (string, required): ユーザー識別子。開発者によって定義されたルールに従い、アプリケーション内で一意である必要があります。
- `last_id` (string, optional): 現在のページの最後のレコードの ID、デフォルトは null です。
- `limit` (int, optional): 1 回のリクエストで返すレコードの数、デフォルトは最新の 20 件です。最大 100、最小 1。
### 応答
- `limit` (int): ページごとのアイテム数
- `has_more` (bool): さらにアイテムがあるかどうか
- `data` (array[object]): 変数のリスト
- `id` (string): 変数 ID
- `name` (string): 変数名
- `value_type` (string): 変数タイプ（文字列、数値、真偽値など）
- `value` (string): 変数値
- `description` (string): 変数の説明
- `created_at` (int): 作成タイムスタンプ
- `updated_at` (int): 最終更新タイムスタンプ
### エラー
- 404, `conversation_not_exists`, 会話が見つかりません
<CodeGroup>
```bash cURL (全変数) curl -X GET
'https://api.dify.ai/v1/conversations/your_conversation_id/variables?user=abc-123'
\ --header 'Authorization: Bearer {api_key}' ``` ```bash cURL
(変数名でフィルタ) curl -X GET
'https://api.dify.ai/v1/conversations/your_conversation_id/variables?user=abc-123&variable_name=customer_name'
\ --header 'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json 応答
{
"limit": 100,
"has_more": false,
"data": [
{
"id": "variable-uuid-1",
"name": "customer_name",
"value_type": "string",
"value": "John Doe",
"description": "会話から抽出された顧客名",
"created_at": 1650000000000,
"updated_at": 1650000000000
},
{
"id": "variable-uuid-2",
"name": "order_details",
"value_type": "json",
"value": "{\"product\":\"Widget\",\"quantity\":5,\"price\":19.99}",
"description": "顧客の注文詳細",
"created_at": 1650000000000,
"updated_at": 1650000000000
}
]
}
```
</CodeGroup>
---
## 音声からテキストへ `POST /audio-to-text`
このエンドポイントは`multipart/form-data`リクエストを必要とします。
### リクエストボディ
- `file` (file, required): オーディオファイル。サポートされている形式：`['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']`。ファイルサイズ制限：15MB。
- `user` (string, required): ユーザー識別子、開発者のルールで定義され、アプリケーション内で一意でなければなりません。
### 応答
- `text` (string): 出力テキスト
<CodeGroup>
```bash cURL curl -X POST 'https://api.dify.ai/v1/audio-to-text' \ --header
'Authorization: Bearer {api_key}' \ --form
'file=@/path/to/your/audio.mp3;type=audio/mp3' \ --form 'user=abc-123' ```
</CodeGroup>
<CodeGroup>
```json 応答
{
"text": "変換されたテキストがここに入ります。"
}
```
</CodeGroup>
---
## テキストから音声へ `POST /text-to-audio`
テキストを音声に変換します。
### リクエストボディ
- `message_id` (string, optional): Dify によって生成されたテキストメッセージの場合、生成されたメッセージ ID を直接渡します。バックエンドはメッセージ ID を使用して対応するコンテンツを検索し、音声情報を直接合成します。`message_id`と`text`が同時に提供される場合、`message_id`が優先されます。
- `text` (string, optional): 音声生成コンテンツ。`message_id` がない場合は必須です。
- `user` (string, required): ユーザー識別子、開発者によって定義され、アプリ内で一意である必要があります。
### 応答
成功すると、レスポンスボディは `audio/wav` 形式の音声データを含みます。
<CodeGroup>
```bash cURL curl --location --request POST
'https://api.dify.ai/v1/text-to-audio' \ --header 'Authorization: Bearer{' '}
{api_key}' \ --form 'text=Hello Dify' \ --form 'user=abc-123' # --form
'message_id=your_message_id' # message_id を使用する場合 ```
</CodeGroup>
<CodeGroup>```http Headers Content-Type: audio/wav ```</CodeGroup>
---
## アプリケーションの基本情報を取得 `GET /info`
このアプリケーションの基本情報を取得するために使用されます。
### 応答
- `name` (string): アプリケーションの名前
- `description` (string): アプリケーションの説明
- `tags` (array[string]): アプリケーションのタグ
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/info' \ -H 'Authorization:
Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json 応答
{
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}
```
</CodeGroup>
---
## アプリケーションのパラメータ情報を取得 `GET /parameters`
ページに入る際に、機能、入力パラメータ名、タイプ、デフォルト値などの情報を取得するために使用されます。
### 応答
- `opening_statement` (string): 開始文
- `suggested_questions` (array[string]): 開始時の推奨質問のリスト
- `suggested_questions_after_answer` (object): 答えを有効にした後の質問を提案します。
- `enabled` (bool): 有効かどうか
- `speech_to_text` (object): 音声からテキストへ
- `enabled` (bool): 有効かどうか
- `retriever_resource` (object): 引用と帰属
- `enabled` (bool): 有効かどうか
- `annotation_reply` (object): 注釈返信
- `enabled` (bool): 有効かどうか
- `user_input_form` (array[object]): ユーザー入力フォームの構成
- `text-input` (object): テキスト入力コントロール
- `label` (string): 変数表示ラベル名
- `variable` (string): 変数 ID
- `required` (bool): 必須かどうか
- `default` (string): デフォルト値
- `paragraph` (object): 段落テキスト入力コントロール
- `label` (string): 変数表示ラベル名
- `variable` (string): 変数 ID
- `required` (bool): 必須かどうか
- `default` (string): デフォルト値
- `select` (object): ドロップダウンコントロール
- `label` (string): 変数表示ラベル名
- `variable` (string): 変数 ID
- `required` (bool): 必須かどうか
- `default` (string): デフォルト値
- `options` (array[string]): オプション値
- `file_upload` (object): ファイルアップロード構成
- `image` (object): 画像設定。現在サポートされている画像タイプ：`png`, `jpg`, `jpeg`, `webp`, `gif`
- `enabled` (bool): 有効かどうか
- `number_limits` (int): 画像数の制限、デフォルトは 3
- `transfer_methods` (array[string]): 転送方法のリスト（`remote_url`, `local_file`）。いずれかを選択する必要があります。
- `system_parameters` (object): システムパラメータ
- `file_size_limit` (int): ドキュメントアップロードサイズ制限（MB）
- `image_file_size_limit` (int): 画像ファイルアップロードサイズ制限（MB）
- `audio_file_size_limit` (int): オーディオファイルアップロードサイズ制限（MB）
- `video_file_size_limit` (int): ビデオファイルアップロードサイズ制限（MB）
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/parameters' \ --header
'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json 応答
{
"opening_statement": "こんにちは！",
"suggested_questions_after_answer": {
"enabled": true
},
"speech_to_text": {
"enabled": true
},
"retriever_resource": {
"enabled": true
},
"annotation_reply": {
"enabled": true
},
"user_input_form": [
{
"paragraph": {
"label": "クエリ",
"variable": "query",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": false,
"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
}
}
```
</CodeGroup>
---
## アプリケーションのメタ情報を取得 `GET /meta`
このアプリケーションのツールのアイコンを取得するために使用されます。
### 応答
- `tool_icons` (object): ツールのアイコン。キーはツール名です。
- `[tool_name]` (string | object): アイコンの定義。
- 文字列の場合: アイコンの URL。
- オブジェクトの場合:
- `background` (string): 背景色 (16 進数形式)。
- `content` (string): 絵文字。
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/meta' \ -H 'Authorization:
Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json 応答
{
"tool_icons": {
"dalle2": "https://cloud.dify.ai/console/api/workspaces/current/tool-provider/builtin/dalle/icon",
"api_tool": {
"background": "#252525",
"content": "\ud83d\ude01"
}
}
}
```
</CodeGroup>

1025
api_access/chat.zh.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

1147
api_access/chatflow.en.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

1004
api_access/chatflow.ja.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

1154
api_access/chatflow.zh.mdx Executable file
View File

File diff suppressed because it is too large Load Diff

495
api_access/completion.en.mdx Executable file
View File

@@ -0,0 +1,495 @@
---
title: Completion App API
---
The text generation application offers non-session support and is ideal for translation, article writing, summarization AI, and more.
### Base URL
```text
https://api.dify.ai/v1
```
### Authentication
The Service API uses `API-Key` authentication.
<i>
**Strongly recommend storing your API Key on the server-side, not shared or
stored on the client-side, to avoid possible API-Key leakage that can lead
to serious consequences.**
</i>
For all API requests, include your API Key in the `Authorization` HTTP Header, as shown below:
```http
Authorization: Bearer {API_KEY}
```
---
## POST /completion-messages
Create Completion Message
Send a request to the text generation application.
### Request Body
- `inputs` (object): Allows the entry of various variable values defined by the App.
The `inputs` parameter contains multiple key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable.
The text generation application requires at least one key/value pair to be inputted.
- `query` (string, Required): The input text, the content to be processed.
- `response_mode` (string): The mode of response return, supporting:
- `streaming`: Streaming mode (recommended), implements a typewriter-like output through SSE ([Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)).
- `blocking`: Blocking mode, returns result after execution is complete. (Requests may be interrupted if the process is long)
<i>
Due to Cloudflare restrictions, the request will be interrupted
without a return after 100 seconds.
</i>
- `user` (string): User identifier, used to define the identity of the end-user for retrieval and statistics. Should be uniquely defined by the developer within the application.
- `files` (array[object]): File list, suitable for inputting files (images) combined with text understanding and answering questions, available only when the model supports Vision capability.
- `type` (string): Supported type: `image` (currently only supports image type).
- `transfer_method` (string): Transfer method, `remote_url` for image URL / `local_file` for file upload.
- `url` (string): Image URL (when the transfer method is `remote_url`).
- `upload_file_id` (string): Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`).
### Response
When `response_mode` is `blocking`, return a CompletionResponse object.
When `response_mode` is `streaming`, return a ChunkCompletionResponse stream.
#### ChatCompletionResponse
Returns the complete App result, `Content-Type` is `application/json`.
- `message_id` (string): Unique message ID.
- `mode` (string): App mode, fixed as `completion`.
- `answer` (string): Complete response content.
- `metadata` (object): Metadata.
- `usage` (Usage): Model usage information.
- `retriever_resources` (array[RetrieverResource]): Citation and Attribution List.
- `created_at` (int): Message creation timestamp, e.g., 1705395332.
#### ChunkChatCompletionResponse
Returns the stream chunks outputted by the App, `Content-Type` is `text/event-stream`.
Each streaming chunk starts with `data:`, separated by two newline characters `\n\n`, as shown below:
```streaming Response
data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n
```
The structure of the streaming chunks varies depending on the `event`:
- `event: message`: LLM returns text chunk event, i.e., the complete text is output in a chunked fashion.
- `task_id` (string): Task ID, used for request tracking and the below Stop Generate API.
- `message_id` (string): Unique message ID.
- `answer` (string): LLM returned text chunk content.
- `created_at` (int): Creation timestamp, e.g., 1705395332.
- `event: message_end`: Message end event, receiving this event means streaming has ended.
- `task_id` (string): Task ID, used for request tracking and the below Stop Generate API.
- `message_id` (string): Unique message ID.
- `metadata` (object): Metadata.
- `usage` (Usage): Model usage information.
- `retriever_resources` (array[RetrieverResource]): Citation and Attribution List.
- `event: tts_message`: TTS audio stream event, that is, speech synthesis output. The content is an audio block in Mp3 format, encoded as a base64 string. When playing, simply decode the base64 and feed it into the player. (This message is available only when auto-play is enabled).
- `task_id` (string): Task ID, used for request tracking and the stop response interface below.
- `message_id` (string): Unique message ID.
- `audio` (string): The audio after speech synthesis, encoded in base64 text content, when playing, simply decode the base64 and feed it into the player.
- `created_at` (int): Creation timestamp, e.g.: 1705395332.
- `event: tts_message_end`: TTS audio stream end event, receiving this event indicates the end of the audio stream.
- `task_id` (string): Task ID, used for request tracking and the stop response interface below.
- `message_id` (string): Unique message ID.
- `audio` (string): The end event has no audio, so this is an empty string.
- `created_at` (int): Creation timestamp, e.g.: 1705395332.
- `event: message_replace`: Message content replacement event.
When output content moderation is enabled, if the content is flagged, then the message content will be replaced with a preset reply through this event.
- `task_id` (string): Task ID, used for request tracking and the below Stop Generate API.
- `message_id` (string): Unique message ID.
- `answer` (string): Replacement content (directly replaces all LLM reply text).
- `created_at` (int): Creation timestamp, e.g., 1705395332.
- `event: error`: Exceptions that occur during the streaming process will be output in the form of stream events, and reception of an error event will end the stream.
- `task_id` (string): Task ID, used for request tracking and the below Stop Generate API.
- `message_id` (string): Unique message ID.
- `status` (int): HTTP status code.
- `code` (string): Error code.
- `message` (string): Error message.
- `event: ping`: Ping event every 10 seconds to keep the connection alive.
### Errors
- 404, Conversation does not exists
- 400, `invalid_param`, abnormal parameter input
- 400, `app_unavailable`, App configuration unavailable
- 400, `provider_not_initialize`, no available model credential configuration
- 400, `provider_quota_exceeded`, model invocation quota insufficient
- 400, `model_currently_not_support`, current model unavailable
- 400, `completion_request_error`, text generation failed
- 500, internal server error
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/completion-messages' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"inputs": {"query": "Hello, world!"},
"response_mode": "streaming",
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Blocking Mode Response
{
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"mode": "completion",
"answer": "Hello World!...",
"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
}
},
"created_at": 1705407629
}
```
```streaming Streaming Mode Response
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": "'m", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " glad", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " to", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " meet", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " you", "created_at": 1679586595}
data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548}}}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
</CodeGroup>
---
## POST /files/upload
File Upload
Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text.
Supports png, jpg, jpeg, webp, gif formats.
Uploaded files are for use by the current end-user only.
### Request Body
This interface requires a `multipart/form-data` request.
- `file` (File, Required): The file to be uploaded.
- `user` (string, Required): User identifier, defined by the developer's rules, must be unique within the application.
### Response
After a successful upload, the server will return the file's ID and related information.
- `id` (uuid): ID.
- `name` (string): File name.
- `size` (int): File size (bytes).
- `extension` (string): File extension.
- `mime_type` (string): File mime-type.
- `created_by` (uuid): End-user ID.
- `created_at` (timestamp): Creation timestamp, e.g., 1705395332.
### Errors
- 400, `no_file_uploaded`, a file must be provided.
- 400, `too_many_files`, currently only one file is accepted.
- 400, `unsupported_preview`, the file does not support preview.
- 400, `unsupported_estimate`, the file does not support estimation.
- 413, `file_too_large`, the file is too large.
- 415, `unsupported_file_type`, unsupported extension, currently only document files are accepted.
- 503, `s3_connection_failed`, unable to connect to S3 service.
- 503, `s3_permission_denied`, no permission to upload files to S3.
- 503, `s3_file_too_large`, file exceeds S3 size limit.
- 500, internal server error.
<CodeGroup>
```bash cURL curl -X POST 'https://api.dify.ai/v1/files/upload' \ --header
'Authorization: Bearer {api_key}' \ --form
'file=@"/path/to/file";type=image/png' \ --form 'user="abc-123"' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13",
"created_at": 1577836800
}
```
</CodeGroup>
---
## POST /completion-messages/:task_id/stop
Stop Generate
Only supported in streaming mode.
### Path Parameters
- `task_id` (string): Task ID, can be obtained from the streaming chunk return.
### Request Body
- `user` (string, Required): User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface.
### Response
- `result` (string): Always returns "success".
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/completion-messages/:task_id/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## POST /messages/:message_id/feedbacks
Message Feedback
End-users can provide feedback messages, facilitating application developers to optimize expected outputs.
### Path Parameters
- `message_id` (string): Message ID.
### Request Body
- `rating` (string): Upvote as `like`, downvote as `dislike`, revoke upvote as `null`.
- `user` (string): User identifier, defined by the developer's rules, must be unique within the application.
- `content` (string): The specific content of message feedback.
### Response
- `result` (string): Always returns "success".
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/messages/:message_id/feedbacks' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"rating": "like",
"user": "abc-123",
"content": "message feedback information"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## POST /text-to-audio
Text to Audio
Text to speech.
### Request Body
- `message_id` (string): For text messages generated by Dify, simply pass the generated message-id directly. The backend will use the message-id to look up the corresponding content and synthesize the voice information directly. If both `message_id` and `text` are provided simultaneously, the `message_id` is given priority.
- `text` (string): Speech generated content.
- `user` (string): The user identifier, defined by the developer, must ensure uniqueness within the app.
### Response
The response is an audio file stream.
**Headers:**
- `Content-Type`: `audio/wav` (or other audio format depending on system configuration)
<CodeGroup>
```bash cURL
curl -o text-to-audio.mp3 -X POST 'https://api.dify.ai/v1/text-to-audio' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290",
"text": "Hello Dify",
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```text Response Headers Content-Type: audio/wav ``` ```text Response Body
(Binary audio data) ```
</CodeGroup>
---
## GET /info
Get Application Basic Information
Used to get basic information about this application.
### Response
- `name` (string): application name.
- `description` (string): application description.
- `tags` (array[string]): application tags.
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/info' \ -H 'Authorization:
Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}
```
</CodeGroup>
---
## GET /parameters
Get Application Parameters Information
Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values.
### Response
- `opening_statement` (string): Opening statement.
- `suggested_questions` (array[string]): List of suggested questions for the opening.
- `suggested_questions_after_answer` (object): Suggest questions after enabling the answer.
- `enabled` (bool): Whether it is enabled.
- `speech_to_text` (object): Speech to text.
- `enabled` (bool): Whether it is enabled.
- `retriever_resource` (object): Citation and Attribution.
- `enabled` (bool): Whether it is enabled.
- `annotation_reply` (object): Annotation reply.
- `enabled` (bool): Whether it is enabled.
- `user_input_form` (array[object]): User input form configuration.
- `text-input` (object): Text input control.
- `label` (string): Variable display label name.
- `variable` (string): Variable ID.
- `required` (bool): Whether it is required.
- `default` (string): Default value.
- `paragraph` (object): Paragraph text input control.
- `label` (string): Variable display label name.
- `variable` (string): Variable ID.
- `required` (bool): Whether it is required.
- `default` (string): Default value.
- `select` (object): Dropdown control.
- `label` (string): Variable display label name.
- `variable` (string): Variable ID.
- `required` (bool): Whether it is required.
- `default` (string): Default value.
- `options` (array[string]): Option values.
- `file_upload` (object): File upload configuration.
- `image` (object): Image settings. Currently only supports image types: `png`, `jpg`, `jpeg`, `webp`, `gif`.
- `enabled` (bool): Whether it is enabled.
- `number_limits` (int): Image number limit, default is 3.
- `transfer_methods` (array[string]): List of transfer methods, `remote_url`, `local_file`, must choose one.
- `system_parameters` (object): System parameters.
- `file_size_limit` (int): Document upload size limit (MB).
- `image_file_size_limit` (int): Image file upload size limit (MB).
- `audio_file_size_limit` (int): Audio file upload size limit (MB).
- `video_file_size_limit` (int): Video file upload size limit (MB).
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/parameters' \ --header
'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"opening_statement": "Hello!",
"suggested_questions_after_answer": {
"enabled": true
},
"speech_to_text": {
"enabled": true
},
"retriever_resource": {
"enabled": true
},
"annotation_reply": {
"enabled": true
},
"user_input_form": [
{
"paragraph": {
"label": "Query",
"variable": "query",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": false,
"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
}
}
```
</CodeGroup>

496
api_access/completion.ja.mdx Executable file
View File

@@ -0,0 +1,496 @@
---
title: Completion アプリ API
---
テキスト生成アプリケーションはセッションレスをサポートし、翻訳、記事作成、要約 AI 等に最適です。
### ベース URL
```text
https://api.dify.ai/v1
```
### 認証
サービス API は`API-Key`認証を使用します。
**_API キーの漏洩による重大な結果を避けるため、API キーはサーバーサイドに保存し、クライアントサイドでは共有や保存しないことを強く推奨します。_**
すべての API リクエストで、以下のように`Authorization` HTTP ヘッダーに API キーを含めてください：
```text
Authorization: Bearer {API_KEY}
```
---
## 完了メッセージの作成 `POST /completion-messages`
テキスト生成アプリケーションにリクエストを送信します。
### リクエストボディ
- `inputs` (object)
アプリで定義された各種変数値を入力できます。
`inputs`パラメータには複数のキー/値ペアが含まれ、各キーは特定の変数に対応し、各値はその変数の具体的な値となります。
テキスト生成アプリケーションでは、少なくとも 1 つのキー/値ペアの入力が必要です。
- `query` (string) 必須
入力テキスト、処理される内容。
- `response_mode` (string)
レスポンス返却モード、以下をサポート：
- `streaming` ストリーミングモード（推奨）、SSE（[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)）によるタイプライター風の出力を実装。
- `blocking` ブロッキングモード、実行完了後に結果を返却。（処理が長い場合はリクエストが中断される可能性があります）
_Cloudflare の制限により、100 秒後に返却なしで中断されます。_
- `user` (string)
ユーザー識別子、エンドユーザーの身元を定義し、取得や統計に使用します。
アプリケーション内で開発者が一意に定義する必要があります。
- `files` (array[object])
ファイルリスト、モデルが Vision 機能をサポートしている場合のみ、テキスト理解と質問応答を組み合わせたファイル（画像）の入力に適しています。
- `type` (string) サポートされるタイプ：`image`（現在は画像タイプのみサポート）
- `transfer_method` (string) 転送方法、画像 URL の場合は`remote_url` / ファイルアップロードの場合は`local_file`
- `url` (string) 画像 URL（転送方法が`remote_url`の場合）
- `upload_file_id` (string) アップロードされたファイル ID、事前にファイルアップロード API を通じてアップロードする必要があります（転送方法が`local_file`の場合）
### レスポンス
`response_mode`が`blocking`の場合、CompletionResponse オブジェクトを返却します。
`response_mode`が`streaming`の場合、ChunkCompletionResponse ストリームを返却します。
#### ChatCompletionResponse
アプリの完全な結果を返却、`Content-Type`は`application/json`です。
- `message_id` (string) 一意のメッセージ ID
- `mode` (string) アプリモード、固定で`chat`
- `answer` (string) 完全な応答内容
- `metadata` (object) メタデータ
- `usage` (Usage) モデル使用情報
- `retriever_resources` (array[RetrieverResource]) 引用と帰属のリスト
- `created_at` (int) メッセージ作成タイムスタンプ、例：1705395332
#### ChunkChatCompletionResponse
アプリが出力するストリームチャンクを返却、`Content-Type`は`text/event-stream`です。
各ストリーミングチャンクは`data:`で始まり、2 つの改行文字`\n\n`で区切られます：
```streaming
data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n
```
ストリーミングチャンクの構造は`event`によって異なります：
- `event: message` LLM がテキストチャンクを返すイベント、つまり完全なテキストがチャンク形式で出力されます。
- `task_id` (string) タスク ID、リクエストの追跡と以下の生成停止 API に使用
- `message_id` (string) 一意のメッセージ ID
- `answer` (string) LLM が返したテキストチャンクの内容
- `created_at` (int) 作成タイムスタンプ、例：1705395332
- `event: message_end` メッセージ終了イベント、このイベントを受信するとストリーミングが終了したことを意味します。
- `task_id` (string) タスク ID、リクエストの追跡と以下の生成停止 API に使用
- `message_id` (string) 一意のメッセージ ID
- `metadata` (object) メタデータ
- `usage` (Usage) モデル使用情報
- `retriever_resources` (array[RetrieverResource]) 引用と帰属のリスト
- `event: tts_message` TTS 音声ストリームイベント、つまり音声合成出力。内容は Mp3 形式の音声ブロックで、base64 文字列としてエンコードされています。再生時は単に base64 をデコードしてプレーヤーに供給するだけです。（このメッセージは自動再生が有効な場合のみ利用可能）
- `task_id` (string) タスク ID、リクエストの追跡と以下の応答停止インターフェースに使用
- `message_id` (string) 一意のメッセージ ID
- `audio` (string) 音声合成後の音声、base64 テキストコンテンツとしてエンコード、再生時は単に base64 をデコードしてプレーヤーに供給
- `created_at` (int) 作成タイムスタンプ、例：1705395332
- `event: tts_message_end` TTS 音声ストリーム終了イベント、このイベントを受信すると音声ストリームが終了したことを示します。
- `task_id` (string) タスク ID、リクエストの追跡と以下の応答停止インターフェースに使用
- `message_id` (string) 一意のメッセージ ID
- `audio` (string) 終了イベントには音声がないため、空文字列
- `created_at` (int) 作成タイムスタンプ、例：1705395332
- `event: message_replace` メッセージ内容置換イベント。
出力内容のモデレーションが有効な場合、コンテンツがフラグ付けされると、このイベントを通じてメッセージ内容が事前設定された返信に置き換えられます。
- `task_id` (string) タスク ID、リクエストの追跡と以下の生成停止 API に使用
- `message_id` (string) 一意のメッセージ ID
- `answer` (string) 置換内容（LLM の返信テキストすべてを直接置換）
- `created_at` (int) 作成タイムスタンプ、例：1705395332
- `event: error`
ストリーミング処理中に発生した例外は、ストリームイベントの形式で出力され、エラーイベントを受信するとストリームが終了します。
- `task_id` (string) タスク ID、リクエストの追跡と以下の生成停止 API に使用
- `message_id` (string) 一意のメッセージ ID
- `status` (int) HTTP ステータスコード
- `code` (string) エラーコード
- `message` (string) エラーメッセージ
- `event: ping` 接続を維持するため 10 秒ごとの Ping イベント。
### エラー
- 404, 会話が存在しません
- 400, `invalid_param`, パラメータ入力異常
- 400, `app_unavailable`, アプリ設定が利用できません
- 400, `provider_not_initialize`, 利用可能なモデル認証情報設定がありません
- 400, `provider_quota_exceeded`, モデル呼び出しクォータ不足
- 400, `model_currently_not_support`, 現在のモデルは利用できません
- 400, `completion_request_error`, テキスト生成に失敗しました
- 500, 内部サーバーエラー
<CodeGroup>
```bash Request
curl -X POST 'https://api.dify.ai/v1/completion-messages' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"inputs": {"query": "Hello, world!"},
"response_mode": "streaming",
"user": "abc-123"
}'
```
</CodeGroup>
#### ブロッキングモード
<CodeGroup>
```json Response
{
"event": "message",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"mode": "completion",
"answer": "Hello World!...",
"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
}
},
"created_at": 1705407629
}
```
</CodeGroup>
#### ストリーミングモード
<CodeGroup>
```streaming Response
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": "'m", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " glad", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " to", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " meet", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " you", "created_at": 1679586595}
data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548}}}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
</CodeGroup>
---
## ファイルアップロード `POST /files/upload`
メッセージ送信時に使用するファイル（現在は画像のみ対応）をアップロードし、画像とテキストのマルチモーダルな理解を可能にします。
png、jpg、jpeg、webp、gif 形式に対応しています。
_アップロードされたファイルは、現在のエンドユーザーのみが使用できます。_
### リクエストボディ
このインターフェースは`multipart/form-data`リクエストが必要です。
- `file` (File) 必須
アップロードするファイル。
- `user` (string) 必須
開発者のルールで定義されたユーザー識別子。アプリケーション内で一意である必要があります。
### レスポンス
アップロードが成功すると、サーバーはファイルの ID と関連情報を返します。
- `id` (uuid) ID
- `name` (string) ファイル名
- `size` (int) ファイルサイズ（バイト）
- `extension` (string) ファイル拡張子
- `mime_type` (string) ファイルの MIME タイプ
- `created_by` (uuid) エンドユーザー ID
- `created_at` (timestamp) 作成タイムスタンプ、例：1705395332
### エラー
- 400, `no_file_uploaded`, ファイルを提供する必要があります
- 400, `too_many_files`, 現在は 1 つのファイルのみ受け付けています
- 400, `unsupported_preview`, ファイルがプレビューに対応していません
- 400, `unsupported_estimate`, ファイルが推定に対応していません
- 413, `file_too_large`, ファイルが大きすぎます
- 415, `unsupported_file_type`, サポートされていない拡張子です。現在はドキュメントファイルのみ受け付けています
- 503, `s3_connection_failed`, S3 サービスに接続できません
- 503, `s3_permission_denied`, S3 へのファイルアップロード権限がありません
- 503, `s3_file_too_large`, ファイルが S3 のサイズ制限を超えています
- 500, 内部サーバーエラー
<CodeGroup>
```bash Request curl -X POST 'https://api.dify.ai/v1/files/upload' \
--header 'Authorization: Bearer {api_key}' \ --form
'file=@"/path/to/your/image.png";type=image/png' \ --form 'user=abc-123' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13",
"created_at": 1577836800
}
```
</CodeGroup>
---
## 生成の停止 `POST /completion-messages/:task_id/stop`
ストリーミングモードでのみサポートされています。
### パスパラメータ
- `task_id` (string) タスク ID、ストリーミングチャンクの返信から取得可能
### リクエストボディ
- `user` (string) 必須
ユーザー識別子。エンドユーザーの身元を定義するために使用され、メッセージ送信インターフェースで渡されたユーザーと一致する必要があります。
### レスポンス
- `result` (string) 常に"success"を返します
<CodeGroup>
```bash Request
curl -X POST 'https://api.dify.ai/v1/completion-messages/:task_id/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## メッセージフィードバック `POST /messages/:message_id/feedbacks`
エンドユーザーはフィードバックメッセージを提供でき、アプリケーション開発者が期待される出力を最適化するのに役立ちます。
### パスパラメータ
- `message_id` (string)
メッセージ ID
### リクエストボディ
- `rating` (string)
高評価は`like`、低評価は`dislike`、高評価の取り消しは`null`
- `user` (string)
開発者のルールで定義されたユーザー識別子。アプリケーション内で一意である必要があります。
- `content` (string)
メッセージのフィードバックです。
### レスポンス
- `result` (string) 常に"success"を返します
<CodeGroup>
```bash Request
curl -X POST 'https://api.dify.ai/v1/messages/:message_id/feedbacks' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"rating": "like",
"user": "abc-123",
"content": "message feedback information"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## テキストから音声 `POST /text-to-audio`
テキストを音声に変換します。
### リクエストボディ
- `message_id` (str)
Dify が生成したテキストメッセージの場合、生成された message-id を直接渡すだけです。バックエンドは message-id を使用して対応するコンテンツを検索し、音声情報を直接合成します。message_id と text の両方が同時に提供された場合、message_id が優先されます。
- `text` (str)
音声生成コンテンツ。
- `user` (string)
開発者が定義したユーザー識別子。アプリ内で一意性を確保する必要があります。
### レスポンス
レスポンスは音声ファイルです（例: `audio/wav`）。
レスポンスヘッダーの例:
```json
{
"Content-Type": "audio/wav"
}
```
<CodeGroup>
```bash Request
curl -o text-to-audio.mp3 -X POST 'https://api.dify.ai/v1/text-to-audio' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290",
"text": "Hello Dify",
"user": "abc-123"
}'
```
</CodeGroup>
---
## アプリケーションの基本情報を取得 `GET /info`
このアプリケーションの基本情報を取得するために使用されます
### レスポンス
- `name` (string) アプリケーションの名前
- `description` (string) アプリケーションの説明
- `tags` (array[string]) アプリケーションのタグ
<CodeGroup>
```bash Request curl -X GET 'https://api.dify.ai/v1/info' \ -H
'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}
```
</CodeGroup>
---
## アプリケーションのパラメータ情報を取得 `GET /parameters`
ページ開始時に、機能、入力パラメータ名、タイプ、デフォルト値などの情報を取得するために使用されます。
### レスポンス
- `opening_statement` (string) 開始文
- `suggested_questions` (array[string]) 開始時の提案質問リスト
- `suggested_questions_after_answer` (object) 回答後の提案質問を有効にします。
- `enabled` (bool) 有効かどうか
- `speech_to_text` (object) 音声からテキスト
- `enabled` (bool) 有効かどうか
- `retriever_resource` (object) 引用と帰属
- `enabled` (bool) 有効かどうか
- `annotation_reply` (object) 注釈付き返信
- `enabled` (bool) 有効かどうか
- `user_input_form` (array[object]) ユーザー入力フォーム設定
- `text-input` (object) テキスト入力コントロール
- `label` (string) 変数表示ラベル名
- `variable` (string) 変数 ID
- `required` (bool) 必須かどうか
- `default` (string) デフォルト値
- `paragraph` (object) 段落テキスト入力コントロール
- `label` (string) 変数表示ラベル名
- `variable` (string) 変数 ID
- `required` (bool) 必須かどうか
- `default` (string) デフォルト値
- `select` (object) ドロップダウンコントロール
- `label` (string) 変数表示ラベル名
- `variable` (string) 変数 ID
- `required` (bool) 必須かどうか
- `default` (string) デフォルト値
- `options` (array[string]) オプション値
- `file_upload` (object) ファイルアップロード設定
- `image` (object) 画像設定
現在は画像タイプのみ対応：`png`、`jpg`、`jpeg`、`webp`、`gif`
- `enabled` (bool) 有効かどうか
- `number_limits` (int) 画像数制限、デフォルトは 3
- `transfer_methods` (array[string]) 転送方法リスト、remote_url、local_file、いずれかを選択
- `system_parameters` (object) システムパラメータ
- `file_size_limit` (int) ドキュメントアップロードサイズ制限（MB）
- `image_file_size_limit` (int) 画像ファイルアップロードサイズ制限（MB）
- `audio_file_size_limit` (int) 音声ファイルアップロードサイズ制限（MB）
- `video_file_size_limit` (int) 動画ファイルアップロードサイズ制限（MB）
<CodeGroup>
```bash Request curl -X GET 'https://api.dify.ai/v1/parameters' \ --header
'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"opening_statement": "Hello!",
"suggested_questions_after_answer": {
"enabled": true
},
"speech_to_text": {
"enabled": true
},
"retriever_resource": {
"enabled": true
},
"annotation_reply": {
"enabled": true
},
"user_input_form": [
{
"paragraph": {
"label": "Query",
"variable": "query",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": false,
"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
}
}
```
</CodeGroup>

658
api_access/completion.zh.mdx Executable file
View File

@@ -0,0 +1,658 @@
---
title: 文本生成型应用 API
---
文本生成应用无会话支持，适合用于翻译/文章写作/总结 AI 等等。
### 基础 URL
```text
https://api.dify.ai/v1
```
### 鉴权
Dify Service API 使用 `API-Key` 进行鉴权。
_强烈建议开发者把 `API-Key` 放在后端存储，而非分享或者放在客户端存储，以免 `API-Key` 泄露，导致财产损失。_
所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`，如下所示：
```text
Authorization: Bearer {API_KEY}
```
---
## 发送消息
**POST** `/completion-messages`
发送请求给文本生成型应用。
### Request Body
- **`inputs`** (`object`): (选填) 允许传入 App 定义的各变量值。inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。文本生成型应用要求至少传入一组键值对。
- **`query`** (`string`): 必填. 用户输入的文本内容。
- **`response_mode`** (`string`):
- `streaming`: 流式模式（推荐）。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现类似打字机输出方式的流式返回。
- `blocking`: 阻塞模式，等待执行完毕后返回结果。（请求若流程较长可能会被中断）。
_由于 Cloudflare 限制，请求会在 100 秒超时无返回后中断。_
- **`user`** (`string`): 用户标识，用于定义终端用户的身份，方便检索、统计。由开发者定义规则，需保证用户标识在应用内唯一。
- **`files`** (`array[object]`): 上传的文件。
- **`type`** (`string`): 支持类型：图片 `image`（目前仅支持图片格式）。
- **`transfer_method`** (`string`): 传递方式:
- `remote_url`: 图片地址。
- `local_file`: 上传文件。
- **`url`** (`string`): 图片地址。（仅当传递方式为 `remote_url` 时）。
- **`upload_file_id`** (`string`): 上传文件 ID。（仅当传递方式为 `local_file` 时）。
### Response
当 `response_mode` 为 `blocking` 时，返回 ChatCompletionResponse object。
当 `response_mode` 为 `streaming`时，返回 ChunkChatCompletionResponse object 流式序列。
#### ChatCompletionResponse
返回完整的 App 结果，`Content-Type` 为 `application/json`。
- **`message_id`** (`string`): 消息唯一 ID
- **`mode`** (`string`): App 模式，固定为 chat
- **`answer`** (`string`): 完整回复内容
- **`metadata`** (`object`): 元数据
- **`usage`** (`Usage`): 模型用量信息
- **`retriever_resources`** (`array[RetrieverResource]`): 引用和归属分段列表
- **`created_at`** (`int`): 消息创建时间戳，如：1705395332
#### ChunkChatCompletionResponse
返回 App 输出的流式块，`Content-Type` 为 `text/event-stream`。
每个流式块均为 data: 开头，块之间以 `\n\n` 即两个换行符分隔，如下所示：
```text
data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n
```
流式块中根据 `event` 不同，结构也不同：
- `event: message`: LLM 返回文本块事件，即：完整的文本以分块的方式输出。
- **`task_id`** (`string`): 任务 ID，用于请求跟踪和下方的停止响应接口
- **`message_id`** (`string`): 消息唯一 ID
- **`answer`** (`string`): LLM 返回文本块内容
- **`created_at`** (`int`): 创建时间戳，如：1705395332
- `event: message_end`: 消息结束事件，收到此事件则代表文本流式返回结束。
- **`task_id`** (`string`): 任务 ID，用于请求跟踪和下方的停止响应接口
- **`message_id`** (`string`): 消息唯一 ID
- **`metadata`** (`object`): 元数据
- **`usage`** (`Usage`): 模型用量信息
- **`retriever_resources`** (`array[RetrieverResource]`): 引用和归属分段列表
- `event: tts_message`: TTS 音频流事件，即：语音合成输出。内容是 Mp3 格式的音频块，使用 base64 编码后的字符串，播放的时候直接解码即可。(开启自动播放才有此消息)
- **`task_id`** (`string`): 任务 ID，用于请求跟踪和下方的停止响应接口
- **`message_id`** (`string`): 消息唯一 ID
- **`audio`** (`string`): 语音合成之后的音频块使用 Base64 编码之后的文本内容，播放的时候直接 base64 解码送入播放器即可
- **`created_at`** (`int`): 创建时间戳，如：1705395332
- `event: tts_message_end`: TTS 音频流结束事件，收到这个事件表示音频流返回结束。
- **`task_id`** (`string`): 任务 ID，用于请求跟踪和下方的停止响应接口
- **`message_id`** (`string`): 消息唯一 ID
- **`audio`** (`string`): 结束事件是没有音频的，所以这里是空字符串
- **`created_at`** (`int`): 创建时间戳，如：1705395332
- `event: message_replace`: 消息内容替换事件。
开启内容审查和审查输出内容时，若命中了审查条件，则会通过此事件替换消息内容为预设回复。
- **`task_id`** (`string`): 任务 ID，用于请求跟踪和下方的停止响应接口
- **`message_id`** (`string`): 消息唯一 ID
- **`answer`** (`string`): 替换内容（直接替换 LLM 所有回复文本）
- **`created_at`** (`int`): 创建时间戳，如：1705395332
- `event: error`:
流式输出过程中出现的异常会以 stream event 形式输出，收到异常事件后即结束。
- **`task_id`** (`string`): 任务 ID，用于请求跟踪和下方的停止响应接口
- **`message_id`** (`string`): 消息唯一 ID
- **`status`** (`int`): HTTP 状态码
- **`code`** (`string`): 错误码
- **`message`** (`string`): 错误消息
- `event: ping`: 每 10s 一次的 ping 事件，保持连接存活。
### Errors
- 404，对话不存在
- 400，`invalid_param`，传入参数异常
- 400，`app_unavailable`，App 配置不可用
- 400，`provider_not_initialize`，无可用模型凭据配置
- 400，`provider_quota_exceeded`，模型调用额度不足
- 400，`model_currently_not_support`，当前模型不可用
- 400，`completion_request_error`，文本生成失败
- 500，服务内部异常
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/completion-messages' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"inputs": {
"query": "Hello, world!"
},
"response_mode": "streaming",
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Blocking
{
"id": "0b089b9a-24d9-48cc-94f8-762677276261",
"answer": "how are you?",
"created_at": 1679586667
}
```
```text Streaming
data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595}
data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
</CodeGroup>
---
## 上传文件
**POST** `/files/upload`
上传文件（目前仅支持图片）并在发送消息时使用，可实现图文多模态理解。
支持 png, jpg, jpeg, webp, gif 格式。
_上传的文件仅供当前终端用户使用。_
### Request Body
该接口需使用 `multipart/form-data` 进行请求。
- **`file`** (`file`): 要上传的文件。
- **`user`** (`string`): 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。
### Response
成功上传后，服务器会返回文件的 ID 和相关信息。
- **`id`** (`uuid`): ID
- **`name`** (`string`): 文件名
- **`size`** (`int`): 文件大小（byte）
- **`extension`** (`string`): 文件后缀
- **`mime_type`** (`string`): 文件 mime-type
- **`created_by`** (`uuid`): 上传人 ID
- **`created_at`** (`timestamp`): 上传时间
### Errors
- 400，`no_file_uploaded`，必须提供文件
- 400，`too_many_files`，目前只接受一个文件
- 400，`unsupported_preview`，该文件不支持预览
- 400，`unsupported_estimate`，该文件不支持估算
- 413，`file_too_large`，文件太大
- 415，`unsupported_file_type`，不支持的扩展名，当前只接受文档类文件
- 503，`s3_connection_failed`，无法连接到 S3 服务
- 503，`s3_permission_denied`，无权限上传文件到 S3
- 503，`s3_file_too_large`，文件超出 S3 大小限制
<CodeGroup>
```bash cURL curl -X POST 'https://api.dify.ai/v1/files/upload' \ --header
'Authorization: Bearer {api_key}' \ --form 'file=@"/path/to/file"' \ --form
'user="abc-123"' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "123",
"created_at": 1577836800
}
```
</CodeGroup>
---
## 停止响应
**POST** `/completion-messages/:task_id/stop`
仅支持流式模式。
### Path Parameters
- **`task_id`** (`string`): 任务 ID，可在流式返回 Chunk 中获取
### Request Body
- **`user`** (`string`): Required. 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。
### Response
- **`result`** (`string`): 固定返回 success
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/completion-messages/:task_id/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## 消息反馈（点赞）
**POST** `/messages/:message_id/feedbacks`
消息终端用户反馈、点赞，方便应用开发者优化输出预期。
### Path Parameters
- **`message_id`** (`string`): 消息 ID
### Request Body
- **`rating`** (`string`): 点赞 `like`, 点踩 `dislike`, 撤销点赞 `null`
- **`user`** (`string`): 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
- **`content`** (`string`): 消息反馈的具体信息。
### Response
- **`result`** (`string`): 固定返回 success
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/messages/:message_id/feedbacks' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"rating": "like",
"user": "abc-123",
"content": "message feedback information"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## 文字转语音
**POST** `/text-to-audio`
文字转语音。
### Request Body
- **`message_id`** (`string`): Dify 生成的文本消息，那么直接传递生成的 message-id 即可，后台会通过 message_id 查找相应的内容直接合成语音信息。如果同时传 message_id 和 text，优先使用 message_id。
- **`text`** (`string`): 语音生成内容。如果没有传 message-id 的话，则会使用这个字段的内容
- **`user`** (`string`): 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
### Response
响应体为 `audio/wav` 格式的音频文件。
<CodeGroup>
```bash cURL
curl -o text-to-audio.mp3 -X POST 'https://api.dify.ai/v1/text-to-audio' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290",
"text": "你好Dify",
"user": "abc-123",
"streaming": false
}'
```
</CodeGroup>
<CodeGroup>
```text Headers
Content-Type: audio/wav
```
```text Body
(Binary audio data)
```
</CodeGroup>
---
## 获取应用基本信息
**GET** `/info`
用于获取应用的基本信息。
### Response
- **`name`** (`string`): 应用名称
- **`description`** (`string`): 应用描述
- **`tags`** (`array[string]`): 应用标签
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/info' \ -H 'Authorization:
Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}
```
</CodeGroup>
---
## 获取应用参数
**GET** `/parameters`
用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。
### Response
- **`opening_statement`** (`string`): 开场白
- **`suggested_questions`** (`array[string]`): 开场推荐问题列表
- **`suggested_questions_after_answer`** (`object`): 启用回答后给出推荐问题。
- **`enabled`** (`bool`): 是否开启
- **`speech_to_text`** (`object`): 语音转文本
- **`enabled`** (`bool`): 是否开启
- **`retriever_resource`** (`object`): 引用和归属
- **`enabled`** (`bool`): 是否开启
- **`annotation_reply`** (`object`): 标记回复
- **`enabled`** (`bool`): 是否开启
- **`user_input_form`** (`array[object]`): 用户输入表单配置
- **`text-input`** (`object`): 文本输入控件
- **`label`** (`string`): 控件展示标签名
- **`variable`** (`string`): 控件 ID
- **`required`** (`bool`): 是否必填
- **`default`** (`string`): 默认值
- **`paragraph`** (`object`): 段落文本输入控件
- **`label`** (`string`): 控件展示标签名
- **`variable`** (`string`): 控件 ID
- **`required`** (`bool`): 是否必填
- **`default`** (`string`): 默认值
- **`select`** (`object`): 下拉控件
- **`label`** (`string`): 控件展示标签名
- **`variable`** (`string`): 控件 ID
- **`required`** (`bool`): 是否必填
- **`default`** (`string`): 默认值
- **`options`** (`array[string]`): 选项值
- **`file_upload`** (`object`): 文件上传配置
- **`image`** (`object`): 图片设置
当前仅支持图片类型：`png`, `jpg`, `jpeg`, `webp`, `gif`
- **`enabled`** (`bool`): 是否开启
- **`number_limits`** (`int`): 图片数量限制，默认 3
- **`transfer_methods`** (`array[string]`): 传递方式列表，`remote_url` , `local_file`，必选一个
- **`system_parameters`** (`object`): 系统参数
- **`file_size_limit`** (`int`): 文档上传大小限制 (MB)
- **`image_file_size_limit`** (`int`): 图片文件上传大小限制（MB）
- **`audio_file_size_limit`** (`int`): 音频文件上传大小限制 (MB)
- **`video_file_size_limit`** (`int`): 视频文件上传大小限制 (MB)
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/parameters' \ --header
'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"introduction": "nice to meet you",
"user_input_form": [
{
"text-input": {
"label": "a",
"variable": "a",
"required": true,
"max_length": 48,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": true,
"number_limits": 3,
"transfer_methods": [
"remote_url",
"local_file"
]
}
},
"system_parameters": {
"file_size_limit": 15,
"image_file_size_limit": 10,
"audio_file_size_limit": 50,
"video_file_size_limit": 100
}
}
```
</CodeGroup>
---
## 获取标注列表
**GET** `/apps/annotations`
### Query Parameters
- **`page`** (`string`): 页码
- **`limit`** (`string`): 每页数量
<CodeGroup>
```bash cURL curl --location --request GET
'https://api.dify.ai/v1/apps/annotations?page=1&limit=20' \ --header
'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"data": [
{
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
"question": "What is your name?",
"answer": "I am Dify.",
"hit_count": 0,
"created_at": 1735625869
}
],
"has_more": false,
"limit": 20,
"total": 1,
"page": 1
}
```
</CodeGroup>
---
## 创建标注
**POST** `/apps/annotations`
### Request Body
- **`question`** (`string`): 问题
- **`answer`** (`string`): 答案内容
<CodeGroup>
```bash cURL
curl --location --request POST 'https://api.dify.ai/v1/apps/annotations' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"question": "What is your name?",
"answer": "I am Dify."
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
"question": "What is your name?",
"answer": "I am Dify.",
"hit_count": 0,
"created_at": 1735625869
}
```
</CodeGroup>
---
## 更新标注
**PUT** `/apps/annotations/{annotation_id}`
### Path Parameters
- **`annotation_id`** (`string`): 标注 ID
### Request Body
- **`question`** (`string`): 问题
- **`answer`** (`string`): 答案内容
<CodeGroup>
```bash cURL
curl --location --request PUT 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"question": "What is your name?",
"answer": "I am Dify."
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
"question": "What is your name?",
"answer": "I am Dify.",
"hit_count": 0,
"created_at": 1735625869
}
```
</CodeGroup>
---
## 删除标注
**DELETE** `/apps/annotations/{annotation_id}`
### Path Parameters
- **`annotation_id`** (`string`): 标注 ID
<CodeGroup>
```bash cURL curl --location --request DELETE
'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \ --header
'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>```text Response 204 No Content ```</CodeGroup>
---
## 标注回复初始设置
**POST** `/apps/annotation-reply/{action}`
### Path Parameters
- **`action`** (`string`): 动作，只能是 `enable` 或 `disable`
### Request Body
- **`embedding_provider_name`** (`string`): 指定的嵌入模型提供商, 必须先在系统内设定好接入的模型，对应的是 provider 字段
- **`embedding_model_name`** (`string`): 指定的嵌入模型，对应的是 model 字段
- **`score_threshold`** (`number`): 相似度阈值，当相似度大于该阈值时，系统会自动回复，否则不回复
嵌入模型的提供商和模型名称可以通过以下接口获取：`v1/workspaces/current/models/model-types/text-embedding`， 具体见：通过 API 维护知识库。 使用的 Authorization 是 Dataset 的 API Token。
该接口是异步执行，所以会返回一个 job_id，通过查询 job 状态接口可以获取到最终的执行结果。
<CodeGroup>
```bash cURL
curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/{action}' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"score_threshold": 0.9,
"embedding_provider_name": "zhipu",
"embedding_model_name": "embedding_3"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
"job_status": "waiting"
}
```
</CodeGroup>
---
## 查询标注回复初始设置任务状态
**GET** `/apps/annotation-reply/{action}/status/{job_id}`
### Path Parameters
- **`action`** (`string`): 动作，只能是 `enable` 或 `disable`，并且必须和标注回复初始设置接口的动作一致
- **`job_id`** (`string`): 任务 ID，从标注回复初始设置接口返回的 job_id
<CodeGroup>
```bash cURL curl --location --request GET
'https://api.dify.ai/v1/apps/annotation-reply/{action}/status/{job_id}' \
--header 'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
"job_status": "waiting",
"error_msg": ""
}
```
</CodeGroup>

668
api_access/workflow.en.mdx Normal file
View File

@@ -0,0 +1,668 @@
---
title: Workflow App API
---
Workflow applications offers non-session support and is ideal for translation, article writing, summarization AI, and more.
### Base URL
The Base URL for the API is:
```text
https://api.dify.ai/v1
```
### Authentication
The Service API uses `API-Key` authentication.
<i>
**Strongly recommend storing your API Key on the server-side, not shared or
stored on the client-side, to avoid possible API-Key leakage that can lead
to serious consequences.**
</i>
For all API requests, include your API Key in the `Authorization` HTTP Header, as shown below:
```text Authorization Header
Authorization: Bearer {API_KEY}
```
---
## Execute Workflow (POST /workflows/run)
Execute workflow, cannot be executed without a published workflow.
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/workflows/run' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"inputs": {"your_key": "your_value"},
"response_mode": "streaming",
"user": "abc-123"
}'
```
</CodeGroup>
### Request Body
- `inputs` (object) Required
Allows the entry of various variable values defined by the App.
The `inputs` parameter contains multiple key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable.
The workflow application requires at least one key/value pair to be inputted. The variable can be of File Array type.
File Array type variable is suitable for inputting files combined with text understanding and answering questions, available only when the model supports file parsing and understanding capability.
If the variable is of File Array type, the corresponding value should be a list whose elements contain following attributions:
- `type` (string) Supported type:
- `document` ('TXT', 'MD', 'MARKDOWN', 'PDF', 'HTML', 'XLSX', 'XLS', 'DOCX', 'CSV', 'EML', 'MSG', 'PPTX', 'PPT', 'XML', 'EPUB')
- `image` ('JPG', 'JPEG', 'PNG', 'GIF', 'WEBP', 'SVG')
- `audio` ('MP3', 'M4A', 'WAV', 'WEBM', 'AMR')
- `video` ('MP4', 'MOV', 'MPEG', 'MPGA')
- `custom` (Other file types)
- `transfer_method` (string) Transfer method, `remote_url` for image URL / `local_file` for file upload
- `url` (string) Image URL (when the transfer method is `remote_url`)
- `upload_file_id` (string) Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`)
- `response_mode` (string) Required
The mode of response return, supporting:
- `streaming` Streaming mode (recommended), implements a typewriter-like output through SSE ([Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)).
- `blocking` Blocking mode, returns result after execution is complete. (Requests may be interrupted if the process is long)
<i>
Due to Cloudflare restrictions, the request will be interrupted
without a return after 100 seconds.
</i>
- `user` (string) Required
User identifier, used to define the identity of the end-user for retrieval and statistics.
Should be uniquely defined by the developer within the application.
#### Example: file array as an input variable
```json "File variable example"
{
"inputs": {
"{variable_name}": [
{
"transfer_method": "local_file",
"upload_file_id": "{upload_file_id}",
"type": "{document_type}"
}
]
}
}
```
### Responses
When `response_mode` is `blocking`, return a CompletionResponse object.
When `response_mode` is `streaming`, return a ChunkCompletionResponse stream.
<CodeGroup>
<CodeGroup>
```json "Blocking Mode Response"
{
"workflow_run_id": "djflajgkldjgd",
"task_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"data": {
"id": "fdlsjfjejkghjda",
"workflow_id": "fldjaslkfjlsda",
"status": "succeeded",
"outputs": {
"text": "Nice to meet you."
},
"error": null,
"elapsed_time": 0.875,
"total_tokens": 3562,
"total_steps": 8,
"created_at": 1705407629,
"finished_at": 1727807631
}
}
```
```streaming "Streaming Mode Response"
data: {"event": "workflow_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "sequence_number": 1, "created_at": 1679586595}}
data: {"event": "node_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "created_at": 1679586595}}
data: {"event": "node_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "execution_metadata": {"total_tokens": 63127864, "total_price": 2.378, "currency": "USD"}, "created_at": 1679586595}}
data: {"event": "workflow_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "total_tokens": 63127864, "total_steps": "1", "created_at": 1679586595, "finished_at": 1679976595}}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
</CodeGroup>
</CodeGroup>
#### CompletionResponse
Returns the App result, `Content-Type` is `application/json`.
- `workflow_run_id` (string) Unique ID of workflow execution
- `task_id` (string) Task ID, used for request tracking and the below Stop Generate API
- `data` (object) detail of result
- `id` (string) ID of workflow execution
- `workflow_id` (string) ID of related workflow
- `status` (string) status of execution, `running` / `succeeded` / `failed` / `stopped`
- `outputs` (json) Optional content of output
- `error` (string) Optional reason of error
- `elapsed_time` (float) Optional total seconds to be used
- `total_tokens` (int) Optional tokens to be used
- `total_steps` (int) default 0
- `created_at` (timestamp) start time
- `finished_at` (timestamp) end time
#### ChunkCompletionResponse
Returns the stream chunks outputted by the App, `Content-Type` is `text/event-stream`.
Each streaming chunk starts with `data:`, separated by two newline characters `\n\n`, as shown below:
```streaming Response
data: {"event": "text_chunk", "workflow_run_id": "b85e5fc5-751b-454d-b14e-dc5f240b0a31", "task_id": "bd029338-b068-4d34-a331-fc85478922c2", "data": {"text": "\u4e3a\u4e86", "from_variable_selector": ["1745912968134", "text"]}}\n\n
```
The structure of the streaming chunks varies depending on the `event`:
- `event: workflow_started` workflow starts execution
- `task_id` (string) Task ID, used for request tracking and the below Stop Generate API
- `workflow_run_id` (string) Unique ID of workflow execution
- `event` (string) fixed to `workflow_started`
- `data` (object) detail
- `id` (string) Unique ID of workflow execution
- `workflow_id` (string) ID of related workflow
- `sequence_number` (int) Self-increasing serial number, self-increasing in the App, starting from 1
- `created_at` (timestamp) Creation timestamp, e.g., 1705395332
- `event: node_started` node execution started
- `task_id` (string) Task ID, used for request tracking and the below Stop Generate API
- `workflow_run_id` (string) Unique ID of workflow execution
- `event` (string) fixed to `node_started`
- `data` (object) detail
- `id` (string) Unique ID of workflow execution
- `node_id` (string) ID of node
- `node_type` (string) type of node
- `title` (string) name of node
- `index` (int) Execution sequence number, used to display Tracing Node sequence
- `predecessor_node_id` (string) optional Prefix node ID, used for canvas display execution path
- `inputs` (object) Contents of all preceding node variables used in the node
- `created_at` (timestamp) timestamp of start, e.g., 1705395332
- `event: text_chunk` Text fragment
- `task_id` (string) Task ID, used for request tracking and the below Stop Generate API
- `workflow_run_id` (string) Unique ID of workflow execution
- `event` (string) fixed to `text_chunk`
- `data` (object) detail
- `text` (string) Text content
- `from_variable_selector` (array) Text source path, helping developers understand which node and variable generated the text
- `event: node_finished` node execution ends, success or failure in different states in the same event
- `task_id` (string) Task ID, used for request tracking and the below Stop Generate API
- `workflow_run_id` (string) Unique ID of workflow execution
- `event` (string) fixed to `node_finished`
- `data` (object) detail
- `id` (string) Unique ID of workflow execution
- `node_id` (string) ID of node
- `node_type` (string) type of node
- `title` (string) name of node
- `index` (int) Execution sequence number, used to display Tracing Node sequence
- `predecessor_node_id` (string) optional Prefix node ID, used for canvas display execution path
- `inputs` (object) Contents of all preceding node variables used in the node
- `process_data` (json) Optional node process data
- `outputs` (json) Optional content of output
- `status` (string) status of execution, `running` / `succeeded` / `failed` / `stopped`
- `error` (string) Optional reason of error
- `elapsed_time` (float) Optional total seconds to be used
- `execution_metadata` (json) meta data
- `total_tokens` (int) optional tokens to be used
- `total_price` (decimal) optional Total cost
- `currency` (string) optional e.g. `USD` / `RMB`
- `created_at` (timestamp) timestamp of start, e.g., 1705395332
- `event: workflow_finished` workflow execution ends, success or failure in different states in the same event
- `task_id` (string) Task ID, used for request tracking and the below Stop Generate API
- `workflow_run_id` (string) Unique ID of workflow execution
- `event` (string) fixed to `workflow_finished`
- `data` (object) detail
- `id` (string) ID of workflow execution
- `workflow_id` (string) ID of related workflow
- `status` (string) status of execution, `running` / `succeeded` / `failed` / `stopped`
- `outputs` (json) Optional content of output
- `error` (string) Optional reason of error
- `elapsed_time` (float) Optional total seconds to be used
- `total_tokens` (int) Optional tokens to be used
- `total_steps` (int) default 0
- `created_at` (timestamp) start time
- `finished_at` (timestamp) end time
- `event: tts_message` TTS audio stream event, that is, speech synthesis output. The content is an audio block in Mp3 format, encoded as a base64 string. When playing, simply decode the base64 and feed it into the player. (This message is available only when auto-play is enabled)
- `task_id` (string) Task ID, used for request tracking and the stop response interface below
- `message_id` (string) Unique message ID
- `audio` (string) The audio after speech synthesis, encoded in base64 text content, when playing, simply decode the base64 and feed it into the player
- `created_at` (int) Creation timestamp, e.g.: 1705395332
- `event: tts_message_end` TTS audio stream end event, receiving this event indicates the end of the audio stream.
- `task_id` (string) Task ID, used for request tracking and the stop response interface below
- `message_id` (string) Unique message ID
- `audio` (string) The end event has no audio, so this is an empty string
- `created_at` (int) Creation timestamp, e.g.: 1705395332
- `event: ping` Ping event every 10 seconds to keep the connection alive.
### Errors
- 400, `invalid_param`, abnormal parameter input
- 400, `app_unavailable`, App configuration unavailable
- 400, `provider_not_initialize`, no available model credential configuration
- 400, `provider_quota_exceeded`, model invocation quota insufficient
- 400, `model_currently_not_support`, current model unavailable
- 400, `workflow_request_error`, workflow execution failed
- 500, internal server error
### File upload sample code
```python "File upload sample code"
import requests
import json
def upload_file(file_path, user):
upload_url = "https://api.dify.ai/v1/files/upload" # Assuming this is the correct upload URL
headers = {
"Authorization": "Bearer app-xxxxxxxx", # Replace with your app-specific API key for file upload if different
}
try:
print("Upload file...")
with open(file_path, 'rb') as file:
files = {
'file': (file_path, file, 'text/plain') # Make sure the file is uploaded with the appropriate MIME type
}
data = {
"user": user,
# "type": "TXT" # Type might be part of file metadata or not needed for generic upload API
}
response = requests.post(upload_url, headers=headers, files=files, data=data)
if response.status_code == 201: # 201 means creation is successful
print("File uploaded successfully")
return response.json().get("id") # Get the uploaded file ID
else:
print(f"File upload failed, status code: {response.status_code}, message: {response.text}")
return None
except Exception as e:
print(f"Error occurred: {str(e)}")
return None
def run_workflow(file_id, user, response_mode="blocking"):
workflow_url = "https://api.dify.ai/v1/workflows/run"
headers = {
"Authorization": "Bearer app-xxxxxxxxx", # Replace with your workflow execution API key
"Content-Type": "application/json"
}
data = {
"inputs": {
"orig_mail": [{ # Assuming "orig_mail" is your variable name
"transfer_method": "local_file",
"upload_file_id": file_id,
"type": "document" # Ensure this matches the expected type for the variable
}]
},
"response_mode": response_mode,
"user": user
}
try:
print("Run Workflow...")
response = requests.post(workflow_url, headers=headers, json=data)
if response.status_code == 200:
print("Workflow execution successful")
return response.json()
else:
print(f"Workflow execution failed, status code: {response.status_code}, message: {response.text}")
return {"status": "error", "message": f"Failed to execute workflow, status code: {response.status_code}, response: {response.text}"}
except Exception as e:
print(f"Error occurred: {str(e)}")
return {"status": "error", "message": str(e)}
# Usage Examples
# file_path = "{your_file_path}" # e.g., "/path/to/your/file.txt"
# user = "difyuser"
# # Upload files
# file_id = upload_file(file_path, user)
# if file_id:
# # The file was uploaded successfully, and the workflow continues to run
# result = run_workflow(file_id, user)
# print(result)
# else:
# print("File upload failed and workflow cannot be executed")
```
---
## Get Workflow Run Detail (GET /workflows/run/:workflow_id)
Retrieve the current execution results of a workflow task based on the workflow execution ID.
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/workflows/run/{workflow_id}
' \ -H 'Authorization: Bearer {api_key}' \ -H 'Content-Type:
application/json' ```
</CodeGroup>
### Path Parameters
- `workflow_id` (string) Workflow ID, can be obtained from the streaming chunk return
### Response
- `id` (string) ID of workflow execution
- `workflow_id` (string) ID of related workflow
- `status` (string) status of execution, `running` / `succeeded` / `failed` / `stopped`
- `inputs` (json) content of input
- `outputs` (json) content of output
- `error` (string) reason of error
- `total_steps` (int) total steps of task
- `total_tokens` (int) total tokens to be used
- `created_at` (timestamp) start time
- `finished_at` (timestamp) end time
- `elapsed_time` (float) total seconds to be used
<CodeGroup>
```json Response
{
"id": "b1ad3277-089e-42c6-9dff-6820d94fbc76",
"workflow_id": "19eff89f-ec03-4f75-b0fc-897e7effea02",
"status": "succeeded",
"inputs": "{\"sys.files\": [], \"sys.user_id\": \"abc-123\"}",
"outputs": null,
"error": null,
"total_steps": 3,
"total_tokens": 0,
"created_at": 1705407629,
"finished_at": 1727807631,
"elapsed_time": 30.098514399956912
}
```
</CodeGroup>
---
## Stop Generate (POST /workflows/tasks/:task_id/stop)
Only supported in streaming mode.
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/workflows/tasks/{task_id}/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
### Path Parameters
- `task_id` (string) Task ID, can be obtained from the streaming chunk return
### Request Body
- `user` (string) Required
User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface.
### Response
- `result` (string) Always returns "success"
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## File Upload (POST /files/upload)
Upload a file for use when sending messages, enabling multimodal understanding of images and text.
Supports any formats that are supported by your workflow.
Uploaded files are for use by the current end-user only.
<CodeGroup>
```bash cURL curl -X POST 'https://api.dify.ai/v1/files/upload' \ --header
'Authorization: Bearer {api_key}' \ --form 'file=@"/path/to/file"' \ --form
'user="abc-123"' ```
</CodeGroup>
### Request Body
This interface requires a `multipart/form-data` request.
- `file` (File) Required
The file to be uploaded.
- `user` (string) Required
User identifier, defined by the developer's rules, must be unique within the application.
### Response
After a successful upload, the server will return the file's ID and related information.
- `id` (uuid) ID
- `name` (string) File name
- `size` (int) File size (bytes)
- `extension` (string) File extension
- `mime_type` (string) File mime-type
- `created_by` (uuid) End-user ID
- `created_at` (timestamp) Creation timestamp, e.g., 1705395332
<CodeGroup>
```json Response
{
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13",
"created_at": 1577836800
}
```
</CodeGroup>
### Errors
- 400, `no_file_uploaded`, a file must be provided
- 400, `too_many_files`, currently only one file is accepted
- 400, `unsupported_preview`, the file does not support preview
- 400, `unsupported_estimate`, the file does not support estimation
- 413, `file_too_large`, the file is too large
- 415, `unsupported_file_type`, unsupported extension, currently only document files are accepted
- 503, `s3_connection_failed`, unable to connect to S3 service
- 503, `s3_permission_denied`, no permission to upload files to S3
- 503, `s3_file_too_large`, file exceeds S3 size limit
- 500, internal server error
---
## Get Workflow Logs (GET /workflows/logs)
Returns workflow logs, with the first page returning the latest `{limit}` messages, i.e., in reverse order.
<CodeGroup>
```bash cURL curl -X GET
'https://api.dify.ai/v1/workflows/logs?limit=1&page=1&status=succeeded&keyword=mysearch'
\ --header 'Authorization: Bearer {api_key}' ```
</CodeGroup>
### Query Parameters
- `keyword` (string, optional): Keyword to search.
- `status` (string, optional): Filter by status: `succeeded` / `failed` / `stopped`.
- `page` (int, optional): Current page, default is 1.
- `limit` (int, optional): How many chat history messages to return in one request, default is 20.
### Response
- `page` (int) Current page
- `limit` (int) Number of returned items, if input exceeds system limit, returns system limit amount
- `total` (int) Number of total items
- `has_more` (bool) Whether there is a next page
- `data` (array[object]) Log list
- `id` (string) ID
- `workflow_run` (object) Workflow run
- `id` (string) ID
- `version` (string) Version
- `status` (string) status of execution, `running` / `succeeded` / `failed` / `stopped`
- `error` (string) Optional reason of error
- `elapsed_time` (float) total seconds to be used
- `total_tokens` (int) tokens to be used
- `total_steps` (int) default 0
- `created_at` (timestamp) start time
- `finished_at` (timestamp) end time
- `created_from` (string) Created from
- `created_by_role` (string) Created by role
- `created_by_account` (string) Optional Created by account
- `created_by_end_user` (object) Created by end user
- `id` (string) ID
- `type` (string) Type
- `is_anonymous` (bool) Is anonymous
- `session_id` (string) Session ID
- `created_at` (timestamp) create time
<CodeGroup>
```json Response
{
"page": 1,
"limit": 1,
"total": 7,
"has_more": true,
"data": [
{
"id": "e41b93f1-7ca2-40fd-b3a8-999aeb499cc0",
"workflow_run": {
"id": "c0640fc8-03ef-4481-a96c-8a13b732a36e",
"version": "2024-08-01 12:17:09.771832",
"status": "succeeded",
"error": null,
"elapsed_time": 1.3588523610014818,
"total_tokens": 0,
"total_steps": 3,
"created_at": 1726139643,
"finished_at": 1726139644
},
"created_from": "service-api",
"created_by_role": "end_user",
"created_by_account": null,
"created_by_end_user": {
"id": "7f7d9117-dd9d-441d-8970-87e5e7e687a3",
"type": "service_api",
"is_anonymous": false,
"session_id": "abc-123"
},
"created_at": 1726139644
}
]
}
```
</CodeGroup>
---
## Get Application Basic Information (GET /info)
Used to get basic information about this application.
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/info' \ -H 'Authorization:
Bearer {api_key}' ```
</CodeGroup>
### Response
- `name` (string) application name
- `description` (string) application description
- `tags` (array[string]) application tags
<CodeGroup>
```json Response
{
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}
```
</CodeGroup>
---
## Get Application Parameters Information (GET /parameters)
Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values.
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/parameters' \ --header
'Authorization: Bearer {api_key}' ```
</CodeGroup>
### Response
- `user_input_form` (array[object]) User input form configuration
- `text-input` (object) Text input control
- `label` (string) Variable display label name
- `variable` (string) Variable ID
- `required` (bool) Whether it is required
- `default` (string) Default value
- `paragraph` (object) Paragraph text input control
- `label` (string) Variable display label name
- `variable` (string) Variable ID
- `required` (bool) Whether it is required
- `default` (string) Default value
- `select` (object) Dropdown control
- `label` (string) Variable display label name
- `variable` (string) Variable ID
- `required` (bool) Whether it is required
- `default` (string) Default value
- `options` (array[string]) Option values
- `file_upload` (object) File upload configuration
- `image` (object) Image settings
Currently only supports image types: `png`, `jpg`, `jpeg`, `webp`, `gif`
- `enabled` (bool) Whether it is enabled
- `number_limits` (int) Image number limit, default is 3
- `transfer_methods` (array[string]) List of transfer methods, remote_url, local_file, must choose one
- `system_parameters` (object) System parameters
- `file_size_limit` (int) Document upload size limit (MB)
- `image_file_size_limit` (int) Image file upload size limit (MB)
- `audio_file_size_limit` (int) Audio file upload size limit (MB)
- `video_file_size_limit` (int) Video file upload size limit (MB)
<CodeGroup>
```json Response
{
"user_input_form": [
{
"paragraph": {
"label": "Query",
"variable": "query",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": false,
"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
}
}
```
</CodeGroup>

665
api_access/workflow.ja.mdx Normal file
View File

@@ -0,0 +1,665 @@
---
title: ワークフローアプリAPI
---
ワークフローアプリケーションは、セッションをサポートせず、翻訳、記事作成、要約 AI などに最適です。
### ベース URL
```text
https://api.dify.ai/v1
```
### 認証
サービス API は`API-Key`認証を使用します。
<i>
**APIキーの漏洩を防ぐため、APIキーはクライアント側で共有または保存せず、サーバー側で保存することを強くお勧めします。**
</i>
すべての API リクエストにおいて、以下のように`Authorization`HTTP ヘッダーに API キーを含めてください：
```text
Authorization: Bearer {API_KEY}
```
---
## POST /workflows/run ワークフローを実行
ワークフローを実行します。公開されたワークフローがないと実行できません。
### リクエストボディ
- `inputs` (object) 必須
アプリで定義されたさまざまな変数値の入力を許可します。
`inputs`パラメータには複数のキー/値ペアが含まれ、各キーは特定の変数に対応し、各値はその変数の特定の値です。
ワークフローアプリケーションは少なくとも 1 つのキー/値ペアの入力を必要とします。値はファイルリストである場合もあります。
ファイルリストは、テキスト理解と質問への回答を組み合わせたファイルの入力に適しています。モデルがファイルの解析と理解機能をサポートしている場合にのみ使用できます。
変数がファイルリストの場合、リストの各要素は以下の属性を持つ必要があります。
- `type` (string) サポートされているタイプ:
- `document` ('TXT', 'MD', 'MARKDOWN', 'PDF', 'HTML', 'XLSX', 'XLS', 'DOCX', 'CSV', 'EML', 'MSG', 'PPTX', 'PPT', 'XML', 'EPUB')
- `image` ('JPG', 'JPEG', 'PNG', 'GIF', 'WEBP', 'SVG')
- `audio` ('MP3', 'M4A', 'WAV', 'WEBM', 'AMR')
- `video` ('MP4', 'MOV', 'MPEG', 'MPGA')
- `custom` (他のファイルタイプ)
- `transfer_method` (string) 転送方法、画像 URL の場合は`remote_url` / ファイルアップロードの場合は`local_file`
- `url` (string) 画像 URL（転送方法が`remote_url`の場合）
- `upload_file_id` (string) アップロードされたファイル ID、事前にファイルアップロード API を通じて取得する必要があります（転送方法が`local_file`の場合）
- `response_mode` (string) 必須
応答の返却モードを指定します。サポートされているモード：
- `streaming` ストリーミングモード（推奨）、SSE（[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)）を通じてタイプライターのような出力を実装します。
- `blocking` ブロッキングモード、実行完了後に結果を返します。（プロセスが長い場合、リクエストが中断される可能性があります）
<i>
Cloudflareの制限により、100秒後に応答がない場合、リクエストは中断されます。
</i>
- `user` (string) 必須
ユーザー識別子、エンドユーザーのアイデンティティを定義するために使用されます。
アプリケーション内で開発者によって一意に定義される必要があります。
- `files` (array[object]) オプション
### 応答
`response_mode`が`blocking`の場合、CompletionResponse オブジェクトを返します。
`response_mode`が`streaming`の場合、ChunkCompletionResponse ストリームを返します。
#### CompletionResponse
アプリの結果を返します。`Content-Type`は`application/json`です。
- `workflow_run_id` (string) ワークフロー実行の一意の ID
- `task_id` (string) タスク ID、リクエスト追跡と以下の Stop Generate API に使用
- `data` (object) 結果の詳細
- `id` (string) ワークフロー実行の ID
- `workflow_id` (string) 関連するワークフローの ID
- `status` (string) 実行のステータス、`running` / `succeeded` / `failed` / `stopped`
- `outputs` (json) オプションの出力内容
- `error` (string) オプションのエラー理由
- `elapsed_time` (float) オプションの使用時間（秒）
- `total_tokens` (int) オプションの使用トークン数
- `total_steps` (int) デフォルト 0
- `created_at` (timestamp) 開始時間
- `finished_at` (timestamp) 終了時間
#### ChunkCompletionResponse
アプリによって出力されたストリームチャンクを返します。`Content-Type`は`text/event-stream`です。
各ストリーミングチャンクは`data:`で始まり、2 つの改行文字`\n\n`で区切られます。以下のように表示されます：
```text
data: {"event": "text_chunk", "workflow_run_id": "b85e5fc5-751b-454d-b14e-dc5f240b0a31", "task_id": "bd029338-b068-4d34-a331-fc85478922c2", "data": {"text": "\u4e3a\u4e86", "from_variable_selector": ["1745912968134", "text"]}}\n\n
```
ストリーミングチャンクの構造は`event`に応じて異なります：
- `event: workflow_started` ワークフローが実行を開始
- `task_id` (string) タスク ID、リクエスト追跡と以下の Stop Generate API に使用
- `workflow_run_id` (string) ワークフロー実行の一意の ID
- `event` (string) `workflow_started`に固定
- `data` (object) 詳細
- `id` (string) ワークフロー実行の一意の ID
- `workflow_id` (string) 関連するワークフローの ID
- `sequence_number` (int) 自己増加シリアル番号、アプリ内で自己増加し、1 から始まります
- `created_at` (timestamp) 作成タイムスタンプ、例：1705395332
- `event: node_started` ノード実行開始
- `task_id` (string) タスク ID、リクエスト追跡と以下の Stop Generate API に使用
- `workflow_run_id` (string) ワークフロー実行の一意の ID
- `event` (string) `node_started`に固定
- `data` (object) 詳細
- `id` (string) ワークフロー実行の一意の ID
- `node_id` (string) ノードの ID
- `node_type` (string) ノードのタイプ
- `title` (string) ノードの名前
- `index` (int) 実行シーケンス番号、トレースノードシーケンスを表示するために使用
- `predecessor_node_id` (string) オプションのプレフィックスノード ID、キャンバス表示実行パスに使用
- `inputs` (object) ノードで使用されるすべての前のノード変数の内容
- `created_at` (timestamp) 開始のタイムスタンプ、例：1705395332
- `event: text_chunk` テキストフラグメント
- `task_id` (string) タスク ID、リクエスト追跡と以下の Stop Generate API に使用
- `workflow_run_id` (string) ワークフロー実行の一意の ID
- `event` (string) `text_chunk`に固定
- `data` (object) 詳細
- `text` (string) テキスト内容
- `from_variable_selector` (array) テキスト生成元パス（開発者がどのノードのどの変数から生成されたかを理解するための情報）
- `event: node_finished` ノード実行終了、同じイベントで異なる状態で成功または失敗
- `task_id` (string) タスク ID、リクエスト追跡と以下の Stop Generate API に使用
- `workflow_run_id` (string) ワークフロー実行の一意の ID
- `event` (string) `node_finished`に固定
- `data` (object) 詳細
- `id` (string) ワークフロー実行の一意の ID
- `node_id` (string) ノードの ID
- `node_type` (string) ノードのタイプ
- `title` (string) ノードの名前
- `index` (int) 実行シーケンス番号、トレースノードシーケンスを表示するために使用
- `predecessor_node_id` (string) オプションのプレフィックスノード ID、キャンバス表示実行パスに使用
- `inputs` (object) ノードで使用されるすべての前のノード変数の内容
- `process_data` (json) オプションのノードプロセスデータ
- `outputs` (json) オプションの出力内容
- `status` (string) 実行のステータス、`running` / `succeeded` / `failed` / `stopped`
- `error` (string) オプションのエラー理由
- `elapsed_time` (float) オプションの使用時間（秒）
- `execution_metadata` (json) メタデータ
- `total_tokens` (int) オプションの使用トークン数
- `total_price` (decimal) オプションの総コスト
- `currency` (string) オプション 例：`USD` / `RMB`
- `created_at` (timestamp) 開始のタイムスタンプ、例：1705395332
- `event: workflow_finished` ワークフロー実行終了、同じイベントで異なる状態で成功または失敗
- `task_id` (string) タスク ID、リクエスト追跡と以下の Stop Generate API に使用
- `workflow_run_id` (string) ワークフロー実行の一意の ID
- `event` (string) `workflow_finished`に固定
- `data` (object) 詳細
- `id` (string) ワークフロー実行の ID
- `workflow_id` (string) 関連するワークフローの ID
- `status` (string) 実行のステータス、`running` / `succeeded` / `failed` / `stopped`
- `outputs` (json) オプションの出力内容
- `error` (string) オプションのエラー理由
- `elapsed_time` (float) オプションの使用時間（秒）
- `total_tokens` (int) オプションの使用トークン数
- `total_steps` (int) デフォルト 0
- `created_at` (timestamp) 開始時間
- `finished_at` (timestamp) 終了時間
- `event: tts_message` TTS オーディオストリームイベント、つまり音声合成出力。内容は Mp3 形式のオーディオブロックで、base64 文字列としてエンコードされています。再生時には、base64 をデコードしてプレーヤーに入力するだけです。（このメッセージは自動再生が有効な場合にのみ利用可能）
- `task_id` (string) タスク ID、リクエスト追跡と以下の停止応答インターフェースに使用
- `message_id` (string) 一意のメッセージ ID
- `audio` (string) 音声合成後のオーディオ、base64 テキストコンテンツとしてエンコードされており、再生時には base64 をデコードしてプレーヤーに入力するだけです
- `created_at` (int) 作成タイムスタンプ、例：1705395332
- `event: tts_message_end` TTS オーディオストリーム終了イベント。このイベントを受信すると、オーディオストリームの終了を示します。
- `task_id` (string) タスク ID、リクエスト追跡と以下の停止応答インターフェースに使用
- `message_id` (string) 一意のメッセージ ID
- `audio` (string) 終了イベントにはオーディオがないため、これは空の文字列です
- `created_at` (int) 作成タイムスタンプ、例：1705395332
- `event: ping` 接続を維持するために 10 秒ごとに送信される Ping イベント。
### エラー
- 400, `invalid_param`, 異常なパラメータ入力
- 400, `app_unavailable`, アプリの設定が利用できません
- 400, `provider_not_initialize`, 利用可能なモデル資格情報の設定がありません
- 400, `provider_quota_exceeded`, モデル呼び出しのクォータが不足しています
- 400, `model_currently_not_support`, 現在のモデルは利用できません
- 400, `workflow_request_error`, ワークフロー実行に失敗しました
- 500, 内部サーバーエラー
<CodeGroup>
```bash Request
curl -X POST 'https://api.dify.ai/v1/workflows/run' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"inputs": {},
"response_mode": "streaming",
"user": "abc-123"
}'
```
</CodeGroup>
### ファイル変数の例
```json example.json
{
"inputs": {
"{variable_name}": [
{
"transfer_method": "local_file",
"upload_file_id": "{upload_file_id}",
"type": "{document_type}"
}
]
}
}
```
<CodeGroup>
#### ブロッキングモード応答
```json Response
{
"workflow_run_id": "djflajgkldjgd",
"task_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"data": {
"id": "fdlsjfjejkghjda",
"workflow_id": "fldjaslkfjlsda",
"status": "succeeded",
"outputs": {
"text": "Nice to meet you."
},
"error": null,
"elapsed_time": 0.875,
"total_tokens": 3562,
"total_steps": 8,
"created_at": 1705407629,
"finished_at": 1727807631
}
}
```
#### ストリーミングモード応答
```text StreamingResponse
data: {"event": "workflow_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "sequence_number": 1, "created_at": 1679586595}}
data: {"event": "node_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "created_at": 1679586595}}
data: {"event": "node_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "execution_metadata": {"total_tokens": 63127864, "total_price": 2.378, "currency": "USD"}, "created_at": 1679586595}}
data: {"event": "workflow_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "total_tokens": 63127864, "total_steps": "1", "created_at": 1679586595, "finished_at": 1679976595}}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
</CodeGroup>
### ファイルアップロードのサンプルコード
```python example_upload.py
import requests
import json
def upload_file(file_path, user):
upload_url = "https://api.dify.ai/v1/files/upload"
headers = {
"Authorization": "Bearer app-xxxxxxxx", # あなたのAPIキーに置き換えてください
}
try:
print("ファイルをアップロードしています...")
with open(file_path, 'rb') as file:
files = {
'file': (file_path, file, 'text/plain') # ファイルが適切な MIME タイプでアップロードされていることを確認してください
}
data = {
"user": user,
"type": "TXT" # ファイルタイプをTXTに設定します (必要に応じて変更)
}
response = requests.post(upload_url, headers=headers, files=files, data=data)
if response.status_code == 201: # 201 は作成が成功したことを意味します
print("ファイルが正常にアップロードされました")
return response.json().get("id") # アップロードされたファイルIDを取得する
else:
print(f"ファイルのアップロードに失敗しました。ステータス コード: {response.status_code}, 応答: {response.text}")
return None
except Exception as e:
print(f"エラーが発生しました: {str(e)}")
return None
def run_workflow(file_id, user, response_mode="blocking"):
workflow_url = "https://api.dify.ai/v1/workflows/run"
headers = {
"Authorization": "Bearer app-xxxxxxxxx", # あなたのAPIキーに置き換えてください
"Content-Type": "application/json"
}
# `orig_mail` はワークフローで定義された変数名です。実際の変数名に置き換えてください。
data = {
"inputs": {
"orig_mail": [{ # このキーはワークフローの入力変数名と一致する必要があります
"transfer_method": "local_file",
"upload_file_id": file_id,
"type": "document" # アップロードしたファイルのタイプに合わせてください
}]
},
"response_mode": response_mode,
"user": user
}
try:
print("ワークフローを実行...")
response = requests.post(workflow_url, headers=headers, json=data)
if response.status_code == 200:
print("ワークフローが正常に実行されました")
return response.json()
else:
print(f"ワークフローの実行がステータス コードで失敗しました: {response.status_code}, 応答: {response.text}")
return {"status": "error", "message": f"Failed to execute workflow, status code: {response.status_code}, response: {response.text}"}
except Exception as e:
print(f"エラーが発生しました: {str(e)}")
return {"status": "error", "message": str(e)}
# 使用例
# file_path = "{your_file_path}" # アップロードするファイルのパスに置き換えてください
# user = "difyuser" # ユーザーIDに置き換えてください
# # ファイルをアップロードする
# file_id = upload_file(file_path, user)
# if file_id:
# # ファイルは正常にアップロードされました。ワークフローの実行を続行します
# result = run_workflow(file_id, user)
# print(result)
# else:
# print("ファイルのアップロードに失敗し、ワークフローを実行できません")
```
---
## GET /workflows/run/:workflow_id ワークフロー実行詳細を取得
ワークフロー実行 ID に基づいて、ワークフロータスクの現在の実行結果を取得します。
### パスパラメータ
- `workflow_id` (string) ワークフロー ID、ストリーミングチャンクの返り値から取得可能
### 応答
- `id` (string) ワークフロー実行の ID
- `workflow_id` (string) 関連するワークフローの ID
- `status` (string) 実行のステータス、`running` / `succeeded` / `failed` / `stopped`
- `inputs` (json) 入力内容
- `outputs` (json) 出力内容
- `error` (string) エラー理由
- `total_steps` (int) タスクの総ステップ数
- `total_tokens` (int) 使用されるトークンの総数
- `created_at` (timestamp) 開始時間
- `finished_at` (timestamp) 終了時間
- `elapsed_time` (float) 使用される総秒数
<CodeGroup>
```bash Request curl -X GET
'https://api.dify.ai/v1/workflows/run/:workflow_id' \ -H 'Authorization:
Bearer {api_key}' \ -H 'Content-Type: application/json' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "b1ad3277-089e-42c6-9dff-6820d94fbc76",
"workflow_id": "19eff89f-ec03-4f75-b0fc-897e7effea02",
"status": "succeeded",
"inputs": "{\"sys.files\": [], \"sys.user_id\": \"abc-123\"}",
"outputs": null,
"error": null,
"total_steps": 3,
"total_tokens": 0,
"created_at": 1705407629,
"finished_at": 1727807631,
"elapsed_time": 30.098514399956912
}
```
</CodeGroup>
---
## POST /workflows/tasks/:task_id/stop 生成を停止
ストリーミングモードでのみサポートされています。
### パスパラメータ
- `task_id` (string) タスク ID、ストリーミングチャンクの返り値から取得可能
### リクエストボディ
- `user` (string) 必須
ユーザー識別子、エンドユーザーのアイデンティティを定義するために使用され、送信メッセージインターフェースで渡されたユーザーと一致している必要があります。
### 応答
- `result` (string) 常に"success"を返します
<CodeGroup>
```bash Request
curl -X POST 'https://api.dify.ai/v1/workflows/tasks/:task_id/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## POST /files/upload ファイルアップロード
メッセージ送信時に使用するためのファイルをアップロードし、画像とテキストのマルチモーダル理解を可能にします。
ワークフローでサポートされている任意の形式をサポートします。
アップロードされたファイルは、現在のエンドユーザーのみが使用できます。
### リクエストボディ
このインターフェースは`multipart/form-data`リクエストを必要とします。
- `file` (File) 必須
アップロードするファイル。
- `user` (string) 必須
ユーザー識別子、開発者のルールで定義され、アプリケーション内で一意でなければなりません。
### 応答
アップロードが成功すると、サーバーはファイルの ID と関連情報を返します。
- `id` (uuid) ID
- `name` (string) ファイル名
- `size` (int) ファイルサイズ（バイト）
- `extension` (string) ファイル拡張子
- `mime_type` (string) ファイルの MIME タイプ
- `created_by` (uuid) エンドユーザー ID
- `created_at` (timestamp) 作成タイムスタンプ、例：1705395332
### エラー
- 400, `no_file_uploaded`, ファイルが提供されていません
- 400, `too_many_files`, 現在は 1 つのファイルのみ受け付けています
- 400, `unsupported_preview`, ファイルはプレビューをサポートしていません
- 400, `unsupported_estimate`, ファイルは推定をサポートしていません
- 413, `file_too_large`, ファイルが大きすぎます
- 415, `unsupported_file_type`, サポートされていない拡張子、現在はドキュメントファイルのみ受け付けています
- 503, `s3_connection_failed`, S3 サービスに接続できません
- 503, `s3_permission_denied`, S3 にファイルをアップロードする権限がありません
- 503, `s3_file_too_large`, ファイルが S3 のサイズ制限を超えています
- 500, 内部サーバーエラー
<CodeGroup>
```bash Request curl -X POST 'https://api.dify.ai/v1/files/upload' \
--header 'Authorization: Bearer {api_key}' \ --form
'file=@"/path/to/your/file.txt"' \ --form 'user="abc-123"' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13",
"created_at": 1577836800
}
```
</CodeGroup>
---
## GET /workflows/logs ワークフローログを取得
ワークフローログを返します。最初のページは最新の`{limit}`メッセージを返します。つまり、逆順です。
### クエリパラメータ
- `keyword` (string, optional): 検索するキーワード
- `status` (string, optional): フィルタリングするステータス (`succeeded`/`failed`/`stopped`)
- `page` (int, optional): 現在のページ、デフォルトは 1。
- `limit` (int, optional): 1 回のリクエストで返すチャット履歴メッセージの数、デフォルトは 20。
### 応答
- `page` (int) 現在のページ
- `limit` (int) 返されたアイテムの数、入力がシステム制限を超える場合、システム制限量を返します
- `total` (int) 合計アイテム数
- `has_more` (bool) 次のページがあるかどうか
- `data` (array[object]) ログリスト
- `id` (string) ID
- `workflow_run` (object) ワークフロー実行
- `id` (string) ID
- `version` (string) バージョン
- `status` (string) 実行のステータス、`running` / `succeeded` / `failed` / `stopped`
- `error` (string) オプションのエラー理由
- `elapsed_time` (float) 使用される総秒数
- `total_tokens` (int) 使用されるトークン数
- `total_steps` (int) デフォルト 0
- `created_at` (timestamp) 開始時間
- `finished_at` (timestamp) 終了時間
- `created_from` (string) 作成元
- `created_by_role` (string) 作成者の役割
- `created_by_account` (string) オプションの作成者アカウント
- `created_by_end_user` (object) エンドユーザーによって作成
- `id` (string) ID
- `type` (string) タイプ
- `is_anonymous` (bool) 匿名かどうか
- `session_id` (string) セッション ID
- `created_at` (timestamp) 作成時間
<CodeGroup>
```bash Request curl -X GET 'https://api.dify.ai/v1/workflows/logs?limit=1'
\ --header 'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"page": 1,
"limit": 1,
"total": 7,
"has_more": true,
"data": [
{
"id": "e41b93f1-7ca2-40fd-b3a8-999aeb499cc0",
"workflow_run": {
"id": "c0640fc8-03ef-4481-a96c-8a13b732a36e",
"version": "2024-08-01 12:17:09.771832",
"status": "succeeded",
"error": null,
"elapsed_time": 1.3588523610014818,
"total_tokens": 0,
"total_steps": 3,
"created_at": 1726139643,
"finished_at": 1726139644
},
"created_from": "service-api",
"created_by_role": "end_user",
"created_by_account": null,
"created_by_end_user": {
"id": "7f7d9117-dd9d-441d-8970-87e5e7e687a3",
"type": "service_api",
"is_anonymous": false,
"session_id": "abc-123"
},
"created_at": 1726139644
}
]
}
```
</CodeGroup>
---
## GET /info アプリケーションの基本情報を取得
このアプリケーションの基本情報を取得するために使用されます
### 応答
- `name` (string) アプリケーションの名前
- `description` (string) アプリケーションの説明
- `tags` (array[string]) アプリケーションのタグ
<CodeGroup>
```bash Request curl -X GET 'https://api.dify.ai/v1/info' \ -H
'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}
```
</CodeGroup>
---
## GET /parameters アプリケーションのパラメータ情報を取得
ページに入る際に、機能、入力パラメータ名、タイプ、デフォルト値などの情報を取得するために使用されます。
### 応答
- `user_input_form` (array[object]) ユーザー入力フォームの設定
- `text-input` (object) テキスト入力コントロール
- `label` (string) 変数表示ラベル名
- `variable` (string) 変数 ID
- `required` (bool) 必須かどうか
- `default` (string) デフォルト値
- `paragraph` (object) 段落テキスト入力コントロール
- `label` (string) 変数表示ラベル名
- `variable` (string) 変数 ID
- `required` (bool) 必須かどうか
- `default` (string) デフォルト値
- `select` (object) ドロップダウンコントロール
- `label` (string) 変数表示ラベル名
- `variable` (string) 変数 ID
- `required` (bool) 必須かどうか
- `default` (string) デフォルト値
- `options` (array[string]) オプション値
- `file_upload` (object) ファイルアップロード設定
- `image` (object) 画像設定
現在サポートされている画像タイプのみ：`png`, `jpg`, `jpeg`, `webp`, `gif`
- `enabled` (bool) 有効かどうか
- `number_limits` (int) 画像数の制限、デフォルトは 3
- `transfer_methods` (array[string]) 転送方法のリスト、remote_url, local_file、いずれかを選択する必要があります
- `system_parameters` (object) システムパラメータ
- `file_size_limit` (int) ドキュメントアップロードサイズ制限（MB）
- `image_file_size_limit` (int) 画像ファイルアップロードサイズ制限（MB）
- `audio_file_size_limit` (int) オーディオファイルアップロードサイズ制限（MB）
- `video_file_size_limit` (int) ビデオファイルアップロードサイズ制限（MB）
<CodeGroup>
```bash Request curl -X GET 'https://api.dify.ai/v1/parameters' \ --header
'Authorization: Bearer {api_key}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"user_input_form": [
{
"paragraph": {
"label": "Query",
"variable": "query",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": false,
"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
}
}
```
</CodeGroup>

651
api_access/workflow.zh.mdx Normal file
View File

@@ -0,0 +1,651 @@
---
title: Workflow 应用 API
---
Workflow 应用无会话支持，适合用于翻译/文章写作/总结 AI 等等。
### Base URL
```text
https://api.dify.ai/v1
```
### Authentication
Dify Service API 使用 `API-Key` 进行鉴权。
<i>**强烈建议开发者把 `API-Key` 放在后端存储，而非分享或者放在客户端存储，以免 `API-Key` 泄露，导致财产损失。**</i>
所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`，如下所示：
```text
Authorization: Bearer {API_KEY}
```
---
## 执行 workflow
`POST /workflows/run`
执行 workflow，没有已发布的 workflow，不可执行。
### Request Body
- `inputs` (object) Required
允许传入 App 定义的各变量值。
inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。变量可以是文件列表类型。
文件列表类型变量适用于传入文件结合文本理解并回答问题，仅当模型支持该类型文件解析能力时可用。如果该变量是文件列表类型，该变量对应的值应是列表格式，其中每个元素应包含以下内容：
- `type` (string) 支持类型：
- `document` 具体类型包含：'TXT', 'MD', 'MARKDOWN', 'PDF', 'HTML', 'XLSX', 'XLS', 'DOCX', 'CSV', 'EML', 'MSG', 'PPTX', 'PPT', 'XML', 'EPUB'
- `image` 具体类型包含：'JPG', 'JPEG', 'PNG', 'GIF', 'WEBP', 'SVG'
- `audio` 具体类型包含：'MP3', 'M4A', 'WAV', 'WEBM', 'AMR'
- `video` 具体类型包含：'MP4', 'MOV', 'MPEG', 'MPGA'
- `custom` 具体类型包含：其他文件类型
- `transfer_method` (string) 传递方式，`remote_url` 图片地址 / `local_file` 上传文件
- `url` (string) 图片地址（仅当传递方式为 `remote_url` 时）
- `upload_file_id` (string) 上传文件 ID（仅当传递方式为 `local_file` 时）
- `response_mode` (string) Required
返回响应模式，支持：
- `streaming` 流式模式（推荐）。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现类似打字机输出方式的流式返回。
- `blocking` 阻塞模式，等待执行完毕后返回结果。（请求若流程较长可能会被中断）。
<i>由于 Cloudflare 限制，请求会在 100 秒超时无返回后中断。</i>
- `user` (string) Required
用户标识，用于定义终端用户的身份，方便检索、统计。
由开发者定义规则，需保证用户标识在应用内唯一。
### Response
当 `response_mode` 为 `blocking` 时，返回 CompletionResponse object。
当 `response_mode` 为 `streaming`时，返回 ChunkCompletionResponse object 流式序列。
### CompletionResponse
返回完整的 App 结果，`Content-Type` 为 `application/json` 。
- `workflow_run_id` (string) workflow 执行 ID
- `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口
- `data` (object) 详细内容
- `id` (string) workflow 执行 ID
- `workflow_id` (string) 关联 Workflow ID
- `status` (string) 执行状态, `running` / `succeeded` / `failed` / `stopped`
- `outputs` (json) Optional 输出内容
- `error` (string) Optional 错误原因
- `elapsed_time` (float) Optional 耗时(s)
- `total_tokens` (int) Optional 总使用 tokens
- `total_steps` (int) 总步数（冗余），默认 0
- `created_at` (timestamp) 开始时间
- `finished_at` (timestamp) 结束时间
### ChunkCompletionResponse
返回 App 输出的流式块，`Content-Type` 为 `text/event-stream`。
每个流式块均为 data: 开头，块之间以 `\n\n` 即两个换行符分隔，如下所示：
```text
data: {"event": "text_chunk", "workflow_run_id": "b85e5fc5-751b-454d-b14e-dc5f240b0a31", "task_id": "bd029338-b068-4d34-a331-fc85478922c2", "data": {"text": "\u4e3a\u4e86", "from_variable_selector": ["1745912968134", "text"]}}\n\n
```
流式块中根据 `event` 不同，结构也不同，包含以下类型：
- `event: workflow_started` workflow 开始执行
- `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口
- `workflow_run_id` (string) workflow 执行 ID
- `event` (string) 固定为 `workflow_started`
- `data` (object) 详细内容
- `id` (string) workflow 执行 ID
- `workflow_id` (string) 关联 Workflow ID
- `sequence_number` (int) 自增序号，App 内自增，从 1 开始
- `created_at` (timestamp) 开始时间
- `event: node_started` node 开始执行
- `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口
- `workflow_run_id` (string) workflow 执行 ID
- `event` (string) 固定为 `node_started`
- `data` (object) 详细内容
- `id` (string) workflow 执行 ID
- `node_id` (string) 节点 ID
- `node_type` (string) 节点类型
- `title` (string) 节点名称
- `index` (int) 执行序号，用于展示 Tracing Node 顺序
- `predecessor_node_id` (string) 前置节点 ID，用于画布展示执行路径
- `inputs` (object) 节点中所有使用到的前置节点变量内容
- `created_at` (timestamp) 开始时间
- `event: text_chunk` 文本片段
- `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口
- `workflow_run_id` (string) workflow 执行 ID
- `event` (string) 固定为 `text_chunk`
- `data` (object) 详细内容
- `text` (string) 文本内容
- `from_variable_selector` (array) 文本来源路径，帮助开发者了解文本是由哪个节点的哪个变量生成的
- `event: node_finished` node 执行结束，成功失败同一事件中不同状态
- `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口
- `workflow_run_id` (string) workflow 执行 ID
- `event` (string) 固定为 `node_finished`
- `data` (object) 详细内容
- `id` (string) node 执行 ID
- `node_id` (string) 节点 ID
- `index` (int) 执行序号，用于展示 Tracing Node 顺序
- `predecessor_node_id` (string) optional 前置节点 ID，用于画布展示执行路径
- `inputs` (object) 节点中所有使用到的前置节点变量内容
- `process_data` (json) Optional 节点过程数据
- `outputs` (json) Optional 输出内容
- `status` (string) 执行状态 `running` / `succeeded` / `failed` / `stopped`
- `error` (string) Optional 错误原因
- `elapsed_time` (float) Optional 耗时(s)
- `execution_metadata` (json) 元数据
- `total_tokens` (int) optional 总使用 tokens
- `total_price` (decimal) optional 总费用
- `currency` (string) optional 货币，如 `USD` / `RMB`
- `created_at` (timestamp) 开始时间
- `event: workflow_finished` workflow 执行结束，成功失败同一事件中不同状态
- `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口
- `workflow_run_id` (string) workflow 执行 ID
- `event` (string) 固定为 `workflow_finished`
- `data` (object) 详细内容
- `id` (string) workflow 执行 ID
- `workflow_id` (string) 关联 Workflow ID
- `status` (string) 执行状态 `running` / `succeeded` / `failed` / `stopped`
- `outputs` (json) Optional 输出内容
- `error` (string) Optional 错误原因
- `elapsed_time` (float) Optional 耗时(s)
- `total_tokens` (int) Optional 总使用 tokens
- `total_steps` (int) 总步数（冗余），默认 0
- `created_at` (timestamp) 开始时间
- `finished_at` (timestamp) 结束时间
- `event: tts_message` TTS 音频流事件，即：语音合成输出。内容是Mp3格式的音频块，使用 base64 编码后的字符串，播放的时候直接解码即可。(开启自动播放才有此消息)
- `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口
- `message_id` (string) 消息唯一 ID
- `audio` (string) 语音合成之后的音频块使用 Base64 编码之后的文本内容，播放的时候直接 base64 解码送入播放器即可
- `created_at` (int) 创建时间戳，如：1705395332
- `event: tts_message_end` TTS 音频流结束事件，收到这个事件表示音频流返回结束。
- `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口
- `message_id` (string) 消息唯一 ID
- `audio` (string) 结束事件是没有音频的，所以这里是空字符串
- `created_at` (int) 创建时间戳，如：1705395332
- `event: ping` 每 10s 一次的 ping 事件，保持连接存活。
### Errors
- 400，`invalid_param`，传入参数异常
- 400，`app_unavailable`，App 配置不可用
- 400，`provider_not_initialize`，无可用模型凭据配置
- 400，`provider_quota_exceeded`，模型调用额度不足
- 400，`model_currently_not_support`，当前模型不可用
- 400，`workflow_request_error`，workflow 执行失败
- 500，服务内部异常
#### 文件变量示例
```json
{
"inputs": {
"{variable_name}": [
{
"transfer_method": "local_file",
"upload_file_id": "{upload_file_id}",
"type": "{document_type}"
}
]
}
}
```
#### 文件上传Python示例代码
```python
import requests
import json
def upload_file(file_path, user):
upload_url = "https://api.dify.ai/v1/files/upload"
headers = {
"Authorization": "Bearer app-xxxxxxxx", # 请替换为您的 API Key
}
try:
print("上传文件中...")
with open(file_path, 'rb') as file:
files = {
'file': (file_path, file, 'text/plain') # 确保文件以适当的MIME类型上传
}
data = {
"user": user,
# "type": "TXT" # type 参数在 v0.6 已废弃，由后端自动判断
}
response = requests.post(upload_url, headers=headers, files=files, data=data)
if response.status_code == 201: # 201 表示创建成功
print("文件上传成功")
return response.json().get("id") # 获取上传的文件 ID
else:
print(f"文件上传失败，状态码: {response.status_code}, 错误: {response.text}")
return None
except Exception as e:
print(f"发生错误: {str(e)}")
return None
def run_workflow(file_id, user, response_mode="blocking"):
workflow_url = "https://api.dify.ai/v1/workflows/run"
headers = {
"Authorization": "Bearer app-xxxxxxxxx", # 请替换为您的 API Key
"Content-Type": "application/json"
}
data = {
"inputs": {
"orig_mail": [{ # "orig_mail" 是示例变量名，请替换为您 workflow 中定义的变量名
"transfer_method": "local_file",
"upload_file_id": file_id,
"type": "document" # 根据实际文件类型填写 'document', 'image', 'audio', 'video', 'custom'
}]
},
"response_mode": response_mode,
"user": user
}
try:
print("运行工作流...")
response = requests.post(workflow_url, headers=headers, json=data)
if response.status_code == 200:
print("工作流执行成功")
return response.json()
else:
print(f"工作流执行失败，状态码: {response.status_code}, 错误: {response.text}")
return {"status": "error", "message": f"Failed to execute workflow, status code: {response.status_code}, error: {response.text}"}
except Exception as e:
print(f"发生错误: {str(e)}")
return {"status": "error", "message": str(e)}
# 使用示例
# file_path = "{your_file_path}" # 替换为您的文件路径
# user = "difyuser" # 替换为您的用户标识
# 上传文件
# file_id = upload_file(file_path, user)
# if file_id:
# # 文件上传成功，继续运行工作流
# result = run_workflow(file_id, user)
# print(result)
# else:
# print("文件上传失败，无法执行工作流")
```
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/workflows/run' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"inputs": {},
"response_mode": "streaming",
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Blocking
{
"workflow_run_id": "djflajgkldjgd",
"task_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"data": {
"id": "fdlsjfjejkghjda",
"workflow_id": "fldjaslkfjlsda",
"status": "succeeded",
"outputs": {
"text": "Nice to meet you."
},
"error": null,
"elapsed_time": 0.875,
"total_tokens": 3562,
"total_steps": 8,
"created_at": 1705407629,
"finished_at": 1727807631
}
}
```
```text Streaming
data: {"event": "workflow_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "sequence_number": 1, "created_at": 1679586595}}
data: {"event": "node_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "created_at": 1679586595}}
data: {"event": "node_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "execution_metadata": {"total_tokens": 63127864, "total_price": 2.378, "currency": "USD"}, "created_at": 1679586595}}
data: {"event": "workflow_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "total_tokens": 63127864, "total_steps": "1", "created_at": 1679586595, "finished_at": 1679976595}}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
</CodeGroup>
---
## 获取workflow执行情况
`GET /workflows/run/:workflow_run_id`
根据 workflow 执行 ID 获取 workflow 任务当前执行结果
### Path
- `workflow_run_id` (string) workflow_run_id，可在流式返回 Chunk 中获取
### Response
- `id` (string) workflow 执行 ID
- `workflow_id` (string) 关联的 Workflow ID
- `status` (string) 执行状态 `running` / `succeeded` / `failed` / `stopped`
- `inputs` (json) 任务输入内容
- `outputs` (json) 任务输出内容
- `error` (string) 错误原因
- `total_steps` (int) 任务执行总步数
- `total_tokens` (int) 任务执行总 tokens
- `created_at` (timestamp) 任务开始时间
- `finished_at` (timestamp) 任务结束时间
- `elapsed_time` (float) 耗时(s)
<CodeGroup>
```bash cURL
curl -X GET 'https://api.dify.ai/v1/workflows/run/:workflow_run_id' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "b1ad3277-089e-42c6-9dff-6820d94fbc76",
"workflow_id": "19eff89f-ec03-4f75-b0fc-897e7effea02",
"status": "succeeded",
"inputs": "{\"sys.files\": [], \"sys.user_id\": \"abc-123\"}",
"outputs": null,
"error": null,
"total_steps": 3,
"total_tokens": 0,
"created_at": 1705407629,
"finished_at": 1727807631,
"elapsed_time": 30.098514399956912
}
```
</CodeGroup>
---
## 停止响应
`POST /workflows/tasks/:task_id/stop`
仅支持流式模式。
### Path
- `task_id` (string) 任务 ID，可在流式返回 Chunk 中获取
### Request Body
- `user` (string) Required
用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。
### Response
- `result` (string) 固定返回 "success"
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/workflows/tasks/:task_id/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## 上传文件
`POST /files/upload`
上传文件并在发送消息时使用，可实现图文多模态理解。
支持您的工作流程所支持的任何格式。
<i>上传的文件仅供当前终端用户使用。</i>
### Request Body
该接口需使用 `multipart/form-data` 进行请求。
- `file` (file): 要上传的文件。
- `user` (string): 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。
### Response
成功上传后，服务器会返回文件的 ID 和相关信息。
- `id` (uuid) ID
- `name` (string) 文件名
- `size` (int) 文件大小（byte）
- `extension` (string) 文件后缀
- `mime_type` (string) 文件 mime-type
- `created_by` (uuid) 上传人 ID
- `created_at` (timestamp) 上传时间
### Errors
- 400，`no_file_uploaded`，必须提供文件
- 400，`too_many_files`，目前只接受一个文件
- 400，`unsupported_preview`，该文件不支持预览
- 400，`unsupported_estimate`，该文件不支持估算
- 413，`file_too_large`，文件太大
- 415，`unsupported_file_type`，不支持的扩展名，当前只接受文档类文件
- 503，`s3_connection_failed`，无法连接到 S3 服务
- 503，`s3_permission_denied`，无权限上传文件到 S3
- 503，`s3_file_too_large`，文件超出 S3 大小限制
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/files/upload' \
--header 'Authorization: Bearer {api_key}' \
--form 'file=@"/path/to/file"' \
--form 'user="abc-123"'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "abc-123",
"created_at": 1577836800
}
```
</CodeGroup>
---
## 获取 workflow 日志
`GET /workflows/logs`
倒序返回workflow日志
### Query
- `keyword` (string): 关键字
- `status` (string): 执行状态 succeeded/failed/stopped
- `page` (int): 当前页码, 默认1.
- `limit` (int): 每页条数, 默认20.
### Response
- `page` (int) 当前页码
- `limit` (int) 每页条数
- `total` (int) 总条数
- `has_more` (bool) 是否还有更多数据
- `data` (array[object]) 当前页码的数据
- `id` (string) 标识
- `workflow_run` (object) Workflow 执行日志
- `id` (string) 标识
- `version` (string) 版本
- `status` (string) 执行状态, `running` / `succeeded` / `failed` / `stopped`
- `error` (string) (可选) 错误
- `elapsed_time` (float) 耗时，单位秒
- `total_tokens` (int) 消耗的token数量
- `total_steps` (int) 执行步骤长度
- `created_at` (timestamp) 开始时间
- `finished_at` (timestamp) 结束时间
- `created_from` (string) 来源
- `created_by_role` (string) 角色
- `created_by_account` (string) (可选) 帐号
- `created_by_end_user` (object) 用户
- `id` (string) 标识
- `type` (string) 类型
- `is_anonymous` (bool) 是否匿名
- `session_id` (string) 会话标识
- `created_at` (timestamp) 创建时间
<CodeGroup>
```bash cURL
curl -X GET 'https://api.dify.ai/v1/workflows/logs?limit=1' \
--header 'Authorization: Bearer {api_key}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"page": 1,
"limit": 1,
"total": 7,
"has_more": true,
"data": [
{
"id": "e41b93f1-7ca2-40fd-b3a8-999aeb499cc0",
"workflow_run": {
"id": "c0640fc8-03ef-4481-a96c-8a13b732a36e",
"version": "2024-08-01 12:17:09.771832",
"status": "succeeded",
"error": null,
"elapsed_time": 1.3588523610014818,
"total_tokens": 0,
"total_steps": 3,
"created_at": 1726139643,
"finished_at": 1726139644
},
"created_from": "service-api",
"created_by_role": "end_user",
"created_by_account": null,
"created_by_end_user": {
"id": "7f7d9117-dd9d-441d-8970-87e5e7e687a3",
"type": "service_api",
"is_anonymous": false,
"session_id": "abc-123"
},
"created_at": 1726139644
}
]
}
```
</CodeGroup>
---
## 获取应用基本信息
`GET /info`
用于获取应用的基本信息
### Response
- `name` (string) 应用名称
- `description` (string) 应用描述
- `tags` (array[string]) 应用标签
<CodeGroup>
```bash cURL
curl -X GET 'https://api.dify.ai/v1/info' \
-H 'Authorization: Bearer {api_key}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}
```
</CodeGroup>
---
## 获取应用参数
`GET /parameters`
用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。
### Response
- `user_input_form` (array[object]) 用户输入表单配置
- `text-input` (object) 文本输入控件
- `label` (string) 控件展示标签名
- `variable` (string) 控件 ID
- `required` (bool) 是否必填
- `default` (string) 默认值
- `paragraph` (object) 段落文本输入控件
- `label` (string) 控件展示标签名
- `variable` (string) 控件 ID
- `required` (bool) 是否必填
- `default` (string) 默认值
- `select` (object) 下拉控件
- `label` (string) 控件展示标签名
- `variable` (string) 控件 ID
- `required` (bool) 是否必填
- `default` (string) 默认值
- `options` (array[string]) 选项值
- `file_upload` (object) 文件上传配置
- `image` (object) 图片设置
当前仅支持图片类型：`png`, `jpg`, `jpeg`, `webp`, `gif`
- `enabled` (bool) 是否开启
- `number_limits` (int) 图片数量限制，默认 3
- `transfer_methods` (array[string]) 传递方式列表，remote_url , local_file，必选一个
- `system_parameters` (object) 系统参数
- `file_size_limit` (int) 文档上传大小限制 (MB)
- `image_file_size_limit` (int) 图片文件上传大小限制（MB）
- `audio_file_size_limit` (int) 音频文件上传大小限制 (MB)
- `video_file_size_limit` (int) 视频文件上传大小限制 (MB)
<CodeGroup>
```bash cURL
curl -X GET 'https://api.dify.ai/v1/parameters' \
--header 'Authorization: Bearer {api_key}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"user_input_form": [
{
"paragraph": {
"label": "Query",
"variable": "query",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": false,
"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
}
}
```
</CodeGroup>

27
docs.json
View File

@@ -594,6 +594,15 @@
"pages": [
"en/termbase/termbase"
]
},
{
"tab": "API Access",
"pages": [
"api_access/chat.en",
"api_access/chatflow.en",
"api_access/completion.en",
"api_access/workflow.en"
]
}
]
},
@@ -1215,6 +1224,15 @@
"pages": [
"zh-hans/termbase/termbase"
]
},
{
"tab": "访问 API",
"pages": [
"api_access/chat.zh",
"api_access/chatflow.zh",
"api_access/completion.zh",
"api_access/workflow.zh"
]
}
]
},
@@ -1678,6 +1696,15 @@
"pages": [
"ja-jp/termbase/termbase"
]
},
{
"tab": "APIアクセス",
"pages": [
"api_access/chat.ja",
"api_access/chatflow.ja",
"api_access/completion.ja",
"api_access/workflow.ja"
]
}
]
},