npm-anthropic-ai--sdk

1
# Models API
2

3
The Models API provides access to information about available Claude models, their capabilities, and specifications. Use this API to discover which models are available and their technical details.
4

5
## Capabilities
6

7
### Retrieve Model Information
8

9
Get detailed information about a specific model, including its capabilities and specifications.
10

11
```typescript { .api }
12
/**
13
 * Get information about a specific model
14
 * @param modelID - The model identifier
15
 * @param params - Optional parameters for the request
16
 * @returns Promise resolving to model information
17
 */
18
retrieve(
19
  modelID: string, 
20
  params?: ModelRetrieveParams
21
): APIPromise<ModelInfo>;
22

23
interface ModelRetrieveParams {
24
  /** Beta features to enable for this request */
25
  betas?: AnthropicBeta;
26
}
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import Anthropic from "@anthropic-ai/sdk";
33

34
const client = new Anthropic();
35

36
// Get information about a specific model
37
const modelInfo = await client.models.retrieve("claude-3-5-sonnet-latest");
38

39
console.log(`Model: ${modelInfo.display_name}`);
40
console.log(`Context length: ${modelInfo.context_length} tokens`);
41
console.log(`Created: ${modelInfo.created_at}`);
42

43
// Get model info with beta features
44
const betaModelInfo = await client.models.retrieve(
45
  "claude-3-5-sonnet-latest",
46
  { betas: ["computer-use-2024-10-22"] }
47
);
48
```
49

50
### List Available Models
51

52
Get a list of all available models, with the most recently released models listed first.
53

54
```typescript { .api }
55
/**
56
 * List all available models
57
 * @param params - Optional parameters for filtering and pagination
58
 * @returns PagePromise for iterating through model list
59
 */
60
list(params?: ModelListParams): PagePromise<ModelInfosPage, ModelInfo>;
61

62
interface ModelListParams {
63
  /** Maximum number of models to return per page */
64
  limit?: number;
65
  /** Pagination cursor for next page */
66
  after?: string;
67
  /** Pagination cursor for previous page */
68
  before?: string;
69
  /** Beta features to enable for this request */
70
  betas?: AnthropicBeta;
71
}
72
```
73

74
**Usage Examples:**
75

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

80
for (const model of models.data) {
81
  console.log(`${model.id}: ${model.display_name}`);
82
}
83

84
// List with pagination
85
const firstPage = await client.models.list({ limit: 5 });
86
console.log(`Found ${firstPage.data.length} models`);
87

88
if (firstPage.has_more) {
89
  const nextPage = await client.models.list({ 
90
    limit: 5, 
91
    after: firstPage.last_id 
92
  });
93
}
94

95
// Iterate through all models automatically
96
for await (const model of client.models.list()) {
97
  console.log(model.display_name);
98
}
99
```
100

101
## Model Information Types
102

103
```typescript { .api }
104
interface ModelInfo {
105
  /** Unique model identifier */
106
  id: string;
107
  /** Human-readable model name */
108
  display_name: string;
109
  /** Model creation timestamp */
110
  created_at: string;
111
  /** Maximum context length in tokens */
112
  context_length: number;
113
  /** Maximum output tokens (if specified) */
114
  max_tokens?: number;
115
  /** Model type indicator */
116
  type: "model";
117
}
118

119
interface ModelInfosPage {
120
  /** Array of model information objects */
121
  data: ModelInfo[];
122
  /** Whether there are more results available */
123
  has_more: boolean;
124
  /** ID of the first model in this page */
125
  first_id?: string;
126
  /** ID of the last model in this page */
127
  last_id?: string;
128
}
129
```
130

131
## Available Models
132

133
The following models are commonly available (availability may vary):
134

135
```typescript { .api }
136
type Model = 
137
  | "claude-3-7-sonnet-latest"
138
  | "claude-3-7-sonnet-20250219"
139
  | "claude-sonnet-4-20250514"
140
  | "claude-sonnet-4-0"
141
  | "claude-4-sonnet-20250514"
142
  | "claude-3-5-sonnet-latest"
143
  | "claude-3-5-sonnet-20241022"
144
  | "claude-3-5-sonnet-20240620"
145
  | "claude-3-5-haiku-latest"
146
  | "claude-3-5-haiku-20241022"
147
  | "claude-opus-4-0"
148
  | "claude-opus-4-20250514"
149
  | "claude-4-opus-20250514"
150
  | "claude-opus-4-1-20250805"
151
  | "claude-3-opus-latest"
152
  | "claude-3-opus-20240229"
153
  | "claude-3-haiku-20240307"
154
  | "claude-2.1"
