`generateObject()`

Generates a typed, structured object for a given prompt and schema using a language model.

It can be used to force the language model to return structured data, e.g. for information extraction, synthetic data generation, or classification tasks.

Example: generate an object using a schema

import { openai } from '@ai-sdk/openai';
import { generateObject } from 'ai';
import { z } from 'zod';

const { object } = await generateObject({
  model: openai('gpt-4-turbo'),
  schema: z.object({
    recipe: z.object({
      name: z.string(),
      ingredients: z.array(z.string()),
      steps: z.array(z.string()),
    }),
  }),
  prompt: 'Generate a lasagna recipe.',
});

console.log(JSON.stringify(object, null, 2));

Example: generate an array using a schema

For arrays, you specify the schema of the array items.

import { openai } from '@ai-sdk/openai';
import { generateObject } from 'ai';
import { z } from 'zod';

const { object } = await generateObject({
  model: openai('gpt-4-turbo'),
  output: 'array',
  schema: z.object({
    name: z.string(),
    class: z
      .string()
      .describe('Character class, e.g. warrior, mage, or thief.'),
    description: z.string(),
  }),
  prompt: 'Generate 3 hero descriptions for a fantasy role playing game.',
});

Example: generate an enum

When you want to generate a specific enum value, you can set the output strategy to enum and provide the list of possible values in the enum parameter.

import { generateObject } from 'ai';

const { object } = await generateObject({
  model: yourModel,
  output: 'enum',
  enum: ['action', 'comedy', 'drama', 'horror', 'sci-fi'],
  prompt:
    'Classify the genre of this movie plot: ' +
    '"A group of astronauts travel through a wormhole in search of a ' +
    'new habitable planet for humanity."',
});

Example: generate JSON without a schema

import { openai } from '@ai-sdk/openai';
import { generateObject } from 'ai';

const { object } = await generateObject({
  model: openai('gpt-4-turbo'),
  output: 'no-schema',
  prompt: 'Generate a lasagna recipe.',
});

To see generateObject in action, check out the additional examples.

Import

import { generateObject } from "ai"

API Signature

model:

LanguageModel

The language model to use. Example: openai('gpt-4-turbo')

output:

'object' | 'array' | 'enum' | 'no-schema' | undefined

The type of output to generate. Defaults to 'object'.

mode:

'auto' | 'json' | 'tool'

The mode to use for object generation. Not every model supports all modes. Defaults to 'auto' for 'object' output and to 'json' for 'no-schema' output. Must be 'json' for 'no-schema' output.

schema:

Zod Schema | JSON Schema

The schema that describes the shape of the object to generate. It is sent to the model to generate the object and used to validate the output. You can either pass in a Zod schema or a JSON schema (using the `jsonSchema` function). In 'array' mode, the schema is used to describe an array element. Not available with 'no-schema' or 'enum' output.

schemaName:

string | undefined

Optional name of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema name. Not available with 'no-schema' or 'enum' output.

schemaDescription:

string | undefined

Optional description of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema name. Not available with 'no-schema' or 'enum' output.

enum:

string[]

List of possible values to generate. Only available with 'enum' output.

system:

string

The system prompt to use that specifies the behavior of the model.

prompt:

string

The input prompt to generate the text from.

messages:

Array<CoreSystemMessage | CoreUserMessage | CoreAssistantMessage | CoreToolMessage> | Array<UIMessage>

A list of messages that represent a conversation. Automatically converts UI messages from the useChat hook.

CoreSystemMessage

role:

'system'

The role for the system message.

content:

string

The content of the message.

CoreUserMessage

role:

'user'

The role for the user message.

content:

string | Array<TextPart | ImagePart | FilePart>

The content of the message.

TextPart

type:

'text'

The type of the message part.

text:

string

The text content of the message part.

ImagePart

type:

'image'

The type of the message part.

image:

string | Uint8Array | Buffer | ArrayBuffer | URL

The image content of the message part. String are either base64 encoded content, base64 data URLs, or http(s) URLs.

mimeType?:

string

The mime type of the image. Optional.

FilePart

type:

'file'

The type of the message part.

data:

string | Uint8Array | Buffer | ArrayBuffer | URL

