> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dify-guide/chatflow/dify-docs-publish-and-api-integration.md).

# 公開とAPI連携

チャットフローで作成した対話アプリ（デジタルヒューマン対話システム）を、実運用で利用するための**公開方法**と、外部システムから呼び出すための**API連携**について解説します。

{% hint style="warning" %}
本ドキュメントはDifyの一般的な仕様に基づいています。Difyは頻繁にアップデートされるため、パラメータ名やエンドポイントの詳細は必ず\*\*Dify管理画面の「APIアクセス」\*\*ページにある最新の仕様書を参照してください。
{% endhint %}

## 1. 公開方法の種類

利用シーンに合わせて以下の3つの方法から選択します。

| 公開方法             | 特徴                                                 | 推奨シーン                      |
| ---------------- | -------------------------------------------------- | -------------------------- |
| **Webアプリとして公開**  | <p>Difyが提供するホスティング機能を使用する。<br>URLを共有するだけで利用可能。</p> | 社内検証、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/v1`
  * OSS版: `http://{your-domain}/v1`

{% hint style="warning" %}
デジタルヒューマン環境をご利用の場合、API Base URLはご契約内容によって異なります。デジタルヒューマン株式会社またはご担当のパートナー・リセラーにご確認ください。
{% endhint %}

* **API Key**

  ![](/files/rhWZYv9JvvjKWT3yjmuW)

  * アプリ管理画面の「APIアクセス」からAPIキーを発行します。
  * リクエストヘッダーに `Authorization: Bearer {API_KEY}` を含めて認証します。
* **DIP側でのendpoint\_base\_url設定**

  DIP（Digital Humans Identity Portal）上でNLPアカウントからプロファイルを選択し、`endpoint_base_url` キーに、DifyのAPI Base URLの値を入力してください。

  ![](/files/4E3ytlYz6Rg3VyiCbbTn)

  ![](/files/6qfvtIgtTPierpf7ptAW)

{% hint style="info" %}
API連携についてDIPおよびデジタルヒューマンの設定は以下を参照してください。

<https://docs.digitalhumans.jp/connect-dify>
{% endhint %}

### 3.2 主要なAPIエンドポイント

| アプリタイプ                   | エンドポイント                     | 用途                   |
| ------------------------ | --------------------------- | -------------------- |
| **Chat App**             | `POST /chat-messages`       | 会話型アプリ。文脈を保持して対話を行う。 |
| **Workflow / Generator** | `POST /completion-messages` | 一問一答型やテキスト生成アプリ。     |

## 4. リクエストパラメータの詳細

![](/files/zwHh1uQ7AzwGtCGPOkvM)

`POST /chat-messages` の代表的なパラメータは以下の通りです。

* **query** (必須): ユーザーからの入力テキスト。
* **user** (必須): ユーザー識別子。エンドユーザーを一意に特定するID（例: `user-123`）。ログ分析やレート制限の基準になります。
* **inputs** (任意): アプリ内で定義した変数（Variables）に値を渡すためのオブジェクト。
  * 例: プロンプト内に`{{topic}}`という変数がある場合、`"inputs": {"topic": "科学"}` のように指定します。
  * 変数がない場合でも、空のオブジェクト`{}`が推奨されることがあります。
* **response\_mode** (必須):
  * `streaming`: ストリーミング形式（SSE）で逐次レスポンスを受け取る。
  * `blocking`: 処理完了後にJSONを一括で受け取る。

{% hint style="info" %}
**パラメータの対応関係**

DifyとDIPでは、ストリーミング設定のパラメータ名・値が異なります。

\| DifyのAPIパラメータ | DIPのパラメータ |\
\| --- | --- |\
\| `response_mode: streaming` （推奨） | `stream: true`（推奨） |\
\| `response_mode: blocking` | `stream: false` |
{% endhint %}

* **conversation\_id** (任意): 会話を継続する場合に指定します。初回リクエスト時は空にし、レスポンスに含まれるIDを2回目以降にセットします。
* **files** (任意): 画像などを送信する場合に使用します（マルチモーダル対応モデルが必要）。

{% hint style="info" %}
**実装ヒント**: 管理画面の「APIアクセス」>「APIリファレンス」で、現在のアプリ設定に基づいた具体的な`curl`コマンド例が確認できます。
{% endhint %}

## 5. ストリーミングと会話管理

### 5.1 ストリーミング (SSE) の活用

デジタルヒューマンなどのリアルタイム性が求められる用途では、`response_mode: "streaming"` が必須です。

* **Server-Sent Events (SSE)** 形式でデータがチャンク（断片）ごとに届きます。
* テキスト生成と並行して音声合成（TTS）やリップシンク処理を開始することで、待機時間を大幅に短縮できます。

### 5.2 会話の継続（セッション）

1. **初回**: `conversation_id` なしでリクエスト。
2. **応答**: レスポンスJSON内の `conversation_id` を保存。
3. **継続**: 次のリクエストのbodyに `conversation_id` を含めることで、Difyが文脈（コンテキスト）を維持しながら、会話を継続できます。

## 6. 運用とセキュリティのベストプラクティス

### 6.1 APIキーの保護

* APIキーは\*\*サーバーサイド（Backend）\*\*で管理してください。フロントエンド（ブラウザやアプリ内）に埋め込むと、キーが漏洩し不正利用されるリスクがあります。

### 6.2 エラーハンドリングとレート制限

* **429 Too Many Requests**: プランごとのリクエスト上限に達した場合に発生します。バックオフ（待機時間）を入れたリトライ処理を実装してください。
* タイムアウト設定は長め（数十秒〜）に確保するか、ストリーミング受信でタイムアウトを防ぐ設計にします。
* APIレスポンスの`answer`部分をデジタルヒューマンの発話テキストとして利用します。

### 6.3 監視

* Dify管理画面の「ログ」機能でユーザーの会話履歴を確認できます。
* API利用量やエラー率は定期的にモニタリングし、必要に応じてプランのアップグレードやキーのローテーションを行ってください。