Skip to main content

File Input

workflow-code supports file input via executor params declaration. Desktop, server, and external calls upload the file first, and then parse the file content through the file reference in workflow.

file param​

params: [
  {
    name: "images",
    flag: "--images",
    type: "file",
    multiple: true,
    accept: ["image/png", "image/jpeg", "image/webp"],
    format: "json",
    required: false,
    description: "Image attachment.",
  },
]

The value of the file param is serialized as a JSON string to createInput.

FileInputNode​

const imageInputNode = workflow.createFileInputNode({
  name: "images",
  accept: ["image/png", "image/jpeg", "image/webp"],
  multiple: true,
});

const images = await workflow.runNode(imageInputNode, input.images, context);
const imageParts = await Promise.all(images.map((file) => file.toLLMImagePart()));

createFileInputNode will resolve the reference through context.files and return WorkflowResolvedFile[].

WorkflowResolvedFile​

Parsed file support:

file.readBuffer()
file.readBase64()
file.readDataUrl()
file.toLLMImagePart()
file.toJSON()

toLLMImagePart() only accepts image files; non-images throw an input validation error.

Runtime build file​

workflow When generating screenshots, exports, or other files while running, use context.files.createFile(...)：

const file = await context.files?.createFile?.({
  name: "frame.png",
  mimeType: "image/png",
  buffer,
  kind: "image",
});

The server/web run will automatically inject the server management file storage, and the returned reference is available. /api/workflows/files/{fileId} Open. Desktop/CLI run locally on connected server When proxying to the same server file API; When the server is not connected, the call will throw an error and will not Run the generated file and drop it to the local store. Local resolution of input attachments still continues through context.files.resolveFile(...) work.

Storage Recommendations​

Do not save base64 file contents into KV or session history. Save the reference metadata returned by file.toJSON() when cross-round multiplexing is required.

workspace/workflow/gpt-image The example uses the same file param process to receive one or more reference images: workflow resolves to WorkflowResolvedFile[] when there is a current picture or an input picture reference in the recent session history And call the picture editing; no picture context at all to call the picture generation. This example turns on conversation mode, and the cross wheel only turns on User prompts, generate summaries, and file.toJSON() reference metadata to write session history; subsequent rounds try to parse the most recent input image Reference and pass it to the picture editor as a context reference diagram. The sample locally retains up to 16 pictures for input. Generate results Markdown The preview of data:image/...;base64,... in output item is returned, and the generated graph base64 is not written into session KV, Therefore, the generated graph itself will not automatically become the next round of picture input. When you need to generate files across pages or repositories, you should use context.files.createFile(...) Generate server file reference.

Desktop and server behavior​

  • A local Desktop run uploads the attachment to local file storage, with storage: "local".
  • The server management interface POST /api/workflows/{name}/files saves the running file, and the storage field is server.
  • Runtime-generated files use server file references. Desktop and CLI upload them automatically when connected to Server and report an error when no Server connection is available.
  • GET /api/workflows/files/{fileId} can read or download the server file.

If conversation workflow has conversation.defaultInput.attachments enabled, share Pasting, dragging and uploading pictures/files in the composer also reuse the same file reference protocol. The host will first The browser/Electron File writes the local or server managed file store, and then writes the reference back to the fixed parameter --images / --files;workflow side continues to press normal file param or workflow.parseConversationDefaultInputArgs(args) can be resolved.

MCP file parameters​

Local stdio MCP file parameters accept absolute paths, with an array of absolute paths for multiple files. The host verifies regular files and the 50 MB limit before importing them into the local managed-file store. Relative paths, URLs, and Base64 are rejected.

Server Streamable HTTP MCP file parameters accept { "id": "<file-id>" }, with an array of those objects for multiple files. Upload through POST /api/workflows/{workflowName}/files first, then pass only the returned ID to the tool. Server rereads authoritative metadata and verifies ownership by the current project; it never trusts a submitted name, type, or path. See the Server MCP guide for a complete example.

External API files​

The outer Dify style /workflows/run receives the files field and saves it to the run metadata. Whether the specific workflow uses a file, it needs to be aligned by inputs or args and executor params.