Gemini File Upload

Upload files to Gemini File API for use in prompts.

Overview

Gemini File Upload uses the Google Gemini File API (POST /upload/v1beta/files) to upload files for use in Gemini model prompts. It takes a file from binary data on the incoming item and uploads it. Returns the file object with name, displayName, mimeType, sizeBytes, createTime, expirationTime, sha256Hash, uri, and state. The file URI can be used in subsequent Gemini API calls to reference the uploaded content — the Gemini nodes that take a File URIs parameter accept it directly, so a file is uploaded once and referenced many times.

Category: AI
Tool Name: gemini_file_upload
Version: 1

Appearance: Icon: gemini | Color: #ffffff

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires Google AI credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Binary Property Name	string	No	data	The name of the binary property containing the file to upload. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use. Supports expressions.
Display Name	string	No	—	A human-readable display name for the uploaded file. If empty, defaults to the original filename from binary metadata. Supports expressions.
Options	collection	No	{}	Output settings.
— Response Field Name	string	No	file	The output field name where the file upload response will be stored.
Include Input	boolean	No	false	Whether to include the original input item fields in the output alongside the upload response.
Max Concurrency	number	No	5	Maximum number of items to process concurrently.

Output Data

One upload per input item, and one output item per input item. The full file object lands on the field named by Response Field Name (file by default), and the two values downstream nodes actually need — the file URI and the stored name — are lifted onto fileUri and fileName. Binary data on the input item is forwarded unchanged, so the original bytes stay available downstream. With Include Input on, the original item fields are merged in alongside the result.

{
  "file": {
    "name": "files/abc123",
    "displayName": "contract.pdf",
    "mimeType": "application/pdf",
    "sizeBytes": "184320",
    "createTime": "2026-01-01T00:00:00Z",
    "expirationTime": "2026-01-03T00:00:00Z",
    "sha256Hash": "…",
    "uri": "https://generativelanguage.googleapis.com/v1beta/files/abc123",
    "state": "the processing state the API reported"
  },
  "fileUri": "https://generativelanguage.googleapis.com/v1beta/files/abc123",
  "fileName": "contract.pdf"
}

• fileUri is the same value as file.uri, promoted to the top level because that is what the downstream File URIs parameter asks for. Wire the upload into Gemini Chat, File Search, Code Execution, Google Search, Google Maps, Deep Research or Batch and set that parameter to {{ $json.fileUri }} — those nodes fall back to a plural fileUris field on the item, which this node does not write, so the expression is what connects the two.
• fileName is the display name the file was stored under — the value you passed in Display Name, or the original filename from the binary metadata when you left it empty.
• The item errors when the named binary property is missing, so check the upstream node’s Binary Data panel if uploads fail on every item.
• Uploads are retained by the Gemini File API for 48 hours. Upload inside the same run that consumes the file rather than storing a URI for later.

Reference the result downstream by expression, e.g. {{ $json.fileUri }}.

Usage Examples

• Upload an image for use in a Gemini vision prompt
• Upload a PDF document for Gemini to analyze
• Upload an audio file for Gemini multimodal processing
• Upload a video for Gemini to describe and analyze
• Upload files in bulk and get file URIs for batch prompts

Example Configuration

Minimal — upload the file on the standard data property:

{
  "type": "gemini_file_upload",
  "parameters": {
    "binaryPropertyName": "data"
  }
}

Upload with a meaningful name and keep the original item fields:

{
  "type": "gemini_file_upload",
  "parameters": {
    "binaryPropertyName": "data",
    "displayName": "{{ $json.title }}.pdf",
    "includeInput": true,
    "maxConcurrency": 5
  }
}

Batch upload attachments under a custom output field, at reduced concurrency:

{
  "type": "gemini_file_upload",
  "parameters": {
    "binaryPropertyName": "attachment",
    "includeInput": true,
    "maxConcurrency": 2,
    "options": {
      "responseFieldName": "geminiFile"
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Gemini File Upload sends binary files to the Google Gemini File API, making content available for use in Gemini model prompts. Use this tool when a workflow must supply images, documents, or other media to a Gemini inference call before the prompt is submitted. It returns a file object with name, displayName, uri, mimeType, sizeBytes, sha256Hash, state, createTime, and expirationTime fields for referencing the content in downstream Gemini API calls.