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

> Node: OpenAI File Upload (`openai_file_upload`) · Action (binary) · v1
> Category: AI · Credentials: OpenAI (`openai`)
> Updated: 2026-08-16

# OpenAI File Upload

> Upload files to OpenAI for use with assistants, fine-tuning, and batch.

## Overview

OpenAI File Upload uses the OpenAI Files API (POST /files) to upload files for various purposes including assistants, fine-tuning, batch processing, and vision. Accepts binary file input and uploads it as multipart/form-data with a specified purpose. Returns the file object with id, filename, bytes, purpose, and status metadata. The file ID can be used in subsequent OpenAI API calls.

**Category:** AI  
**Tool Name:** `openai_file_upload`  
**Version:** 1

**Appearance:** Icon: `openai` | Color: `#10a37f`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **OpenAI** credentials.
See the [Credentials Guide](https://busybot.net/credentials/openai/) 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. |
| Purpose | `options` | No | `assistants` | The intended purpose of the uploaded file. This determines how OpenAI processes and validates the file. |
| | | | | Options: `assistants` (use with OpenAI Assistants), `fine-tune` (training file for fine-tuning a model), `batch` (input file for batch processing), `vision` (image file for vision analysis) |
| Options | `collection` | No | `{}` | Optional output settings — add only the fields you need. |
| — 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 output item per input item. The full file object lands on the field named by **Response Field Name** (`file` by default), and the two fields you almost always need — `fileId` and `fileName` — are lifted to the top level. The rest of the input item JSON is dropped unless **Include Input** is on; the input binary is forwarded unchanged.

```json
{
  "file": {
    "id": "file-abc123",
    "object": "file",
    "bytes": 120432,
    "filename": "training.jsonl",
    "purpose": "fine-tune",
    "status": "processed"
  },
  "fileId": "file-abc123",
  "fileName": "training.jsonl"
}
```

- `fileId` is the value other OpenAI nodes expect. Wire it into **OpenAI Chat**, **OpenAI Reasoning**, **OpenAI Structured Output**, **OpenAI Vision** or **OpenAI Code Interpreter** as `{{ $json.fileId }}`.
- Uploading the same file twice creates two distinct file IDs — OpenAI does not deduplicate. Upload once and reuse the ID across runs where you can.

## Usage Examples

- Upload a JSONL file for fine-tuning an OpenAI model
- Upload a document for use with an OpenAI assistant
- Upload a batch processing input file to OpenAI
- Upload an image file for OpenAI vision analysis
- Upload training data and get the file ID for a fine-tuning job

## Example Configuration

Upload a file arriving on the default binary property:

```json
{
  "type": "openai_file_upload",
  "parameters": {
    "binaryPropertyName": "data",
    "purpose": "assistants"
  }
}
```

Upload fine-tuning data and keep the original item fields:

```json
{
  "type": "openai_file_upload",
  "parameters": {
    "binaryPropertyName": "trainingFile",
    "purpose": "fine-tune",
    "includeInput": true,
    "options": {
      "responseFieldName": "uploadedFile"
    }
  }
}
```

Upload an image for a later vision step:

```json
{
  "type": "openai_file_upload",
  "parameters": {
    "binaryPropertyName": "photo",
    "purpose": "vision",
    "maxConcurrency": 10
  }
}
```

### 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

OpenAI File Upload sends binary files to the OpenAI Files API as multipart/form-data with a specified purpose such as assistants, fine-tuning, batch processing, or vision. Use this tool when a downstream OpenAI operation requires a pre-uploaded file reference, such as attaching documents to an assistant or supplying training data for a fine-tune job. It returns a file object with the id, filename, byte size, purpose, and status fields, where the file id is passed directly into subsequent OpenAI API calls.