Skip to main content

OpenAI Integration

OpenAI provides cutting-edge language models including GPT-5, GPT-4.1, and specialized models for reasoning, audio, and vision. This guide shows you how to integrate OpenAI with Lava’s payment platform.

Quick Reference

  • Authentication: Bearer token via Authorization header
  • Endpoint: https://api.openai.com/v1/chat/completions
  • Request Format: OpenAI-compatible (standard model + messages)
  • Usage Data: Available in response body at data.usage
  • Billing Basis: Tokens (input + output)
  • BYOK Support: Yes (managed keys + bring your own key)

Current Models (October 2025)

Frontier Models

  • gpt-5 - Best for coding and agentic tasks
  • gpt-5-mini - Faster, cost-efficient version
  • gpt-5-nano - Fastest, most cost-efficient
  • gpt-5-pro - Smarter and more precise responses
  • gpt-4.1 - Smartest non-reasoning model

Reasoning Models

  • o3 - Reasoning model for complex tasks (succeeded by GPT-5)
  • o4-mini - Fast, cost-efficient reasoning
  • o3-mini - Small alternative to o3

Legacy (Still Available)

  • gpt-4o - Fast, intelligent, flexible
  • gpt-4o-mini - Fast, affordable for focused tasks
  • gpt-4-turbo - Older high-intelligence model
  • gpt-3.5-turbo - Legacy model for cheaper tasks

Specialized Models

Audio: gpt-audio, gpt-audio-mini, gpt-realtime, gpt-realtime-mini Image Generation: gpt-image-1, gpt-image-1-mini, dall-e-3 Video: sora-2, sora-2-pro Embeddings: text-embedding-3-large, text-embedding-3-small

Integration Example

Prerequisites

  • Lava forward token (get from dashboard: Build > Secret Keys)
  • Backend server (CORS blocks frontend calls for security)

Environment Setup

.env.local
LAVA_BASE_URL=https://api.lavapayments.com/v1
LAVA_FORWARD_TOKEN=your_forward_token_from_dashboard

Complete Example

/**
 * OpenAI Chat Completion via Lava
 *
 * Response Data:
 * - Usage tracking: Available in response body at `data.usage`
 * - Request ID: Available in `x-lava-request-id` response header
 */

// Load environment variables
require('dotenv').config({ path: '.env.local' });

async function callOpenAIViaLava() {
  // 1. Define the provider endpoint
  const PROVIDER_ENDPOINT = 'https://api.openai.com/v1/chat/completions';

  // 2. Build the Lava forward proxy URL
  const url = `${process.env.LAVA_BASE_URL}/forward?u=${PROVIDER_ENDPOINT}`;

  // 3. Set up authentication headers
  const headers = {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.LAVA_FORWARD_TOKEN}`
  };

  // 4. Define the request body (standard OpenAI format)
  const requestBody = {
    model: 'gpt-5',  // or gpt-4o, gpt-4.1, etc.
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Say hello in one sentence.' }
    ],
    temperature: 0.7,
    max_tokens: 1024
  };

  // 5. Make the request
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(requestBody)
    });

    // 6. Parse the response
    const data = await response.json();

    // 7. Extract usage data (from response body)
    const usage = data.usage;
    console.log('\nUsage Tracking:');
    console.log(`  Prompt tokens: ${usage.prompt_tokens}`);
    console.log(`  Completion tokens: ${usage.completion_tokens}`);
    console.log(`  Total tokens: ${usage.total_tokens}`);

    // Check for cached tokens (GPT-4o feature)
    if (usage.prompt_tokens_details?.cached_tokens) {
      console.log(`  Cached tokens: ${usage.prompt_tokens_details.cached_tokens}`);
    }

    // 8. Extract request ID (from response header)
    const requestId = response.headers.get('x-lava-request-id');
    console.log(`\nLava Request ID: ${requestId}`);
    console.log('  (Use this ID to find the request in your dashboard)');

    // 9. Display the AI response
    console.log('\nAI Response:');
    console.log(data.choices[0].message.content);

    return data;
  } catch (error) {
    console.error('Error calling OpenAI via Lava:', error.message);
    throw error;
  }
}

// Run the example
callOpenAIViaLava();

Request Format

Standard OpenAI Format:
{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}

Response Format

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 7,
    "total_tokens": 20,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}

Key Features

Multi-modal Capabilities

  • Text: All GPT models
  • Images: GPT-4o and GPT-4 models support image inputs
  • Audio: GPT-audio models for voice interactions
  • Video: Sora models for video generation

Function Calling

Use the tools parameter for structured outputs:
{
  "model": "gpt-4o",
  "messages": [...],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string"}
        }
      }
    }
  }]
}

JSON Mode

Force structured JSON responses:
{
  "model": "gpt-4o",
  "messages": [...],
  "response_format": {"type": "json_object"}
}

Prompt Caching

GPT-4o supports prompt caching for cost savings. Cached tokens are reported in usage.prompt_tokens_details.cached_tokens and billed at a discount.

Usage Tracking

Location: All usage data is in the response body at data.usage (NOT in headers). Fields:
  • prompt_tokens - Input tokens consumed
  • completion_tokens - Output tokens generated
  • total_tokens - Sum of input + output
  • prompt_tokens_details.cached_tokens - Cached tokens (discount applied)
Lava Headers:
  • x-lava-request-id - Request ID for dashboard lookup (ONLY Lava-added header)
Lava does NOT add usage/cost/balance headers. All usage data comes from the response body.

BYOK Support

OpenAI supports BYOK (Bring Your Own Key) mode. See the BYOK Guide for details on using your own OpenAI API key with Lava metering.

Official Documentation

For complete API details, see the official OpenAI documentation.
Documentation current as of October 2025. Model availability subject to change.