DifyのAPIの使い方|APIキーの発行・リクエスト例・ストリーミングと料金の上限

DifyのAPIキーと呼び出し方

DifyのAPIは、公開済みのアプリを呼び出したり、ナレッジを操作したりするための仕組みです。自分のプログラムやサービスから利用できます。Webアプリとして使っているのと同じアプリを、自社のシステムの裏側(サーバー)から動かせます。

この記事では、Dify Cloudの公式ドキュメントをもとに、次の内容を説明します。料金と上限は2026年11月時点の表示です。

  • Dify APIでできること(チャット・ワークフロー・テキスト生成・ナレッジのAPI)
  • APIキーの発行場所と、公式ドキュメントに載っているリクエストの例
  • ストリーミングとブロッキングの違い、会話ID(conversation_id)の使い方
  • プランごとのAPIの呼び出し上限と、APIキーを管理するときの注意点

画面の名前は公式ドキュメントの日本語版の表記に合わせています。日本語版のドキュメントは自動翻訳のため、実際の画面の表記と違う場合があります。Difyの概要は「Difyとは?読み方・できること・料金・始め方」で説明しています。

目次

Dify APIでできること

公式ドキュメントでは、Difyで公開したアプリは、そのままREST API(URLにリクエストを送ってデータをやり取りする仕組み)としても使えると説明されています。ナレッジも同じようにAPIで操作できます。使うAPIは、アプリの種類によって変わります。

Dify API:キーは自分のサーバーで扱う
スクロールできます
API対象主なエンドポイントできること
チャットチャットフロー、チャットボット、AgentPOST /chat-messagesメッセージを送って回答を受け取る。会話の一覧や履歴も取得できる
ワークフローワークフローPOST /workflows/run公開中のワークフローを入力値つきで実行し、結果を受け取る
テキスト生成テキストジェネレーターPOST /completion-messages入力値をもとに文章を1回生成する。会話は引き継がない
ナレッジナレッジベースPOST /datasets/{dataset_id}/retrieve などナレッジベースの作成、文書の追加・更新、検索をプログラムから行う

このほか、アプリの基本情報の取得(GET /info)、入力欄の名前や種類の取得(GET /parameters)、ファイルのアップロード、音声と文字の変換、回答への評価(フィードバック)のAPIもあります。アプリの種類と違うAPIを呼ぶと、エラーになります。

Dify APIを使う前の準備

APIで呼び出せるのは、公開したアプリです。ワークフローを実行するAPIは、公開済みのワークフローを動かします。編集中の内容は、「公開する」→「更新を公開」を選ぶまでAPIには反映されません。アプリの作り方と公開の手順は「Difyの使い方」で説明しています。

アプリのAPIキーを発行する

アプリのAPIキーは、そのアプリの中で作成します。公式のチュートリアルでは、アプリの「アクセスポイント」でAPIキーを取得すると案内されています。キーはそのアプリ1つだけに使え、1つのキーで、アプリを使うすべての利用者のリクエストを送れます。

利用者ごとの区別は、APIキーではなく、リクエストに入れるuserの値で行います(あとの「会話IDとuserの扱い」で説明します)。

ナレッジのAPIキーを発行する

ナレッジのAPIキーは、アプリのキーとは別に発行します。「ナレッジ」の画面で右上の「サービスAPI」を選び、「APIキー」から作成します。同じ画面に、ナレッジのAPIのベースURL(サービスAPIエンドポイント)も表示されます。

  • 作成できる人:ワークスペースのオーナーと管理者だけが、キーを作成・表示・削除できます
  • 作成できる数:1つのワークスペースで10個までです
  • アクセス範囲:すべてのナレッジベースか、選んだナレッジベースだけかを、作成時に決めます。あとから変更できないため、変えるときは新しいキーを作り直します

ナレッジベースの一覧の取得や新規作成など、特定のナレッジベースを指定しない操作を使う場合は、すべてのナレッジベースを対象にしたキーが必要です。また、ナレッジベースごとに左下の「APIアクセス」をオフにすると、どのキーからもそのナレッジベースを操作できなくなります。

リクエストを送る先(ベースURL)

Dify CloudのAPIのベースURLはhttps://api.dify.ai/v1です。APIキーは、ほとんどのリクエストで「Bearerトークン」としてAuthorizationヘッダーに入れて送ります。自分のサーバーでDifyを動かしている場合は、ベースURLを自分の環境のAPIのURLに置き換えます。セルフホストの導入方法は「Difyのセルフホスト方法」で説明しています。

Dify APIのリクエストの例

