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

# OpenAI SDK Integration

> How to use Verlon AI with the OpenAI SDK

Verlon AI provides an OpenAI-compatible API endpoint. You can use the official OpenAI SDK by pointing it to Verlon's base URL instead of OpenAI's.

## Quick Start

### Prerequisites

* Verlon AI account ([sign up](https://verlon.ai/signup))
* Verlon API key from your [Dashboard](https://verlon.ai/dashboard)
* A configured gate (gate UUID)

### Installation

```bash npm theme={null}
npm install openai
```

```bash pnpm theme={null}
pnpm add openai
```

```bash yarn theme={null}
yarn add openai
```

### Configuration

Update your OpenAI client initialization - just 2 lines:

```typescript Before theme={null}
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});
```

```typescript After theme={null}
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://api.verlon.ai/v1',  // Add this
  apiKey: process.env.VERLON_API_KEY,      // Change this
});
```

### Making Requests

Verlon supports three ways to specify your gate:

> [tab] Using gateId (Recommended)
>
> ```typescript theme={null}
> // @ts-ignore - gateId is a Verlon AI extension
> const response = await openai.chat.completions.create({
>   gateId: process.env.GATE_ID,
>   messages: [
>     { role: 'user', content: 'Hello!' }
>   ],
> });
> ```
>
> > [!NOTE]
> >
> > Requires `@ts-ignore` comment for TypeScript, but provides the clearest intent.

> [tab] Using model field
>
> ```typescript theme={null}
> const response = await openai.chat.completions.create({
>   model: process.env.GATE_ID,  // Gate UUID as model
>   messages: [
>     { role: 'user', content: 'Hello!' }
>   ],
> });
> ```
>
> > [!TIP]
> >
> > No TypeScript errors, works seamlessly with existing code.

> [tab] Using header
>
> ```typescript theme={null}
> const openai = new OpenAI({
>   baseURL: 'https://api.verlon.ai/v1',
>   apiKey: process.env.VERLON_API_KEY,
>   defaultHeaders: {
>     'X-Verlon-Gate-Id': process.env.GATE_ID,
>   },
> });
>
> // Then make requests without specifying gateId
> const response = await openai.chat.completions.create({
>   messages: [
>     { role: 'user', content: 'Hello!' }
>   ],
> });
> ```
>
> > [!TIP]
> >
> > Cleanest for TypeScript - set once, use everywhere.

## Responses API

Verlon also serves OpenAI's newer Responses API at `/v1/responses` — the same two-line client setup, then `openai.responses.create()`:

```typescript theme={null}
const response = await openai.responses.create({
  model: process.env.GATE_ID, // must be an OpenAI-backed gate
  input: 'Summarize this support ticket for the on-call engineer.',
  reasoning: { effort: 'medium' },
});

console.log(response.output_text);
```

**When to prefer it over chat completions:** tool-heavy agent loops (Responses removes chat completions' tool-count ceiling) and reasoning models — the route passes `reasoning` items through verbatim, including `encrypted_content`, so multi-turn tool loops replay correctly.

**Two constraints to know:**

* **OpenAI-backed gates only.** The Responses dialect is OpenAI-specific; a gate that routes to another provider returns a 400. Chat completions remains the portable default that works with every provider behind any gate.
* **Stateless.** `store: true` and `previous_response_id` are rejected — echo prior `reasoning` and `function_call` items back in `input` each turn, exactly as you would against a stateless upstream.

## Streaming Example

Streaming works exactly like the standard OpenAI SDK:

```typescript theme={null}
const stream = await openai.chat.completions.create({
  gateId: process.env.GATE_ID,
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Tell me a joke.' }
  ],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(content);
}
```

## What's Supported

> [accordion] Streaming
>
> Full support for `stream: true` with identical behavior to OpenAI

> [accordion] Tool/Function Calling
>
> Works across all providers - Verlon handles format conversion

> [accordion] Vision
>
> Image inputs in messages fully supported

> [accordion] All Message Types
>
> System, user, assistant, and tool messages all supported

> [accordion] Standard Parameters
>
> `temperature`, `max_tokens`, `top_p`, and other OpenAI parameters

> [accordion] Usage & Cost Tracking
>
> Standard `response.usage` with token counts, plus Verlon's `cost` field

## Language Examples

```typescript TypeScript theme={null}
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://api.verlon.ai/v1',
  apiKey: process.env.VERLON_API_KEY,
});

const response = await openai.chat.completions.create({
  gateId: process.env.GATE_ID,
  messages: [
    { role: 'user', content: 'Hello!' }
  ],
});

console.log(response.choices[0].message.content);
```

```python Python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.verlon.ai/v1",
    api_key="sk-vrln-your_api_key",
)

response = client.chat.completions.create(
    model="your-gate-uuid",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)
```

```javascript JavaScript theme={null}
const OpenAI = require('openai');

const openai = new OpenAI({
  baseURL: 'https://api.verlon.ai/v1',
  apiKey: process.env.VERLON_API_KEY,
});

async function chat() {
  const response = await openai.chat.completions.create({
    gateId: process.env.GATE_ID,
    messages: [
      { role: 'user', content: 'Hello!' }
    ],
  });

  console.log(response.choices[0].message.content);
}

chat();
```

```bash cURL theme={null}
curl https://api.verlon.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-vrln-your_api_key" \
  -d '{
    "gateId": "your-gate-uuid",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

## Migration Guide

Follow these steps to migrate an existing OpenAI application:

### 1. Update Client Initialization

Find where you initialize the OpenAI client and update it:

```typescript theme={null}
// Before
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// After
const openai = new OpenAI({
  baseURL: 'https://api.verlon.ai/v1',
  apiKey: process.env.VERLON_API_KEY,
});
```

### 2. Add Gate ID

Add `gateId` to your completion calls:

```typescript theme={null}
// Before
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [...],
});

// After
const response = await openai.chat.completions.create({
  gateId: process.env.GATE_ID,  // Add this
  messages: [...],               // Everything else stays the same
});
```

### 3. Update Environment Variables

```bash .env theme={null}
VERLON_API_KEY=sk-vrln-your_key
GATE_ID=your-gate-uuid
```

### 4. Test & Deploy

1. Test in development
2. Verify requests appear in Verlon dashboard
3. Check cost tracking is working
4. Deploy to production

> [!NOTE]
>
> **Easy Rollback:** If anything breaks, revert the 2 changes (`baseURL` + `apiKey`) - takes 30 seconds.

## Advanced Usage

### Multiple Gates

Use different gates based on the task:

```typescript theme={null}
const COMPLEX_TASK_GATE = 'uuid-for-gpt-4o';
const SIMPLE_TASK_GATE = 'uuid-for-gpt-4o-mini';

async function complexTask(prompt: string) {
  return await openai.chat.completions.create({
    gateId: COMPLEX_TASK_GATE,
    messages: [{ role: 'user', content: prompt }],
  });
}

async function simpleTask(prompt: string) {
  return await openai.chat.completions.create({
    gateId: SIMPLE_TASK_GATE,
    messages: [{ role: 'user', content: prompt }],
  });
}
```

### Environment-Specific Configuration

```typescript theme={null}
const baseURL = process.env.NODE_ENV === 'production'
  ? 'https://api.verlon.ai/v1'
  : 'http://localhost:3001/v1';  // Local Verlon API for dev

const openai = new OpenAI({ baseURL, apiKey: process.env.VERLON_API_KEY });
```

### Error Handling

```typescript theme={null}
try {
  const response = await openai.chat.completions.create({
    gateId: process.env.GATE_ID,
    messages: [{ role: 'user', content: 'Hello!' }],
  });

  console.log(response.choices[0].message.content);
} catch (error) {
  if (error.status === 404) {
    console.error('Gate not found - check your GATE_ID');
  } else if (error.status === 429) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Request failed:', error.message);
  }
}
```

## How It Works

1. **You send**  OpenAI SDK request to `https://api.verlon.ai/v1/chat/completions`
2. **Verlon receives**  Validates gate, applies routing rules
3. **Verlon routes**  Sends to the model configured in your gate (GPT, Claude, Gemini, etc.)
4. **Provider responds**  Returns response in provider's format
5. **Verlon normalizes**  Converts back to OpenAI format
6. **You receive**  Standard OpenAI response with added cost/metadata

Your code doesn't know the difference.

## FAQ

> [accordion] Do I need to change my code?
>
> No. Just change `baseURL` and `apiKey` in the OpenAI client initialization.

> [accordion] Can I still use OpenAI directly?
>
> Yes. Just revert `baseURL` and `apiKey` to OpenAI values.

> [accordion] Does streaming work?
>
> Yes. `stream: true` works exactly like OpenAI.

> [accordion] Can I use Claude or Gemini?
>
> Yes. Configure your gate to use any model  your code stays the same.

> [accordion] What about function calling?
>
> Fully supported. Verlon handles the conversion across all providers.

> [accordion] Do I need the Verlon SDK?
>
> No. This approach uses only the OpenAI SDK.

> [accordion] Does this work with Vercel AI SDK?
>
> Yes. The Vercel AI SDK's OpenAI adapter works with Verlon's OpenAI-compatible endpoint.

## Where the Verlon SDK fits

This guide is the recommended integration path for inference — new projects
and existing apps alike. The [Verlon SDK](https://docs.verlon.ai/sdk-reference/overview.md) is not an
alternative inference client; it's the observability SDK, and it composes
with this setup rather than replacing it:

```typescript theme={null}
import OpenAI from 'openai';
import { Verlon } from '@verlon-ai/sdk';

const verlon = new Verlon({ apiKey: process.env.VERLON_API_KEY });
const agent = verlon.agent(process.env.GATE_ID);
const respond = agent.task('respond');

await agent.trace({ conversationId: chatId }, async () => {
  // clientOptions() supplies baseURL, a trace-aware fetch, and
  // gate/task identity headers — this call lands on the trace timeline
  const openai = new OpenAI({
    apiKey: process.env.VERLON_API_KEY,
    ...respond.clientOptions('openai'),
  });
  return openai.chat.completions.create({ messages });
});
```

Reach for it when you want agent traces, per-task model control, and session
grouping in the dashboard — see [Agent Tracing](https://docs.verlon.ai/platform/agent-gates.md). The
gateway does not need it for routing, logging, or cost tracking; those come
with this guide's two-line setup. Video generation is served drop-in too — the async Videos surface (`openai.videos.create()` / `retrieve()` / `downloadContent()`) works against `/v1/videos`, and OCR against [`/mistral/v1/ocr`](https://docs.verlon.ai/provider-compatibility/mistral).

## Next Steps

> [card] [Create a Gate](https://docs.verlon.ai/dashboard/creating-gates)
>
> Set up routing rules and configure models

> [card] [View Request Logs](https://docs.verlon.ai/dashboard/monitoring)
>
> Monitor your API usage and costs

> [card] [Configure Fallbacks](https://docs.verlon.ai/platform/gates.md)
>
> Learn about fallback strategies

> [card] [Verlon SDK](https://docs.verlon.ai/sdk-reference/overview.md)
>
> Add agent tracing and task attribution on top of this setup


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