Files
dify-docs/api_access/completion.ja.mdx
2025-05-12 02:41:59 +08:00

520 lines
22 KiB
Plaintext
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: テキスト ジェネレーター
---
テキスト生成アプリケーションはセッションレスをサポートし、翻訳、記事作成、要約 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>
{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}
<CardGroup cols="2">
<Card
title="Edit this page"
icon="pen-to-square"
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/api_access/completion.ja.mdx"
>
Help improve our documentation by contributing directly
</Card>
<Card
title="Report an issue"
icon="github"
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=Documentation%20Issue%3A%20etion&body=%23%23%20Issue%20Description%0A%3C%21--%20Please%20briefly%20describe%20the%20issue%20you%20found%20--%3E%0A%0A%23%23%20Page%20Link%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fapi_access%2Fcompletion.ja.mdx%0A%0A%23%23%20Suggested%20Changes%0A%3C%21--%20If%20you%20have%20specific%20suggestions%20for%20changes%2C%20please%20describe%20them%20here%20--%3E%0A%0A%3C%21--%20Thank%20you%20for%20helping%20improve%20our%20documentation%21%20--%3E"
>
Found an error or have suggestions? Let us know
</Card>
</CardGroup>