<!-- BusyBot node reference — https://busybot.net/tools/gemini-file-upload/ -->

> Node: Gemini File Upload (`gemini_file_upload`) · Action (binary) · v1
> Category: AI · Credentials: Google AI (`googleAi`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/google-ai/) 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.

```json
{
  "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:

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

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

```json
{
  "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:

```json
{
  "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.