ai 6.0.31 → 6.0.33

package/docs/07-reference/01-ai-sdk-core/03-generate-object.mdx

@@ -0,0 +1,780 @@
+---
+title: generateObject
+description: API Reference for generateObject.
+---
+
+# `generateObject()`
+
+<Note type="warning">
+  `generateObject` is deprecated. Use
+  [`generateText`](/docs/reference/ai-sdk-core/generate-text) with the
+  [`output`](/docs/reference/ai-sdk-core/output) property instead. See
+  [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) for
+  more information.
+</Note>
+
+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
+
+```ts
+import { generateObject } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const { object } = await generateObject({
+  model: __MODEL__,
+  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.
+
+```ts highlight="7"
+import { generateObject } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+const { object } = await generateObject({
+  model: __MODEL__,
+  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.
+
+```ts highlight="5-6"
+import { generateObject } from 'ai';
+
+const { object } = await generateObject({
+  model: __MODEL__,
+  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
+
+```ts highlight="6"
+import { generateObject } from 'ai';
+
+const { object } = await generateObject({
+  model: __MODEL__,
+  output: 'no-schema',
+  prompt: 'Generate a lasagna recipe.',
+});
+```
+
+To see `generateObject` in action, check out the [additional examples](#more-examples).
+
+## Import
+
+<Snippet text={`import { generateObject } from "ai"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'model',
+      type: 'LanguageModel',
+      description: "The language model to use. Example: openai('gpt-4.1')",
+    },
+    {
+      name: 'output',
+      type: "'object' | 'array' | 'enum' | 'no-schema' | undefined",
+      description: "The type of output to generate. Defaults to 'object'.",
+    },
+    {
+      name: 'schema',
+      type: 'Zod Schema | JSON Schema',
+      description:
+        "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.",
+    },
+    {
+      name: 'schemaName',
+      type: 'string | undefined',
+      description:
+        "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.",
+    },
+    {
+      name: 'schemaDescription',
+      type: 'string | undefined',
+      description:
+        "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.",
+    },
+    {
+      name: 'enum',
+      type: 'string[]',
+      description:
+        "List of possible values to generate. \
+        Only available with 'enum' output.",
+    },
+    {
+      name: 'system',
+      type: 'string | SystemModelMessage | SystemModelMessage[]',
+      description:
+        'The system prompt to use that specifies the behavior of the model.',
+    },
+    {
+      name: 'prompt',
+      type: 'string | Array<SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage>',
+      description: 'The input prompt to generate the text from.',
+    },
+    {
+      name: 'messages',
+      type: 'Array<SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage>',
+      description:
+        'A list of messages that represent a conversation. Automatically converts UI messages from the useChat hook.',
+      properties: [
+        {
+          type: 'SystemModelMessage',
+          parameters: [
+            {
+              name: 'role',
+              type: "'system'",
+              description: 'The role for the system message.',
+            },
+            {
+              name: 'content',
+              type: 'string',
+              description: 'The content of the message.',
+            },
+          ],
+        },
+        {
+          type: 'UserModelMessage',
+          parameters: [
+            {
+              name: 'role',
+              type: "'user'",
+              description: 'The role for the user message.',
+            },
+            {
+              name: 'content',
+              type: 'string | Array<TextPart | ImagePart | FilePart>',
+              description: 'The content of the message.',
+              properties: [
+                {
+                  type: 'TextPart',
+                  parameters: [
+                    {
+                      name: 'type',
+                      type: "'text'",
+                      description: 'The type of the message part.',
+                    },
+                    {
+                      name: 'text',
+                      type: 'string',
+                      description: 'The text content of the message part.',
+                    },
+                  ],
+                },
+                {
+                  type: 'ImagePart',
+                  parameters: [
+                    {
+                      name: 'type',
+                      type: "'image'",
+                      description: 'The type of the message part.',
+                    },
+                    {
+                      name: 'image',
+                      type: 'string | Uint8Array | Buffer | ArrayBuffer | URL',
+                      description:
+                        'The image content of the message part. String are either base64 encoded content, base64 data URLs, or http(s) URLs.',
+                    },
+                    {
+                      name: 'mediaType',
+                      type: 'string',
+                      description:
+                        'The IANA media type of the image. Optional.',
+                      isOptional: true,
+                    },
+                  ],
+                },
+                {
+                  type: 'FilePart',
+                  parameters: [
+                    {
+                      name: 'type',
+                      type: "'file'",
+                      description: 'The type of the message part.',
+                    },
+                    {
+                      name: 'data',
+                      type: 'string | Uint8Array | Buffer | ArrayBuffer | URL',
+                      description:
+                        'The file content of the message part. String are either base64 encoded content, base64 data URLs, or http(s) URLs.',
+                    },
+                    {
+                      name: 'mediaType',
+                      type: 'string',
+                      description: 'The IANA media type of the file.',
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+        {
+          type: 'AssistantModelMessage',
+          parameters: [
+            {
+              name: 'role',
+              type: "'assistant'",
+              description: 'The role for the assistant message.',
+            },
+            {
+              name: 'content',
+              type: 'string | Array<TextPart | FilePart | ReasoningPart | ToolCallPart>',
+              description: 'The content of the message.',
+              properties: [
+                {
+                  type: 'TextPart',
+                  parameters: [
+                    {
+                      name: 'type',
+                      type: "'text'",
+                      description: 'The type of the message part.',
+                    },
+                    {
+                      name: 'text',
+                      type: 'string',
+                      description: 'The text content of the message part.',
+                    },
+                  ],
+                },
+                {
+                  type: 'ReasoningPart',
+                  parameters: [
+                    {
+                      name: 'type',
+                      type: "'reasoning'",
+                      description: 'The type of the message part.',
+                    },
+                    {
+                      name: 'text',
+                      type: 'string',
+                      description: 'The reasoning text.',
+                    },
+                  ],
+                },
+                {
+                  type: 'FilePart',
+                  parameters: [
+                    {
+                      name: 'type',
+                      type: "'file'",
+                      description: 'The type of the message part.',
+                    },
+                    {
+                      name: 'data',
+                      type: 'string | Uint8Array | Buffer | ArrayBuffer | URL',
+                      description:
+                        'The file content of the message part. String are either base64 encoded content, base64 data URLs, or http(s) URLs.',
+                    },
+                    {
+                      name: 'mediaType',
+                      type: 'string',
+                      description: 'The IANA media type of the file.',
+                    },
+                    {
+                      name: 'filename',
+                      type: 'string',
+                      description: 'The name of the file.',
+                      isOptional: true,
+                    },
+                  ],
+                },
+                {
+                  type: 'ToolCallPart',
+                  parameters: [
+                    {
+                      name: 'type',
+                      type: "'tool-call'",
+                      description: 'The type of the message part.',
+                    },
+                    {
+                      name: 'toolCallId',
+                      type: 'string',
+                      description: 'The id of the tool call.',
+                    },
+                    {
+                      name: 'toolName',
+                      type: 'string',
+                      description:
+                        'The name of the tool, which typically would be the name of the function.',
+                    },
+                    {
+                      name: 'args',
+                      type: 'object based on zod schema',
+                      description:
+                        'Parameters generated by the model to be used by the tool.',
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+        {
+          type: 'ToolModelMessage',
+          parameters: [
+            {
+              name: 'role',
+              type: "'tool'",
+              description: 'The role for the assistant message.',
+            },
+            {
+              name: 'content',
+              type: 'Array<ToolResultPart>',
+              description: 'The content of the message.',
+              properties: [
+                {
+                  type: 'ToolResultPart',
+                  parameters: [
+                    {
+                      name: 'type',
+                      type: "'tool-result'",
+                      description: 'The type of the message part.',
+                    },
+                    {
+                      name: 'toolCallId',
+                      type: 'string',
+                      description:
+                        'The id of the tool call the result corresponds to.',
+                    },
+                    {
+                      name: 'toolName',
+                      type: 'string',
+                      description:
+                        'The name of the tool the result corresponds to.',
+                    },
+                    {
+                      name: 'result',
+                      type: 'unknown',
+                      description:
+                        'The result returned by the tool after execution.',
+                    },
+                    {
+                      name: 'isError',
+                      type: 'boolean',
+                      isOptional: true,
+                      description:
+                        'Whether the result is an error or an error message.',
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'maxOutputTokens',
+      type: 'number',
+      isOptional: true,
+      description: 'Maximum number of tokens to generate.',
+    },
+    {
+      name: 'temperature',
+      type: 'number',
+      isOptional: true,
+      description:
+        '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.',
+    },
+    {
+      name: 'topP',
+      type: 'number',
+      isOptional: true,
+      description:
+        '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.',
+    },
+    {
+      name: 'topK',
+      type: 'number',
+      isOptional: true,
+      description:
+        '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.',
+    },
+    {
+      name: 'presencePenalty',
+      type: 'number',
+      isOptional: true,
+      description:
+        '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.',
+    },
+    {
+      name: 'frequencyPenalty',
+      type: 'number',
+      isOptional: true,
+      description:
+        '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.',
+    },
+    {
+      name: 'seed',
+      type: 'number',
+      isOptional: true,
+      description:
+        'The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.',
+    },
+    {
+      name: 'maxRetries',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of retries. Set to 0 to disable retries. Default: 2.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description:
+        'An optional abort signal that can be used to cancel the call.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string>',
+      isOptional: true,
+      description:
+        'Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.',
+    },
+    {
+      name: 'experimental_repairText',
+      type: '(options: RepairTextOptions) => Promise<string>',
+      isOptional: true,
+      description:
+        'A function that attempts to repair the raw output of the model to enable JSON parsing. Should return the repaired text or null if the text cannot be repaired.',
+      properties: [
+        {
+          type: 'RepairTextOptions',
+          parameters: [
+            {
+              name: 'text',
+              type: 'string',
+              description: 'The text that was generated by the model.',
+            },
+            {
+              name: 'error',
+              type: 'JSONParseError | TypeValidationError',
+              description: 'The error that occurred while parsing the text.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'experimental_download',
+      type: '(requestedDownloads: Array<{ url: URL; isUrlSupportedByModel: boolean }>) => Promise<Array<null | { data: Uint8Array; mediaType?: string }>>',
+      isOptional: true,
+      description:
+        'Custom download function to control how URLs are fetched when they appear in prompts. By default, files are downloaded if the model does not support the URL for the given media type. Experimental feature. Return null to pass the URL directly to the model (when supported), or return downloaded content with data and media type.',
+    },
+    {
+      name: 'experimental_telemetry',
+      type: 'TelemetrySettings',
+      isOptional: true,
+      description: 'Telemetry configuration. Experimental feature.',
+      properties: [
+        {
+          type: 'TelemetrySettings',
+          parameters: [
+            {
+              name: 'isEnabled',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable telemetry. Disabled by default while experimental.',
+            },
+            {
+              name: 'recordInputs',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable input recording. Enabled by default.',
+            },
+            {
+              name: 'recordOutputs',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable output recording. Enabled by default.',
+            },
+            {
+              name: 'functionId',
+              type: 'string',
+              isOptional: true,
+              description:
+                'Identifier for this function. Used to group telemetry data by function.',
+            },
+            {
+              name: 'metadata',
+              isOptional: true,
+              type: 'Record<string, string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>>',
+              description:
+                'Additional information to include in the telemetry data.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'providerOptions',
+      type: 'Record<string,JSONObject> | undefined',
+      isOptional: true,
+      description:
+        'Provider-specific options. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'object',
+      type: 'based on the schema',
+      description:
+        'The generated object, validated by the schema (if it supports validation).',
+    },
+    {
+      name: 'finishReason',
+      type: "'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other'",
+      description: 'The reason the model finished generating the text.',
+    },
+    {
+      name: 'usage',
+      type: 'LanguageModelUsage',
+      description: 'The token usage of the generated text.',
+      properties: [
+        {
+          type: 'LanguageModelUsage',
+          parameters: [
+            {
+              name: 'inputTokens',
+              type: 'number | undefined',
+              description: 'The total number of input (prompt) tokens used.',
+            },
+            {
+              name: 'inputTokenDetails',
+              type: 'LanguageModelInputTokenDetails',
+              description:
+                'Detailed information about the input (prompt) tokens. See also: cached tokens and non-cached tokens.',
+              properties: [
+                {
+                  type: 'LanguageModelInputTokenDetails',
+                  parameters: [
+                    {
+                      name: 'noCacheTokens',
+                      type: 'number | undefined',
+                      description:
+                        'The number of non-cached input (prompt) tokens used.',
+                    },
+                    {
+                      name: 'cacheReadTokens',
+                      type: 'number | undefined',
+                      description:
+                        'The number of cached input (prompt) tokens read.',
+                    },
+                    {
+                      name: 'cacheWriteTokens',
+                      type: 'number | undefined',
+                      description:
+                        'The number of cached input (prompt) tokens written.',
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              name: 'outputTokens',
+              type: 'number | undefined',
+              description:
+                'The number of total output (completion) tokens used.',
+            },
+            {
+              name: 'outputTokenDetails',
+              type: 'LanguageModelOutputTokenDetails',
+              description:
+                'Detailed information about the output (completion) tokens.',
+              properties: [
+                {
+                  type: 'LanguageModelOutputTokenDetails',
+                  parameters: [
+                    {
+                      name: 'textTokens',
+                      type: 'number | undefined',
+                      description: 'The number of text tokens used.',
+                    },
+                    {
+                      name: 'reasoningTokens',
+                      type: 'number | undefined',
+                      description: 'The number of reasoning tokens used.',
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              name: 'totalTokens',
+              type: 'number | undefined',
+              description: 'The total number of tokens used.',
+            },
+            {
+              name: 'raw',
+              type: 'object | undefined',
+              isOptional: true,
+              description:
+                "Raw usage information from the provider. This is the provider's original usage information and may include additional fields.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'request',
+      type: 'LanguageModelRequestMetadata',
+      isOptional: true,
+      description: 'Request metadata.',
+      properties: [
+        {
+          type: 'LanguageModelRequestMetadata',
+          parameters: [
+            {
+              name: 'body',
+              type: 'string',
+              description:
+                'Raw request HTTP body that was sent to the provider API as a string (JSON should be stringified).',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'response',
+      type: 'LanguageModelResponseMetadata',
+      isOptional: true,
+      description: 'Response metadata.',
+      properties: [
+        {
+          type: 'LanguageModelResponseMetadata',
+          parameters: [
+            {
+              name: 'id',
+              type: 'string',
+              description:
+                'The response identifier. The AI SDK uses the ID from the provider response when available, and generates an ID otherwise.',
+            },
+            {
+              name: 'modelId',
+              type: 'string',
+              description:
+                '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.',
+            },
+            {
+              name: 'timestamp',
+              type: 'Date',
+              description:
+                'The timestamp of the response. The AI SDK uses the response timestamp from the provider response when available, and creates a timestamp otherwise.',
+            },
+            {
+              name: 'headers',
+              isOptional: true,
+              type: 'Record<string, string>',
+              description: 'Optional response headers.',
+            },
+            {
+              name: 'body',
+              isOptional: true,
+              type: 'unknown',
+              description: 'Optional response body.',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'reasoning',
+      type: 'string | undefined',
+      description:
+        'The reasoning that was used to generate the object. Concatenated from all reasoning parts.',
+    },
+    {
+      name: 'warnings',
+      type: 'Warning[] | undefined',
+      description:
+        'Warnings from the model provider (e.g. unsupported settings).',
+    },
+    {
+      name: 'providerMetadata',
+      type: 'ProviderMetadata | undefined',
+      description:
+        'Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',
+    },
+    {
+      name: 'toJsonResponse',
+      type: '(init?: ResponseInit) => Response',
+      description:
+        '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
+
+<ExampleLinks
+  examples={[
+    {
+      title:
+        'Learn to generate structured data using a language model in Next.js',
+      link: '/examples/next-app/basics/generating-object',
+    },
+    {
+      title:
+        'Learn to generate structured data using a language model in Node.js',
+      link: '/examples/node/generating-structured-data/generate-object',
+    },
+  ]}
+/>