generateObject()

Overview

The generateObject() function generates structured objects from chat models. With a Standard Schema, such as a Zod 4.2+ schema, core-ai validates the model output and returns a typed object. With plain JSON Schema, it returns the parsed JSON for you to validate.

Function signature

export async function generateObject<TSchema extends SchemaInput>(
    params: GenerateObjectParams<TSchema>
): Promise<GenerateObjectResult<TSchema>>

export type GenerateObjectParams<TSchema extends SchemaInput> =
    GenerateObjectOptions<TSchema> & {
        model: ChatModel;
    };

Parameters

ChatModel

required

The chat model instance to use for generation.

Message[]

required

Array of messages in the conversation. Must not be empty.

SchemaInput

required

Schema of the object to generate: a Standard Schema with JSON Schema support, such as a Zod 4.2+ schema, or plain JSON Schema. See Schemas for the supported libraries.

string

Optional name for the schema. Used by some providers for better results.

string

Optional description of the schema. Helps the model understand what to generate.

number

Sampling temperature (0-2).

number

Total output allowance for the response, covering reasoning tokens and the visible answer. When omitted, the model’s output ceiling applies. If the value cannot hold the reasoning budget of the requested effort, the call throws a ValidationError. See maxTokens.

number

Nucleus sampling parameter (0-1).

ReasoningConfig

Configuration for extended thinking/reasoning capabilities.

Show ReasoningConfig

ReasoningEffort

required

The effort level for reasoning: 'minimal', 'low', 'medium', 'high', or 'max'.

GenerateProviderOptions

Provider-specific options, namespaced by provider name.

AbortSignal

AbortSignal for cancelling the request.

Return value

Returns a Promise<GenerateObjectResult<TSchema>> with the following properties:

InferSchemaOutput<TSchema>

For a Standard Schema, the validated output of the schema, typed with its output type. For plain JSON Schema, the parsed JSON, typed unknown and not validated.

FinishReason

Why generation stopped: 'stop', 'length', 'tool-calls', 'content-filter', or 'unknown'.

ChatUsage

Token usage statistics including input/output tokens and cache details.

Examples

Basic object generation

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

const openai = createOpenAI();
const model = openai.chatModel('gpt-5-mini');

const schema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email()
});

const result = await generateObject({
  model,
  messages: [
    { role: 'user', content: 'Generate a person named John who is 30 years old' }
  ],
  schema
});

console.log(result.object.name);
console.log(result.object.age);
console.log(result.object.email);

Complex schema

const schema = z.object({
  title: z.string(),
  author: z.object({
    name: z.string(),
    bio: z.string()
  }),
  chapters: z.array(
    z.object({
      title: z.string(),
      summary: z.string(),
      wordCount: z.number()
    })
  ),
  publishedAt: z.string().datetime()
});

const result = await generateObject({
  model,
  messages: [
    { role: 'user', content: 'Create a book outline about artificial intelligence' }
  ],
  schema,
  schemaName: 'BookOutline',
  schemaDescription: 'A structured book outline with chapters'
});

console.log(result.object.title);
console.log(result.object.chapters.length);

With configuration

const result = await generateObject({
  model,
  messages: [
    { role: 'user', content: 'Generate creative character profiles' }
  ],
  schema: z.object({
    characters: z.array(
      z.object({
        name: z.string(),
        personality: z.string(),
        backstory: z.string()
      })
    )
  }),
  temperature: 1.2,
  maxTokens: 1000,
});

Plain JSON Schema

Pass plain JSON Schema as schema to get the parsed JSON, typed unknown and not validated. See Plain JSON Schema for an example.

Error handling

generateObject() throws:

StructuredOutputValidationError when the output does not match a Standard Schema. issues holds the schema library’s messages, formatted as path.to.key: message. When the schema’s validator throws instead, such as a transform calling new URL(), its error is the cause.
StructuredOutputParseError when the output is not valid JSON.
StructuredOutputNoObjectGeneratedError when the model returns no object.
ValidationError when the schema cannot be converted to JSON Schema, before any provider call.

import {
  CoreAIError,
  StructuredOutputError,
  StructuredOutputNoObjectGeneratedError,
  StructuredOutputParseError,
  StructuredOutputValidationError,
} from '@core-ai/core-ai';

try {
  const result = await generateObject({
    model,
    messages: [
      { role: 'user', content: 'Generate user data' }
    ],
    schema: z.object({
      name: z.string(),
      age: z.number()
    })
  });
} catch (error) {
  if (error instanceof StructuredOutputValidationError) {
    console.error('Validation errors:', error.issues);
  } else if (error instanceof StructuredOutputParseError) {
    console.error('Parse error:', error.message);
  } else if (error instanceof StructuredOutputNoObjectGeneratedError) {
    console.error('No object generated');
  } else if (error instanceof CoreAIError) {
    console.error('Generation failed:', error.message);
  }
}

Type safety

The type of object is inferred from the output type of a Standard Schema. For plain JSON Schema it is unknown.

const userSchema = z.object({
  id: z.number(),
  username: z.string(),
  isActive: z.boolean()
});

const result = await generateObject({
  model,
  messages: [{ role: 'user', content: 'Generate a user' }],
  schema: userSchema
});

const id: number = result.object.id;
const username: string = result.object.username;
const isActive: boolean = result.object.isActive;

​Overview

​Function signature

​Parameters

​Return value

​Examples

​Basic object generation

​Complex schema

​With configuration

​Plain JSON Schema

​Error handling

​Type safety

Overview

Function signature

Parameters

Return value

Examples

Basic object generation

Complex schema

With configuration

Plain JSON Schema

Error handling

Type safety