Interface GenerateObjectOptions<T>

Options for a generateObject call.

At minimum, schema and either prompt or messages must be supplied. Provider/model resolution follows the same rules as generateText.

Example

const opts: GenerateObjectOptions<typeof mySchema> = {
  schema: z.object({ name: z.string(), age: z.number() }),
  prompt: 'Extract: "John is 30 years old"',
};
interface GenerateObjectOptions<T> {
    provider?: string;
    model?: string;
    schema: T;
    schemaName?: string;
    schemaDescription?: string;
    prompt?: string;
    system?: string | SystemContentBlock[];
    messages?: Message[];
    temperature?: number;
    maxTokens?: number;
    maxRetries?: number;
    apiKey?: string;
    baseUrl?: string;
    fallbackProviders?: FallbackProviderEntry[];
    onFallback?: ((error, fallbackProvider) => void);
    policyTier?: "safe" | "standard" | "mature" | "private-adult";
    requestTimeout?: number;
    maxAttempts?: number;
    onAttempt?: ((outcome) => void);
    abortSignal?: AbortSignal;
    effort?: string;
    thinking?: false | {
        budgetTokens: number;
    };
    cache?: false | {
        ttl?: "5m" | "1h";
    };
    schemaCacheTtl?: "5m" | "1h";
    sessionId?: string;
    serviceTier?: "priority" | "auto" | "default" | "flex";
    customModelParams?: Record<string, unknown>;
    source?: string;
    budget?: SpendBudget | SpendBudgetOptions;
}

Type Parameters

  • T extends ZodType

    The Zod schema type that defines the expected output shape.

Properties

provider? model? schema schemaName? schemaDescription? prompt? system? messages? temperature? maxTokens? maxRetries? apiKey? baseUrl? fallbackProviders? onFallback? policyTier? requestTimeout? maxAttempts? onAttempt? abortSignal? effort? thinking? cache? schemaCacheTtl? sessionId? serviceTier? customModelParams? source? budget?

Properties

Optional provider

provider?: string

Provider name. When supplied without model, the default text model for the provider is resolved automatically.

Example

`"openai"`, `"anthropic"`, `"ollama"`

Optional model

model?: string

Model identifier. Prefer the plain model name with provider set; the combined "provider:model" string is also accepted.

Example

`"gpt-4o"` (with `provider: 'openai'`), `"gpt-4o-mini"`

schema

schema: T

Zod schema defining the expected output shape.

Optional schemaName

schemaName?: string

Human-readable name for the schema, injected into the system prompt to give the model context about what it is generating.

Example

`"PersonInfo"`

Optional schemaDescription

schemaDescription?: string

Description of the schema, injected into the system prompt alongside the JSON Schema definition.

Example

`"Information about a person extracted from unstructured text."`

Optional prompt

prompt?: string

User prompt. Convenience alternative to building a messages array.

Optional system

system?: string | SystemContentBlock[]

System prompt. The schema extraction instructions are appended to this, so any custom system context is preserved.

Accepts a plain string (single system message) or an ordered array of SystemContentBlock entries. When an array is supplied, caller cacheBreakpoint flags are preserved on each block and a final non-cached block is appended with the JSON schema + formatting rules. This enables Anthropic prompt caching on the stable prefix while letting the per-call schema vary freely.

Optional messages

messages?: Message[]

Full conversation history.

Optional temperature

temperature?: number

Sampling temperature forwarded to the provider (0-2 for most providers).

Optional maxTokens

maxTokens?: number

Hard cap on output tokens.

Optional maxRetries

maxRetries?: number

Number of times to retry when JSON parsing or Zod validation fails. Each retry appends the error details to the conversation so the model can self-correct.

Default

2

Optional apiKey

apiKey?: string

Override the API key instead of reading from environment variables.

Optional baseUrl

baseUrl?: string

Override the provider base URL (useful for local proxies or Ollama).

Optional fallbackProviders

fallbackProviders?: FallbackProviderEntry[]

Ordered fallback providers tried when the primary fails with a retryable error. When undefined, auto-built from env keys. Pass [] to disable.

See

GenerateTextOptions.fallbackProviders

Optional onFallback

onFallback?: ((error, fallbackProvider) => void)

Called when a fallback provider is about to be tried.

Type declaration

    • (error, fallbackProvider): void

    • Parameters

      • error: Error
      • fallbackProvider: string

      Returns void

Optional policyTier

policyTier?: "safe" | "standard" | "mature" | "private-adult"

Caller's intended content policy tier. Forwarded to GenerateTextOptions.policyTier so structured-output callers get the same policy-aware fallback behavior as plain text callers — mature/private-adult requests auto-route refusals to an uncensored OpenRouter model instead of hard-failing on a content_policy_violation.

Particularly relevant here because OpenAI's strict structured- output mode (response_format: json_schema) is the most aggressively-moderated path on the platform; a mature story extraction tagged with policyTier: 'mature' that the primary refuses walks on to the tier's uncensored OpenRouter models, which take the looser json_object mode that generateObject uses for non-OpenAI providers.

Optional requestTimeout

