generateObject()

Overview

The generateObject() function generates structured, type-safe objects from chat models using Zod schema validation. This ensures the model output conforms to your expected data structure.

Function signature

export async function generateObject<TSchema extends z.ZodType>(
    params: GenerateObjectParams<TSchema>
): Promise<GenerateObjectResult<TSchema>>

export type GenerateObjectParams<TSchema extends z.ZodType> = 
    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.

z.ZodType

required

Zod schema that defines the structure of the object to generate.

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

Maximum number of tokens to generate.

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:

z.infer<TSchema>

The generated object, fully typed according to your Zod schema.

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,
});

Error handling

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 return type is fully inferred from your Zod schema:

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

​Error handling

​Type safety

Overview

Function signature

Parameters

Return value

Examples

Basic object generation

Complex schema

With configuration

Error handling

Type safety