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

> Node: Gemini Structured Output (`gemini_structured_output`) · Action · v1
> Category: AI · Credentials: Google AI (`googleAi`)
> Updated: 2026-08-16

# Gemini Structured Output

> Get structured JSON responses with Gemini schema enforcement.

## Overview

Gemini Structured Output sends a message to a Google Gemini model with a JSON schema attached, forcing the model to answer with valid JSON that matches that schema. The schema is applied at generation time, so downstream nodes get predictable, typed data instead of free-form text that has to be parsed. The parsed object is written to a configurable field on the output item, together with the model name and token usage. Optional file references can be sent as multimodal context alongside the message.

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

**Appearance:** Icon: `gemini` | Color: `#ffffff`

## Node Type

**Action** — processes input items and produces output

## 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 |
|-----------|------|----------|---------|-------------|
| Model | `options` | No | — | The Gemini model to use for structured output generation. Pick a specific version — labels are pinned, not aliased to "latest". The dropdown lists the models currently available for this node; leave it unset to use the default. |
| System Prompt | `string` | No | — | Optional system instruction that sets the behavior and context for the model. Supports expressions. |
| User Message | `string` | Yes | — | The message to send to the Gemini model. Falls back to item.message or item.prompt if empty. Supports expressions. |
| File URIs | `string` | No | — | Optional. fileUri value(s) from the Gemini File Upload tool. Pass a single URI or a JSON array for multiple files. Files are sent as multimodal context alongside the message. Falls back to item.fileUris if empty. Gemini File API retains uploads for 48 hours. |
| JSON Schema | `json` | Yes | `{}` | The JSON Schema that the model response must conform to. Passed as generationConfig.responseSchema. Can be a JSON object or a string that will be parsed. |
| Options | `collection` | No | `{}` | Optional tuning for the generation request. |
| — Temperature | `number` | No | `1` | Controls randomness. Lower values are more deterministic, higher values are more creative. Range: 0-2. |
| — Max Output Tokens | `number` | No | `8192` | Maximum number of tokens in the generated response. |
| — Response Field Name | `string` | No | `structured` | The key name in the output JSON where the parsed structured response will be stored. |
| Include Input | `boolean` | No | `false` | Whether to merge the input item JSON into the output item. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. Binary data arriving from upstream is forwarded untouched.

The output item's JSON contains only the fields below. The input item's JSON is merged in **only** when Include Input is on:

| Field | Description |
|-------|-------------|
| `structured` | The parsed object the model returned, shaped by your JSON Schema. Renamed by **Response Field Name**. |
| `model` | The model that produced the response. |
| `usage` | Token usage metadata reported by the model. |

If the response cannot be parsed as JSON, the response field holds `_raw` (the raw text) and `_parseError` (why parsing failed) instead of your schema's keys — worth guarding for in a downstream branch if the workflow must not silently continue.

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

## Usage Examples

- Extract structured data from unstructured text using a JSON schema
- Parse entities from a document into a defined JSON format
- Generate structured product descriptions matching a schema
- Convert free-text responses into typed JSON objects
- Use Gemini to classify items and return results in a fixed schema

## Example Configuration

Minimal — a message and the schema it must satisfy:

```json
{
  "type": "gemini_structured_output",
  "parameters": {
    "userMessage": "Extract the key facts from the following text: {{ $json.text }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "facts": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "required": ["facts"]
    }
  }
}
```

Ticket triage with a system prompt, a renamed output field and the source data kept:

```json
{
  "type": "gemini_structured_output",
  "parameters": {
    "systemPrompt": "You are a precise data extraction assistant. Return only factual information present in the source text. Do not infer or hallucinate.",
    "userMessage": "Analyze the following customer support ticket and extract structured data:\n\n{{ $json.ticketBody }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "category": { "type": "string", "enum": ["billing", "technical", "account", "other"] },
        "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
        "issueDescription": { "type": "string" },
        "suggestedActions": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["category", "priority", "issueDescription", "suggestedActions"]
    },
    "includeInput": true,
    "maxConcurrency": 5,
    "options": {
      "temperature": 0.2,
      "maxOutputTokens": 1024,
      "responseFieldName": "ticketData"
    }
  }
}
```

Batch classification at temperature `0` for consistent labels:

```json
{
  "type": "gemini_structured_output",
  "parameters": {
    "userMessage": "Classify this product description into a single category: {{ $json.description }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "category": { "type": "string", "enum": ["electronics", "clothing", "food", "furniture", "other"] },
        "confidence": { "type": "number" }
      },
      "required": ["category", "confidence"]
    },
    "maxConcurrency": 20,
    "options": {
      "temperature": 0,
      "maxOutputTokens": 256,
      "responseFieldName": "classification"
    }
  }
}
```

Analyze an uploaded file by passing its URI from the Gemini File Upload node:

```json
{
  "type": "gemini_structured_output",
  "parameters": {
    "userMessage": "Extract the invoice number, total and due date from the attached document.",
    "fileUris": "{{ $json.fileUri }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "invoiceNumber": { "type": "string" },
        "total": { "type": "number" },
        "dueDate": { "type": "string" }
      },
      "required": ["invoiceNumber", "total"]
    }
  }
}
```

### 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 Structured Output sends a user message to the Google Gemini generateContent API with a strict JSON schema constraint, forcing the model to return syntactically valid, schema-conformant JSON. Use it when downstream workflow nodes require predictable, typed data structures rather than free-form text, such as extracting entities, classifying inputs, or populating structured records. It produces a parsed JSON object matching your schema, the model name used, and token usage metadata containing prompt and completion counts.