> ## Documentation Index
> Fetch the complete documentation index at: https://sferadev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ai-gateway-proxy

> A lightweight proxy for Vercel AI Gateway

A proxy handler for [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) that supports both API key and OIDC authentication methods.

## Features

* **Request/Response Hooks** - Transform requests and responses with `beforeRequest`, `afterResponse`, and `onError` hooks
* **Streaming Support** - Full SSE streaming with content aggregation using AI SDK V3 protocol
* **Framework Agnostic** - Works with Next.js, Hono, Express, and other frameworks

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install ai-gateway-proxy
  ```

  ```bash pnpm theme={null}
  pnpm add ai-gateway-proxy
  ```

  ```bash yarn theme={null}
  yarn add ai-gateway-proxy
  ```
</CodeGroup>

## Usage

### Next.js App Router

Create a catch-all route handler at `app/api/ai/[...segments]/route.ts`:

```typescript theme={null}
import { createGatewayProxy } from "ai-gateway-proxy";

export const { GET, POST, PUT, DELETE, PATCH } = createGatewayProxy();
```

#### Custom Catch-All Parameter Name

If your route uses a different parameter name (e.g., `app/api/ai/[...path]/route.ts`):

```typescript theme={null}
import { createGatewayProxy } from "ai-gateway-proxy";

export const { GET, POST, PUT, DELETE, PATCH } = createGatewayProxy({
  segmentsParam: "path",
});
```

### Hono

For frameworks without catch-all route support, use the `extractPath` option:

```typescript theme={null}
import { Hono } from "hono";
import { createGatewayProxy } from "ai-gateway-proxy";

const app = new Hono();

const proxy = createGatewayProxy({
  extractPath: (request) => {
    const url = new URL(request.url);
    // Remove the base path prefix to get the gateway path
    return url.pathname.replace(/^\/api\/ai\//, "");
  },
});

// Handle all routes under /api/ai/*
app.all("/api/ai/*", (c) => proxy(c.req.raw));

export default app;
```

### Express / Node.js

```typescript theme={null}
import express from "express";
import { createGatewayProxy } from "ai-gateway-proxy";

const app = express();

const proxy = createGatewayProxy({
  extractPath: (request) => {
    const url = new URL(request.url);
    return url.pathname.replace(/^\/api\/ai\//, "");
  },
});

app.all("/api/ai/*", async (req, res) => {
  const response = await proxy(req);
  // Convert Web Response to Express response
  res.status(response.status);
  response.headers.forEach((value, key) => res.setHeader(key, value));
  const body = await response.arrayBuffer();
  res.send(Buffer.from(body));
});
```

## Configuration

### Custom Base URL

```typescript theme={null}
createGatewayProxy({
  baseUrl: "https://ai-gateway.vercel.sh/v1/ai",
});
```

### Additional Headers

```typescript theme={null}
createGatewayProxy({
  headers: {
    "x-custom-header": "value",
  },
});
```

### Request Transformation

Transform the request body before forwarding to the gateway:

```typescript theme={null}
createGatewayProxy({
  beforeRequest: ({ request }) => {
    return {
      ...request,
      maxOutputTokens: 1000,
    };
  },
});
```

### Response Transformation

Transform the response after receiving from the gateway. For streaming responses, this is called when the stream completes with aggregated content:

```typescript theme={null}
createGatewayProxy({
  afterResponse: ({ request, response }) => {
    console.log("Usage:", response.usage);
    return response;
  },
});
```

### Error Handling

Custom error handling with the `onError` hook:

```typescript theme={null}
createGatewayProxy({
  onError: ({ request, error, status }) => {
    console.error("Gateway error:", error);

    // Return modified error
    return error;

    // Or return a custom Response
    // return new Response("Custom error", { status: 500 });
  },
});
```

## Authentication

The proxy automatically handles authentication using one of the following methods (in order of priority):

### API Key

Set the `AI_GATEWAY_API_KEY` environment variable:

```bash theme={null}
AI_GATEWAY_API_KEY=your-api-key
```

### OIDC (Vercel)

When deployed on Vercel, the proxy automatically uses [Vercel OIDC](https://vercel.com/docs/oidc) for authentication. No additional configuration is required.

## API Reference

### `createGatewayProxy(options?)`

Creates a proxy handler for the AI Gateway.

#### Options

| Option          | Type                                              | Default                                | Description                                                                                     |
| --------------- | ------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `baseUrl`       | `string`                                          | `"https://ai-gateway.vercel.sh/v1/ai"` | The base URL of the AI Gateway                                                                  |
| `headers`       | `Record<string, string>`                          | `{}`                                   | Additional headers to include in requests                                                       |
| `segmentsParam` | `string`                                          | `"segments"`                           | The name of the catch-all parameter in the route                                                |
| `extractPath`   | `(request: Request) => string \| Promise<string>` | -                                      | Custom function to extract the path from the request. When provided, `segmentsParam` is ignored |
| `beforeRequest` | `(ctx) => request`                                | -                                      | Transform request body before forwarding                                                        |
| `afterResponse` | `(ctx) => response`                               | -                                      | Transform response after receiving (aggregated for streaming)                                   |
| `onError`       | `(ctx) => error \| Response`                      | -                                      | Custom error handling                                                                           |

#### Returns

A handler function with named exports for HTTP methods: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`.

### `getGatewayAuthToken()`

Retrieves the authentication token for the AI Gateway.

```typescript theme={null}
import { getGatewayAuthToken } from "ai-gateway-proxy";

const auth = await getGatewayAuthToken();
// { token: "...", authMethod: "api-key" | "oidc" }
```

### `StreamContentAggregator`

Aggregates streaming content into a complete response. Used internally by the proxy for `afterResponse` hooks on streaming requests.

```typescript theme={null}
import { StreamContentAggregator } from "ai-gateway-proxy";

const aggregator = new StreamContentAggregator();
aggregator.process(streamPart);
const response = aggregator.getResponse();
```

### `createStreamTransformer(body, requestBody, afterResponse)`

Creates a transform stream that passes through SSE events while aggregating content and calling the `afterResponse` hook on completion.

## Types

```typescript theme={null}
import type {
  CreateGatewayProxyOptions,
  CreateGatewayProxyFn,
  CreateGatewayProxyResult,
  GatewayResponse,
  GatewayError,
} from "ai-gateway-proxy";
```