ここで紹介するコードは、公式ドキュメントの例をもとにしています。チャットの例は初回の呼び出しに使えるよう、既存の会話IDを省いています。質問文や入力値は、アプリに合わせて変更してください。

APIキーが使えるかを確認する

公式のクイックスタートでは、最初の確認として、アプリの基本情報を取得するAPIを呼び出します。どの種類のアプリでも使えます。ターミナル(コマンドを入力する画面)から送る場合の例は次のとおりです。

curl https://api.dify.ai/v1/info \
  -H "Authorization: Bearer $DIFY_API_KEY"

$DIFY_API_KEYは、APIキーをDIFY_API_KEYという環境変数に入れておき、その値を読み込む書き方です。キーが有効なら、アプリの名前・説明・種類(mode)などが返ってきて、どのアプリのキーかを確認できます。公式ドキュメントのページの「試す(Try it)」から、コードを書かずに送ることもできます。

チャット系のアプリにメッセージを送る

チャットフロー・チャットボット・Agentのアプリには、/chat-messagesにメッセージを送ります。次はチャットフロー・チャットボット向けのブロッキングモードの例です。AgentとレガシーAgentでは、response_modeをstreamingにします。

curl --request POST \
  --url https://{api_base_url}/chat-messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": {},
  "query": "What are the specs of the iPhone 13 Pro Max?",
  "response_mode": "blocking",
  "user": "abc-123"
}
'

{api_base_url}はDify Cloudならapi.dify.ai/v1、<token>はアプリのAPIキーに置き換えます。送る項目は次のとおりです。

スクロールできます
項目必須内容
query必須利用者のメッセージ
inputs必須アプリの入力欄に入れる値。変数名をキーにして指定する。入力欄が無ければ空の{}
user必須利用者を区別する識別子。アプリ側で決める
response_mode任意streamingかblocking。省略するとブロッキング
conversation_id任意続ける会話のID。省略するか空にすると新しい会話になる
files任意メッセージに添付するファイル(画像・文書など)

ブロッキングモードの応答には、回答の本文(answer)、会話ID(conversation_id)、メッセージID(message_id)のほか、使ったトークン数や、ナレッジから参照した資料の情報(metadata)が入ります。

ワークフローを実行する

ワークフローのアプリは、/workflows/runで実行します。公式ドキュメントのブロッキングモードの例は次のとおりです。

curl --request POST \
  --url https://{api_base_url}/workflows/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": {
    "query": "Translate this to French: Hello world"
  },
  "response_mode": "blocking",
  "user": "user_workflow_456"
}
'

inputsには、ワークフローの「ユーザー入力」ノードで作った入力欄の変数名と値を入れます(この例ではqueryという変数)。変数名と種類が分からないときは、GET /parametersで取得できます。必須の項目はinputsとuserです。

応答には、実行結果(outputs)、状態(status)、かかった時間、使ったトークン数が入ります。あわせて、実行中の処理を止めるときに使うtask_idと、実行の記録を指すworkflow_run_idも返ります。ワークフローは呼び出しごとに独立して動き、前回の実行内容は引き継ぎません。

テキスト生成アプリとナレッジのAPI

テキストジェネレーターのアプリは、/completion-messagesにinputsとuserを送ります。呼び出しごとに1回文章を返し、会話は引き継ぎません。

ナレッジのAPIでは、ナレッジベースのIDをURLのdataset_idに入れます。IDは、Difyでナレッジベースを開いたときのURLの/datasets/のあとの部分で確認できます。文書を追加するAPIは処理が終わるのを待たずに応答を返すため、公式ドキュメントでは、返ってきたbatchのIDでインデックスの状態を確認し、completedかerrorになるまで待つ流れが説明されています。

Dify APIのストリーミングとブロッキングの違い

文章を生成するAPIは、response_modeで応答の受け取り方を選べます。

スクロールできます
項目ブロッキング(blocking)ストリーミング(streaming)
受け取り方生成が終わってから、結果をまとめて1回で受け取る生成しながら、少しずつ受け取る(Server-Sent Events)
向いている使い方短い処理、画面に表示しない処理利用者に見せる回答、時間のかかる処理
注意点長い処理は途中で接続が切れることがある受け取ったデータを順番に組み立てる処理が必要

response_modeを省略するとブロッキングになりますが、公式ドキュメントではストリーミングが推奨されています。Dify Cloudでは、応答が一定の時間内に返らないと、途中の中継サーバー(エッジプロキシ)が接続を切ることがあるためです。なお、AgentとレガシーAgentのアプリはストリーミングだけに対応しています。

