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

> Node: Grok Vision (`grok_vision`) · Action (binary) · v1
> Category: AI · Credentials: xAI (`xai`)
> Updated: 2026-08-16

# Grok Vision

> Analyze images using xAI Grok's vision capabilities.

## Overview

Sends an image — from binary data attached to the item, or from a URL — along with a text prompt to xAI's Grok API, and returns the model's text analysis of the image. The response text is stored in a configurable output field (default: "response") along with the model name and token usage.

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

**Appearance:** Icon: `brain` | Color: `#000000`

## Node Type

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

## Input / Output

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

## Credentials

This tool requires **xAI** credentials.
See the [Credentials Guide](https://busybot.net/credentials/xai/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Model | `options` | No | Platform default | The Grok vision model to use for image analysis. |
| | | | | Options: the Grok chat models currently available — the dropdown tracks the model catalog, so it changes as xAI's line-up changes. |
| System Prompt | `string` | No | — | Optional system message to set the model's behavior and context for image analysis. Supports expressions like {{ $json.persona }}. |
| User Message | `string` | No | `Describe this image in detail` | The text prompt to send alongside the image. Describes what analysis to perform. Supports expressions. |
| Image Source | `options` | No | `binary` | Where to get the image — from binary data in the input item or from a URL. |
| | | | | Options: `binary` (read image from binary data attached to the input item), `url` (provide an image URL for Grok to analyze) |
| 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 | — | URL of the image to analyze. Falls back to item.imageUrl if empty. Supports expressions. _(shown when Image Source is `url`)_ |
| Options | `collection` | No | `{}` | Optional generation and output settings — add only the fields you want to override. |
| — Max Tokens | `number` | No | `4096` | Maximum number of tokens to generate in the response. |
| — Temperature | `number` | No | — | Sampling temperature (0-2). Lower values are more deterministic. Left unset, the model's own default applies. |
| — Image Detail | `options` | No | `auto` | Controls the detail level for image processing. "auto" lets the model decide. |
| | | | | Options: `auto` (automatically determine detail level), `low` (faster processing, lower cost), `high` (best quality, higher cost) |
| — Response Field Name | `string` | No | `response` | The output field name where the vision analysis text will be stored. |
| Include Input | `boolean` | No | `false` | Whether to include the original input item fields in the output alongside the response. |
| Max Concurrency | `number` | No | `5` | Maximum number of items to process concurrently. Lower values recommended for vision due to larger payloads. |

## Output Data

One output item per input item. The analysis text is written to the field named by Response Field Name (`response` by default). The rest of the input JSON is carried over only when Include Input is on; the input item's binary data is forwarded untouched — this node reads images, it does not produce them.

- `response` — the model's text analysis of the image, under whatever name Response Field Name is set to.
- `model` — the model that produced the analysis.
- `usage` — the token counts reported by xAI for the request.

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

## Usage Examples

- Describe what is in an uploaded image using Grok
- Extract text from a screenshot with Grok vision
- Classify product images by category
- Analyze social media images for content
- Identify objects in photos from URLs

## Example Configuration

Describe an image that arrived as binary data:

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

Read fine detail out of a screenshot and keep the source fields:

```json
{
  "type": "grok_vision",
  "parameters": {
    "imageSource": "binary",
    "binaryPropertyName": "screenshot",
    "systemPrompt": "You are an OCR engine. Extract all text exactly as it appears.",
    "userMessage": "Extract all text from this document image.",
    "includeInput": true,
    "maxConcurrency": 2,
    "options": {
      "maxTokens": 4096,
      "temperature": 0,
      "detail": "high",
      "responseFieldName": "extractedText"
    }
  }
}
```

Classify remote images cheaply, one per item:

```json
{
  "type": "grok_vision",
  "parameters": {
    "imageSource": "url",
    "imageUrl": "{{ $json.imageUrl }}",
    "systemPrompt": "Classify the image as one of: electronics, clothing, furniture, food, other. Reply with only the category.",
    "userMessage": "What category does this product belong to?",
    "includeInput": true,
    "options": {
      "maxTokens": 16,
      "temperature": 0,
      "detail": "low",
      "responseFieldName": "category"
    }
  }
}
```

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

Grok Vision analyzes images by sending binary data or direct URL references alongside a text prompt to the xAI Grok completions API, supporting base64-encoded data URIs. Use it when a workflow step requires visual understanding, such as reading text in images, describing scenes, or answering questions grounded in visual content. Produces a configurable output field containing the model text analysis, along with the model name and token usage statistics.