The file content of the message part. String are either base64 encoded content, base64 data URLs, or http(s) URLs.

mimeType:

string

The mime type of the file.

CoreAssistantMessage

role:

'assistant'

The role for the assistant message.

content:

string | Array<TextPart | ToolCallPart>

The content of the message.

TextPart

type:

'text'

The type of the message part.

text:

string

The text content of the message part.

ToolCallPart

type:

'tool-call'

The type of the message part.

toolCallId:

string

The id of the tool call.

toolName:

string

The name of the tool, which typically would be the name of the function.

args:

object based on schema

Parameters generated by the model to be used by the tool.

CoreToolMessage

role:

'tool'

The role for the assistant message.

content:

Array<ToolResultPart>

The content of the message.

ToolResultPart

type:

'tool-result'

The type of the message part.

toolCallId:

string

The id of the tool call the result corresponds to.

toolName:

string

The name of the tool the result corresponds to.

result:

unknown

The result returned by the tool after execution.

isError?:

boolean

Whether the result is an error or an error message.

maxTokens?:

number

Maximum number of tokens to generate.

temperature?:

number

Temperature setting. The value is passed through to the provider. The range depends on the provider and model. It is recommended to set either `temperature` or `topP`, but not both.

topP?:

number

Nucleus sampling. The value is passed through to the provider. The range depends on the provider and model. It is recommended to set either `temperature` or `topP`, but not both.

topK?:

number

Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. Recommended for advanced use cases only. You usually only need to use temperature.

presencePenalty?:

number

Presence penalty setting. It affects the likelihood of the model to repeat information that is already in the prompt. The value is passed through to the provider. The range depends on the provider and model.

frequencyPenalty?:

number

Frequency penalty setting. It affects the likelihood of the model to repeatedly use the same words or phrases. The value is passed through to the provider. The range depends on the provider and model.

seed?:

number

The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.

maxRetries?:

number

Maximum number of retries. Set to 0 to disable retries. Default: 2.

abortSignal?:

AbortSignal

An optional abort signal that can be used to cancel the call.

headers?:

Record<string, string>

Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.

experimental_telemetry?:

TelemetrySettings

Telemetry configuration. Experimental feature.

TelemetrySettings

isEnabled?:

boolean

Enable or disable telemetry. Disabled by default while experimental.

recordInputs?:

boolean

Enable or disable input recording. Enabled by default.

recordOutputs?:

boolean

Enable or disable output recording. Enabled by default.

functionId?:

string

Identifier for this function. Used to group telemetry data by function.

metadata?:

Additional information to include in the telemetry data.

experimental_providerMetadata?:

Record<string,Record<string,JSONValue>> | undefined

Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.

Returns

object:

based on the schema

The generated object, validated by the schema (if it supports validation).

finishReason:

The reason the model finished generating the text.

usage:

CompletionTokenUsage

The token usage of the generated text.

CompletionTokenUsage

promptTokens:

number

The total number of tokens in the prompt.

completionTokens:

number

The total number of tokens in the completion.

totalTokens:

number

The total number of tokens generated.

request?:

RequestMetadata

Request metadata.

RequestMetadata

body:

string

Raw request HTTP body that was sent to the provider API as a string (JSON should be stringified).

response?:

ResponseMetadata

Response metadata.

ResponseMetadata

id:

string

The response identifier. The AI SDK uses the ID from the provider response when available, and generates an ID otherwise.

model:

string

The model that was used to generate the response. The AI SDK uses the response model from the provider response when available, and the model from the function call otherwise.

timestamp:

Date

The timestamp of the response. The AI SDK uses the response timestamp from the provider response when available, and creates a timestamp otherwise.

headers?:

Record<string, string>

Optional response headers.

warnings:

Warning[] | undefined

Warnings from the model provider (e.g. unsupported settings).

experimental_providerMetadata:

Record<string,Record<string,JSONValue>> | undefined

Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.

toJsonResponse:

(init?: ResponseInit) => Response

Converts the object to a JSON response. The response will have a status code of 200 and a content type of `application/json; charset=utf-8`.

More Examples

Learn to generate structured data using a language model in Next.js

Learn to generate structured data using a language model in Node.js