Output

The Output object provides output specifications for structured data generation with generateText and streamText. It allows you to specify the expected shape of the generated data and handles validation automatically.

import { generateText, Output } from 'ai';
import { z } from 'zod';


const { output } = await generateText({
  model: "anthropic/claude-sonnet-4.5",
  output: Output.object({
    schema: z.object({
      name: z.string(),
      age: z.number(),
    }),
  }),
  prompt: 'Generate a user profile.',
});

Import 

import { Output } from "ai"

Output Types

Output.text()

Output specification for plain text generation. This is the default behavior when no output is specified.

import { generateText, Output } from 'ai';


const { output } = await generateText({
  model: yourModel,
  output: Output.text(),
  prompt: 'Tell me a joke.',
});
// output is a string

Parameters

No parameters required.

Returns

An Output<string, string> specification that generates plain text without schema validation.

Output.object()

Output specification for typed object generation using schemas. The output is validated against the provided schema to ensure type safety.

import { generateText, Output } from 'ai';
import { z } from 'zod';


const { output } = await generateText({
  model: yourModel,
  output: Output.object({
    schema: z.object({
      name: z.string(),
      age: z.number().nullable(),
      labels: z.array(z.string()),
    }),
  }),
  prompt: 'Generate information for a test user.',
});
// output matches the schema type

Parameters

schema:

FlexibleSchema<OBJECT>
The schema that defines the structure of the object to generate. Supports Zod schemas, Valibot schemas, or JSON schemas.

Returns

An Output<OBJECT, DeepPartial<OBJECT>> specification where:

  • Complete output is fully validated against the schema
  • Partial output (during streaming) is a deep partial version of the schema type

Partial outputs streamed via streamText cannot be validated against your provided schema, as incomplete data may not yet conform to the expected structure.

Output.array()

Output specification for generating arrays of typed elements. Each element is validated against the provided element schema.

import { generateText, Output } from 'ai';
import { z } from 'zod';


const { output } = await generateText({
  model: yourModel,
  output: Output.array({
    element: z.object({
      location: z.string(),
      temperature: z.number(),
      condition: z.string(),
    }),
  }),
  prompt: 'List the weather for San Francisco and Paris.',
});
// output is an array of weather objects

Parameters

element:

FlexibleSchema<ELEMENT>
The schema that defines the structure of each array element. Supports Zod schemas, Valibot schemas, or JSON schemas.

Returns

An Output<Array<ELEMENT>, Array<ELEMENT>> specification where:

  • Complete output is an array with all elements validated
  • Partial output contains only fully validated elements (incomplete elements are excluded)

Streaming with elementStream

When using streamText with Output.array(), you can iterate over elements as they are generated using elementStream:

import { streamText, Output } from 'ai';
import { z } from 'zod';


const { elementStream } = streamText({
  model: yourModel,
  output: Output.array({
    element: z.object({
      name: z.string(),
      class: z.string(),
      description: z.string(),
    }),
  }),
  prompt: 'Generate 3 hero descriptions for a fantasy role playing game.',
});


for await (const hero of elementStream) {
  console.log(hero); // Each hero is complete and validated
}

Each element emitted by elementStream is complete and validated against your element schema, ensuring type safety for each item as it is generated.

Output.choice()

Output specification for selecting from a predefined set of string options. Useful for classification tasks or fixed-enum answers.

import { generateText, Output } from 'ai';


const { output } = await generateText({
  model: yourModel,
  output: Output.choice({
    options: ['sunny', 'rainy', 'snowy'],
  }),
  prompt: 'Is the weather sunny, rainy, or snowy today?',
});
// output is 'sunny' | 'rainy' | 'snowy'

Parameters

options:

Array<CHOICE>
An array of string options that the model can choose from. The output will be exactly one of these values.

Returns

An Output<CHOICE, CHOICE> specification where:

  • Complete output is validated to be exactly one of the provided options

Output.json()

Output specification for unstructured JSON generation. Use this when you want to generate arbitrary JSON without enforcing a specific schema.

import { generateText, Output } from 'ai';


const { output } = await generateText({
  model: yourModel,
  output: Output.json(),
  prompt:
    'For each city, return the current temperature and weather condition as a JSON object.',
});
// output is any valid JSON value

Parameters

No parameters required.

Returns

An Output<JSONValue, JSONValue> specification that:

  • Validates that the output is valid JSON
  • Does not enforce any specific structure

With Output.json(), the AI SDK only checks that the response is valid JSON; it doesn't validate the structure or types of the values. If you need schema validation, use Output.object() or Output.array() instead.

Error Handling

When generateText with structured output cannot generate a valid object, it throws a NoObjectGeneratedError.

import { generateText, Output, NoObjectGeneratedError } from 'ai';


try {
  await generateText({
    model: yourModel,
    output: Output.object({ schema }),
    prompt: 'Generate a user profile.',
  });
} catch (error) {
  if (NoObjectGeneratedError.isInstance(error)) {
    console.log('NoObjectGeneratedError');
    console.log('Cause:', error.cause);
    console.log('Text:', error.text);
    console.log('Response:', error.response);
    console.log('Usage:', error.usage);
  }
}

See also