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

Configuration

Update your OpenAI client initialization - just 2 lines:

import OpenAI from 'openai';

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

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

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

Comparison: OpenAI SDK vs Verlon SDK

Feature	OpenAI SDK + Verlon	Verlon SDK
Migration Effort	2 lines of code	Full refactor
API Format	OpenAI format	Verlon native format
Use Case	Drop-in replacement	New projects
Multi-modal	Chat only	Chat, image, video, audio
Streaming
Tool Calling
Cost Tracking
Admin Operations	L	(via Admin SDK)

Recommendation:

Existing OpenAI apps � Use OpenAI SDK + Verlon (this guide)
New projects � Use Verlon SDK for full feature set

Next Steps

Create a Gate

Set up routing rules and configure models

View Request Logs

Monitor your API usage and costs

Agent Gates

Session tracking for AI agent workflows

Verlon SDK

Explore the full-featured Verlon SDK

Documentation Index

​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

​Comparison: OpenAI SDK vs Verlon SDK

​Next Steps

Create a Gate

View Request Logs

Agent Gates

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

Comparison: OpenAI SDK vs Verlon SDK

Next Steps