# 公開と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利用量やエラー率は定期的にモニタリングし、必要に応じてプランのアップグレードやキーのローテーションを行ってください。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalhumans.jp/dify-guide/chatflow/dify-docs-publish-and-api-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.