merge-gateway-ai-sdk-provider weekly downloads statistics

merge-gateway-ai-sdk-provider

Merge Gateway provider for the Vercel AI SDK. Route requests to OpenAI, Anthropic, Google, and more through a single provider with built-in failover, intelligent routing, and cost optimization.

Installation

Quick start

Two ways to integrate

Native provider (recommended)

Install merge-gateway-ai-sdk-provider for typed Gateway features:

URL shim (zero install)

If you already have @ai-sdk/openai, point it at the Gateway:

Both approaches hit the same endpoints. The native provider adds typed providerOptions for Gateway features.

Text generation

Streaming

Embeddings

Gateway features

The native provider exposes Gateway-specific features via providerOptions.mergeGateway:

Tags

Categorize requests for filtering, cost tracking, and routing policy overrides:

Vendor routing

Control which execution host handles the request:

Project association

Track cost and usage per project:

Extended thinking

Enable reasoning/thinking for supported models:

Routing metadata

Get details about routing decisions, cost, and latency:

Attachments

File parts are forwarded to the model. Images become OpenAI image_url blocks, audio becomes input_audio, and everything else (PDF, Office documents, video) becomes the gateway's unified file block, which it translates into each vendor's own document format.

data may be bytes, a base64 string, a data: URI, or a URL, and the AI SDK v6 tagged forms ({ type: "data" | "url" | "text" }) are read as well. Provider file references ({ type: "reference" }) cannot be resolved by the gateway.

Whether the model can *read* a given media type still depends on the route: the gateway forwards the attachment, and a vendor that does not accept it returns an error. Anything this provider cannot forward is reported in warnings on the result rather than dropped silently:

Prompt caching

Cache markers ride on providerOptions, either on a content part or on the message as a whole, and are translated into the gateway's cache_control:

The anthropic, openrouter, and mergeGateway namespaces are all read, in either the cacheControl or cache_control spelling. Caching applies on explicit routes; the response reports cache activity in its usage.

Tool calling

Tools work the same as with any AI SDK provider:

Structured output

generateObject / streamObject map to the gateway's native json_schema structured output. Schemas pass through untouched — nested objects, $defs, anyOf, and optional fields all reach the provider as you wrote them.

Controlling strict

The strict flag defaults to true. Schemas with optional fields, unions (anyOf), or open objects are rejected by OpenAI-style strict mode — turn it off per call (or per model via gateway(modelId, { strictJsonSchema: false })):

If a routed model can't honor the schema, the gateway fails loudly with a 400 unsupported_params (surfaced as an APICallError) — never a silent fallback to best-effort JSON.

AI SDK v5

AI SDK v5 (ai@5) uses provider spec v2 and cannot load the default entry point. Import from merge-gateway-ai-sdk-provider/v5 instead — same implementation and options, wrapped in a v2 adapter:

| AI SDK major | Import |

| ai@6 | merge-gateway-ai-sdk-provider | | ai@5 | merge-gateway-ai-sdk-provider/v5 | | ai@4 | not supported — use the URL shim |

API reference

createMergeGateway(options?)

Creates a Merge Gateway provider instance.

| Option | Type | Default | Description |

| apiKey | string | MERGE_GATEWAY_API_KEY env | Merge Gateway API key | | baseURL | string | https://api-gateway.merge.dev/v1/ai-sdk | Base URL for AI SDK endpoints | | headers | Record | — | Custom headers for every request | | fetch | typeof fetch | — | Custom fetch implementation |

Provider methods

| Method | Returns | Description |

| gateway(modelId) | MergeGatewayChatLanguageModel | Create a chat model | | gateway.chat(modelId) | MergeGatewayChatLanguageModel | Create a chat model (explicit) | | gateway.textEmbeddingModel(modelId) | MergeGatewayEmbeddingModel | Create an embedding model |

MergeGatewayProviderOptions

Passed via providerOptions.mergeGateway:

| Option | Type | Description |

| tags | Array | Request categorization tags | | projectId | string | Project ID for cost tracking | | vendor | string | Single vendor preference | | vendors | string[] | Ordered vendor preference list | | includeRoutingMetadata | boolean | Include routing metadata in response | | thinking | { type: "enabled" \| "disabled"; budgetTokens: number } | Extended thinking config | | strictJsonSchema | boolean | strict flag for json_schema structured output (default true; set false for schemas with optional fields/unions) |

License

MIT

Description from the npm listing.