公開とAPI連携
チャットフローで作成した対話アプリ（デジタルヒューマン対話システム）を、実運用で利用するための公開方法と、外部システムから呼び出すためのAPI連携について解説します。
本ドキュメントはDifyの一般的な仕様に基づいています。Difyは頻繁にアップデートされるため、パラメータ名やエンドポイントの詳細は必ず**Dify管理画面の「APIアクセス」**ページにある最新の仕様書を参照してください。
1. 公開方法の種類
利用シーンに合わせて以下の3つの方法から選択します。
Webアプリとして公開
Difyが提供するホスティング機能を使用する。 URLを共有するだけで利用可能。
社内検証、PoC、デモ用途
埋め込み (Embed)
既存のWebサイトにJavaScriptやiframeで埋め込む。
自社サイトやポータルへの簡易組み込み
API連携
Backend API経由で独自アプリケーションからDifyを呼び出す。
デジタルヒューマン、独自UI、モバイルアプリへの統合
2. Webアプリ公開の設定
アプリ編集画面の右上にある 「公開する」 ボタンから設定します。
2.1 アクセス制御
公開範囲: 公開（誰でもアクセス可能）または限定公開（パスワード保護）などが選択可能です。
運用推奨: 社外公開前は関係者のみに限定公開し、検証完了後に一般公開へ切り替える運用を推奨します。
2.2 UIカスタマイズ
アイコン、アプリ名、説明文、テーマカラーを設定し、ブランドイメージに合わせます。
必要に応じてフッターの著作権表示（Powered by Dify）のオン/オフを調整します（プランによる）。
3. API連携の実装
デジタルヒューマンや独自フロントエンドと連携する場合、APIアクセス機能を使用します。
3.1 認証とエンドポイント
Base URLの例
Cloud版:
https://api.dify.ai/v1OSS版:
http://{your-domain}/v1
デジタルヒューマン環境をご利用の場合、API Base URLはご契約内容によって異なります。デジタルヒューマン株式会社またはご担当のパートナー・リセラーにご確認ください。
API Key
アプリ管理画面の「APIアクセス」からAPIキーを発行します。
リクエストヘッダーに
Authorization: Bearer {API_KEY}を含めて認証します。
DIP側でのendpoint_base_url設定
DIP（Digital Humans Identity Portal）上でNLPアカウントからプロファイルを選択し、
endpoint_base_urlキーに、DifyのAPI Base URLの値を入力してください。
API連携についてDIPおよびデジタルヒューマンの設定は以下を参照してください。
3.2 主要なAPIエンドポイント
Chat App
POST /chat-messages
会話型アプリ。文脈を保持して対話を行う。
Workflow / Generator
POST /completion-messages
一問一答型やテキスト生成アプリ。
4. リクエストパラメータの詳細
POST /chat-messages の代表的なパラメータは以下の通りです。
query (必須): ユーザーからの入力テキスト。
user (必須): ユーザー識別子。エンドユーザーを一意に特定するID（例:
user-123）。ログ分析やレート制限の基準になります。inputs (任意): アプリ内で定義した変数（Variables）に値を渡すためのオブジェクト。
例: プロンプト内に
{{topic}}という変数がある場合、"inputs": {"topic": "科学"}のように指定します。変数がない場合でも、空のオブジェクト
{}が推奨されることがあります。
response_mode (必須):
streaming: ストリーミング形式（SSE）で逐次レスポンスを受け取る。blocking: 処理完了後にJSONを一括で受け取る。
パラメータの対応関係
DifyとDIPでは、ストリーミング設定のパラメータ名・値が異なります。
| DifyのAPIパラメータ | DIPのパラメータ |
| --- | --- |
| response_mode: streaming （推奨） | stream: true（推奨） |
| response_mode: blocking | stream: false |
conversation_id (任意): 会話を継続する場合に指定します。初回リクエスト時は空にし、レスポンスに含まれるIDを2回目以降にセットします。
files (任意): 画像などを送信する場合に使用します（マルチモーダル対応モデルが必要）。
実装ヒント: 管理画面の「APIアクセス」>「APIリファレンス」で、現在のアプリ設定に基づいた具体的なcurlコマンド例が確認できます。
5. ストリーミングと会話管理
5.1 ストリーミング (SSE) の活用
デジタルヒューマンなどのリアルタイム性が求められる用途では、response_mode: "streaming" が必須です。
Server-Sent Events (SSE) 形式でデータがチャンク（断片）ごとに届きます。
テキスト生成と並行して音声合成（TTS）やリップシンク処理を開始することで、待機時間を大幅に短縮できます。
5.2 会話の継続（セッション）
初回:
conversation_idなしでリクエスト。応答: レスポンスJSON内の
conversation_idを保存。継続: 次のリクエストのbodyに
conversation_idを含めることで、Difyが文脈（コンテキスト）を維持しながら、会話を継続できます。
6. 運用とセキュリティのベストプラクティス
6.1 APIキーの保護
APIキーは**サーバーサイド（Backend）**で管理してください。フロントエンド（ブラウザやアプリ内）に埋め込むと、キーが漏洩し不正利用されるリスクがあります。
6.2 エラーハンドリングとレート制限
429 Too Many Requests: プランごとのリクエスト上限に達した場合に発生します。バックオフ（待機時間）を入れたリトライ処理を実装してください。
タイムアウト設定は長め（数十秒〜）に確保するか、ストリーミング受信でタイムアウトを防ぐ設計にします。
APIレスポンスの
answer部分をデジタルヒューマンの発話テキストとして利用します。
6.3 監視
Dify管理画面の「ログ」機能でユーザーの会話履歴を確認できます。
API利用量やエラー率は定期的にモニタリングし、必要に応じてプランのアップグレードやキーのローテーションを行ってください。
最終更新