requestTimeout?: number

Per-call request timeout in milliseconds, forwarded to GenerateTextOptions.requestTimeout. Structured-output callers that emit long strings (e.g. codegen TSX) raise the abort window for this call without slowing the provider's default failover for chat / narration traffic.

Optional maxAttempts

maxAttempts?: number

The most attempts each generation's call makes, a first and its retries together; the provider's configured count when left out. A validation retry (maxRetries) is a generation of its own, with its own count. Within one attempt, a key-scoped failure on a pool of several keys re-sends the same request with the next usable key, at most once per key, and those sends are not counted.

Optional onAttempt

onAttempt?: ((outcome) => void)

Called once per attempt a generation's call made, with the answer of the attempt's last send (a key hop's earlier answers are not reported), so a caller can settle the attempts it paid for.

Type declaration

Optional abortSignal

abortSignal?: AbortSignal

Ends the call when it aborts: no further attempt or fallback hop starts, and the call rejects with the signal's reason. Forwarded to every attempt's GenerateTextOptions.abortSignal, which hands it to the provider request.

Optional effort

effort?: string

Reasoning-depth / token-spend control, forwarded to GenerateTextOptions.effort. On effort-capable models the provider emits it as output_config.effort (Anthropic) or reasoning_effort (OpenAI o-series / GPT-5). Dropped on models that don't support it.

Optional thinking

thinking?: false | {
    budgetTokens: number;
}

Extended-thinking switch, forwarded to GenerateTextOptions.thinking. false turns thinking off with the model's own off shape (Sonnet 5.5 takes between_tools, at effort high or below); Opus 5.5, Fable and Mythos always think. Omitted keeps the model's default, which is thinking on for Opus 5 and later, Sonnet 5 and later, Fable and Mythos. Thinking tokens count toward maxTokens, so a structured call on a thinking model needs room for both.

Type declaration

  • budgetTokens: number

Optional cache

cache?: false | {
    ttl?: "5m" | "1h";
}

Per-call prompt-cache control, forwarded to GenerateTextOptions.cache. false opts this call out of ALL cache marking (the schema block's marker included — right for one-shot extractions); { ttl: '1h' } puts a 1-hour TTL on the provider's auto markers (the moving message-tail).

Type declaration

  • Optional ttl?: "5m" | "1h"

Optional schemaCacheTtl

schemaCacheTtl?: "5m" | "1h"

TTL for the schema block's own cache marker (the block this call appends after the caller's system). The schema bytes are stable per call SITE, so sites whose calls gap more than 5 minutes (human-paced pipelines, slow loops) should set '1h' — otherwise the entry expires between calls and every call re-writes the prefix at the write premium. Defaults to the 5-minute marker (previous behavior). Ignored when cache is false.

Optional sessionId

sessionId?: string

Per-conversation affinity key, forwarded to GenerateTextOptions.sessionId. OpenRouter emits it as session_id for provider sticky routing — upstream prompt caches are host-scoped, so a load-balanced multi-call pipeline otherwise cold-misses the cache a prior call wrote on a different host. Pass a stable id per logical session (blueprint/build id for codegen loops, conversation id for chat extraction). Providers without an affinity concept ignore the field.

Optional serviceTier

serviceTier?: "priority" | "auto" | "default" | "flex"

OpenAI service tier, forwarded to GenerateTextOptions.serviceTier and sent as service_tier verbatim on every attempt, a validation retry included. No default: OpenAI then serves the request at the project's configured tier. 'flex' bills at about batch rates but can answer 429 under load; 'priority' is a paid tier. Other providers ignore it.

Optional customModelParams

customModelParams?: Record<string, unknown>

Provider-specific top-level request fields, forwarded to GenerateTextOptions.customModelParams and spread onto every attempt's request body, a validation retry included, with the same rules as there: a fallback leg gets them minus the fields only another vendor accepts (OpenRouter's routing controls, Gemini's request fields, OpenAI's response_format, Anthropic's output_config), and keys collide last-wins with the typed fields at the provider layer. A passthrough tool_choice, tools or response_format here can change the structured-output route this call takes (generateObject).

Optional source

source?: string

Opt-in source label forwarded to GenerateTextOptions.source and surfaced on the global LLM usage observer event. Hosts tag their cost/telemetry rows with it (e.g. 'codegen_tool', 'narrator_state_extractor') — without it every structured-output call rolls up under the generic surface bucket.

Optional budget

budget?: SpendBudget | SpendBudgetOptions

A spend budget for this call and, when the same SpendBudget instance is passed to several calls, for all of them: each attempt's provider call is checked against what is left before it is made and recorded after it, so a refused attempt ends the call with no further attempt.

Settings

Member Visibility

Theme

On This Page

providermodelschemaschemaNameschemaDescriptionpromptsystemmessagestemperaturemaxTokensmaxRetriesapiKeybaseUrlfallbackProvidersonFallbackpolicyTierrequestTimeoutmaxAttemptsonAttemptabortSignaleffortthinkingcacheschemaCacheTtlsessionIdserviceTiercustomModelParamssourcebudget