# Models API

The Models API provides information about available Claude models, including their capabilities, context windows, and creation dates.

## API Reference

```typescript { .api }
class Models extends APIResource {
  retrieve(modelID: string, params?: ModelRetrieveParams): APIPromise<ModelInfo>;
  list(params?: ModelListParams): ModelInfosPage;
}
```

Access via:

```typescript
client.models.*  // Standard API
client.beta.models.*  // Beta API
```

## Model Information

```typescript { .api }
interface ModelInfo {
  type: 'model';
  id: string;
  display_name: string;
  created_at: string;
}
```

## Retrieving Model Info

```typescript { .api }
client.models.retrieve(
  modelID: string,
  params?: ModelRetrieveParams
): APIPromise<ModelInfo>;

interface ModelRetrieveParams {
  betas?: AnthropicBeta[];
}
```

**Example:**

```typescript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const model = await client.models.retrieve('claude-sonnet-4-5-20250929');

console.log('Model ID:', model.id);
console.log('Display name:', model.display_name);
console.log('Created at:', model.created_at);
```

## Listing Models

```typescript { .api }
client.models.list(
  params?: ModelListParams
): ModelInfosPage;

interface ModelListParams {
  before_id?: string;
  after_id?: string;
  limit?: number;  // Default: 20, max: 1000
  betas?: AnthropicBeta[];
}
```

**Example:**

```typescript
// List all available models
const models = await client.models.list();

for (const model of models.data) {
  console.log(`${model.display_name} (${model.id})`);
}

// Auto-pagination
for await (const model of client.models.list({ limit: 100 })) {
  console.log(model.id);
}
```

## Available Models

### Claude Opus 4.5

```typescript
model: 'claude-opus-4-5-20250514'
```

- **Capabilities**: Most capable model, excels at complex reasoning and analysis
- **Context Window**: 200K tokens
- **Use Cases**: Research, complex problem solving, detailed analysis

### Claude Sonnet 4.5

```typescript
model: 'claude-sonnet-4-5-20250929'
```

- **Capabilities**: Balance of intelligence and speed
- **Context Window**: 200K tokens
- **Use Cases**: Most applications, coding, writing, analysis

### Claude 3.5 Sonnet

```typescript
model: 'claude-3-5-sonnet-20241022'
```

- **Capabilities**: Previous generation, still highly capable
- **Context Window**: 200K tokens
- **Use Cases**: General purpose applications

### Claude 3.5 Haiku

```typescript
model: 'claude-3-5-haiku-20241022'
```

- **Capabilities**: Fast and efficient for simpler tasks
- **Context Window**: 200K tokens
- **Use Cases**: Quick responses, simple queries, high-throughput

### Claude 3 Family

```typescript
model: 'claude-3-opus-20240229'     // Most capable (previous generation)
model: 'claude-3-sonnet-20240229'   // Balanced (previous generation)
model: 'claude-3-haiku-20240307'    // Fast (previous generation)
```

## Model Selection Guide

Choose based on your needs:

### Opus 4.5 - Maximum Capability
```typescript
const message = await client.messages.create({
  model: 'claude-opus-4-5-20250514',
  max_tokens: 4096,
  messages: [{
    role: 'user',
    content: 'Provide a detailed analysis of quantum computing trends...',
  }],
});
```

Use for:
- Complex reasoning and analysis
- Research and academic work
- Detailed creative writing
- Advanced coding tasks

### Sonnet 4.5 - Best All-Around
```typescript
const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 2048,
  messages: [{
    role: 'user',
    content: 'Help me debug this code...',
  }],
});
```

Use for:
- Most applications
- Coding and development
- Content generation
- Data analysis
- Customer support

### Haiku 3.5 - Speed and Efficiency
```typescript
const message = await client.messages.create({
  model: 'claude-3-5-haiku-20241022',
  max_tokens: 1024,
  messages: [{
    role: 'user',
    content: 'What is 2+2?',
  }],
});
```

Use for:
- Simple queries
- High-throughput scenarios
- Quick responses
- Classification tasks
- Simple data extraction

## Dynamic Model Selection

```typescript
function selectModel(complexity: 'simple' | 'moderate' | 'complex'): string {
  switch (complexity) {
    case 'simple':
      return 'claude-3-5-haiku-20241022';
    case 'moderate':
      return 'claude-sonnet-4-5-20250929';
    case 'complex':
      return 'claude-opus-4-5-20250514';
  }
}

const model = selectModel('moderate');
const message = await client.messages.create({
  model,
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Task...' }],
});
```

## Beta Models

Access beta models with beta headers:

```typescript
const model = await client.beta.models.retrieve(
  'claude-sonnet-4-5-20250929',
  {
    betas: ['extended-thinking-2025-05-14'],
  }
);
```

## Model Deprecation

Models are deprecated over time. The SDK will warn when using deprecated models:

```typescript
// Using deprecated model
const message = await client.messages.create({
  model: 'claude-2.1',  // Deprecated model
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});

// Console warning:
// "The model 'claude-2.1' is deprecated and will reach end-of-life on 2024-12-31
//  Please migrate to a newer model. Visit https://docs.anthropic.com/..."
```

## Context Windows

All current models support 200K token context windows:

```typescript
// You can use large context
const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4096,
  system: largeSystemPrompt,  // Can be very large
  messages: longConversation,  // Many turns
});

// Count tokens first
const count = await client.messages.countTokens({
  model: 'claude-sonnet-4-5-20250929',
  system: largeSystemPrompt,
  messages: longConversation,
});

console.log('Input tokens:', count.input_tokens);
// Ensure: count.input_tokens + max_tokens <= 200000
```

## Best Practices

### Model Choice

```typescript
// ✅ Good: Choose based on task
async function processTask(task: Task) {
  let model: string;

  if (task.requiresDeepReasoning) {
    model = 'claude-opus-4-5-20250514';
  } else if (task.isSimple) {
    model = 'claude-3-5-haiku-20241022';
  } else {
    model = 'claude-sonnet-4-5-20250929';  // Default
  }

  return client.messages.create({ model, /* ... */ });
}

// ❌ Bad: Always using most expensive model
async function processTask(task: Task) {
  return client.messages.create({
    model: 'claude-opus-4-5-20250514',  // Overkill for simple tasks
    /* ... */
  });
}
```

### Cost Optimization

```typescript
// ✅ Good: Use appropriate model for workload
const simpleQueries = tasks.filter(t => t.complexity === 'simple');
const complexQueries = tasks.filter(t => t.complexity === 'complex');

// Process simple with Haiku (cheaper)
for (const task of simpleQueries) {
  await client.messages.create({
    model: 'claude-3-5-haiku-20241022',
    /* ... */
  });
}

// Process complex with Opus (necessary)
for (const task of complexQueries) {
  await client.messages.create({
    model: 'claude-opus-4-5-20250514',
    /* ... */
  });
}
```

### Model Validation

```typescript
// ✅ Good: Validate model exists
async function createMessage(model: string, content: string) {
  try {
    await client.models.retrieve(model);
  } catch (error) {
    if (error instanceof Anthropic.NotFoundError) {
      console.error(`Model ${model} not found`);
      model = 'claude-sonnet-4-5-20250929';  // Fallback
    }
  }

  return client.messages.create({ model, /* ... */ });
}
```

## See Also

- [Messages API](./messages.md) - Using models for message creation
- [Batches](./batches.md) - Model selection in batches
- [Client](./client.md) - Client configuration