ストリーミングの応答の読み方

ストリーミングでは、応答がdata: で始まる行として届き、1行に1つのJSONが入ります。公式ドキュメントで説明されている主な決まりは次のとおりです。

  • 回答の本文:チャットボットとチャットフローではmessageのイベントを順番につなげます
  • 終わりの合図:チャットボットはmessage_end、チャットフローはmessage_endのあとにworkflow_finished、ワークフローはworkflow_finishedで終わります
  • 接続の維持:中身のないevent: pingの行が、およそ10秒ごとに届きます。読み飛ばしてかまいません
  • 途中のエラー:ストリームが始まったあとに失敗しても、HTTPのステータスは200のままです。失敗はerrorのイベントや、status: "failed"の付いたイベントで届きます

curlで試すときは、-N(--no-buffer)を付けると、届いた順に表示されます。ワークフローとチャットフローでは、接続が途中で切れても、workflow_run_idと同じuserを使えば、実行の続きのイベントを受け取り直せます。

Dify APIの会話ID(conversation_id)とuserの扱い

会話を続けるときは会話IDを送る

チャット系のアプリで、前のやり取りを踏まえて会話を続けるには、会話IDを使います。

  1. 最初のメッセージはconversation_idを省略するか、空の文字列で送る(新しい会話になる)
  2. 応答に入っているconversation_idを保存する
  3. 次のメッセージから、保存したconversation_idを付けて送る

以前の会話を再開したいときは、会話の一覧を取得するAPIでIDを調べられます。会話が終了済みというエラー(conversation_completed)が返った場合は、conversation_idを付けずに新しい会話を始めます。

userは利用者ごとに同じ値を使う

userは、APIを呼び出す側が決める利用者の識別子です。Difyはこの値が本人かどうかを確認しないため、公式ドキュメントでは、アカウントIDなど、1人ごとに変わらない値を毎回同じように送るよう案内されています。

  • 会話の一覧・履歴・名前の変更・削除は、同じuserの会話だけが対象になります
  • アップロードしたファイルは、アップロードしたuserのものとして扱われます
  • APIで作られた会話と、DifyのWebアプリで作られた会話は別々に管理され、互いに表示されません

Dify APIの料金と呼び出し上限

Dify CloudのAPIは、無料のSandboxプランでも使えます。2026年11月時点の料金ページでは、プランごとの上限は次のとおりです。

スクロールできます
項目SandboxProfessionalTeam
Dify APIの呼び出し上限月5,000回レート制限なしレート制限なし
ナレッジへのリクエスト1分あたり10回1分あたり100回1分あたり1,000回
メッセージクレジット200(1回限り)月5,000月10,000

APIから呼び出した場合も、アプリの中でAIモデルを呼び出すたびにクレジットを消費します。自分のAPIキーを追加したモデルなら、Difyのクレジットではなく、モデルの提供元の料金がかかります。プランごとの料金とクレジットの消費量は「Difyの料金プラン」で説明しています。

ナレッジへのリクエストの上限は、ワークスペース全体で数えます。公式ドキュメントによると、従来型のナレッジベースでは、APIでの文書・チャンク・メタデータの変更や検索のほか、ワークフローやチャットフローの「知識検索」ノードが実行されるたびにも数えられます。上限に達したあとの失敗したリクエストも数えられるため、公式ドキュメントでは、すぐに再試行せず1分待つよう案内されています。

このほか、チャットフローで公開済みの特定のバージョンを指定して実行する機能(workflow_idの指定)は、Dify Cloudでは有料プランが必要です。

Dify APIを使うときの注意点

APIキーはサーバー側だけで使う

公式ドキュメントでは、APIは自分のサーバー側(バックエンド)からだけ呼び出すよう注意されています。Webページのプログラムやスマートフォンのアプリにキーを埋め込むと、キーを抜き出されて悪用されるおそれがあるためです。アプリのAPIキーは、知っている人なら誰でもそのアプリを呼び出せるので、パスワードと同じように扱います。

APIキーを替えるときの順番

ナレッジのAPIキーについて、公式ドキュメントでは、キーの入れ替え(ローテーション)やアクセス範囲の変更を次の順番で行うよう案内されています。削除したキーはすぐに使えなくなるため、先に新しいキーへ切り替えておきます。

  1. 新しいキーを作る
  2. 連携しているプログラムを新しいキーに切り替える
  3. 古いキーを削除する

ナレッジのキーは、連携先が使うナレッジベースだけを対象にして作ると、キーが漏れたときに影響する範囲を小さくできます。

