Skip to main content

Anthropic Claude Integration

Anthropic provides Claude, a family of state-of-the-art language models known for extended thinking, safety, and nuanced understanding. This guide shows you how to integrate Anthropic Claude with Lava’s payment platform.

Quick Reference

  • Authentication: x-api-key header (NOT Authorization: Bearer)
  • Additional Header: anthropic-version: 2023-06-01 (required)
  • Endpoint: https://api.anthropic.com/v1/messages
  • Request Format: Anthropic-specific (max_tokens required, system separate)
  • 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)

Active Models

  • claude-sonnet-4-5-20250929 - Latest Sonnet (September 2025)
  • claude-opus-4-1-20250805 - Latest Opus (August 2025)
  • claude-opus-4-20250514 - Opus 4 (May 2025)
  • claude-sonnet-4-20250514 - Sonnet 4 (May 2025)
  • claude-haiku-4-5-20251001 - Latest Haiku (October 2025)
  • claude-3-7-sonnet-20250219 - Sonnet 3.7 (February 2025)
  • claude-3-5-haiku-20241022 - Haiku 3.5 (October 2024)
  • claude-3-haiku-20240307 - Haiku 3 (March 2024)

Model Families

  • Opus: Most capable, best for complex tasks (creative writing, strategy, research)
  • Sonnet: Balanced intelligence and speed (content creation, analysis, coding)
  • Haiku: Fastest, most cost-effective (customer support, moderation, extraction)

Pricing (per million tokens)

ModelInputOutputCache Write (5min)Cache Read
Opus 4.1$15$75$18.75$1.50
Sonnet 4.5$3$15$3.75$0.30
Haiku 4.5$1$5$1.25$0.10

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

/**
 * Anthropic Claude Messages API via Lava
 *
 * Key Differences from OpenAI:
 * - Uses `x-api-key` header (NOT `Authorization: Bearer`)
 * - Requires `anthropic-version: 2023-06-01` header
 * - `max_tokens` is REQUIRED (not optional)
 * - `system` prompt is separate field (not in messages array)
 * - Usage fields: `input_tokens` and `output_tokens`
 */

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

async function callClaudeViaLava() {
  // 1. Define the provider endpoint
  const PROVIDER_ENDPOINT = 'https://api.anthropic.com/v1/messages';

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

  // 3. Set up authentication headers (Anthropic-specific)
  const headers = {
    'Content-Type': 'application/json',
    'x-api-key': process.env.LAVA_FORWARD_TOKEN,  // NOTE: x-api-key, not Authorization
    'anthropic-version': '2023-06-01'  // Required by Anthropic
  };

  // 4. Define the request body (Anthropic format)
  const requestBody = {
    model: 'claude-sonnet-4-5',
    max_tokens: 1024,  // REQUIRED (not optional like OpenAI)
    messages: [
      { role: 'user', content: 'Say hello in one sentence.' }
    ],
    system: 'You are a helpful assistant.'  // Separate from messages array
  };

  // 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 (Anthropic-specific field names)
    const usage = data.usage;
    console.log('\nUsage Tracking:');
    console.log(`  Input tokens: ${usage.input_tokens}`);
    console.log(`  Output tokens: ${usage.output_tokens}`);
    console.log(`  Total tokens: ${usage.input_tokens + usage.output_tokens}`);

    // Check for prompt caching
    if (usage.cache_read_input_tokens) {
      console.log(`  Cache read tokens: ${usage.cache_read_input_tokens}`);
    }
    if (usage.cache_creation_input_tokens) {
      console.log(`  Cache creation tokens: ${usage.cache_creation_input_tokens}`);
    }

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

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

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

// Run the example
callClaudeViaLava();

Request Format

Anthropic-Specific Format:
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Hello, Claude"}
  ],
  "system": "You are a helpful assistant",
  "temperature": 0.7
}
Key Differences from OpenAI:
  • max_tokens is required (not optional)
  • system prompt is separate field (not in messages array)
  • Uses x-api-key header instead of Authorization: Bearer
  • Requires anthropic-version header

Response Format

{
  "id": "msg_01HCDu5LRGeP2o7s2xGmxyx8",
  "type": "message",
  "role": "assistant",
  "content": [{
    "type": "text",
    "text": "Hello! How can I help you today?"
  }],
  "model": "claude-sonnet-4-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 25
  }
}

Key Features

Extended Thinking

Claude models support extended reasoning with thinking tokens tracked separately for transparency and billing.

Prompt Caching

Use cache_control blocks to cache frequently used context (system prompts, documents, code) for up to 5 minutes:
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "Large system prompt or document...",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [...]
}
Cache Pricing:
  • Cache writes: 25% markup on input token price
  • Cache reads: 90% discount from input token price
  • Cache duration: 5 minutes

Vision Support

All Claude 3+ models support image inputs:
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "image",
        "source": {
          "type": "base64",
          "media_type": "image/jpeg",
          "data": "iVBORw0KGgoAAAANS..."
        }
      },
      {
        "type": "text",
        "text": "What's in this image?"
      }
    ]
  }]
}

Message Batches

Process multiple requests asynchronously at 50% discount:
POST /v1/messages/batches
(See Anthropic docs for batch API details)

Usage Tracking

Location: All usage data is in the response body at data.usage (NOT in headers). Fields:
  • input_tokens - Prompt tokens consumed
  • output_tokens - Completion tokens generated
  • cache_read_input_tokens - Cached input tokens (90% discount)
  • cache_creation_input_tokens - Cache write tokens (25% markup)
Lava Headers:
  • x-lava-request-id - Request ID for dashboard lookup
Lava does NOT add usage/cost/balance headers. All usage data comes from the response body.

BYOK Support

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

Official Documentation

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