OpenAI SDK Integration

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)
Verlon API key from your Dashboard
A configured gate (gate UUID)

Installation

npm install openai

pnpm add openai

yarn add openai

Configuration

Update your OpenAI client initialization - just 2 lines:

import OpenAI from 'openai';

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

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:

Using gateId (Recommended)
Using model field
Using header

// @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!' }
  ],
});

Requires @ts-ignore comment for TypeScript, but provides the clearest intent.

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

No TypeScript errors, works seamlessly with existing code.

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!' }
  ],
});

Cleanest for TypeScript - set once, use everywhere.

Streaming Example

Streaming works exactly like the standard OpenAI SDK:

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

Streaming

Full support for stream: true with identical behavior to OpenAI

Tool/Function Calling

Works across all providers - Verlon handles format conversion

Vision

Image inputs in messages fully supported

All Message Types

System, user, assistant, and tool messages all supported

Standard Parameters

temperature, max_tokens, top_p, and other OpenAI parameters

Usage & Cost Tracking

Standard response.usage with token counts, plus Verlon’s cost field

Language Examples

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);

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)

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();

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:

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

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

.env

VERLON_API_KEY=sk-vrln-your_key
GATE_ID=your-gate-uuid

4. Test & Deploy

Test in development
Verify requests appear in Verlon dashboard
Check cost tracking is working
Deploy to production

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:

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

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

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

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

Your code doesn’t know the difference.

FAQ

Do I need to change my code?

No. Just change baseURL and apiKey in the OpenAI client initialization.

Can I still use OpenAI directly?

Yes. Just revert baseURL and apiKey to OpenAI values.

Does streaming work?

Yes. stream: true works exactly like OpenAI.

Can I use Claude or Gemini?

Yes. Configure your gate to use any model your code stays the same.

What about function calling?

Fully supported. Verlon handles the conversion across all providers.

Do I need the Verlon SDK?

No. This approach uses only the OpenAI SDK.

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 is not an alternative inference client; it’s the observability SDK, and it composes with this setup rather than replacing it:

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

Create a Gate

Set up routing rules and configure models

View Request Logs

Monitor your API usage and costs

Configure Fallbacks

Learn about fallback strategies

Verlon SDK

Add agent tracing and task attribution on top of this setup

Getting Started

SDK Reference

Platform

Integrations

Provider Compatibility

OpenAI SDK Integration

Quick Start

Prerequisites

Installation

Configuration

Making Requests

Streaming Example

What’s Supported

Language Examples

Migration Guide

1. Update Client Initialization

2. Add Gate ID

3. Update Environment Variables

4. Test & Deploy

Advanced Usage

Multiple Gates

Environment-Specific Configuration

Error Handling

How It Works

FAQ

Where the Verlon SDK fits

Next Steps

Create a Gate

View Request Logs

Configure Fallbacks

Verlon SDK

​Quick Start

​Prerequisites

​Installation

​Configuration

​Making Requests

​Streaming Example

​What’s Supported

​Language Examples

​Migration Guide

​1. Update Client Initialization

​2. Add Gate ID

​3. Update Environment Variables

​4. Test & Deploy

​Advanced Usage

​Multiple Gates

​Environment-Specific Configuration

​Error Handling

​How It Works

​FAQ

​Where the Verlon SDK fits

​Next Steps

Create a Gate

View Request Logs

Configure Fallbacks

Verlon SDK

Quick Start

Prerequisites

Installation

Configuration

Making Requests

Streaming Example

What’s Supported

Language Examples

Migration Guide

1. Update Client Initialization

2. Add Gate ID

3. Update Environment Variables

4. Test & Deploy

Advanced Usage

Multiple Gates

Environment-Specific Configuration

Error Handling

How It Works

FAQ

Where the Verlon SDK fits

Next Steps