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

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

# OpenAI Vision

> Analyze images using the GPT-5.x frontier multimodal models.

## Overview

OpenAI Vision uses the Responses API (POST /responses) to analyze images with OpenAI natively multimodal models; the Model dropdown lists the vision-capable models currently available to the workspace. Images can come from the binary store (base64-encoded), from a URL, or by OpenAI file ID. Supports system prompts, detail level (auto/low/high), temperature, and max output tokens. Each input item receives a separate vision analysis. The response text is placed in a configurable field name in the output JSON, along with model and usage metadata.

**Category:** AI  
**Tool Name:** `openai_vision`  
**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 |
|-----------|------|----------|---------|-------------|
| Model | `options` | No | (current default) | The OpenAI model to use for image analysis. The GPT-5.x frontier line is natively multimodal — pick a specific pinned version. |
| | | | | Options: the OpenAI vision models available to your workspace — pick one from the dropdown. |
| System Prompt | `string` | No | — | System instructions that set the behavior and persona of the model. Leave empty for default behavior. Supports expressions. |
| User Message | `string` | No | `Describe this image in detail` | The question or instruction about the image. If empty, falls back to item.json.message. Supports expressions. |
| Image Source | `options` | No | `binary` | Where to get the image for analysis. |
| | | | | Options: `binary` (read the image from the binary store — uploaded or piped from another node), `url` (fetch the image from a URL), `fileId` (reference an image previously uploaded via openai_file_upload) |
| Binary Property Name | `string` | No | `data` | The name of the binary property containing the image data. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. _(shown when Image Source is `binary`)_ |
| Image URL | `string` | No | — | The URL of the image to analyze. If empty, falls back to item.json.imageUrl. Supports expressions. _(shown when Image Source is `url`)_ |
| Image File ID | `string` | No | — | OpenAI file ID (file-...) for a previously uploaded image. Falls back to item.json.imageFileId or item.json.attachmentFileId. Supports {{ $json.fileId }} expressions from an upstream openai_file_upload node. _(shown when Image Source is `fileId`)_ |
| Options | `collection` | No | `{}` | Optional analysis settings — add only the fields you need. |
| — Temperature | `number` | No | `1` | Sampling temperature (0-2). Lower values make output more focused and deterministic. |
| — Max Output Tokens | `number` | No | `4096` | Maximum number of tokens the model can generate in the response. |
| — Detail | `options` | No | `auto` | Image detail level. "high" uses more tokens but provides better analysis of fine details. |
| | | | | Options: `auto` (let the model decide), `low` (low-resolution analysis — faster, fewer tokens), `high` (high-resolution analysis — more detailed, more tokens) |
| — Response Field Name | `string` | No | `response` | Field name in the output JSON where the response text will be placed. |
| Include Input | `boolean` | No | `false` | Whether to include the original input item fields in the output alongside the response. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The analysis text lands on the field named by **Response Field Name** (`response` by default), with `model` and `usage` beside it. The rest of the input item JSON is dropped unless **Include Input** is on; binary data on the input item is forwarded unchanged, so the image travels with its description.

```json
{
  "response": "A description of what the model sees in the image",
  "model": "the model that produced the analysis",
  "usage": { "input_tokens": 1180, "output_tokens": 220 }
}
```

- Image tokens dominate `usage` on this node. Setting **Detail** to `low` is the single biggest cost lever for high-volume image pipelines.

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

## Usage Examples

- Describe the contents of an uploaded image
- Extract text from a screenshot using OCR
- Classify images by their content
- Analyze a chart or diagram from a URL
- Identify objects in photos from binary data

## Example Configuration

Describe an image piped in from an upstream node:

```json
{
  "type": "openai_vision",
  "parameters": {
    "imageSource": "binary",
    "binaryPropertyName": "data",
    "userMessage": "Describe this image in detail"
  }
}
```

Read a document image at high detail and keep the original fields:

```json
{
  "type": "openai_vision",
  "parameters": {
    "systemPrompt": "You are a precise document reader. Return only what is written.",
    "userMessage": "Extract the invoice number, date and total from this image.",
    "imageSource": "binary",
    "binaryPropertyName": "scan",
    "includeInput": true,
    "options": {
      "detail": "high",
      "temperature": 0,
      "responseFieldName": "invoiceText"
    }
  }
}
```

Classify images from URLs cheaply:

```json
{
  "type": "openai_vision",
  "parameters": {
    "userMessage": "Reply with one word: PRODUCT, PERSON, or OTHER.",
    "imageSource": "url",
    "imageUrl": "{{ $json.photoUrl }}",
    "maxConcurrency": 20,
    "options": {
      "detail": "low",
      "maxOutputTokens": 8,
      "responseFieldName": "imageClass"
    }
  }
}
```

### 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 Vision analyzes images using an OpenAI multimodal model — whichever option is picked in the Model dropdown — via the Responses API, with configurable detail level, system prompts, and temperature. Use it when a workflow needs visual understanding of images sourced from URLs, the binary store, or an OpenAI file ID returned by openai_file_upload, across one or more input items. Each item produces an output JSON object with response text in a configurable field, plus model identifier and token usage metadata, with failures routed to the error output.