室谷今回はDifyのファイル操作について話しましょう。.AI（ドットエーアイ）のコミュニティでも「ワークフローで生成した結果をファイルとして出力したい」「ユーザーにPDFを返したい」という声が増えてきていて・・・
テキトー教師増えてますね。講座でも「Difyでファイルを扱うにはどうするんですか？」という質問が毎回出ます。
DifyはLLMとのチャットや文章生成のイメージが強いので、「ファイルを返せるの？」と驚く方が多い。
DifyはLLMとのチャットや文章生成のイメージが強いので、「ファイルを返せるの？」と驚く方が多い。
室谷そうなんですよね。実はDifyはかなりしっかりファイルを扱えます。
ただ「どこで何ができるか」がドキュメントに散らばっていて、全体像が見えにくい。今回はその整理をしていきましょう。
ただ「どこで何ができるか」がドキュメントに散らばっていて、全体像が見えにくい。今回はその整理をしていきましょう。
テキトー教師前回はDifyのナレッジベースについて学びましたが、今回はファイルのダウンロード・出力に絞って深掘りしていきます。Difyでファイルを扱うには、大きく5つのシーン別に考えると整理しやすいです。
- ファイルアップロード変数 — ユーザーから受け取るファイルを変数として扱う
- Outputノードのfile型 — ワークフローの実行結果としてファイルを返す
- HTTPリクエストノード — 外部サービスからファイルをダウンロードする
- API経由のファイル操作 — REST APIでファイルをアップロード・ダウンロードする
- DSLファイルの出力 — ワークフロー設定をYAMLファイルとして書き出す
室谷この5つがごっちゃになっているケースが多いんですよね。「ファイルをダウンロードしたい」と言っても、何をダウンロードしたいかによって全然アプローチが変わります。
テキトー教師まさにそこが混乱ポイントです。順番に整理していきましょう。
Difyのファイル変数とは何か
室谷まず大前提として、Difyにおける「ファイル変数」の概念を理解する必要があります。Difyのワークフローやチャットフローでは、変数にファイルを持たせることができます。
テキトー教師これ、テキスト変数や数値変数と同じ扱いで、ファイルも「変数の型のひとつ」として存在するんですよね。Difyのドキュメントを確認すると、Outputノードでサポートされる変数型は
string, number, integer, boolean, object, file, array[string], array[file] などがあります（より）。室谷ファイル変数はDify内部でIDとURLを持ちます。前段のノードでアップロードされたファイルや、HTTPリクエストノードで取得したファイルを後続ノードに渡せる。
これがDifyのファイル操作の基本です。
これがDifyのファイル操作の基本です。
テキトー教師コードノードやHTTPリクエストノードからファイルをOutputノードに渡してユーザーに返す、という流れが一番よく使われるパターンですね。
室谷DifyのHTTPリクエストノードのドキュメントには、「ファイルのダウンロードは自動的に処理され、ダウンロードされたファイルは後続のノードで利用可能なファイル変数になる」と書いてあります。これを知っているかどうかで、できることが全然変わってくる。
テキトー教師そうなんです。「Difyはファイルを出力できない」と思っている人が多いのはもったいないですよね。
ユーザーからファイルを受け取る：Startノードのファイルアップロード設定
テキトー教師まずはユーザーからファイルを受け取る側から見ていきましょう。DifyのStartノード（トリガーノード）では、ファイルアップロードを入力変数として設定できます。
室谷これがDifyのドキュメントアップロード機能のベースになっている部分ですね。PDFや画像、CSVを入力として受け取れる。
テキトー教師設定の流れはこうです。
- Startノードを開く
- 入力フィールドに「File」型の変数を追加する
- 許可するファイル種別（画像・ドキュメント等）を選ぶ
- 後続のノードでその変数を参照する
室谷ファイルアップロードを許可する種別は、
image、document（PDF、Word、Excelなど）、audio、video があります。自分のワークフローで使う用途に合わせて設定します。テキトー教師講座でよく聞かれるのが「複数のファイルを同時に受け取れますか？」という質問ですが、複数ファイルは
array[file] 型の変数で受け取れます。室谷Difyのナレッジベース機能と組み合わせれば、ユーザーがアップロードしたファイルを一時的なドキュメントとして使う「ChatPDF」的なワークフローも作れます。Document Extractorノードでテキストを抽出して、LLMに渡す流れです。
テキトー教師Document Extractorノードのサポート形式は豊富です。TXT、Markdown、HTML、DOCX、PDF（テキスト系）、Excel、CSV、PowerPoint、EPUBなどに対応しています（より）。
PDF+AI要約のワークフローを作る場合、このノードが必須になります。
PDF+AI要約のワークフローを作る場合、このノードが必須になります。
室谷ただし、コードノードのサンドボックス環境はファイルシステムへのアクセスが制限されているので注意が必要です。ローカルファイルの直接操作はセキュリティ上できない。
テキトー教師ここ、コミュニティのメンバーさんがよくハマるポイントです。「Pythonコードでファイルを開こうとしたらエラーになる」というやつですね。
ワークフローの実行結果をファイルで返す：Outputノードのfile型
室谷次に、ワークフローの実行結果をファイルとして返す方法です。DifyのOutputノード（以前はEndノードと呼ばれていました）では、変数型としてfileを選択できます。
テキトー教師これを使うことで、ワークフローの実行結果としてファイルをAPIレスポンスに含められます。例えばHTTPリクエストノードで外部APIから取得したPDFをそのままユーザーに返す、というパターンです。
室谷APIレスポンスの構造はシンプルで、
outputs オブジェクトの中に変数名をキーとして値が入ります。file型の場合、ファイルのメタデータ（ID、URL、MIMEタイプなど）がJSON形式で返ってきます。テキトー教師ここで注意が必要なのが、OutputノードはワークフローのEnd（終了）じゃないという点です。最新のDifyでは「Outputノードがないと実行結果がAPIに返らない」けど、「Outputノードでワークフローが止まるわけではない」。
室谷これ、v1.0以降で仕様が変わったんですよね。以前のEndノードはワークフローの終了を意味していたけど、今のOutputノードは「結果を返す」だけで、並列ブランチは引き続き実行される。
テキトー教師ドキュメントにも「The Output node does not stop workflow execution—other parallel branches (if any) continue running after it completes.」と書かれています。
室谷MYUUUでもファイルを返すワークフローをいくつか作っていますが、OutputノードのAPIレスポンス構造を把握していると、フロントエンド側での実装がだいぶ楽になります。
HTTPリクエストノードで外部ファイルをダウンロードする
テキトー教師次はHTTPリクエストノードを使ったファイルダウンロードです。外部のAPIからPDFや画像を取得して、次のノードに渡すパターンです。
室谷これ、使いこなせるかどうかでDifyでできることが一気に広がるんですよね。HTTPリクエストノードはファイルレスポンスを自動検出してくれます。
テキトー教師具体的には、レスポンスの
Content-Disposition ヘッダーや MIMEタイプを見て、バイナリコンテンツはファイル変数として扱ってくれます。公式ドキュメントには「Text-based responses (JSON, XML, HTML, etc.) are treated as regular data, while binary content becomes file variables.」と書かれています（より）。室谷つまり、
https://example.com/report.pdf にGETリクエストを投げるだけで、自動的にファイル変数として扱われる。この変数を次のノードに渡したり、OutputノードでAPIレスポンスに含めたりできます。テキトー教師実際の使い方の例を整理するとこうなります。
| ユースケース | 方法 |
|---|---|
| 外部APIのPDFをダウンロードして処理 | HTTPリクエストノード(GET) → Document Extractor → LLM |
| S3などのクラウドストレージからCSVを取得 | HTTPリクエストノード(GET) + 署名付きURL |
| 生成したドキュメントをSlackに添付 | LLM → コードノード → HTTPリクエストノード(POST) |
| 外部サービスにファイルをアップロード | ファイル変数 → HTTPリクエストノード(POST/binary) |
室谷ファイルのアップロードも同じノードでできます。
Binary ボディタイプを選択して、前のノードからのファイル変数を選ぶだけです。テキトー教師Google DriveやDropboxのAPIと組み合わせれば、「ユーザーがアップロードしたファイルを処理してクラウドストレージに保存する」といったワークフローも組めます。
室谷室谷のツイートでも紹介しましたが、n8nと組み合わせてGoogleドライブへのファイルアップロードを検知 → DifyでAI処理 → 結果をGoogleドライブに保存、という完全自動化フローが作れます。これが実務レベルの活用方法です。
Dify APIでファイルをアップロード・ダウンロードする
テキトー教師ここからはDifyをAPIとして使う場合のファイル操作の話をしていきましょう。開発者がDifyを外部から呼び出すときに関係してくる部分です。
室谷アプリに組み込む場合とか、バックエンドから呼び出す場合ですね。DifyのAPIには専用のファイルエンドポイントがあります。
テキトー教師ファイルのアップロードは
POST /files/upload、ダウンロードは GET /files/{file_id}/preview です（より）。室谷ファイルアップロードAPIの仕様はこんな感じです。
POST /files/upload
Content-Type: multipart/form-data
Authorization: Bearer {API_KEY}
-- file: [アップロードするファイル]
-- user: [ユーザーID]
レスポンスに含まれる id が、その後のワークフロー実行時に使えるファイルIDです。
テキトー教師ワークフロー実行APIでファイルを渡すときは、
inputs の中にファイル型変数のキーを入れます。{
"inputs": {
"file_variable_name": {
"type": "document",
"transfer_method": "local_file",
"upload_file_id": "ここに/files/uploadで取得したID"
}
},
"user": "user-123",
"response_mode": "blocking"
}
transfer_method が local_file の場合は事前にアップロードが必要で、remote_url の場合は直接URLを指定できます。外部のS3リンクや公開URLなら後者の方が楽ですね。テキトー教師remote_url を使うときは url フィールドにURLを入れます。ただし、ネットワークアクセスできないURL（ローカルネットワークのみ等）は使えません。室谷ダウンロード側ですが、
セキュリティ面でちゃんと考えられていますね。
GET /files/{file_id}/preview はアップロードAPIで取得したIDに対してのみ機能します。別のアプリでアップロードしたファイルは取得できない設計です。セキュリティ面でちゃんと考えられていますね。
テキトー教師ナレッジベース側にはまた別のダウンロードAPIがあります。
GET /datasets/{dataset_id}/documents/{document_id}/download でドキュメントをダウンロードでき、複数まとめて取りたい場合は POST /datasets/{dataset_id}/documents/download-zip でZIPとしてまとめてダウンロードできます（より）。室谷ナレッジベースのバックアップを定期的に取りたい場合はこのAPIが便利です。
DSLファイルのダウンロードとインポート
室谷次に「DSLファイルのダウンロード」の話をしましょう。Difyのワークフロー設定はDSL（Domain Specific Language）形式のYAMLファイルでエクスポートできます。
これが
これが
dify dslファイル ダウンロード とか dify dslファイル インポート で検索している人が求めているものです。テキトー教師DSLファイルは、ワークフローの設定を丸ごとYAML形式で書き出したものです。これを別のDifyインスタンスにインポートすれば、同じワークフローを再現できます。
チーム共有や環境移行のときに使います。
チーム共有や環境移行のときに使います。
室谷室谷もDSLファイルを配布することがよくあります。DSLファイルさえあれば、Difyを使っている人なら誰でも同じワークフローを手元で動かせる。
テキトー教師DSLファイルのダウンロード方法はシンプルです。
UIからDSLファイルをダウンロードする手順
- Difyのスタジオページを開く
- 対象のアプリにカーソルを合わせる
- 右クリックメニューか「...」から「Export DSL」を選ぶ
- または、アプリの編集画面（オーケストレーション画面）左上の「Export DSL」をクリック
室谷エクスポートされるのはワークフローの設定情報（ノードの配置、プロンプト、モデルパラメータ）です。APIキーのような機密情報はデフォルトではエクスポートされません。
Secretタイプの環境変数は「含めるかどうか」を選べます。
Secretタイプの環境変数は「含めるかどうか」を選べます。
テキトー教師インポート（読み込み）のほうはこちらです。
DSLファイルをインポートする手順
- Difyのスタジオページの「+新しいアプリ」または「アプリを作成」を選ぶ
- 「DSLファイルからインポート」を選択
- YAMLファイルをアップロードする
- バージョン互換性の確認が行われ、インポートが完了する
室谷DSLのバージョンはv0.6以降が現在の標準です。クラウド版（SaaS）は常に最新バージョンのDSLが使われますが、セルフホスト版ではバージョンの差異に注意が必要です。
テキトー教師「dify dslファイル」で詰まりやすいのが、古いバージョンのDSLを新しいDifyにインポートしようとする場合です。警告が出ても多くの場合はインポート自体はできますが、一部のノード設定が反映されないことがあります。
複数アプリのDSLを一括ダウンロードする（コンソールAPI活用）
室谷アプリが多くなってくると、UIで一つずつエクスポートするのが大変になります。そこで使えるのがDifyの内部API（Console API）を使った一括ダウンロードです。
テキトー教師これ、知っている人が少ないんですよね。Difyには公開されているAPP API（ワークフロー実行用）とは別に、ダッシュボードの内部処理を担うCONSOLE APIがあります。
このAPIを使えばプログラム的に全アプリのDSLを取得できます。
このAPIを使えばプログラム的に全アプリのDSLを取得できます。
室谷実用的なユースケースとしては、定期バックアップ自動化や、本番環境から開発環境への設定同期があります。MYUUUでも複数のDifyプロジェクトを運用しているので、こういった自動化は地味に重要なんですよね。
テキトー教師CONSOLE APIはDifyのWebUIが内部的に使っているAPIです。Pythonスクリプトで認証セッションを取得してから、アプリ一覧を取得→各アプリのDSLをダウンロードという手順で実装できます。
室谷ただし、CONSOLE APIは公式に公開されているものではないので、バージョンアップで仕様が変わる可能性があります。実務で使う場合はその点を踏まえて実装する必要があります。
コードノードとPythonライブラリでファイルを操作する
テキトー教師コードノードについてはさっき少し触れましたが、改めて整理しましょう。DifyのコードノードはPythonとJavaScriptをサポートしています。
室谷重要な制約として、コードノードのサンドボックスはファイルシステムへのアクセスを制限しています。ドキュメントにも「Code executes in a strict sandbox that prevents file system access, network requests, and system commands.」と明記されています（より）。
テキトー教師これが「dify コード実行 ファイル」で詰まる人の原因です。ローカルファイルを
open() で開こうとしてもできない。室谷ではコードノードでファイル関連の何ができるかというと・・・
テキトー教師テキストデータの変換・整形はできます。例えばCSVの文字列を受け取って、JSONに変換してOutputに返すとか、Markdownを整形するとか。
室谷json、math、datetime、re などの標準ライブラリは使えます。加えて、numpy、pandas、requests（ただしネットワークアクセスは制限あり）などの外部ライブラリも事前インストールされているものは使えます。テキトー教師dify python ライブラリ 追加 で調べている人もいますが、コードノードで使えるライブラリは基本的に事前インストールされているものに限られます。自由にインストールすることは（クラウド版では）できません。室谷セルフホスト版であれば、サンドボックスのDockerイメージをカスタマイズすることで追加ライブラリを使えるようにはなりますが、これはかなり上級者向けです。
テキトー教師実務的なアドバイスとしては、「ファイルの生成や保存が必要な処理はコードノードではなく、HTTPリクエストノードで外部APIを呼ぶ」というアプローチが安全です。
ナレッジベースのファイルをダウンロードする
室谷ナレッジベース（RAG機能）に登録したファイルのダウンロードについても触れておきましょう。
dify ナレッジ ファイル ダウンロード で検索している人が求めているのがここです。テキトー教師ナレッジベースには自分でドキュメントをアップロードして、LLMが参照できるようにする機能です。このドキュメントをAPIで取得できます。
室谷APIとしては
GET /datasets/{dataset_id}/documents でドキュメント一覧を取得して、個別ダウンロードは GET /datasets/{dataset_id}/documents/{document_id}/download で取得できます。複数をまとめたい場合は先ほど触れたZIPダウンロードAPIを使います。テキトー教師ナレッジベースのAPIキーはDifyのナレッジAPIキー（Knowledge API Key）を使います。通常のワークフロー用APIキーとは別なので注意が必要です。
室谷dify pdf ダウンロード や dify csv ダウンロード と検索している方は多くの場合、「ナレッジベースに登録したPDFやCSVを取り出したい」というケースが多いと思います。テキトー教師ナレッジベースに登録したドキュメントは、元のファイル形式で取り出せます。PDFを登録したらPDFで、CSVを登録したらCSVで返ってきます。
セルフホスト版のローカルファイル操作
室谷最後にセルフホスト版特有の話をしましょう。
dify ローカル ファイル 操作 や dify python ファイル 読み込み で検索している人はほぼセルフホスト版ユーザーです。テキトー教師セルフホスト版のDifyはDockerで動いているので、コンテナ内のファイルシステムはホストマシンとは分離されています。ここがローカルファイルアクセスの難しさの原因です。
室谷Docker Composeのボリュームマウントを設定することで、ホストマシンのフォルダをDifyのコンテナ内に見せることができます。ただ、コードノードのサンドボックスはさらに別のコンテナで動いているので、そこからもアクセスするには追加の設定が必要です。
テキトー教師コミュニティのメンバーさんからよく聞くのが「Difyのワークフローで処理した結果をサーバー上のファイルに保存したい」という要望です。この場合、コードノードで直接ファイルを書くのではなく、HTTPリクエストノードで自前のAPIエンドポイントを叩いてファイル保存を行うアーキテクチャが推奨されます。
室谷「ファイルの書き込みはDify外の仕組みに任せる」という設計思想ですね。Difyはあくまでオーケストレーター（指揮者）として使い、ファイル操作の実行は別のマイクロサービスやサーバーレス関数に委譲する。
テキトー教師これがDifyを実務で使いこなす上での重要な考え方だと思います。Difyに全部やらせようとすると制限に当たる。
どこをDifyがやって、どこを別のシステムに委ねるかを設計する力が問われます。
どこをDifyがやって、どこを別のシステムに委ねるかを設計する力が問われます。
よくあるトラブルと解決策
室谷実際にファイル操作を実装する中でよく出てくるエラーを整理しておきましょう。
テキトー教師一番多いのは「コードノードでファイルを開こうとしてエラーになる」ですね。原因はサンドボックスによるファイルシステムアクセス制限です。
| トラブル | 原因 | 解決策 |
|---|---|---|
open() でファイルを開けない | コードノードのサンドボックス制限 | HTTPリクエストノードで外部APIを経由する |
| ファイルアップロードに失敗する | ファイルサイズ制限（デフォルト15MB） | セルフホスト版はdocker-compose.yamlで変更可能 |
| DSLインポート後にノードが見つからない | Difyのバージョン不一致 | Difyをアップデートするか、古いバージョンのDSLを使用 |
file_idが見つからないエラー | 別アプリのファイルIDを使用している | 同じアプリで発行したfile_idを使う |
| HTTPリクエストでファイルが変数にならない | レスポンスがテキスト形式 | Content-Typeがバイナリ形式か確認する |
室谷dify ファイルアップロード 失敗 で調べている人の多くは、ファイルサイズ制限にひっかかっているケースが多いです。セルフホスト版ではnginx.confのclient_max_body_sizeを変更することで上限を引き上げられます。テキトー教師dify ファイルアップロード できない の別パターンとして、ファイル種別が許可されていないケースもあります。Startノードでどのファイル種別を受け付けるかを設定していないと、アップロード自体ができません。室谷あとは
dify ファイル url 関係で「ファイルのURLを取得して別のサービスに渡したい」という質問もよく来ます。ファイルアップロードAPIのレスポンスに source_url と preview_url が含まれているので、これを使います。テキトー教師preview_url は一時的なURLで、有効期限があります。永続的にアクセスしたい場合は自前のストレージ（S3等）に保存してURLを管理する必要があります。FAQ
室谷よくある質問をまとめてお答えします。
Q: DifyワークフローでPDFを生成してダウンロードさせることはできますか？
室谷「LLMで生成したテキストをPDFにしてダウンロードさせる」というのは、現時点のDifyの標準機能だけでは難しいです。PDF生成の処理はコードノードやDifyのサンドボックスで直接できない。
テキトー教師実現するなら、LLMの出力テキストをHTTPリクエストノードでPDF生成API（WeasyPrintやPuppeteerを使った自前API、または外部サービス）に送信して、返ってきたPDFファイルをOutputノードに渡す、という構成になります。
Q: Difyのチャットフローでファイルを返せますか？
テキトー教師チャットフローにはOutputノードがなく、Answerノードを使います。Answerノードはテキストの返却が主目的なので、ファイルそのものを「チャット画面でダウンロードさせる」のは標準機能では難しいです。
室谷チャットインターフェースでファイルを出力したい場合は、ファイルへのリンクURLをMarkdown形式でAnswerノードに渡すのが現実的なアプローチです。
Q: DifyのAPIで生成した画像をダウンロードするには？
室谷画像生成AIとDifyを組み合わせた場合、生成した画像URLをOutputノードで返すのが基本です。その後、クライアント側でURLに対してGETリクエストを投げてダウンロードします。
テキトー教師dify 画像 ダウンロード で調べている方は、多くの場合この流れで解決します。Dify側はあくまでURLを返すまでが仕事で、ダウンロード処理はクライアント側で行います。Q: dify ファイルアップロード URLとはどういう意味ですか？
テキトー教師これは
transfer_method: remote_url の話です。ファイルをサーバー上にアップロードする代わりに、公開URLを直接指定してファイルを渡す方法です。dify ファイルアップロード url や dify ファイル url で調べている方はこれを求めているケースが多いです。室谷S3の署名付きURLやCDNのURLを直接指定できるので、大きなファイルを扱うときに便利です。ただし、Difyのサーバーからアクセスできる公開URLである必要があります。
まとめ
室谷では今回のまとめをしましょう。Difyのファイルダウンロード・出力は「何をしたいか」によってアプローチが全然変わります。
テキトー教師整理するとこういう対応になります。
| やりたいこと | 使う機能 |
|---|---|
| ユーザーからファイルを受け取る | Startノードのfile型変数 |
| 外部サービスのファイルを取得する | HTTPリクエストノード(GET) |
| ワークフロー結果としてファイルを返す | OutputノードのFile型変数 |
| APIからファイルをアップロード | POST /files/upload |
| APIからファイルをダウンロード | GET /files/{file_id}/preview |
| DSLファイルを書き出す | UIの「Export DSL」 |
| ナレッジのドキュメントを取得 | Knowledge API |
室谷「Difyでファイルを出力できない」と思っていた方に、できることのイメージが伝わったなら嬉しいです。制限はありますが、アーキテクチャの設計次第でかなりのことができます。
テキトー教師コードノードでファイルを直接操作しようとして詰まっている方は、「HTTPリクエストノードで外部APIを呼ぶ」という発想の転換が突破口になります。
室谷.AI（ドットエーアイ）のコミュニティでも、Difyのより高度な使い方について情報共有しています。ファイル操作以外にも困っていることがあれば、ぜひコミュニティで聞いてみてください。
出典
- Dify公式ドキュメント: Output Node
- Dify公式ドキュメント: HTTP Request Node
- Dify公式ドキュメント: Code Node
- Dify公式ドキュメント: Document Extractor Node
- Dify公式APIリファレンス: Upload File
- Dify公式APIリファレンス: Download File
- Dify公式APIリファレンス: Download Documents as ZIP
- Dify公式ドキュメント: App Management (DSL export/import)
- Dify公式APIリファレンス: Run Workflow
