Batch API

Batch functions submit many requests to a provider for asynchronous processing, then poll for status and read the results. The functions are experimental and carry the Experimental prefix.

A Provider field accepts a provider.BatchV4 value, a provider that exposes ExperimentalBatch(), or nil. When it is nil, the batch runs through the AI Gateway.

Functions

Function	Returns
ai.ExperimentalStartBatch(ctx, StartBatchOptions)	*StartBatchResult. Submits the batch.
ai.ExperimentalGetBatchStatus(ctx, GetBatchStatusOptions)	*Batch. The batch with its latest status.
ai.ExperimentalGetBatchResults(ctx, GetBatchResultsOptions)	*BatchResultsStream. Streams the terminal results.
ai.ExperimentalCancelBatch(ctx, CancelBatchOptions)	*CancelBatchResult. Requests cancellation.
ai.ExperimentalListBatches(ctx, ListBatchesOptions)	*ListBatchesResult. One page of batches.

BatchReference and Batch

ai.BatchReference is the value to persist. It holds Version, ID and Provider, which is enough to check status, read results or cancel from another process. ai.Batch embeds BatchReference and provider.BatchV4Status.

StartBatchOptions

Field	Type	Description
Provider	interface{}	Provider is a provider.BatchV4 instance, a provider.BatchProvider (a Provider exposing ExperimentalBatch()), or nil. When nil, batches are processed through the AI Gateway (mirrors TypeScript: globalThis.AI_SDK_DEFAULT_PROVIDER ?? gateway).
Requests	[]BatchRequest
ProviderOptions	map[string]interface{}
WebhookURL	string	WebhookURL, when set, is the URL the provider notifies when the batch reaches a terminal state. Providers that do not support completion webhooks return an unsupported-functionality warning instead of erroring.
MaxRetries	*int
Headers	map[string]string
Timeout	*time.Duration

StartBatchResult

Field	Type	Description
(embedded)	Batch	Embedded.
Warnings	[]provider.BatchV4Warning

BatchImageRequest

An image request inside a batch.

Field	Type	Description
ID	string
Model	string
Prompt	string
N	*int
Size	string
AspectRatio	string
Seed	*int
Files	[]provider.ImageFile
Mask	*provider.ImageFile
ProviderOptions	map[string]interface{}

GetBatchStatusOptions

Field	Type	Description
Provider	interface{}
Batch	BatchReference
ProviderOptions	map[string]interface{}
MaxRetries	*int
Headers	map[string]string
Timeout	*time.Duration

GetBatchResultsOptions

Field	Type	Description
Provider	interface{}
Batch	BatchReference
ProviderOptions	map[string]interface{}
MaxRetries	*int
Headers	map[string]string
Timeout	*time.Duration

BatchResultsStream

Next() returns the next *ai.BatchItemResult and io.EOF when the stream is complete. Err() returns the first error. Close() releases the stream. The shape matches provider.TextStream.

Field	Type	Description
Type	provider.BatchRequestType
ID	string
Status	provider.BatchItemStatus
Text	*types.GenerateResult	Text is populated when Type is text and Status is succeeded.
Image	*types.ImageResult	Image is populated when Type is image and Status is succeeded.
Error	*provider.BatchError
ProviderMetadata	map[string]interface{}

CancelBatchOptions

Field	Type	Description
Provider	interface{}
Batch	BatchReference
ProviderOptions	map[string]interface{}
Headers	map[string]string
Timeout	*time.Duration

Field	Type	Description
ProviderMetadata	map[string]interface{}

ListBatchesOptions

Field	Type	Description
Provider	interface{}
ProviderOptions	map[string]interface{}
Limit	*int	Limit is optional (nil means unset), mirroring TypeScript's limit?: number. An explicit 0 is forwarded to the provider rather than treated as "not set".
Cursor	string
MaxRetries	*int
Headers	map[string]string
Timeout	*time.Duration

ListBatchesResult

Field	Type	Description
Batches	[]Batch
NextCursor	string
ProviderMetadata	map[string]interface{}