> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verlon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic SDK Integration

> How to use Verlon AI with the Anthropic SDK

Verlon AI provides an Anthropic-compatible API endpoint. You can use the official Anthropic SDK by pointing it to Verlon's base URL instead of Anthropic's.

## Quick Start

### Prerequisites

* Verlon AI account ([sign up](https://verlon.ai/signup))
* Verlon API key from your [Dashboard](https://verlon.ai/dashboard)
* A configured gate (gate UUID)

### Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @anthropic-ai/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @anthropic-ai/sdk
  ```

  ```bash yarn theme={null}
  yarn add @anthropic-ai/sdk
  ```
</CodeGroup>

### Configuration

Update your Anthropic client initialization - just 2 lines:

<CodeGroup>
  ```typescript Before theme={null}
  import Anthropic from '@anthropic-ai/sdk';

  const anthropic = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY,
  });
  ```

  ```typescript After theme={null}
  import Anthropic from '@anthropic-ai/sdk';

  const anthropic = new Anthropic({
    baseURL: 'https://api.verlon.ai',  // ✓ Add this
    apiKey: process.env.VERLON_API_KEY,   // ✓ Change this
  });
  ```
</CodeGroup>

### Making Requests

Verlon supports three ways to specify your gate:

<Tabs>
  <Tab title="Using gateId (Recommended)">
    ```typescript theme={null}
    // @ts-ignore - gateId is a Verlon AI extension
    const response = await anthropic.messages.create({
      gateId: process.env.GATE_ID,
      max_tokens: 1024,
      messages: [
        { role: 'user', content: 'Hello!' }
      ],
    });
    ```

    <Note>
      Requires `@ts-ignore` comment for TypeScript, but provides the clearest intent.
    </Note>
  </Tab>

  <Tab title="Using model field">
    ```typescript theme={null}
    const response = await anthropic.messages.create({
      model: process.env.GATE_ID,  // Gate UUID as model
      max_tokens: 1024,
      messages: [
        { role: 'user', content: 'Hello!' }
      ],
    });
    ```

    <Tip>
      No TypeScript errors, works seamlessly with existing code.
    </Tip>
  </Tab>

  <Tab title="Using header">
    ```typescript theme={null}
    const anthropic = new Anthropic({
      baseURL: 'https://api.verlon.ai',
      apiKey: process.env.VERLON_API_KEY,
      defaultHeaders: {
        'X-Verlon-Gate-Id': process.env.GATE_ID,
      },
    });

    // Then make requests without specifying gateId
    const response = await anthropic.messages.create({
      max_tokens: 1024,
      messages: [
        { role: 'user', content: 'Hello!' }
      ],
    });
    ```

    <Tip>
      Cleanest for TypeScript - set once, use everywhere.
    </Tip>
  </Tab>
</Tabs>

## Streaming Example

Streaming works exactly like the standard Anthropic SDK:

```typescript theme={null}
const stream = await anthropic.messages.create({
  gateId: process.env.GATE_ID,
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Tell me a joke.' }
  ],
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
    process.stdout.write(event.delta.text);
  }
}
```

## What's Supported

<AccordionGroup>
  <Accordion title="Streaming" icon="wave-pulse">
    Full support for `stream: true` with identical behavior to Anthropic
  </Accordion>

  <Accordion title="Tool Use" icon="wrench">
    Works across all providers - Verlon handles format conversion
  </Accordion>

  <Accordion title="Vision" icon="eye">
    Image inputs in messages fully supported
  </Accordion>

  <Accordion title="All Message Types" icon="messages">
    System prompts, user, and assistant messages all supported
  </Accordion>

  <Accordion title="Standard Parameters" icon="sliders">
    `temperature`, `max_tokens`, `top_p`, and other Anthropic parameters
  </Accordion>

  <Accordion title="Usage & Cost Tracking" icon="chart-mixed">
    Standard `response.usage` with token counts, plus Verlon's `cost` field
  </Accordion>
</AccordionGroup>

## Language Examples

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Anthropic from '@anthropic-ai/sdk';

  const anthropic = new Anthropic({
    baseURL: 'https://api.verlon.ai',
    apiKey: process.env.VERLON_API_KEY,
  });

  const response = await anthropic.messages.create({
    gateId: process.env.GATE_ID,
    max_tokens: 1024,
    messages: [
      { role: 'user', content: 'Hello!' }
    ],
  });

  console.log(response.content[0].text);
  ```

  ```python Python theme={null}
  from anthropic import Anthropic

  client = Anthropic(
      base_url="https://api.verlon.ai",
      api_key="sk-vrln-your_api_key",
  )

  response = client.messages.create(
      model="your-gate-uuid",
      max_tokens=1024,
      messages=[
          {"role": "user", "content": "Hello!"}
      ]
  )

  print(response.content[0].text)
  ```

  ```javascript JavaScript theme={null}
  const Anthropic = require('@anthropic-ai/sdk');

  const anthropic = new Anthropic({
    baseURL: 'https://api.verlon.ai',
    apiKey: process.env.VERLON_API_KEY,
  });

  async function chat() {
    const response = await anthropic.messages.create({
      gateId: process.env.GATE_ID,
      max_tokens: 1024,
      messages: [
        { role: 'user', content: 'Hello!' }
      ],
    });

    console.log(response.content[0].text);
  }

  chat();
  ```

  ```bash cURL theme={null}
  curl https://api.verlon.ai/v1/messages \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sk-vrln-your_api_key" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "gateId": "your-gate-uuid",
      "max_tokens": 1024,
      "messages": [
        {"role": "user", "content": "Hello!"}
      ]
    }'
  ```
