chore(provider): align V4 model return types to have their own definitions across all model interfaces (#14250)

## Background

Many V4 model interfaces in `provider` defined their return types inline
inside the `doGenerate`/`doEmbed`/etc. method signatures. This made it
cumbersome to reference those types by name elsewhere (requiring
`Awaited<ReturnType<ModelV4['doMethod']>>`). It also made them
inconsistent with `LanguageModelV4` and `EmbeddingModelV4`, which were
already using their own distinct type definitions for their return
types.

## Summary

Each V4 model interface now has its return type extracted into a
dedicated file (e.g. `image-model-v4-result.ts`,
`speech-model-v4-result.ts`) and exported by name. This applies to all
V4 interfaces: `LanguageModelV4`, `EmbeddingModelV4`, `ImageModelV4`,
`VideoModelV4`, `SpeechModelV4`, `TranscriptionModelV4`,
`RerankingModelV4`, `FilesV4`, and `SkillsV4`.

The `ai` package is updated to use these named types instead of the
verbose `Awaited<ReturnType<...>>` pattern.

## Manual Verification

N/A — pure type-level refactoring with no runtime behavior changes.

## Checklist

- [ ] Tests have been added / updated (for bug fixes / features)
- [ ] Documentation has been added / updated (for bug fixes / features)
- [x] A _patch_ changeset for relevant packages has been added (for bug
fixes / features - run `pnpm changeset` in the project root)
- [x] I have reviewed this pull request (self-review)

## Future Work

N/A

## Related Issues

N/A

Author: felixarntz

.changeset/hot-pugs-count.md

@@ -0,0 +1,6 @@
+---
+"@ai-sdk/provider": patch
+"ai": patch
+---
+
+chore(provider): align V4 model return types to have their own definitions across all model interfaces

packages/ai/src/generate-text/generate-text.ts

@@ -1,6 +1,6 @@
 import {
-  LanguageModelV4,
   LanguageModelV4Content,
+  LanguageModelV4GenerateResult,
   LanguageModelV4ToolCall,
 } from '@ai-sdk/provider';
 import {
@@ -673,9 +673,9 @@ export async function generateText<
 
     const callSettings = prepareCallSettings(settings);
 
-    let currentModelResponse: Awaited<
-      ReturnType<LanguageModelV4['doGenerate']>
-    > & { response: { id: string; timestamp: Date; modelId: string } };
+    let currentModelResponse: LanguageModelV4GenerateResult & {
+      response: { id: string; timestamp: Date; modelId: string };
+    };
     let clientToolCalls: Array<TypedToolCall<TOOLS>> = [];
     let clientToolOutputs: Array<ToolOutput<TOOLS>> = [];
     const steps: GenerateTextResult<TOOLS, CONTEXT, OUTPUT>['steps'] = [];

packages/ai/src/middleware/wrap-embedding-model.ts

@@ -2,6 +2,7 @@ import {
   EmbeddingModelV3,
   EmbeddingModelV4,
   EmbeddingModelV4CallOptions,
+  EmbeddingModelV4Result,
 } from '@ai-sdk/provider';
 import { asEmbeddingModelV4 } from '../model/as-embedding-model-v4';
 import { EmbeddingModelMiddleware } from '../types';
@@ -74,7 +75,7 @@ const doWrap = ({
       overrideSupportsParallelCalls?.({ model }) ?? model.supportsParallelCalls,
     async doEmbed(
       params: EmbeddingModelV4CallOptions,
-    ): Promise<Awaited<ReturnType<EmbeddingModelV4['doEmbed']>>> {
+    ): Promise<EmbeddingModelV4Result> {
       const transformedParams = await doTransform({ params });
       const doEmbed = async () => model.doEmbed(transformedParams);
       return wrapEmbed

packages/ai/src/middleware/wrap-image-model.ts

@@ -3,6 +3,7 @@ import {
   ImageModelV3,
   ImageModelV4,
   ImageModelV4CallOptions,
+  ImageModelV4Result,
 } from '@ai-sdk/provider';
 import { asImageModelV4 } from '../model/as-image-model-v4';
 import { ImageModelMiddleware } from '../types';
@@ -77,7 +78,7 @@ const doWrap = ({
     maxImagesPerCall,
     async doGenerate(
       params: ImageModelV4CallOptions,
-    ): Promise<Awaited<ReturnType<ImageModelV4['doGenerate']>>> {
+    ): Promise<ImageModelV4Result> {
       const transformedParams = await doTransform({ params });
       const doGenerate = async () => model.doGenerate(transformedParams);
       return wrapGenerate

packages/ai/src/upload-skill/upload-skill-result.ts

@@ -1,9 +1,9 @@
-import { SkillsV4UploadResult } from '@ai-sdk/provider';
+import { SkillsV4UploadSkillResult } from '@ai-sdk/provider';
 import { ProviderReference } from '../types/provider-reference';
 import { Warning } from '../types/warning';
 
 export type UploadSkillResult = Omit<
-  SkillsV4UploadResult,
+  SkillsV4UploadSkillResult,
   'providerReference' | 'warnings'
 > & {
   readonly providerReference: ProviderReference;

packages/provider/src/files/v4/files-v4-upload-file-call-options.ts

@@ -0,0 +1,28 @@
+import { SharedV4ProviderOptions } from '../../shared/v4/shared-v4-provider-options';
+
+/**
+ * Options for uploading a file via the files interface.
+ */
+export type FilesV4UploadFileCallOptions = {
+  /**
+   * The file data as raw bytes or a base64-encoded string.
+   */
+  data: Uint8Array | string;
+
+  /**
+   * The IANA media type of the file (e.g. `'application/pdf'`).
+   */
+  mediaType: string;
+
+  /**
+   * The filename of the file.
+   */
+  filename?: string;
+
+  /**
+   * Additional provider-specific options. 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?: SharedV4ProviderOptions;
+};

packages/provider/src/files/v4/files-v4-upload-file-result.ts

@@ -0,0 +1,35 @@
+import { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provider-metadata';
+import { SharedV4ProviderReference } from '../../shared/v4/shared-v4-provider-reference';
+import { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+
+/**
+ * Result of uploading a file via the files interface.
+ */
+export type FilesV4UploadFileResult = {
+  /**
+   * A provider reference mapping provider names to provider-specific file identifiers.
+   */
+  providerReference: SharedV4ProviderReference;
+
+  /**
+   * The IANA media type of the uploaded file, if available from the provider.
+   */
+  mediaType?: string;
+
+  /**
+   * The filename of the uploaded file, if available from the provider.
+   */
+  filename?: string;
+
+  /**
+   * 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.
+   */
+  providerMetadata?: SharedV4ProviderMetadata;
+
+  /**
+   * Warnings from the provider.
+   */
+  warnings: Array<SharedV4Warning>;
+};

packages/provider/src/files/v4/files-v4.ts

@@ -1,66 +1,5 @@
-import { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provider-metadata';
-import { SharedV4ProviderOptions } from '../../shared/v4/shared-v4-provider-options';
-import { SharedV4ProviderReference } from '../../shared/v4/shared-v4-provider-reference';
-import { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
-
-/**
- * Result of uploading a file via the files interface.
- */
-export type FilesV4UploadFileResult = {
-  /**
-   * A provider reference mapping provider names to provider-specific file identifiers.
-   */
-  providerReference: SharedV4ProviderReference;
-
-  /**
-   * The IANA media type of the uploaded file, if available from the provider.
-   */
-  mediaType?: string;
-
-  /**
-   * The filename of the uploaded file, if available from the provider.
-   */
-  filename?: string;
-
-  /**
-   * 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.
-   */
-  providerMetadata?: SharedV4ProviderMetadata;
-
-  /**
-   * Warnings from the provider.
-   */
-  warnings: Array<SharedV4Warning>;
-};
-
-/**
- * Options for uploading a file via the files interface.
- */
-export type FilesV4UploadFileCallOptions = {
-  /**
-   * The file data as raw bytes or a base64-encoded string.
-   */
-  data: Uint8Array | string;
-
-  /**
-   * The IANA media type of the file (e.g. `'application/pdf'`).
-   */
-  mediaType: string;
-
-  /**
-   * The filename of the file.
-   */
-  filename?: string;
-
-  /**
-   * Additional provider-specific options. 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?: SharedV4ProviderOptions;
-};
+import { FilesV4UploadFileCallOptions } from './files-v4-upload-file-call-options';
+import { FilesV4UploadFileResult } from './files-v4-upload-file-result';
 
 /**
  * Specification for a file management interface that implements the files interface version 4.

packages/provider/src/files/v4/index.ts

@@ -1,5 +1,3 @@
-export type {
-  FilesV4,
-  FilesV4UploadFileCallOptions,
-  FilesV4UploadFileResult,
-} from './files-v4';
+export type { FilesV4 } from './files-v4';
+export type { FilesV4UploadFileCallOptions } from './files-v4-upload-file-call-options';
+export type { FilesV4UploadFileResult } from './files-v4-upload-file-result';

packages/provider/src/image-model/v4/image-model-v4-result.ts

@@ -0,0 +1,73 @@
+import { JSONArray, JSONValue } from '../../json-value';
+import { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+import { ImageModelV4Usage } from './image-model-v4-usage';
+
+export type ImageModelV4ProviderMetadata = Record<
+  string,
+  {
+    images: JSONArray;
+  } & JSONValue
+>;
+
+/**
+ * The result of an image model doGenerate call.
+ */
+export type ImageModelV4Result = {
+  /**
+   * Generated images as base64 encoded strings or binary data.
+   * The images should be returned without any unnecessary conversion.
+   * If the API returns base64 encoded strings, the images should be returned
+   * as base64 encoded strings. If the API returns binary data, the images should
+   * be returned as binary data.
+   */
+  images: Array<string> | Array<Uint8Array>;
+
+  /**
+   * Warnings for the call, e.g. unsupported features.
+   */
+  warnings: Array<SharedV4Warning>;
+
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * from the provider to the AI SDK and enable provider-specific
+   * results that can be fully encapsulated in the provider.
+   *
+   * The outer record is keyed by the provider name, and the inner
+   * record is provider-specific metadata. It always includes an
+   * `images` key with image-specific metadata
+   *
+   * ```ts
+   * {
+   * "openai": {
+   * "images": ["revisedPrompt": "Revised prompt here."]
+   * }
+   * }
+   * ```
+   */
+  providerMetadata?: ImageModelV4ProviderMetadata;
+
+  /**
+   * Response information for telemetry and debugging purposes.
+   */
+  response: {
+    /**
+     * Timestamp for the start of the generated response.
+     */
+    timestamp: Date;
+
+    /**
+     * The ID of the response model that was used to generate the response.
+     */
+    modelId: string;
+
+    /**
+     * Response headers.
+     */
+    headers: Record<string, string> | undefined;
+  };
+
+  /**
+   * Optional token usage for the image generation call (if the provider reports it).
+   */
+  usage?: ImageModelV4Usage;
+};