maka-agent 0.2.0-dev.3.20260830 → 0.2.0-dev.31.20260913

package/node_modules/@maka/runtime/node_modules/ai/docs/03-ai-sdk-core/36-transcription.mdx

@@ -0,0 +1,333 @@
+---
+title: Transcription
+description: Learn how to transcribe audio with the AI SDK.
+---
+
+# Transcription
+
+The AI SDK provides the [`transcribe`](/docs/reference/ai-sdk-core/transcribe)
+function to transcribe audio using a transcription model.
+
+```ts
+import { transcribe } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { readFile } from 'fs/promises';
+
+const transcript = await transcribe({
+  model: openai.transcription('whisper-1'),
+  audio: await readFile('audio.mp3'),
+});
+```
+
+The `audio` property can be a `Uint8Array`, `ArrayBuffer`, `Buffer`, `string` (base64 encoded audio data), or a `URL`.
+
+To access the generated transcript:
+
+```ts
+const text = transcript.text; // transcript text e.g. "Hello, world!"
+const segments = transcript.segments; // array of segments with start and end times, if available
+const language = transcript.language; // language of the transcript e.g. "en", if available
+const durationInSeconds = transcript.durationInSeconds; // duration of the transcript in seconds, if available
+```
+
+## Streaming Transcription
+
+<Note type="warning">Streaming transcription is an experimental feature.</Note>
+
+Use `experimental_streamTranscribe` when you have live raw audio and need transcript updates before the full audio stream is complete. The function uses transcription models with streaming support; provider options configure provider-specific behavior, but the streaming operation is selected by the function itself.
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { experimental_streamTranscribe as streamTranscribe } from 'ai';
+
+const result = streamTranscribe({
+  model: openai.transcription('gpt-realtime-whisper'),
+  audio: audioStream, // ReadableStream<Uint8Array | string>
+  inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
+  providerOptions: {
+    openai: {
+      language: 'en',
+      streaming: {
+        delay: 'low',
+      },
+    },
+  },
+});
+
+for await (const part of result.fullStream) {
+  if (part.type === 'transcript-delta') {
+    process.stdout.write(part.delta);
+  }
+
+  if (part.type === 'transcript-partial') {
+    console.log('partial:', part.text);
+  }
+
+  if (part.type === 'transcript-final') {
+    console.log('final:', part.text);
+  }
+}
+
+console.log(await result.text);
+```
+
+`fullStream` is a single-consumer live stream and can only be accessed once.
+When you need both stream parts and final results, access `fullStream` first and
+await the result promises while or after consuming it. Accessing a result
+promise first consumes the stream internally, so `fullStream` is no longer
+available. This avoids retaining an unbounded replay buffer for live audio.
+
+To access the final transcript metadata:
+
+```ts
+const text = await result.text; // final transcript text
+const segments = await result.segments; // final segments with timing, if available
+const language = await result.language; // language of the transcript, if available
+const durationInSeconds = await result.durationInSeconds; // duration in seconds, if available
+```
+
+The `audio` stream must contain raw audio chunks. `Uint8Array` chunks are raw bytes; `string` chunks are base64-encoded raw bytes. Always set `inputAudioFormat` to match the chunks you send.
+
+<Note>
+  String model IDs resolve through the global provider (AI Gateway by
+  default). AI Gateway supports streaming transcription for supported models
+  (e.g. `openai/gpt-realtime-whisper`, `elevenlabs/eleven-scribe-2-realtime`,
+  `xai/grok-stt`), so string IDs work:
+  `experimental_streamTranscribe({ model: 'openai/gpt-realtime-whisper', ...
+  })`. You can also pass a provider model instance (e.g.
+  `openai.transcription('gpt-realtime-whisper')`) to stream directly against
+  the provider.
+</Note>
+
+OpenAI streaming transcription uses `openai.transcription('gpt-realtime-whisper')`.
+Cartesia uses `cartesia.transcription('ink-2')` for streaming-only Ink 2
+transcription. ElevenLabs uses
+`elevenLabs.transcription('scribe_v2_realtime')` for Scribe v2 Realtime. xAI
+uses the same `xai.transcription()` model for request/response and streaming
+transcription; `experimental_streamTranscribe` selects the provider's
+WebSocket STT transport.
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { experimental_streamTranscribe as streamTranscribe } from 'ai';
+
+const result = streamTranscribe({
+  model: xai.transcription(),
+  audio: audioStream,
+  inputAudioFormat: { type: 'audio/pcm', rate: 16000 },
+  providerOptions: {
+    xai: {
+      language: 'en',
+      keyterm: ['AI SDK', 'Grok'],
+      streaming: {
+        interimResults: true,
+        endpointing: 500,
+      },
+    },
+  },
+});
+```
+
+Some providers require WebSocket headers for direct streaming STT. In those runtimes, pass a provider-specific `webSocket` implementation when creating the provider.
+
+## Settings
+
+### Provider-Specific settings
+
+Transcription models often have provider or model-specific settings which you can set using the `providerOptions` parameter.
+
+```ts highlight="8-12"
+import { transcribe } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { readFile } from 'fs/promises';
+
+const transcript = await transcribe({
+  model: openai.transcription('whisper-1'),
+  audio: await readFile('audio.mp3'),
+  providerOptions: {
+    openai: {
+      timestampGranularities: ['word'],
+    },
+  },
+});
+```
+
+### Download Size Limits
+
+When `audio` is a URL, the SDK downloads the file with a default **2 GiB** size limit.
+You can customize this using `createDownload`:
+
+```ts highlight="1,7"
+import { transcribe, createDownload } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const transcript = await transcribe({
+  model: openai.transcription('whisper-1'),
+  audio: new URL('https://example.com/audio.mp3'),
+  download: createDownload({ maxBytes: 50 * 1024 * 1024 }), // 50 MB limit
+});
+```
+
+You can also provide a fully custom download function:
+
+```ts highlight="7-13"
+import { transcribe } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const transcript = await transcribe({
+  model: openai.transcription('whisper-1'),
+  audio: new URL('https://example.com/audio.mp3'),
+  download: async ({ url }) => {
+    const res = await myAuthenticatedFetch(url);
+    return {
+      data: new Uint8Array(await res.arrayBuffer()),
+      mediaType: res.headers.get('content-type') ?? undefined,
+    };
+  },
+});
+```
+
+If a download exceeds the size limit, a `DownloadError` is thrown:
+
+```ts
+import { transcribe, DownloadError } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+try {
+  await transcribe({
+    model: openai.transcription('whisper-1'),
+    audio: new URL('https://example.com/audio.mp3'),
+  });
+} catch (error) {
+  if (DownloadError.isInstance(error)) {
+    console.log('Download failed:', error.message);
+  }
+}
+```
+
+### Abort Signals and Timeouts
+
+`transcribe` accepts an optional `abortSignal` parameter of
+type [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+that you can use to abort the transcription process or set a timeout.
+
+This is particularly useful when combined with URL downloads to prevent long-running requests:
+
+```ts highlight="7"
+import { openai } from '@ai-sdk/openai';
+import { transcribe } from 'ai';
+
+const transcript = await transcribe({
+  model: openai.transcription('whisper-1'),
+  audio: new URL('https://example.com/audio.mp3'),
+  abortSignal: AbortSignal.timeout(5000), // Abort after 5 seconds
+});
+```
+
+### Custom Headers
+
+`transcribe` accepts an optional `headers` parameter of type `Record<string, string>`
+that you can use to add custom headers to the transcription request.
+
+```ts highlight="8"
+import { openai } from '@ai-sdk/openai';
+import { transcribe } from 'ai';
+import { readFile } from 'fs/promises';
+
+const transcript = await transcribe({
+  model: openai.transcription('whisper-1'),
+  audio: await readFile('audio.mp3'),
+  headers: { 'X-Custom-Header': 'custom-value' },
+});
+```
+
+### Warnings
+
+Warnings (e.g. unsupported parameters) are available on the `warnings` property.
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { transcribe } from 'ai';
+import { readFile } from 'fs/promises';
+
+const transcript = await transcribe({
+  model: openai.transcription('whisper-1'),
+  audio: await readFile('audio.mp3'),
+});
+
+const warnings = transcript.warnings;
+```
+
+### Error Handling
+
+When `transcribe` cannot generate a valid transcript, it throws a [`AI_NoTranscriptGeneratedError`](/docs/reference/ai-sdk-errors/ai-no-transcript-generated-error).
+
+This error can arise for any of the following reasons:
+
+- The model failed to generate a response
+- The model generated a response that could not be parsed
+
+The error preserves the following information to help you log the issue:
+
+- `responses`: Metadata about the transcription model responses, including timestamp, model, and headers.
+- `cause`: The cause of the error. You can use this for more detailed error handling.
+
+```ts
+import { transcribe, NoTranscriptGeneratedError } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { readFile } from 'fs/promises';
+
+try {
+  await transcribe({
+    model: openai.transcription('whisper-1'),
+    audio: await readFile('audio.mp3'),
+  });
+} catch (error) {
+  if (NoTranscriptGeneratedError.isInstance(error)) {
+    console.log('NoTranscriptGeneratedError');
+    console.log('Cause:', error.cause);
+    console.log('Responses:', error.responses);
+  }
+}
+```
+
+## Transcription Models
+
+| Provider                                                                            | Model                       |
+| ----------------------------------------------------------------------------------- | --------------------------- |
+| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `whisper-1`                 |
+| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `gpt-4o-transcribe`         |
+| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `gpt-4o-mini-transcribe`    |
+| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `gpt-4o-transcribe-diarize` |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#transcription-models)           | `scribe_v1`                 |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#transcription-models)           | `scribe_v1_experimental`    |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#transcription-models)           | `scribe_v2`                 |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#streaming-transcription-models) | `scribe_v2_realtime`        |
+| [Groq](/providers/ai-sdk-providers/groq#transcription-models)                       | `whisper-large-v3-turbo`    |
+| [Groq](/providers/ai-sdk-providers/groq#transcription-models)                       | `whisper-large-v3`          |
+| [Mistral](/providers/ai-sdk-providers/mistral#transcription-models)                 | `voxtral-mini-latest`       |
+| [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `whisper-1`                 |
+| [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `gpt-4o-transcribe`         |
+| [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `gpt-4o-mini-transcribe`    |
+| [Rev.ai](/providers/ai-sdk-providers/revai#transcription-models)                    | `machine`                   |
+| [Rev.ai](/providers/ai-sdk-providers/revai#transcription-models)                    | `low_cost`                  |
+| [Rev.ai](/providers/ai-sdk-providers/revai#transcription-models)                    | `fusion`                    |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `base` (+ variants)         |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `enhanced` (+ variants)     |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `nova` (+ variants)         |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `nova-2` (+ variants)       |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `nova-3` (+ variants)       |
+| [Gladia](/providers/ai-sdk-providers/gladia#transcription-models)                   | `default`                   |
+| [AssemblyAI](/providers/ai-sdk-providers/assemblyai#transcription-models)           | `universal-3-5-pro`         |
+| [AssemblyAI](/providers/ai-sdk-providers/assemblyai#transcription-models)           | `universal-3-pro`           |
+| [Fal](/providers/ai-sdk-providers/fal#transcription-models)                         | `whisper`                   |
+| [Fal](/providers/ai-sdk-providers/fal#transcription-models)                         | `wizper`                    |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models)     | `chirp_2`                   |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models)     | `chirp_3`                   |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models)     | `telephony`                 |
+| [xAI](/providers/ai-sdk-providers/xai#transcription-models)                         | `default`                   |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#transcription-models)               | `ink-whisper`               |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#streaming-transcription-models)     | `ink-2`                     |
+| [Fish Audio](/providers/ai-sdk-providers/fish-audio#transcription-models)           | `transcribe-1`              |
+
+Above are a small subset of the transcription models supported by the AI SDK providers. For more, see the respective provider documentation.

package/node_modules/@maka/runtime/node_modules/ai/docs/03-ai-sdk-core/37-speech.mdx

@@ -0,0 +1,163 @@
+---
+title: Speech
+description: Learn how to generate speech from text with the AI SDK.
+---
+
+# Speech
+
+The AI SDK provides the [`generateSpeech`](/docs/reference/ai-sdk-core/generate-speech)
+function to generate speech from text using a speech model.
+
+```ts
+import { generateSpeech } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const audio = await generateSpeech({
+  model: openai.speech('tts-1'),
+  text: 'Hello, world!',
+  voice: 'alloy',
+});
+```
+
+To access the generated audio:
+
+```ts
+const audioData = result.audio.uint8Array; // audio data as Uint8Array
+// or
+const audioBase64 = result.audio.base64; // audio data as base64 string
+```
+
+## Settings
+
+### Provider-Specific settings
+
+You can set model-specific settings with the `providerOptions` parameter.
+
+```ts highlight="7-11"
+import { generateSpeech } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const audio = await generateSpeech({
+  model: openai.speech('tts-1'),
+  text: 'Hello, world!',
+  providerOptions: {
+    openai: {
+      // ...
+    },
+  },
+});
+```
+
+### Abort Signals and Timeouts
+
+`generateSpeech` accepts an optional `abortSignal` parameter of
+type [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+that you can use to abort the speech generation process or set a timeout.
+
+```ts highlight="7"
+import { openai } from '@ai-sdk/openai';
+import { generateSpeech } from 'ai';
+
+const audio = await generateSpeech({
+  model: openai.speech('tts-1'),
+  text: 'Hello, world!',
+  abortSignal: AbortSignal.timeout(1000), // Abort after 1 second
+});
+```
+
+### Custom Headers
+
+`generateSpeech` accepts an optional `headers` parameter of type `Record<string, string>`
+that you can use to add custom headers to the speech generation request.
+
+```ts highlight="7"
+import { openai } from '@ai-sdk/openai';
+import { generateSpeech } from 'ai';
+
+const audio = await generateSpeech({
+  model: openai.speech('tts-1'),
+  text: 'Hello, world!',
+  headers: { 'X-Custom-Header': 'custom-value' },
+});
+```
+
+### Warnings
+
+Warnings (e.g. unsupported parameters) are available on the `warnings` property.
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { generateSpeech } from 'ai';
+
+const audio = await generateSpeech({
+  model: openai.speech('tts-1'),
+  text: 'Hello, world!',
+});
+
+const warnings = audio.warnings;
+```
+
+### Error Handling
+
+When `generateSpeech` cannot generate a valid audio, it throws a [`AI_NoSpeechGeneratedError`](/docs/reference/ai-sdk-errors/ai-no-speech-generated-error).
+
+This error can arise for any of the following reasons:
+
+- The model failed to generate a response
+- The model generated a response that could not be parsed
+
+The error preserves the following information to help you log the issue:
+
+- `responses`: Metadata about the speech model responses, including timestamp, model, and headers.
+- `cause`: The cause of the error. You can use this for more detailed error handling.
+
+```ts
+import { generateSpeech, NoSpeechGeneratedError } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+try {
+  await generateSpeech({
+    model: openai.speech('tts-1'),
+    text: 'Hello, world!',
+  });
+} catch (error) {
+  if (NoSpeechGeneratedError.isInstance(error)) {
+    console.log('AI_NoSpeechGeneratedError');
+    console.log('Cause:', error.cause);
+    console.log('Responses:', error.responses);
+  }
+}
+```
+
+## Speech Models
+
+| Provider                                                                 | Model                               |
+| ------------------------------------------------------------------------ | ----------------------------------- |
+| [OpenAI](/providers/ai-sdk-providers/openai#speech-models)               | `tts-1`                             |
+| [OpenAI](/providers/ai-sdk-providers/openai#speech-models)               | `tts-1-hd`                          |
+| [OpenAI](/providers/ai-sdk-providers/openai#speech-models)               | `gpt-4o-mini-tts`                   |
+| [Mistral](/providers/ai-sdk-providers/mistral#speech-models)             | `voxtral-mini-tts-2603`             |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#speech-models)       | `eleven_v3`                         |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#speech-models)       | `eleven_multilingual_v2`            |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#speech-models)       | `eleven_flash_v2_5`                 |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#speech-models)       | `eleven_flash_v2`                   |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#speech-models)       | `eleven_turbo_v2_5`                 |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#speech-models)       | `eleven_turbo_v2`                   |
+| [Hume](/providers/ai-sdk-providers/hume#speech-models)                   | `default`                           |
+| [Google](/providers/ai-sdk-providers/google#speech-models)               | `gemini-2.5-flash-preview-tts`      |
+| [Google](/providers/ai-sdk-providers/google#speech-models)               | `gemini-2.5-pro-preview-tts`        |
+| [Google](/providers/ai-sdk-providers/google#speech-models)               | `gemini-3.1-flash-tts-preview`      |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#speech-models) | `gemini-2.5-flash-tts`              |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#speech-models) | `gemini-2.5-pro-tts`                |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#speech-models) | `gemini-2.5-flash-lite-preview-tts` |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#speech-models) | `gemini-3.1-flash-tts-preview`      |
+| [xAI](/providers/ai-sdk-providers/xai#speech-models)                     | `default`                           |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#speech-models)           | `sonic-3.5`                         |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#speech-models)           | `sonic-3`                           |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#speech-models)           | `sonic-2`                           |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#speech-models)           | `sonic-turbo`                       |
+| [Fish Audio](/providers/ai-sdk-providers/fish-audio#speech-models)       | `s1`                                |
+| [Fish Audio](/providers/ai-sdk-providers/fish-audio#speech-models)       | `s2-pro`                            |
+| [Fish Audio](/providers/ai-sdk-providers/fish-audio#speech-models)       | `s2.1-pro`                          |
+
+Above are a small subset of the speech models supported by the AI SDK providers. For more, see the respective provider documentation.

package/node_modules/@maka/runtime/node_modules/ai/docs/03-ai-sdk-core/39-file-uploads.mdx

@@ -0,0 +1,180 @@
+---
+title: File Uploads
+description: Learn how to upload files and use provider references with the AI SDK.
+---
+
+# File Uploads
+
+The AI SDK provides the [`uploadFile`](/docs/reference/ai-sdk-core/upload-file)
+function to upload files to a provider and get back a `ProviderReference` that can be
+used in subsequent API calls.
+
+In the AI SDK, the uploaded file is identified by a `ProviderReference` — a
+`Record<string, string>` mapping provider names to provider-specific identifiers.
+This concept is used for other provider specific asset references too, such as
+uploaded skills.
+
+```ts
+import { uploadFile, generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import fs from 'node:fs';
+
+const { providerReference } = await uploadFile({
+  api: openai.files(),
+  data: fs.readFileSync('./photo.png'),
+  filename: 'photo.png',
+});
+
+const { text } = await generateText({
+  model: openai.responses('gpt-4o-mini'),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'Describe what you see in this image.' },
+        { type: 'file', mediaType: 'image', data: providerReference },
+      ],
+    },
+  ],
+});
+```
+
+As a shorthand, you can pass a provider instance directly to `api` instead of calling `.files()` explicitly — the SDK will call `.files()` for you:
+
+```ts highlight="3"
+const { providerReference } = await uploadFile({
+  api: openai, // shorthand for openai.files()
+  data: fs.readFileSync('./photo.png'),
+  filename: 'photo.png',
+});
+```
+
+## Supported File Types
+
+You can upload images, PDFs, text files, and other documents depending on the provider.
+The media type is auto-detected from the file bytes when not specified explicitly:
+
+```ts highlight="4"
+const { providerReference } = await uploadFile({
+  api: anthropic.files(),
+  data: fs.readFileSync('./document.pdf'),
+  mediaType: 'application/pdf', // optional, auto-detected if omitted
+  filename: 'document.pdf',
+});
+```
+
+Use the `providerReference` in a file content part with its media type:
+
+```ts
+{
+  role: 'user',
+  content: [
+    { type: 'text', text: 'Summarize this document.' },
+    { type: 'file', data: providerReference, mediaType: 'application/pdf' },
+  ],
+}
+```
+
+## Provider-Specific Options
+
+Some providers accept additional options through `providerOptions`.
+For example, OpenAI requires a `purpose` field:
+
+```ts highlight="5-9"
+import { openai, type OpenAIFilesOptions } from '@ai-sdk/openai';
+
+const { providerReference } = await uploadFile({
+  api: openai.files(),
+  data: fs.readFileSync('./photo.png'),
+  providerOptions: {
+    openai: {
+      purpose: 'assistants',
+    } satisfies OpenAIFilesOptions,
+  },
+});
+```
+
+## Streaming Uploads
+
+Providers that support streaming uploads (e.g. OpenAI, xAI) accept a tagged
+`{ type: 'stream', stream }` shape, sending the bytes without buffering the
+full file in memory. Providers without streaming support reject stream data
+with an `UnsupportedFunctionalityError`.
+
+```ts
+const { providerReference } = await uploadFile({
+  api: openai.files(),
+  data: { type: 'stream', stream: fileStream },
+  mediaType: 'application/jsonl',
+  filename: 'batch.jsonl',
+});
+```
+
+The provider consumes the stream: any failed upload — including validation
+failures before a request is made — cancels it, and it must not be reused. Stream data cannot be sniffed, so `mediaType` defaults to
+`application/octet-stream` when omitted, and multipart-based providers default
+the filename to `"blob"`.
+
+Uploads can be cancelled with `abortSignal` and carry request-specific
+`headers`. Results include `byteSize`, `createdAt`, and `expiresAt` (the
+provider-applied retention expiry) when the provider reports them.
+
+## Provider References
+
+A `ProviderReference` is a `Record<string, string>` that maps provider names to
+provider-specific file identifiers:
+
+```ts
+// Example ProviderReference
+{
+  openai: 'file-abc123',
+}
+```
+
+When you pass a `ProviderReference` as the `data` or `image` field of a message content
+part, the provider looks up its own file ID from the reference. If the reference doesn't
+contain an entry for the current provider, an error is thrown.
+
+## Multi-Provider Usage
+
+If you switch providers mid-conversation (for example, continuing a chat started with
+OpenAI using Anthropic), you need to upload the file to both providers and merge the
+references:
+
+```ts
+const openaiResult = await uploadFile({
+  api: openai.files(),
+  data: imageBytes,
+  filename: 'photo.png',
+});
+
+const anthropicResult = await uploadFile({
+  api: anthropic.files(),
+  data: imageBytes,
+  filename: 'photo.png',
+});
+
+const mergedReference = {
+  ...openaiResult.providerReference,
+  ...anthropicResult.providerReference,
+};
+
+// mergedReference: { openai: 'file-abc123', anthropic: 'file-xyz789' }
+```
+
+The merged reference can then be used in messages regardless of which provider processes
+the request — each provider will find its own file ID.
+
+## Supported Providers
+
+The following providers support `files()` and file uploads:
+
+| Provider  | Factory Method      |
+| --------- | ------------------- |
+| Anthropic | `anthropic.files()` |
+| Google    | `google.files()`    |
+| OpenAI    | `openai.files()`    |
+| xAI       | `xai.files()`       |
+
+Providers without file upload support will throw an `UnsupportedFunctionalityError`
+if they encounter a provider reference in a message.