</CodeGroup>

## Migration Guide

Follow these steps to migrate an existing Anthropic application:

### 1. Update Client Initialization

Find where you initialize the Anthropic client and update it:

```typescript theme={null}
// Before
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

// After
const anthropic = new Anthropic({
  baseURL: 'https://api.verlon.ai',
  apiKey: process.env.VERLON_API_KEY,
});
```

### 2. Add Gate ID

Add `gateId` to your message calls:

```typescript theme={null}
// Before
const response = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  messages: [...],
});

// After
const response = await anthropic.messages.create({
  gateId: process.env.GATE_ID,  // ✓ Add this
  max_tokens: 1024,
  messages: [...],               // Everything else stays the same
});
```

### 3. Update Environment Variables

```bash .env theme={null}
VERLON_API_KEY=sk-vrln-your_key
GATE_ID=your-gate-uuid
```

### 4. Test & Deploy

1. Test in development
2. Verify requests appear in Verlon dashboard
3. Check cost tracking is working
4. Deploy to production

<Note>
  **Easy Rollback:** If anything breaks, revert the 2 changes (`baseURL` + `apiKey`) - takes 30 seconds.
</Note>

## Advanced Usage

### Multiple Gates

Use different gates based on the task:

```typescript theme={null}
const COMPLEX_TASK_GATE = 'uuid-for-claude-opus';
const SIMPLE_TASK_GATE = 'uuid-for-claude-haiku';

async function complexTask(prompt: string) {
  return await anthropic.messages.create({
    gateId: COMPLEX_TASK_GATE,
    max_tokens: 4096,
    messages: [{ role: 'user', content: prompt }],
  });
}

async function simpleTask(prompt: string) {
  return await anthropic.messages.create({
    gateId: SIMPLE_TASK_GATE,
    max_tokens: 1024,
    messages: [{ role: 'user', content: prompt }],
  });
}
```

### Environment-Specific Configuration

```typescript theme={null}
const baseURL = process.env.NODE_ENV === 'production'
  ? 'https://api.verlon.ai'
  : 'http://localhost:3001';  // Local Verlon API for dev

const anthropic = new Anthropic({ baseURL, apiKey: process.env.VERLON_API_KEY });
```

### Error Handling

```typescript theme={null}
try {
  const response = await anthropic.messages.create({
    gateId: process.env.GATE_ID,
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello!' }],
  });

  console.log(response.content[0].text);
} 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

1. **You send** → Anthropic SDK request to `https://api.verlon.ai/v1/messages`
2. **Verlon receives** → Validates gate, applies routing rules
3. **Verlon routes** → Sends to the model configured in your gate (Claude, GPT, Gemini, etc.)
4. **Provider responds** → Returns response in provider's format
5. **Verlon normalizes** → Converts back to Anthropic format
6. **You receive** → Standard Anthropic response with added cost/metadata

Your code doesn't know the difference.

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to change my code?" icon="code">
    No. Just change `baseURL` and `apiKey` in the Anthropic client initialization.
  </Accordion>

  <Accordion title="Can I still use Anthropic directly?" icon="anthropic">
    Yes. Just revert `baseURL` and `apiKey` to Anthropic values.
  </Accordion>

  <Accordion title="Does streaming work?" icon="wave-pulse">
    Yes. `stream: true` works exactly like Anthropic.
  </Accordion>

  <Accordion title="Can I use GPT or Gemini?" icon="sparkles">
    Yes. Configure your gate to use any model — your code stays the same.
  </Accordion>

  <Accordion title="What about tool use?" icon="function">
    Fully supported. Verlon handles the conversion across all providers.
  </Accordion>

  <Accordion title="Do I need the Verlon SDK?" icon="question">
    No. This approach uses only the Anthropic SDK.
  </Accordion>
</AccordionGroup>

## Comparison: Anthropic SDK vs Verlon SDK

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

**Recommendation:**

* **Existing Anthropic apps** → Use Anthropic SDK + Verlon (this guide)
* **New projects** → Use [Verlon SDK](/sdk-reference/overview) for full feature set

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a Gate" icon="door-open" href="/dashboard/creating-gates">
    Set up routing rules and configure models
  </Card>

  <Card title="View Request Logs" icon="list-timeline" href="/dashboard/monitoring">
    Monitor your API usage and costs
  </Card>

  <Card title="Configure Fallbacks" icon="shield-check" href="/concepts/fallback-strategies">
    Learn about fallback strategies
  </Card>

  <Card title="Verlon SDK" icon="code" href="/sdk-reference/overview">
    Explore the full-featured Verlon SDK
  </Card>
</CardGroup>