Overview

The easiest way to use AI Gateway is with the official OpenAI SDK. Simply change the base URL and API key - all your existing code works unchanged.

Installation

Node.js / TypeScript

npm install openai

Python

pip install openai

Configuration

TypeScript

import OpenAI from 'openai';
 
const openai = new OpenAI({
  baseURL: 'https://api.transactional.dev/ai/v1',
  apiKey: process.env.GATEWAY_API_KEY,  // gw_sk_xxx
});

Python

from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.transactional.dev/ai/v1",
    api_key=os.environ["GATEWAY_API_KEY"]  # gw_sk_xxx
)

Usage Examples

Chat Completions

const response = await openai.chat.completions.create({
  model: 'gpt-4o',  // or claude-3-5-sonnet, etc.
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' }
  ],
});
 
console.log(response.choices[0].message.content);

Streaming

const stream = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});
 
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Function Calling

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'What is the weather?' }],
  tools: [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: 'Get weather for a location',
        parameters: {
          type: 'object',
          properties: {
            location: { type: 'string' }
          }
        }
      }
    }
  ],
});

With Vision

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What is in this image?' },
        {
          type: 'image_url',
          image_url: { url: 'https://example.com/image.jpg' }
        }
      ]
    }
  ],
});

JSON Mode

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You output JSON.' },
    { role: 'user', content: 'List 3 fruits' }
  ],
  response_format: { type: 'json_object' },
});
 
const data = JSON.parse(response.choices[0].message.content);

Using Different Providers

The same OpenAI SDK works with all providers - just change the model:

// OpenAI
const response1 = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [...],
});
 
// Anthropic (same SDK!)
const response2 = await openai.chat.completions.create({
  model: 'claude-3-5-sonnet',
  messages: [...],
});
 
// Google (coming soon)
const response3 = await openai.chat.completions.create({
  model: 'gemini-pro',
  messages: [...],
});

Error Handling

import OpenAI from 'openai';
 
try {
  const response = await openai.chat.completions.create({...});
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    switch (error.status) {
      case 400:
        console.error('Invalid request:', error.message);
        break;
      case 401:
        console.error('Invalid API key');
        break;
      case 429:
        console.error('Rate limited, retry after:', error.headers?.['retry-after']);
        break;
      case 500:
        console.error('Server error:', error.message);
        break;
    }
  }
}

Accessing Response Headers

Access AI Gateway-specific headers:

const response = await openai.chat.completions.create({...});
 
// Access via _response property (if available)
const headers = response._response?.headers;
const cacheStatus = headers?.get('x-cache');  // HIT or MISS
const cost = headers?.get('x-cost-total');

Or use the fetch API directly:

const response = await fetch('https://api.transactional.dev/ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({...}),
});
 
console.log('Cache:', response.headers.get('x-cache'));
console.log('Cost:', response.headers.get('x-cost-total'));

Full Compatibility

AI Gateway is fully compatible with the OpenAI SDK:

Feature	Supported
Chat completions	Yes
Streaming	Yes
Function calling	Yes
Tool use	Yes
Vision	Yes
JSON mode	Yes
Embeddings	Coming Soon
Images	Coming Soon

Migration Guide

Migrating from direct OpenAI:

import OpenAI from 'openai';
 
const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: 'https://api.transactional.dev/ai/v1',
+  apiKey: process.env.GATEWAY_API_KEY,
});
 
// All your existing code works unchanged!