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

npm install merge-gateway-ai-sdk-provider ai

Quick start

import { createMergeGateway } from "merge-gateway-ai-sdk-provider";
import { generateText } from "ai";

const gateway = createMergeGateway({
  apiKey: process.env.MERGE_GATEWAY_API_KEY,
});

const { text } = await generateText({
  model: gateway("openai/gpt-4o"),
  prompt: "Hello!",
});

console.log(text);

Two ways to integrate

Native provider (recommended)

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

import { createMergeGateway } from "merge-gateway-ai-sdk-provider";

const gateway = createMergeGateway({
  apiKey: process.env.MERGE_GATEWAY_API_KEY,
});

URL shim (zero install)

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

import { createOpenAI } from "@ai-sdk/openai";

const gateway = createOpenAI({
  apiKey: process.env.MERGE_GATEWAY_API_KEY,
  baseURL: "https://api-gateway.merge.dev/v1/ai-sdk",
});

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

Text generation

import { generateText } from "ai";

const { text } = await generateText({
  model: gateway("openai/gpt-4o"),
  prompt: "Explain recursion with examples.",
});

Streaming

import { streamText } from "ai";

const result = streamText({
  model: gateway("anthropic/claude-sonnet-4-20250514"),
  prompt: "Write a short story about an otter.",
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Embeddings

import { embedMany } from "ai";

const { embeddings } = await embedMany({
  model: gateway.textEmbeddingModel("openai/text-embedding-3-small"),
  values: ["hello", "world"],
});

Gateway features

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

Tags

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

const { text } = await generateText({
  model: gateway("openai/gpt-4o"),
  prompt: "Hello!",
  providerOptions: {
    mergeGateway: {
      tags: [
        { key: "env", value: "production" },
        { key: "team", value: "data-science" },
      ],
    },
  },
});

Vendor routing

Control which execution host handles the request:

const { text } = await generateText({
  model: gateway("anthropic/claude-sonnet-4-20250514"),
  prompt: "Hello!",
  providerOptions: {
    mergeGateway: {
      vendor: "bedrock", // Force AWS Bedrock
      // Or: vendors: ["bedrock", "anthropic"] for ordered preference
    },
  },
});

Project association

Track cost and usage per project:

const { text } = await generateText({
  model: gateway("openai/gpt-4o"),
  prompt: "Hello!",
  providerOptions: {
    mergeGateway: {
      projectId: "proj_abc123",
    },
  },
});

Extended thinking

Enable reasoning/thinking for supported models:

const { text } = await generateText({
  model: gateway("anthropic/claude-sonnet-4-20250514"),
  prompt: "What is 15 * 23? Show your work.",
  providerOptions: {
    mergeGateway: {
      thinking: { type: "enabled", budgetTokens: 10000 },
    },
  },
});

Routing metadata

Get details about routing decisions, cost, and latency:

const { text, providerMetadata } = await generateText({
  model: gateway("openai/gpt-4o"),
  prompt: "Hello!",
  providerOptions: {
    mergeGateway: {
      includeRoutingMetadata: true,
    },
  },
});

const routing = providerMetadata?.mergeGateway?.routing;
console.log(routing?.model_used);    // "gpt-4o"
console.log(routing?.vendor_used);   // "openai"
console.log(routing?.cost_usd);      // 0.003
console.log(routing?.strategy);      // "fallback"

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.

import { readFileSync } from "node:fs";

const { text } = await generateText({
  model: gateway("openai/gpt-4o"),
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Summarize this contract." },
        {
          type: "file",
          mediaType: "application/pdf",
          filename: "contract.pdf",
          data: readFileSync("contract.pdf"),
        },
      ],
    },
  ],
});

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:

const { text, warnings } = await generateText({ /* ... */ });
// warnings: [{ type: "unsupported", feature: "file attachment", details: "..." }]

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:…