OpenAI Vision

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.

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

{
  "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 }}.

Example Configuration

Describe an image piped in from an upstream node:

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

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

{
  "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. It is the right tool when a workflow requires visual understanding of images from URLs, binary data, or an OpenAI file ID. Each analysis produces an output JSON object containing the response text and usage metadata.