> ## 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

<CodeGroup>
  ```bash npm theme={null}
  npm install openai
  ```

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

  ```bash yarn theme={null}
  yarn add openai
  ```
</CodeGroup>

### Configuration

Update your OpenAI client initialization - just 2 lines:

<CodeGroup>
  ```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
  });
  ```
</CodeGroup>

### Making Requests

Verlon supports three ways to specify your gate:

<Tabs>
  <Tab title="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.
    </Note>
  </Tab>

  <Tab title="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.
    </Tip>
  </Tab>

  <Tab title="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.
    </Tip>
  </Tab>
</Tabs>

## 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

<AccordionGroup>
  <Accordion title="Streaming" icon="wave-pulse">
    Full support for `stream: true` with identical behavior to OpenAI
  </Accordion>

  <Accordion title="Tool/Function Calling" icon="wrench">
    Works across all providers - Verlon handles format conversion
  </Accordion>

  <Accordion title="Vision" icon="eye">
    Image inputs in messages fully supported
  </Accordion>

  <Accordion title="All Message Types" icon="messages">
    System, user, assistant, and tool messages all supported
  </Accordion>

  <Accordion title="Standard Parameters" icon="sliders">
    `temperature`, `max_tokens`, `top_p`, and other OpenAI parameters
  </Accordion>

  <Accordion title="Usage & Cost Tracking" icon="chart-mixed">
    Standard `response.usage` with token counts, plus Verlon's `cost` field
  </Accordion>
</AccordionGroup>

## Language Examples

<CodeGroup>
  ```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!"}
      ]
    }'
  ```
</CodeGroup>

## 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.
</Note>

## 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

<AccordionGroup>
  <Accordion title="Do I need to change my code?" icon="code">
    No. Just change `baseURL` and `apiKey` in the OpenAI client initialization.
  </Accordion>

  <Accordion title="Can I still use OpenAI directly?" icon="openai">
    Yes. Just revert `baseURL` and `apiKey` to OpenAI values.
  </Accordion>

  <Accordion title="Does streaming work?" icon="wave-pulse">
    Yes. `stream: true` works exactly like OpenAI.
  </Accordion>

  <Accordion title="Can I use Claude or Gemini?" icon="sparkles">
    Yes. Configure your gate to use any model  your code stays the same.
  </Accordion>

  <Accordion title="What about function calling?" icon="function">
    Fully supported. Verlon handles the conversion across all providers.
  </Accordion>

  <Accordion title="Do I need the Verlon SDK?" icon="question">
    No. This approach uses only the OpenAI SDK.
  </Accordion>

  <Accordion title="Does this work with Vercel AI SDK?" icon="v">
    Yes. The Vercel AI SDK's OpenAI adapter works with Verlon's OpenAI-compatible endpoint.
  </Accordion>
</AccordionGroup>

## Where the Verlon SDK fits

This guide is the recommended integration path for inference — new projects
and existing apps alike. The [Verlon SDK](/sdk-reference/overview) 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](/platform/agent-gates). The
gateway does not need it for routing, logging, or cost tracking; those come
with this guide's two-line setup. Video and OCR are the exception: Verlon
doesn't mirror drop-in routes for them yet, so they're served by the v3 REST API
(`POST /v3/video`, `POST /v3/ocr`).

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a Gate" icon="door-open" href="/dashboard/creating-gates">
    Set up routing rules and configure models
  </Card>

  <Card title="View Request Logs" icon="list-timeline" href="/dashboard/monitoring">
    Monitor your API usage and costs
  </Card>

  <Card title="Configure Fallbacks" icon="shield-check" href="/platform/gates">
    Learn about fallback strategies
  </Card>

  <Card title="Verlon SDK" icon="https://mintlify.s3.us-west-1.amazonaws.com/layerai/assets/icons/icon-light.svg" href="/sdk-reference/overview">
    Add agent tracing and task attribution on top of this setup
  </Card>
</CardGroup>