エラーの種類で対処を分ける

APIのエラーは、code・message・statusの3つの項目で返ります。公式ドキュメントで説明されている主なエラーと対処は次のとおりです。

スクロールできます
ステータス主な原因対処
400リクエストの内容の誤り。provider_not_initializeなどはアプリのモデル設定の問題リクエストを直す。モデル設定のエラーは、再試行せずDifyでモデルの設定を直す
401APIキーが無効、または削除されたキーを確認する。Dify Cloudでは、IPアクセス制御で止められた場合も401になる
403許可されていない操作、プランの上限。ナレッジのリクエストの上限もこのエラーmessageを読んで原因を区別する
404対象が無い、またはそのキーやuserからは見えないIDとuserの値を確認する
429too_many_requestsは同時に送ったリクエストが多すぎる。rate_limit_errorはプランの上限前者は間隔をあけて再試行する。後者は上限がリセットされるかプランを変えるまで解消しない
500Dify側の問題間隔をあけて再試行する

決まったネットワークからだけ使えるようにする

ProfessionalとTeamのプランでは、IPアクセス制御で、アプリを使える接続元のIPアドレスを限定できます。許可するアドレスを「IPポリシー」として作り、アプリの「アクセスポイント」の右上にある「アクセス制御」で、守りたいアクセスポイントに適用します。

送った文章はAIモデルの提供元へ送られる

アプリの中で外部のAIモデルに渡す文章やファイルは、そのモデルの提供元(OpenAIなど)へ送られます。個人情報や社外秘の情報を扱う場合は、使うモデルと提供元の取り扱いを確認してから連携します。

Dify APIに関するよくある質問

DifyのAPIキーと、OpenAIなどのAPIキーは何が違いますか?

別のものです。DifyのAPIキーは、Difyで作ったアプリやナレッジを外から呼び出すためのキーです。OpenAIやGeminiなどのAPIキーは、Difyの中でAIモデルを使うために、「統合」→「モデルプロバイダー」に登録するキーです。

無料プランでもDifyのAPIは使えますか?

使えます。2026年11月時点の料金ページでは、Sandboxプランの呼び出し上限は月5,000回です。ただし、クレジットは200の1回限りなので、AIモデルを使うアプリを何度も呼び出す場合は、クレジットの残りにも注意します。

セルフホストのDifyでも同じAPIを使えますか?

公式ドキュメントでは、セルフホストの場合はベースURLを自分の環境のAPIのURLに置き換えて使うと案内されています。料金ページの呼び出し上限は、Dify Cloudのプランの上限です。

curl以外の言語でも呼び出せますか?

Dify APIはHTTPでリクエストを送る仕組みなので、HTTPのリクエストを送れる言語なら呼び出せます。公式ドキュメントのストリーミングの説明には、Pythonでストリーミングの応答を読む例も載っています。

まとめ

Dify APIを使うと、公開済みのアプリを自分のプログラムから呼び出し、ナレッジの追加・検索も行えます。

  • アプリのAPIキーはアプリの「アクセスポイント」、ナレッジのAPIキーは「ナレッジ」→「サービスAPI」で発行する
  • Dify CloudのベースURLはhttps://api.dify.ai/v1。チャットは/chat-messages、ワークフローは/workflows/run
  • 応答の受け取り方は、公式ドキュメントが推奨するストリーミングを基本にする
  • 会話を続けるときはconversation_idを送り、userは利用者ごとに同じ値を使う
  • Sandboxプランの呼び出し上限は月5,000回。ProfessionalとTeamはレート制限なし(2026年11月時点)
  • APIキーはサーバー側だけで使い、入れ替えるときは新しいキーに切り替えてから古いキーを消す

まずはアプリの基本情報を取得するAPIでキーが使えることを確認し、次にブロッキングモードで1回呼び出して、応答の形を確認してみてください。Dify・n8n・Zapierの違いは「AI自動化ツールの選び方」で比べています。

ワークフローとチャットフローの違いは「Difyのワークフローとは?」、ナレッジの作り方は「DifyのRAGとは?」、ClaudeなどからMCPで呼び出す方法は「DifyのMCPの使い方」で説明しています。

この記事を書いた人

AI-Riseの企画・編集を担当。日常業務のあらゆる場面でAIをフル活用。AIツールの活用や業務自動化をテーマに、使い方・選び方・利用時の注意点をわかりやすく紹介しています。公式情報と実際の活用経験をもとに、便利な点だけでなく、費用や手間、できることの範囲も整理。仕事や日々の作業に合うツール選びをお手伝いします。

目次