155
  | "claude-2.0"
156
  | "claude-instant-1.2";
157
```
158

159
**Model Characteristics:**
160

161
- **Claude Sonnet 4**: Newest generation with enhanced capabilities and reasoning
162
- **Claude Opus 4**: Most powerful Claude 4 model, best for highly complex tasks  
163
- **Claude 3.7 Sonnet**: Advanced Sonnet with improved performance
164
- **Claude 3.5 Sonnet**: Latest stable Sonnet model, excellent for complex reasoning
165
- **Claude 3.5 Haiku**: Fast and efficient, great for quick responses
166
- **Claude 3 Opus**: Most powerful Claude 3 model for complex tasks
167
- **Claude 3 Haiku**: Fastest Claude 3 model, optimized for speed
168
- **Claude 2.1**: Previous generation, still capable for many tasks
169
- **Claude 2.0**: Earlier version with good general capabilities
170
- **Claude Instant 1.2**: Legacy fast model, being phased out
171

172
## Model Selection Guide
173

174
**For maximum capability and reasoning:**
175
- `claude-opus-4-20250514`
176
- `claude-sonnet-4-20250514`
177
- `claude-3-7-sonnet-latest`
178

179
**For balanced performance:**
180
- `claude-3-5-sonnet-latest`
181
- `claude-3-5-sonnet-20241022`
182

183
**For speed and efficiency:**
184
- `claude-3-5-haiku-latest`
185
- `claude-3-5-haiku-20241022`
186

187
**Usage Examples:**
188

189
```typescript
190
// Check if a specific model is available
191
const models = await client.models.list();
192
const isOpusAvailable = models.data.some(m => m.id === "claude-3-opus-20240229");
193

194
if (isOpusAvailable) {
195
  const message = await client.messages.create({
196
    model: "claude-3-opus-20240229",
197
    max_tokens: 1024,
198
    messages: [{ role: "user", content: "Complex reasoning task..." }],
199
  });
200
}
201

202
// Find the latest Sonnet model
203
const sonnetModels = models.data.filter(m => 
204
  m.id.includes("sonnet") && m.id.includes("claude-3")
205
);
206
const latestSonnet = sonnetModels[0]; // Models are ordered by creation date
207

208
// Check context length for long documents
209
const modelInfo = await client.models.retrieve("claude-3-sonnet-20240229");
210
if (modelInfo.context_length >= 200000) {
211
  console.log("This model can handle very long documents");
212
}
213
```
214

215
## Pagination Support
216

217
```typescript { .api }
218
/**
219
 * Page object for model listings with automatic pagination support
220
 */
221
class ModelInfosPage extends Page<ModelInfo> {
222
  /** Get the next page of results */
223
  nextPage(): Promise<ModelInfosPage | null>;
224
  /** Get the previous page of results */
225
  previousPage(): Promise<ModelInfosPage | null>;
226
  /** Iterate through all pages automatically */
227
  [Symbol.asyncIterator](): AsyncIterableIterator<ModelInfo>;
228
}
229
```
230

231
**Usage Examples:**
232

233
```typescript
234
// Manual pagination
235
let page = await client.models.list({ limit: 10 });
236
while (page) {
237
  for (const model of page.data) {
238
    console.log(model.display_name);
239
  }
240
  page = await page.nextPage();
241
}
242

243
// Automatic iteration through all models
244
for await (const model of client.models.list()) {
245
  console.log(`${model.id}: ${model.context_length} tokens`);
246
}
247
```
248

249
## Beta Features
250

251
Some model information may require beta feature access:
252

253
```typescript { .api }
254
type AnthropicBeta = 
255
  | "computer-use-2024-10-22"
256
  | "pdfs-2024-09-25"
257
  | "token-counting-2024-11-01"
258
  | string[];
259
```
260

261
**Usage Examples:**
262

263
```typescript
264
// Access beta model features
265
const betaModels = await client.models.list({
266
  betas: ["computer-use-2024-10-22"],
267
});
268

269
// Check for beta-specific capabilities
270
const computerUseModel = await client.models.retrieve(
271
  "claude-3-5-sonnet-20241022",
272
  { betas: ["computer-use-2024-10-22"] }
273
);
274
```
275

276
## Error Handling
277

278
```typescript { .api }
279
// Common errors when working with models
280
try {
281
  const model = await client.models.retrieve("nonexistent-model");
282
} catch (error) {
283
  if (error instanceof NotFoundError) {
284
    console.log("Model not found");
285
  } else if (error instanceof AuthenticationError) {
286
    console.log("Invalid API key");
287
  }
288
}
289
```