Core Function Reference
Purpose and Scope
AI SDK Core is the provider-agnostic layer exposed from the ai package. Its job is to let application code call language models, embedding models, reranking models, file APIs, and related utilities through one consistent surface instead of coding directly against each provider. The public import path is intentionally simple: the package entry point re-exports the source module, so user code imports functions such as generateText, streamText, generateObject, embed, rerank, and uploadFile from ai rather than reaching into internal package folders.
Sources: packages/ai/index.ts
This page is a reader-oriented map, not an exhaustive type listing. Use it to decide which core function starts your task, what kind of model or provider capability it expects, and what result shape you should look for. The official reference groups text, structured data, embeddings, reranking, media generation, uploads, schema helpers, model wrapping, stream utilities, identifiers, and validation helpers under AI SDK Core. The repository evidence here shows how several of those functions are exercised in tests, including their option forwarding, normalized result objects, provider metadata, and warning behavior.
Sources: packages/ai/src/generate-object/generate-object.test.ts, packages/ai/src/embed/embed.test.ts, packages/ai/src/rerank/rerank.test.ts, packages/ai/src/upload-file/upload-file.test.ts
Relevant Source Files
packages/ai/index.ts— package-level barrel that makes the Core API available from the top-levelaiimport path.packages/ai/src/generate-text/generate-text.test.ts— requested test source for text generation behavior and public expectations aroundgenerateText.packages/ai/src/generate-object/generate-object.test.ts— test coverage forgenerateObject, schema conversion, JSON response formats, typed object results, and validation/error paths.packages/ai/src/embed/embed.test.ts— test coverage forembed, returned embeddings, request headers, provider options, usage, response bodies, warnings, provider metadata, and lifecycle events.packages/ai/src/rerank/rerank.test.ts— test coverage forrerank, document ordering, ranking records, provider options, response metadata, headers, and start/end event types.packages/ai/src/upload-file/upload-file.test.ts— test coverage foruploadFile, tagged data inputs, default media types, filenames, provider options, provider references, provider metadata, and warnings.
Core Function Families
Use the text functions when your output is primarily natural language. generateText is the one-shot API for asking a model for a complete text result, while streamText is the streaming counterpart for interactive interfaces, long responses, and server responses that should start before the model finishes. The official Core overview demonstrates the simplest call shape: pass a model and a prompt, then read the returned text. In practice, these functions are also the entry point for tool calling, multi-step generation, callbacks, stream transforms such as smoothing, and response helpers used by web frameworks.
Sources: packages/ai/index.ts, packages/ai/src/generate-text/generate-text.test.ts
Use the structured data functions when your application needs a validated value rather than prose. generateObject accepts a schema and prompt, asks the model for JSON, and returns an object that has already been parsed and validated against that schema. The test evidence shows a Zod object schema being converted into a JSON response format with type: 'json', required properties, and additionalProperties: false. The same tests also verify that optional response format metadata such as a schema name and description is forwarded to the model call.
Sources: packages/ai/src/generate-object/generate-object.test.ts
Use embeddings and reranking for retrieval workflows. embed turns a single value into a vector and returns the original value, the embedding, token usage when available, provider response data, warnings, and provider metadata. embedMany is the companion public API for batching multiple values, although its detailed tests are outside this page’s requested source set. rerank takes a query and documents, asks a reranking model to score them, and returns both the original documents and a reordered view. The tests demonstrate that ranking records preserve each document, original index, and relevance score.
Sources: packages/ai/src/embed/embed.test.ts, packages/ai/src/rerank/rerank.test.ts
Use file and media functions when model calls need provider-managed assets or non-text outputs. The official Core reference includes generateImage, transcribe, generateSpeech, experimental_generateVideo, uploadFile, and uploadSkill. The supplied tests cover uploadFile directly: it sends tagged binary or text data to a provider file API, applies default media types, forwards filenames and provider options, and returns provider references, metadata, and warnings. Treat uploads as a preparatory operation: first create the provider-side file reference, then pass that reference into later model-specific workflows that support it.
Sources: packages/ai/src/upload-file/upload-file.test.ts
Compact API Reference
| Task | Public entry point | Primary inputs | Result focus | Notes |
|---|---|---|---|---|
| One-shot text | generateText | model, prompt or messages, call options | generated text and model response data | Use when the caller can wait for a complete answer. |
| Streaming text | streamText | model, prompt/messages, stream options | text stream and stream response helpers | Use for chat UIs, route handlers, and progressive output. |
| Structured object | generateObject | model, schema, prompt, optional name and description | validated object | Tests show JSON response format generation from a Zod schema. |
| Structured stream | streamObject | model, schema, prompt/messages | incremental structured output | Use when partial object updates are useful. |
| Single embedding | embed | embedding model, value, headers, provider options | embedding, value, usage, response, metadata | Tests show custom headers and provider options forwarded to the model. |
| Batched embeddings | embedMany | embedding model, multiple values | multiple embeddings and usage | Use for indexing multiple records. |
| Reranking | rerank | reranking model, query, documents, topN | ranking, rerankedDocuments, originalDocuments | Tests show rankings mapped back to original document indexes. |
| File upload | uploadFile | files API, tagged data, optional mediaType, filename, provider options | provider file reference, metadata, warnings | Tests show binary defaults to application/octet-stream and text defaults to text/plain. |
| Media generation | generateImage, transcribe, generateSpeech, experimental_generateVideo | provider-specific media-capable models and inputs | generated or transformed media artifacts | Publicly listed in Core reference; implementation details are outside this page’s source set. |
| Utilities | jsonSchema, zodSchema, valibotSchema, cosineSimilarity, smoothStream, generateId, createIdGenerator | schemas, vectors, streams, or identifier options | normalized helper outputs | Use to support Core calls without coupling to provider internals. |
Structured Data Behavior
generateObject is the clearest example of how AI SDK Core normalizes provider calls. The caller supplies an application-level schema and a prompt; the function converts that schema into a JSON response format before invoking the model. The test snapshot shows a user prompt represented as a normalized message with text content and an undefined provider options field. The response format contains JSON Schema draft metadata, required fields, property types, and optional name and description fields when the caller provides them.
Sources: packages/ai/src/generate-object/generate-object.test.ts
That behavior matters because structured generation is only useful when the rest of the application can trust the shape of the result. The tests import provider-level parse and validation error types, which signals that invalid JSON and schema mismatches are part of the public failure model. When you design a structured call, start from the consumer of the data, define a narrow schema, and include a prompt that asks for exactly that shape. If the model should return a list, enum, or specialized output mode, use the structured data guide before treating the value as domain data.
Sources: packages/ai/src/generate-object/generate-object.test.ts
Embeddings, Reranking, and Retrieval Results
The embed tests show that embedding calls return more than a vector. A successful result includes the original input value and the generated embedding, and may include usage information such as token counts. The model can also provide response bodies, response headers, provider metadata, and warnings. Request-level details are forwarded too: custom headers are merged with the AI SDK user agent, and provider options are passed through using provider-scoped keys. This makes embed suitable both for simple semantic search and for production indexing paths that need observability or provider-specific tuning.
Sources: packages/ai/src/embed/embed.test.ts
rerank complements embeddings by reordering candidate documents for a query. The tests exercise string documents, a query, a topN limit, and provider options. The mocked model returns an ordered set of indexes and relevance scores; the SDK maps those indexes back into rerankedDocuments and detailed ranking entries that include the original document, original index, and score. This design keeps the model result compact while preserving the caller’s original document values, which is important when ranking records are later displayed, filtered, or joined back to database rows.
Sources: packages/ai/src/rerank/rerank.test.ts
File Upload Behavior
uploadFile is the Core function for sending file-like data to a provider file API. The tests define a FilesV4 mock with an uploadFile method, then verify that the SDK forwards a single normalized call object. Tagged binary data uses the default media type application/octet-stream; tagged text data uses text/plain. Callers can pass base64 data, Uint8Array data, an explicit filename, and provider-scoped options such as a provider-specific purpose. The result preserves provider references and metadata so later calls can refer to uploaded assets without assuming a universal file identifier.
Sources: packages/ai/src/upload-file/upload-file.test.ts
The distinction between provider reference and provider metadata is deliberate. A provider reference is the portable container for the provider’s identifier, such as a generated file id keyed by provider name. Provider metadata is additional information returned by that provider, such as file size or other upload attributes. Warnings are also returned rather than hidden. When you build upload flows, store the provider reference alongside your application record, inspect warnings for degraded behavior, and keep provider options provider-scoped so the same application code can evolve across providers.
Sources: packages/ai/src/upload-file/upload-file.test.ts
System-to-Code Mapping
The top-level package entry point is the public doorway; the tests are the contract examples. When a function under AI SDK Core calls a model, file API, or provider capability, the test suites generally verify three things: normalized inputs sent to the provider, normalized results returned to the caller, and pass-through fields that preserve provider-specific power without polluting the common API. This pattern appears across object generation, embedding, reranking, and uploads. It is also the mental model to use when reading other Core pages: common fields first, provider-scoped escape hatches second.
Sources: packages/ai/index.ts, packages/ai/src/generate-object/generate-object.test.ts, packages/ai/src/embed/embed.test.ts, packages/ai/src/rerank/rerank.test.ts, packages/ai/src/upload-file/upload-file.test.ts
For implementation work, start with the function family that matches your product output. Choose generateText or streamText for prose, generateObject or streamObject for typed values, embed and rerank for retrieval, media functions for non-text generation, and uploadFile when a provider needs an asset before a model call. Next, select a provider package or AI Gateway model that supports that capability. Finally, add schema validation, provider options, headers, telemetry, and tests around the exact result fields your application stores or displays.
Sources: packages/ai/src/generate-text/generate-text.test.ts, packages/ai/src/generate-object/generate-object.test.ts, packages/ai/src/embed/embed.test.ts, packages/ai/src/rerank/rerank.test.ts, packages/ai/src/upload-file/upload-file.test.ts
Testing Signals and Next Steps
The requested test files are useful reading because they express behavior at the boundary an application developer experiences. Snapshot assertions show prompt normalization and JSON schema response formats. Embedding assertions show that metadata, usage, headers, warnings, and provider options are observable. Reranking assertions show how provider index-based rankings become caller-friendly document records. Upload assertions show default media type decisions and provider-reference preservation. These tests are better starting points than internal helpers when you need to understand what user code can rely on.
Sources: packages/ai/src/generate-object/generate-object.test.ts, packages/ai/src/embed/embed.test.ts, packages/ai/src/rerank/rerank.test.ts, packages/ai/src/upload-file/upload-file.test.ts
Next, read the task-specific pages for the function family you are about to use. For language output, continue to Generating Text and Streaming. For schemas, continue to Structured Data Generation. For tool loops, use Tools and Tool Calling before building agents. For retrieval, continue to Embeddings and Reranking. For files and multimodal work, continue to Image, Audio, and Video Generation. Keep this reference as the map: it tells you where the public Core surface begins and which result objects deserve attention in production code.