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

# Vercel AI SDK

*Last edited: 25 Oct 2026 (Asia/Hong\_Kong)*

Point the [Vercel AI SDK](https://sdk.vercel.ai) at NexLLM’s OpenAI-compatible gateway. **Chat and streaming** use `@ai-sdk/openai`. **Images** use the published [`@nexllm/ai-sdk-provider`](https://www.npmjs.com/package/@nexllm/ai-sdk-provider) package (`0.1.0`) with AI SDK `generateImage` / `experimental_generateImage`.

> [!NOTE]
>
> Already migrating off Vercel AI Gateway? Follow [Migrate from Vercel AI Gateway](https://docs.nexllm.ai/migrations/vercel-ai-gateway.md) for env vars, model IDs, and gateway-option cleanup. This page is the Integrations setup for new apps and for using NexLLM as your AI SDK backend.

## Introduction

NexLLM is an OpenAI-compatible inference gateway at `https://www.nexllm.ai/v1`.

| Capability | Status on NexLLM |
| - | - |
| `generateText` / `streamText` (Chat Completions) | **Ready** — `createOpenAI` + `.chat(modelId)` |
| Model discovery | **Ready** — `GET /v1/models` with your key |
| Image generation (`generateImage` via NexLLM provider) | **Ready** — `@nexllm/ai-sdk-provider@0.1.0` → `nexllm.image(modelId)` |
| Images via OpenAI SDK / HTTP | **Ready** — `POST /v1/images/generations` and `/v1/images/edits` |
| Image edits via the thin AI SDK provider | **Not in this package** — use OpenAI SDK or HTTP |
| Embeddings / speech / video via this provider | **No** — use Compatible APIs or other SDKs |

Spend lands on the [wallet](https://docs.nexllm.ai/account/wallet-and-top-up.md) tied to your API key. There is no Vercel-AI-specific surcharge.

If your agent should call NexLLM from Claude or Cursor instead of application code, use the [MCP integration](https://docs.nexllm.ai/integrations/mcp-integration.md).

## Prerequisites

* A NexLLM account at [www.nexllm.ai](https://www.nexllm.ai)
* An API key from the dashboard ([Getting your API keys](https://docs.nexllm.ai/get-started/getting-your-api-keys.md))
* Node.js and a project that uses (or will use) the `ai` package
* Wallet balance for paid inference

Keep `NEXLLM_API_KEY` server-side. Do not expose it in public Next.js `NEXT_PUBLIC_*` vars or browser bundles.

## Install

### Chat only

```bash theme={null}
npm install ai @ai-sdk/openai
```

### Chat + images (recommended)

```bash theme={null}
npm install ai @ai-sdk/openai @nexllm/ai-sdk-provider
```

Peer dependency for the image provider: **`ai` ^6** (ImageModelV3). Use matching majors for `ai` and `@ai-sdk/openai` — do not mix unrelated major upgrades.

Package: [npmjs.com/package/@nexllm/ai-sdk-provider](https://www.npmjs.com/package/@nexllm/ai-sdk-provider)

## Configure environment

```bash theme={null}
export NEXLLM_API_KEY="YOUR_NEXLLM_API_KEY"

# Example only — use an exact id from GET /v1/models for your key
export NEXLLM_MODEL="gpt-4o"
export NEXLLM_IMAGE_MODEL="dall-e-3"
```

Authentication for OpenAI-compatible requests:

```text theme={null}
Authorization: Bearer YOUR_NEXLLM_API_KEY
```

See [Authentication](https://docs.nexllm.ai/api-reference/authentication.md).

## Chat with the AI SDK

Create an explicit OpenAI provider pointed at NexLLM, then use `.chat(modelId)` for Chat Completions.

```javascript theme={null}
import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const apiKey = process.env.NEXLLM_API_KEY;
const modelId = process.env.NEXLLM_MODEL;

if (!apiKey || !modelId) {
  throw new Error("NEXLLM_API_KEY and NEXLLM_MODEL are required");
}

const nexllmChat = createOpenAI({
  baseURL: "https://www.nexllm.ai/v1",
  apiKey,
});

const { text } = await generateText({
  model: nexllmChat.chat(modelId),
  prompt: "Write a short greeting.",
});

console.log(text);
```

> [!WARNING]
>
> Use `nexllmChat.chat(modelId)` when you want Chat Completions. The OpenAI provider’s default model factory can select the Responses API. Do not replace `.chat(modelId)` with `nexllmChat(modelId)` unless you intentionally want `/v1/responses` and have verified the model supports it.

### Streaming

```javascript theme={null}
import { createOpenAI } from "@ai-sdk/openai";
import { streamText } from "ai";

const nexllmChat = createOpenAI({
  baseURL: "https://www.nexllm.ai/v1",
  apiKey: process.env.NEXLLM_API_KEY,
});

const result = streamText({
  model: nexllmChat.chat(process.env.NEXLLM_MODEL),
  prompt: "Explain NexLLM in one paragraph.",
});

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

In a Next.js Route Handler or Server Action, return `result.toDataStreamResponse()` (or the streaming helper your AI SDK major documents) the same way you would for any other OpenAI-compatible provider.

### Discover model IDs

```bash theme={null}
curl https://www.nexllm.ai/v1/models \
  -H "Authorization: Bearer $NEXLLM_API_KEY"
```

Use the exact `data[].id` value in `nexllmChat.chat(...)` and `nexllm.image(...)`. Do not invent a mapping from another gateway’s prefixed strings. See [Models API](https://docs.nexllm.ai/api-reference/models.md) and [Channel groups](https://docs.nexllm.ai/channel-groups/overview.md).

## Images with `@nexllm/ai-sdk-provider`

The published package wraps `POST /v1/images/generations` for AI SDK `generateImage` / `experimental_generateImage`. It does **not** replace `@ai-sdk/openai` for chat.

### Quick start

```javascript theme={null}
import { nexllm } from "@nexllm/ai-sdk-provider";
import { experimental_generateImage as generateImage } from "ai";

const { image, images } = await generateImage({
  model: nexllm.image(process.env.NEXLLM_IMAGE_MODEL || "dall-e-3"),
  prompt: "A serene mountain landscape at sunset with a reflecting lake",
  size: "1024x1024",
});

// AI SDK returns binary / base64-backed image objects
console.log("bytes:", image.uint8Array?.byteLength ?? image.base64?.length);
```

### Custom config

```javascript theme={null}
import { createNexllm } from "@nexllm/ai-sdk-provider";

const nexllm = createNexllm({
  apiKey: process.env.NEXLLM_API_KEY,
  baseURL: "https://www.nexllm.ai/v1", // default
});

const model = nexllm.image("dall-e-2", { maxImagesPerCall: 4 });
```

### Optional provider options

> [!NOTE]
>
> For **GPT Image** model IDs (`nexllm/gpt-image-*`), **do not pass `response_format`** (and prefer a provider/path that omits it). The `b64_json` example below is for models that accept OpenAI Images `response_format` (for example classic DALL·E-style). Confirm with `GET /v1/models` plus a cheap probe.

```javascript theme={null}
await generateImage({
  model: nexllm.image("dall-e-3"),
  prompt: "A product hero shot on a clean studio background",
  size: "1024x1024",
  providerOptions: {
    nexllm: {
      quality: "hd",
      style: "vivid",
      // default inside the provider is b64_json
      response_format: "b64_json",
    },
  },
});
```

Confirm image-capable model IDs with `GET /v1/models` for your key. Full gateway fields: [Image Generation API](https://docs.nexllm.ai/api-reference/image-generation.md).

From an agent (Claude / Cursor), you can also use MCP `generate_image` — see [MCP integration](https://docs.nexllm.ai/integrations/mcp-integration.md).

## Images without the AI SDK provider (fallback)

If your `ai` major does not expose a compatible image provider interface yet, call the OpenAI SDK or HTTP against the same base URL.

### OpenAI SDK

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://www.nexllm.ai/v1",
  apiKey: process.env.NEXLLM_API_KEY,
});

const response = await client.images.generate({
  model: "dall-e-3", // confirm an image model id available to your key
  prompt: "A futuristic cityscape at sunset",
  n: 1,
  size: "1024x1024",
});

console.log(response.data[0]?.url);
```

### Direct HTTP

```bash theme={null}
curl https://www.nexllm.ai/v1/images/generations \
  -H "Authorization: Bearer $NEXLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A futuristic cityscape at sunset",
    "n": 1,
    "size": "1024x1024"
  }'
```

## Optional: Responses API

If you deliberately need the Responses shape:

```javascript theme={null}
const { text } = await generateText({
  model: nexllmChat.responses(modelId), // only after verifying Responses compatibility
  prompt: "Write a short greeting.",
});
```

Confirm the model’s supported endpoint types first. See [API Reference](https://docs.nexllm.ai/api-reference/overview.md) and the Responses notes in [Migrate from Vercel AI Gateway](https://docs.nexllm.ai/migrations/vercel-ai-gateway.md).

## How billing works

| Call path | Billing |
| - | - |
| AI SDK `generateText` / `streamText` via `/v1/chat/completions` | Standard gateway rates for that model |
| `@nexllm/ai-sdk-provider` images | Standard gateway rates for that image model |
| OpenAI SDK / HTTP images | Same wallet rates |
| MCP tools from an agent | Same wallet; no MCP surcharge |

There is no separate “Vercel AI” price list. See [Pricing overview](https://docs.nexllm.ai/channel-groups/pricing-overview.md) and [Wallet](https://docs.nexllm.ai/account/wallet-and-top-up.md).

## Troubleshooting

> [accordion] Requests still go to Vercel AI Gateway
>
> Search the repo for `@ai-sdk/gateway`, `gateway(`, `AI_GATEWAY_API_KEY`, and `ai-gateway.vercel.sh`. Replace migrated call sites with `createOpenAI({ baseURL: "https://www.nexllm.ai/v1", ... })` and `.chat(modelId)`. Check shared registries and background jobs, not only the main route.

> [accordion] The AI SDK hits /responses unexpectedly
>
> Use `model: nexllmChat.chat(modelId)` for Chat Completions. The default OpenAI provider factory may select Responses.

> [accordion] Model not found
>
> Call `GET /v1/models` with the **same** key the app uses. Confirm the exact `id`, the key’s [channel group](https://docs.nexllm.ai/channel-groups/overview.md), and any model restrictions on the key.

> [accordion] Authentication fails
>
> Send a NexLLM key in `NEXLLM_API_KEY`, not a Vercel gateway key or OIDC token. Check expiration, IP allowlist, and whitespace. See [Authentication](https://docs.nexllm.ai/api-reference/authentication.md).

> [accordion] generateImage fails or package not found
>
> Install `@nexllm/ai-sdk-provider` (and `ai` ^6). Confirm the image model ID is available to your key. For edits (`/v1/images/edits`), use the OpenAI SDK — the thin provider only wraps generations.

## Related

* [Migrate from Vercel AI Gateway](https://docs.nexllm.ai/migrations/vercel-ai-gateway.md) — full cutover checklist
* [Compatible APIs](https://docs.nexllm.ai/integrations/compatible-apis.md) — OpenAI-compatible gateway overview
* [MCP integration](https://docs.nexllm.ai/integrations/mcp-integration.md) — agents instead of app code
* [Skills](https://docs.nexllm.ai/integrations/skills.md) — outcome recipes on top of MCP
* [API Reference](https://docs.nexllm.ai/api-reference/overview.md) — all gateway endpoints
* [Getting your API keys](https://docs.nexllm.ai/get-started/getting-your-api-keys.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.