Cette bibliothèque offre un accès pratique à l'API REST d'Anthropic depuis TypeScript ou JavaScript.
Pour la documentation des fonctionnalités de l'API avec des exemples de code, consultez la référence de l'API. Cette page couvre les fonctionnalités et la configuration du SDK spécifiques à TypeScript.
npm install @anthropic-ai/sdkTypeScript >= 4.9 est pris en charge.
Les environnements d'exécution suivants sont pris en charge :
"node" ("jsdom" n'est pas pris en charge pour le moment).dangerouslyAllowBrowser sur true.Notez que React Native n'est pas pris en charge pour le moment.
Si vous êtes intéressé par d'autres environnements d'exécution, ouvrez ou votez pour une issue sur GitHub.
const client = new Anthropic({
apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});
const message = await client.messages.create({
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8"
});
console.log(message.content);Pour les options d'authentification, y compris la « Workload Identity Federation » (fédération d'identité de charge de travail), consultez Authentification.
Cette bibliothèque inclut des définitions TypeScript pour tous les paramètres de requête et les champs de réponse. Vous pouvez les importer et les utiliser comme suit :
const client = new Anthropic({
apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});
const params: Anthropic.MessageCreateParams = {
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8"
};
const message: Anthropic.Message = await client.messages.create(params);La documentation de chaque méthode, paramètre de requête et champ de réponse est disponible dans les docstrings et apparaîtra au survol dans la plupart des éditeurs modernes.
Vous pouvez voir l'utilisation exacte pour une requête donnée via la propriété de réponse usage, par exemple :
const message = await client.messages.create(/* ... */);
console.log(message.usage);
// { input_tokens: 25, output_tokens: 13 }Le SDK prend en charge le « streaming » (diffusion en continu) des réponses à l'aide des Server Sent Events (SSE).
const client = new Anthropic();
const stream = await client.messages.create({
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8",
stream: true
});
for await (const messageStreamEvent of stream) {
console.log(messageStreamEvent.type);
}Si vous devez annuler un flux, vous pouvez utiliser break pour sortir de la boucle ou appeler stream.controller.abort().
Cette bibliothèque fournit plusieurs fonctionnalités pratiques pour le streaming de messages, par exemple :
const anthropic = new Anthropic();
const stream = anthropic.messages
.stream({
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [
{
role: "user",
content: "Say hello there!"
}
]
})
.on("text", (text) => {
console.log(text);
});
const message = await stream.finalMessage();
console.log(message);Le streaming avec client.messages.stream(...) expose divers helpers pour votre commodité, notamment des gestionnaires d'événements et l'accumulation.
Vous pouvez également utiliser client.messages.create({ ..., stream: true }) qui renvoie uniquement un itérable asynchrone des événements du flux et utilise donc moins de mémoire (il ne construit pas d'objet message final pour vous).
Ce SDK fournit des helpers facilitant la création et l'exécution d'outils dans l'API Messages. Vous pouvez utiliser des schémas Zod ou des JSON Schemas pour décrire l'entrée d'un outil. Vous pouvez ensuite exécuter ces outils à l'aide de la méthode client.beta.messages.toolRunner(). Cette méthode se charge de transmettre les entrées générées par le modèle choisi au bon outil et de renvoyer le résultat au modèle.
Pour plus de détails sur l'utilisation d'outils, consultez Utilisation d'outils avec Claude.
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
const anthropic = new Anthropic();
const weatherTool = betaZodTool({
name: "get_weather",
inputSchema: z.object({
location: z.string()
}),
description: "Get the current weather in a given location",
run: (input) => {
return `The weather in ${input.location} is foggy and 60°F`;
}
});
const finalMessage = await anthropic.beta.messages.toolRunner({
model: "claude-opus-4-8",
max_tokens: 1000,
messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
tools: [weatherTool]
});
console.log(finalMessage.content);Pour signaler une erreur d'un outil au modèle, lancez une ToolError depuis la fonction run. Contrairement à une Error classique, ToolError accepte des blocs de contenu, ce qui vous permet d'inclure des images ou d'autres contenus structurés dans la réponse d'erreur :
import { ToolError } from "@anthropic-ai/sdk/lib/tools/BetaRunnableTool";
const screenshotTool = betaZodTool({
name: "take_screenshot",
inputSchema: z.object({ url: z.string() }),
run: async (input) => {
if (!isValidUrl(input.url)) {
throw new ToolError(`Invalid URL: ${input.url}`);
}
const result = await takeScreenshot(input.url);
if (result.error) {
// Inclure la capture d'écran de l'erreur pour que le modèle puisse voir ce qui s'est mal passé
throw new ToolError([
{ type: "text", text: `Failed to load page: ${result.error}` },
{
type: "image",
source: { type: "base64", data: result.screenshot, media_type: "image/png" }
}
]);
}
return {
type: "image",
source: { type: "base64", data: result.screenshot, media_type: "image/png" }
};
}
});Si une Error classique est lancée, le message sera converti en bloc de contenu texte.
Ce SDK prend en charge l'utilisation d'outils, également appelée « function calling » (appel de fonctions). Pour plus de détails, consultez Utilisation d'outils avec Claude.
Ce SDK fournit des helpers pour l'intégration avec les serveurs Model Context Protocol (MCP). Ces helpers convertissent les types MCP en types de l'API Claude, réduisant ainsi le code répétitif lors de l'utilisation d'outils, de prompts et de ressources MCP.
L'API Claude prend également en charge un paramètre mcp_servers qui permet à Claude de se connecter directement à des serveurs MCP distants. Utilisez mcp_servers lorsque vous disposez de serveurs distants accessibles par URL et que vous n'avez besoin que de la prise en charge des outils. Utilisez les helpers MCP lorsque vous avez besoin de serveurs MCP locaux, de prompts, de ressources ou d'un contrôle accru sur la connexion MCP.
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const anthropic = new Anthropic();
// Se connecter à un serveur MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);
// Utiliser les prompts MCP
const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
model: "claude-opus-4-8",
max_tokens: 1024,
messages: mcpMessages(messages)
});
console.log(response.content);
// Utiliser les outils MCP avec toolRunner
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [{ role: "user", content: "Use the available tools" }],
tools: mcpTools(tools, mcpClient)
});
console.log(finalMessage.content);
// Utiliser les ressources MCP comme contenu
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
mcpResourceToContent(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
});
// Téléverser les ressources MCP en tant que fichiers
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });Les fonctions de conversion lancent une UnsupportedMCPValueError si une valeur MCP n'est pas prise en charge par l'API Claude (par exemple, un type de contenu non pris en charge, un type MIME non pris en charge, un lien de ressource non http/https).
Ce SDK prend en charge l'API Message Batches sous l'espace de noms client.messages.batches.
Message Batches prend un tableau de requêtes, où chaque objet possède un identifiant custom_id et exactement les mêmes params de requête que l'API Messages standard :
const batch = await client.messages.batches.create({
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, world" }]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [{ role: "user", content: "Hi again, friend" }]
}
}
]
});Une fois qu'un Message Batch a été traité, ce qui est indiqué par .processing_status === 'ended', vous pouvez accéder aux résultats avec .batches.results()
const results = await client.messages.batches.results(batch.id);
for await (const entry of results) {
if (entry.result.type === "succeeded") {
console.log(entry.result.message.content);
}
}Les paramètres de requête correspondant à des téléversements de fichiers peuvent être transmis sous de nombreuses formes différentes :
File (ou un objet ayant la même structure)Response de fetch (ou un objet ayant la même structure)fs.ReadStreamtoFileDéfinissez explicitement le content-type, car l'API de fichiers ne le déduira pas pour vous :
import fs from "fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";
const client = new Anthropic();
// Si vous avez accès au module `fs` de Node, utilisez `fs.createReadStream()` :
await client.beta.files.upload({
file: await toFile(fs.createReadStream("/path/to/file"), undefined, {
type: "application/json"
})
});
// Ou si vous disposez de l'API web `File`, vous pouvez passer une instance de `File` :
await client.beta.files.upload({
file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// Vous pouvez également passer une `Response` de `fetch` :
await client.beta.files.upload({
file: await fetch("https://somesite/file")
});
// Ou un `Buffer` / `Uint8Array`
await client.beta.files.upload({
file: await toFile(Buffer.from("my bytes"), "file", { type: "text/plain" })
});
await client.beta.files.upload({
file: await toFile(new Uint8Array([0, 1, 2]), "file", { type: "text/plain" })
});Lorsque la bibliothèque ne parvient pas à se connecter à l'API,
ou si l'API renvoie un code d'état d'échec (c'est-à-dire une réponse 4xx ou 5xx),
une sous-classe de APIError est lancée :
const message = await client.messages
.create({
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8"
})
.catch(async (err) => {
if (err instanceof Anthropic.APIError) {
console.log(err.status); // 400
console.log(err.name); // BadRequestError
console.log(err.headers); // {server: 'nginx', ...}
} else {
throw err;
}
});Les codes d'erreur sont les suivants :
| Code d'état | Type d'erreur |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| >=500 | InternalServerError |
| N/A | APIConnectionError |
Pour plus d'informations sur le débogage des requêtes, consultez Identifiant de requête.
Toutes les réponses d'objet dans le SDK fournissent une propriété _request_id qui est ajoutée à partir de l'en-tête de réponse request-id afin que vous puissiez rapidement consigner les requêtes en échec et les signaler à Anthropic.
const message = await client.messages.create({
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8"
});
console.log(message._request_id); // req_018EeWyXxfu5pfWkrYcMdjWGCertaines erreurs feront automatiquement l'objet de 2 nouvelles tentatives par défaut, avec un court délai exponentiel. Les erreurs de connexion (par exemple, en raison d'un problème de connectivité réseau), 408 Request Timeout, 409 Conflict, 429 Rate Limit et les erreurs internes >=500 font toutes l'objet de nouvelles tentatives par défaut.
Vous pouvez utiliser l'option maxRetries pour configurer ou désactiver ce comportement :
// Configurez la valeur par défaut pour toutes les requêtes :
const client = new Anthropic({
maxRetries: 0 // default is 2
});
// Ou configurez par requête :
await client.messages.create(
{
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8"
},
{ maxRetries: 5 }
);Par défaut, les requêtes expirent après 10 minutes. Cependant, si vous avez spécifié une valeur max_tokens élevée et que vous
n'utilisez pas le streaming, le délai d'expiration par défaut sera calculé dynamiquement à l'aide de la formule :
const minimum = 10 * 60;
const calculated = (60 * 60 * maxTokens) / 128_000;
return calculated < minimum ? minimum * 1000 : calculated * 1000;ce qui donnera un délai d'expiration allant jusqu'à 60 minutes, ajusté en fonction du paramètre max_tokens, sauf s'il est remplacé au niveau de la requête ou du client.
Vous pouvez configurer cela avec une option timeout :
// Configurer la valeur par défaut pour toutes les requêtes :
const client = new Anthropic({
timeout: 20 * 1000 // 20 seconds (default is 10 minutes)
});
// Remplacer pour une requête spécifique :
await client.messages.create(
{
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8"
},
{ timeout: 5 * 1000 }
);En cas d'expiration du délai, une APIConnectionTimeoutError est lancée.
Notez que les requêtes qui expirent feront l'objet de deux nouvelles tentatives par défaut.
Envisagez d'utiliser l'API Messages en streaming pour les requêtes de longue durée.
Évitez de définir une valeur max_tokens élevée sans utiliser le streaming.
Certains réseaux peuvent interrompre les connexions inactives après un certain temps, ce qui
peut entraîner l'échec de la requête ou son expiration sans recevoir de réponse d'Anthropic.
Ce SDK lancera également une erreur si une requête sans streaming est censée durer plus d'environ 10 minutes.
Passer stream: true ou remplacer l'option timeout au niveau du client ou de la requête désactive cette erreur.
Une « latency » (latence) de requête attendue supérieure au délai d'expiration pour une requête sans streaming entraînera la fermeture de la connexion par le client et une nouvelle tentative sans recevoir de réponse.
Lorsque l'implémentation de fetch le prend en charge, le SDK définit une option TCP socket keep-alive afin
de réduire l'impact des délais d'expiration de connexion inactive sur certains réseaux.
Cela peut être remplacé en configurant un proxy personnalisé.
Les méthodes de liste dans l'API Claude sont paginées.
Vous pouvez utiliser la syntaxe for await ... of pour itérer sur les éléments de toutes les pages :
async function fetchAllMessageBatches() {
const allMessageBatches = [];
// Récupère automatiquement des pages supplémentaires selon les besoins.
for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
allMessageBatches.push(messageBatch);
}
return allMessageBatches;
}Vous pouvez également demander une seule page à la fois :
let page = await client.messages.batches.list({ limit: 20 });
for (const messageBatch of page.data) {
console.log(messageBatch);
}
// Des méthodes pratiques sont fournies pour paginer manuellement :
while (page.hasNextPage()) {
page = await page.getNextPage();
// ...
}Le SDK envoie automatiquement l'en-tête anthropic-version défini sur 2023-06-01.
Si nécessaire, vous pouvez le remplacer en définissant des en-têtes par défaut au niveau de chaque requête.
Sachez que cela peut entraîner des types incorrects et d'autres comportements inattendus ou non définis dans le SDK.
const client = new Anthropic();
const message = await client.messages.create(
{
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8"
},
{ headers: { "anthropic-version": "My-Custom-Value" } }
);La Response « brute » renvoyée par fetch() est accessible via la méthode .asResponse() sur le type APIPromise que toutes les méthodes renvoient.
Cette méthode retourne dès que les en-têtes d'une réponse réussie sont reçus et ne consomme pas le corps de la réponse, vous êtes donc libre d'écrire une logique d'analyse ou de streaming personnalisée.
Vous pouvez également utiliser la méthode .withResponse() pour obtenir la Response brute ainsi que les données analysées.
Contrairement à .asResponse(), cette méthode consomme le corps et retourne une fois celui-ci analysé.
const client = new Anthropic();
const response = await client.messages
.create({
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8"
})
.asResponse();
console.log(response.headers.get("X-My-Header"));
console.log(response.statusText); // access the underlying Response object
const { data: message, response: raw } = await client.messages
.create({
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
model: "claude-opus-4-8"
})
.withResponse();
console.log(raw.headers.get("X-My-Header"));
console.log(message.content);Tous les messages de journal sont destinés uniquement au débogage. Le format et le contenu des messages de journal peuvent changer entre les versions.
Le niveau de journalisation peut être configuré de deux manières :
ANTHROPIC_LOGlogLevel (remplace la variable d'environnement si elle est définie)const client = new Anthropic({
logLevel: "debug" // Show all log messages
});Niveaux de journalisation disponibles, du plus détaillé au moins détaillé :
'debug' - Afficher les messages de débogage, les informations, les avertissements et les erreurs'info' - Afficher les messages d'information, les avertissements et les erreurs'warn' - Afficher les avertissements et les erreurs (par défaut)'error' - Afficher uniquement les erreurs'off' - Désactiver toute journalisationAu niveau 'debug', toutes les requêtes et réponses HTTP sont journalisées, y compris les en-têtes et les corps.
Certains en-têtes liés à l'authentification sont masqués, mais les données sensibles dans les corps de requête et de réponse
peuvent toujours être visibles.
Par défaut, cette bibliothèque journalise vers globalThis.console. Vous pouvez également fournir un logger personnalisé.
La plupart des bibliothèques de journalisation sont prises en charge, notamment pino, winston, bunyan, consola, signale et @std/log. Si votre logger ne fonctionne pas, ouvrez une issue.
Lorsque vous fournissez un logger personnalisé, l'option logLevel contrôle toujours quels messages sont émis ; les messages
en dessous du niveau configuré ne seront pas envoyés à votre logger.
import pino from "pino";
const logger = pino();
const client = new Anthropic({
logger: logger.child({ name: "Anthropic" }),
logLevel: "debug" // Send all messages to pino, allowing it to filter
});Cette bibliothèque est typée pour un accès pratique à l'API documentée. Si vous devez accéder à des points de terminaison, paramètres ou propriétés de réponse non documentés, la bibliothèque peut toujours être utilisée.
Pour effectuer des requêtes vers des points de terminaison non documentés, vous pouvez utiliser client.get, client.post et d'autres verbes HTTP.
Les options du client, telles que les nouvelles tentatives, seront respectées lors de ces requêtes.
await client.post("/some/path", {
body: { some_prop: "foo" },
query: { some_query_arg: "bar" }
});Pour effectuer des requêtes utilisant des paramètres non documentés, vous pouvez utiliser // @ts-expect-error sur le paramètre
non documenté. Cette bibliothèque ne valide pas à l'exécution que la requête correspond au type, donc toutes les valeurs supplémentaires que vous
envoyez seront transmises telles quelles.
client.messages.create({
// ...
// @ts-expect-error baz is not yet public
baz: "undocumented option"
});Pour les requêtes avec le verbe GET, tous les paramètres supplémentaires seront dans la requête (query) ; toutes les autres requêtes enverront le
paramètre supplémentaire dans le corps.
Si vous souhaitez envoyer explicitement un argument supplémentaire, vous pouvez le faire avec les options de requête query, body et headers.
Pour accéder à des propriétés de réponse non documentées, vous pouvez accéder à l'objet de réponse avec // @ts-expect-error sur
l'objet de réponse, ou convertir l'objet de réponse vers le type requis. Comme pour les paramètres de requête, le SDK ne
valide ni ne supprime les propriétés supplémentaires de la réponse de l'API.
Par défaut, cette bibliothèque s'attend à ce qu'une fonction fetch globale soit définie.
Si vous souhaitez utiliser une fonction fetch différente, vous pouvez soit polyfiller la fonction globale :
import fetch from "my-fetch";
globalThis.fetch = fetch;Soit la passer au client :
import fetch from "my-fetch";
const client = new Anthropic({ fetch });Si vous souhaitez définir des options fetch personnalisées sans remplacer la fonction fetch, vous pouvez fournir un objet fetchOptions lors de la création du client ou de l'exécution d'une requête. (Les options spécifiques à la requête remplacent les options du client.)
const client = new Anthropic({
fetchOptions: {
// Options `RequestInit`
}
});Pour modifier le comportement du proxy, vous pouvez fournir des fetchOptions personnalisées qui ajoutent des options de proxy
spécifiques à l'environnement d'exécution aux requêtes :
Les fonctionnalités bêta sont disponibles avant leur sortie générale afin de recueillir des retours anticipés et de tester de nouvelles fonctionnalités. Vous pouvez vérifier la disponibilité de toutes les capacités et outils de Claude dans la vue d'ensemble de la création avec Claude.
Vous pouvez accéder à la plupart des fonctionnalités bêta de l'API via la propriété beta du client. Pour activer une fonctionnalité bêta particulière, vous devez ajouter l'en-tête bêta approprié au champ betas lors de la création d'un message.
Par exemple, pour utiliser l'API Files :
const client = new Anthropic();
const response = await client.beta.messages.create({
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{ type: "text", text: "Please summarize this document for me." },
{
type: "document",
source: {
type: "file",
file_id: "file_abc123"
}
}
]
}
],
betas: ["files-api-2025-04-14"]
});Pour des guides de configuration de plateforme détaillés avec des exemples de code, consultez :
Le SDK TypeScript prend en charge les plateformes suivantes :
npm install @anthropic-ai/bedrock-sdk : Fournit le client AnthropicBedrockMantle, et AnthropicBedrock pour le chemin bedrock-runtimenpm install @anthropic-ai/vertex-sdk : Fournit le client AnthropicVertexnpm install @anthropic-ai/foundry-sdk : Fournit le client AnthropicFoundrynpm install @anthropic-ai/aws-sdk : Fournit le client AnthropicAws. Passez workspaceId au constructeur ou définissez la variable d'environnement ANTHROPIC_AWS_WORKSPACE_ID. Disponible en bêta.Utilisez AnthropicBedrockMantle pour les nouveaux projets ; AnthropicBedrock reste disponible pour les applications existantes utilisant l'API Bedrock InvokeModel.
Ce package suit généralement les conventions SemVer, bien que certaines modifications incompatibles avec les versions antérieures puissent être publiées en tant que versions mineures :
La rétrocompatibilité est prise au sérieux afin de vous garantir une expérience de mise à niveau fluide.
Consultez le dépôt GitHub pour les FAQ, les issues et le support communautaire.
Was this page helpful?