CLI, SDK et bibliothèquesSDK clients

SDK Java

Installez et configurez le SDK Java d'Anthropic avec les patterns builder et la prise en charge asynchrone

Le SDK Java d'Anthropic offre un accès pratique à l'API REST d'Anthropic depuis des applications écrites en Java. Il utilise le « builder pattern » (pattern de construction) pour créer des requêtes et prend en charge les opérations synchrones et asynchrones.

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 à Java.

Installation

Prérequis

Cette bibliothèque nécessite Java 8 ou une version ultérieure.

Le SDK prend en charge Java 8 et les versions ultérieures. Les exemples de code de cette documentation sont écrits sous forme de fichiers sources compacts JDK 25, utilisant un point d'entrée void main() simple et IO.println() pour la sortie. Les appels d'API eux-mêmes sont identiques sur tous les JDK pris en charge ; pour compiler un exemple sur une version antérieure, remplacez IO.println(...) par System.out.println(...) et placez le corps à l'intérieur de public static void main(String[] args) au sein d'une classe.

Démarrage rapide

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

// Configure à l'aide des propriétés système `anthropic.apiKey`, `anthropic.authToken` et `anthropic.baseUrl`
// Ou configure à l'aide des variables d'environnement `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` et `ANTHROPIC_BASE_URL`
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

Message message = client.messages().create(params);

Configuration du client

Configuration de la clé API

Configurez le client à l'aide des propriétés système ou des variables d'environnement :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

// Configure à l'aide des propriétés système `anthropic.apiKey`, `anthropic.authToken` et `anthropic.baseUrl`
// Ou configure à l'aide des variables d'environnement `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` et `ANTHROPIC_BASE_URL`
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

Ou configurez manuellement :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .apiKey("my-anthropic-api-key")
  .build();

Ou utilisez une combinaison des deux approches :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  // Configure à l'aide des propriétés système ou des variables d'environnement
  .fromEnv()
  .apiKey("my-anthropic-api-key")
  .build();

Pour les options d'authentification, y compris la « Workload Identity Federation » (fédération d'identité de charge de travail), consultez Authentification.

Options de configuration

Setter	Propriété système	Variable d'environnement	Requis	Valeur par défaut
`apiKey`	`anthropic.apiKey`	`ANTHROPIC_API_KEY`	false	-
`authToken`	`anthropic.authToken`	`ANTHROPIC_AUTH_TOKEN`	false	-
`baseUrl`	`anthropic.baseUrl`	`ANTHROPIC_BASE_URL`	true	`"https://api.anthropic.com"`

Les propriétés système ont priorité sur les variables d'environnement.

Ne créez pas plus d'un client dans la même application. Chaque client dispose d'un pool de connexions et de pools de threads, qu'il est plus efficace de partager entre les requêtes.

Modification de la configuration

Pour utiliser temporairement une configuration de client modifiée tout en réutilisant les mêmes pools de connexions et de threads, appelez withOptions() sur n'importe quel client ou service :

import com.anthropic.client.AnthropicClient;

AnthropicClient clientWithOptions = client.withOptions(optionsBuilder -> {
  optionsBuilder.baseUrl("https://example.com");
  optionsBuilder.maxRetries(42);
});

La méthode withOptions() n'affecte pas le client ou le service d'origine.

Utilisation asynchrone

Le client par défaut est synchrone. Pour passer à une exécution asynchrone, appelez la méthode async() :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

CompletableFuture<Message> message = client.async().messages().create(params);

Ou créez un client asynchrone dès le départ :

import com.anthropic.client.AnthropicClientAsync;
import com.anthropic.client.okhttp.AnthropicOkHttpClientAsync;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

AnthropicClientAsync client = AnthropicOkHttpClientAsync.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

CompletableFuture<Message> message = client.messages().create(params);

Le client asynchrone prend en charge les mêmes options que le client synchrone, à ceci près que la plupart des méthodes renvoient des CompletableFuture.

Streaming

Le SDK définit des méthodes qui renvoient des flux de « chunks » (fragments) de réponse, où chaque fragment peut être traité individuellement dès son arrivée au lieu d'attendre la réponse complète.

Streaming synchrone

Ces méthodes de streaming renvoient StreamResponse pour les clients synchrones :

import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.messages.RawMessageStreamEvent;

try (StreamResponse<RawMessageStreamEvent> streamResponse = client.messages().createStreaming(params)) {
    streamResponse.stream().forEach(chunk -> {
        IO.println(chunk);
    });
    IO.println("No more chunks!");
}

Streaming asynchrone

Pour les clients asynchrones, la méthode renvoie AsyncStreamResponse :

import com.anthropic.core.http.AsyncStreamResponse;
import com.anthropic.models.messages.RawMessageStreamEvent;

client.async().messages().createStreaming(params).subscribe(chunk -> {
    IO.println(chunk);
});

// Si vous devez gérer les erreurs ou la fin du stream
client.async().messages().createStreaming(params).subscribe(new AsyncStreamResponse.Handler<>() {
    @Override
    public void onNext(RawMessageStreamEvent chunk) {
        IO.println(chunk);
    }

    @Override
    public void onComplete(Optional<Throwable> error) {
        if (error.isPresent()) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error.get());
        } else {
            IO.println("No more chunks!");
        }
    }
});

// Ou utilisez des futures
client.async().messages().createStreaming(params)
    .subscribe(chunk -> {
        IO.println(chunk);
    })
    .onCompleteFuture()
    .whenComplete((unused, error) -> {
        if (error != null) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error);
        } else {
            IO.println("No more chunks!");
        }
    });

Le streaming asynchrone utilise un Executor dédié par client avec pool de threads mis en cache pour diffuser sans bloquer le thread actuel. Pour utiliser un Executor différent :

Executor executor = Executors.newFixedThreadPool(4);
client.async().messages().createStreaming(params).subscribe(
    chunk -> IO.println(chunk), executor
);

Ou configurez le client globalement à l'aide de la méthode streamHandlerExecutor :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .streamHandlerExecutor(Executors.newFixedThreadPool(4))
  .build();

Streaming avec accumulateur de messages

Un MessageAccumulator peut enregistrer le flux d'événements de la réponse au fur et à mesure de leur traitement et accumuler un objet Message similaire à ce qui aurait été renvoyé par l'API sans streaming.

Pour une réponse synchrone, ajoutez un appel Stream.peek() au pipeline de flux pour accumuler chaque événement :

import com.anthropic.core.http.StreamResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.RawMessageStreamEvent;

MessageAccumulator messageAccumulator = MessageAccumulator.create();

try (StreamResponse<RawMessageStreamEvent> streamResponse =
         client.messages().createStreaming(createParams)) {
    streamResponse.stream()
            .peek(messageAccumulator::accumulate)
            .flatMap(event -> event.contentBlockDelta().stream())
            .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
            .forEach(textDelta -> IO.print(textDelta.text()));
}

Message message = messageAccumulator.message();

Pour une réponse asynchrone, ajoutez le MessageAccumulator à l'appel subscribe() :

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.Message;

MessageAccumulator messageAccumulator = MessageAccumulator.create();

client.async().messages()
        .createStreaming(createParams)
        .subscribe(event -> messageAccumulator.accumulate(event).contentBlockDelta().stream()
                .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
                .forEach(textDelta -> IO.print(textDelta.text())))
        .onCompleteFuture()
        .join();

Message message = messageAccumulator.message();

Un BetaMessageAccumulator est également disponible pour l'accumulation d'un objet BetaMessage. Il s'utilise de la même manière que le MessageAccumulator.

Sorties structurées

Pour la documentation complète sur les sorties structurées, y compris des exemples Java, consultez Sorties structurées.

Utilisation d'outils

L'utilisation d'outils avec Claude vous permet d'intégrer des outils et des fonctions externes directement dans les réponses du modèle d'IA. Au lieu de produire du texte brut, le modèle peut générer des instructions (avec des paramètres) pour appeler un outil ou une fonction lorsque cela est approprié. Vous définissez des schémas JSON pour les outils, et le modèle utilise ces schémas pour déterminer quand et comment utiliser ces outils.

La fonctionnalité d'utilisation d'outils prend en charge un mode « strict » qui garantit que la sortie JSON du modèle d'IA sera conforme au schéma JSON que vous fournissez dans les paramètres d'entrée.

Le SDK peut dériver automatiquement un outil et ses paramètres à partir de la structure d'une classe Java arbitraire : le nom de la classe (converti en snake case) fournit le nom de l'outil, et les champs de la classe définissent les paramètres de l'outil.

Déclarez vos classes d'outils comme des classes de niveau supérieur ou des classes imbriquées static. Cette exigence provient de la bibliothèque Jackson Databind (com.fasterxml.jackson.databind), que le SDK utilise pour désérialiser les entrées d'outils en instances de vos classes et qui ne peut pas instancier des classes internes non statiques.

Définition d'outils avec des annotations

import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;

enum Unit {
  CELSIUS,
  FAHRENHEIT;

  public String toString() {
    switch (this) {
      case CELSIUS:
        return "C";
      case FAHRENHEIT:
      default:
        return "F";
    }
  }

  public double fromKelvin(double temperatureK) {
    switch (this) {
      case CELSIUS:
        return temperatureK - 273.15;
      case FAHRENHEIT:
      default:
        return (temperatureK - 273.15) * 1.8 + 32.0;
    }
  }
}

@JsonClassDescription("Get the weather in a given location")
static class GetWeather {

  @JsonPropertyDescription("The city and state, e.g. San Francisco, CA")
  public String location;

  @JsonPropertyDescription("The unit of temperature")
  public Unit unit;

  public Weather execute() {
    double temperatureK;
    switch (location) {
      case "San Francisco, CA":
        temperatureK = 300.0;
        break;
      case "New York, NY":
        temperatureK = 310.0;
        break;
      case "Dallas, TX":
        temperatureK = 305.0;
        break;
      default:
        temperatureK = 295;
        break;
    }
    return new Weather(String.format("%.0f%s", unit.fromKelvin(temperatureK), unit));
  }
}

static class Weather {

  public String temperature;

  public Weather(String temperature) {
    this.temperature = temperature;
  }
}

Appel des outils

Une fois vos classes d'outils définies, ajoutez-les aux paramètres du message à l'aide de MessageCreateParams.Builder.addTool(Class<T>), puis appelez-les si la réponse du modèle d'IA le demande. BetaToolUseBlock.input(Class<T>) peut être utilisé pour analyser les paramètres d'un outil sous forme JSON en une instance de votre classe définissant l'outil.

Après avoir appelé l'outil, utilisez BetaToolResultBlockParam.Builder.contentAsJson(Object) pour renvoyer le résultat de l'outil au modèle d'IA :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.*;
import com.anthropic.models.messages.Model;

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams.Builder createParamsBuilder = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_8)
        .maxTokens(2048)
        .addTool(GetWeather.class)
        .addUserMessage("What's the temperature in New York?");

client.beta().messages().create(createParamsBuilder.build()).content().stream()
        .flatMap(contentBlock -> contentBlock.toolUse().stream())
        .forEach(toolUseBlock -> createParamsBuilder
              // Ajoutez un message indiquant que l'utilisation d'outils a été demandée.
              .addAssistantMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder()
                              .name(toolUseBlock.name())
                              .id(toolUseBlock.id())
                              .input(toolUseBlock._input())
                              .build())))
              // Ajoutez un message avec le résultat de l'utilisation d'outils demandée.
              .addUserMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolResult(BetaToolResultBlockParam.builder()
                              .toolUseId(toolUseBlock.id())
                              .contentAsJson(callTool(toolUseBlock))
                              .build()))));

client.beta().messages().create(createParamsBuilder.build()).content().stream()
        .flatMap(contentBlock -> contentBlock.text().stream())
        .forEach(textBlock -> IO.println(textBlock.text()));

private static Object callTool(BetaToolUseBlock toolUseBlock) {
  if (!"get_weather".equals(toolUseBlock.name())) {
    throw new IllegalArgumentException("Unknown tool: " + toolUseBlock.name());
  }

  GetWeather tool = toolUseBlock.input(GetWeather.class);
  return tool != null ? tool.execute() : new Weather("unknown");
}

Conversion des noms d'outils

Les noms d'outils sont dérivés des noms de classes d'outils en camel case (par exemple, GetWeather) et convertis en snake case (par exemple, get_weather). Les limites de mots commencent là où le caractère actuel n'est pas le premier caractère, est en majuscule, et soit le caractère précédent est en minuscule, soit le caractère suivant est en minuscule. Par exemple, MyJSONParser devient my_json_parser et ParseJSON devient parse_json. Cette conversion peut être remplacée à l'aide de l'annotation @JsonTypeName.

Validation locale du schéma JSON des outils

Vous pouvez effectuer une validation locale pour vérifier que le schéma JSON dérivé de votre classe d'outil respecte les restrictions d'Anthropic. La validation locale est activée par défaut, mais elle peut être désactivée :

MessageCreateParams.Builder createParamsBuilder = MessageCreateParams.builder()
  .model(Model.CLAUDE_OPUS_4_8)
  .maxTokens(2048)
  .addTool(GetWeather.class, JsonSchemaLocalValidation.NO)
  .addUserMessage("What's the temperature in New York?");

Annotation des classes d'outils

Vous pouvez utiliser des annotations pour ajouter des informations supplémentaires sur les outils aux schémas JSON :

@JsonClassDescription - Ajoute une description à une classe d'outil détaillant quand et comment utiliser cet outil.
@JsonTypeName - Définit le nom de l'outil sur une valeur autre que le nom simple de la classe converti en snake case.
@JsonPropertyDescription - Ajoute une description détaillée à un paramètre d'outil.
@JsonIgnore - Exclut un champ public ou une méthode getter du schéma JSON généré pour les paramètres d'un outil.
@JsonProperty - Inclut un champ non public ou une méthode getter dans le schéma JSON généré pour les paramètres d'un outil.

Lots de messages

Le SDK prend en charge le traitement par lots sous l'espace de noms client.messages().batches(). Consultez Pagination pour savoir comment lister et paginer les lots.

Téléversement de fichiers

Le SDK définit des méthodes qui acceptent des fichiers via la classe MultipartField :

import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;

FileUploadParams params = FileUploadParams.builder()
  .file(
    MultipartField.<InputStream>builder()
      .value(Files.newInputStream(Paths.get("/path/to/file.pdf")))
      .contentType("application/pdf")
      .build()
  )
  .build();

FileMetadata fileMetadata = client.beta().files().upload(params);

Ou à partir d'un InputStream :

import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;

FileUploadParams params = FileUploadParams.builder()
  .file(
    MultipartField.<InputStream>builder()
      .value(new URL("https://example.com/path/to/file").openStream())
      .filename("document.pdf")
      .contentType("application/pdf")
      .build()
  )
  .build();

FileMetadata fileMetadata = client.beta().files().upload(params);

Ou à partir d'octets en mémoire :

import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;

FileUploadParams params = FileUploadParams.builder()
  .file(
    MultipartField.<InputStream>builder()
      .value(new ByteArrayInputStream("content".getBytes()))
      .filename("document.txt")
      .contentType("text/plain")
      .build()
  )
  .build();

FileMetadata fileMetadata = client.beta().files().upload(params);

Réponses binaires

Le SDK définit des méthodes qui renvoient des réponses binaires pour les réponses d'API qui ne sont pas nécessairement analysées en JSON :

import com.anthropic.core.http.HttpResponse;

HttpResponse response = client.beta().files().download("file_id");

Pour enregistrer le contenu de la réponse dans un fichier :

import com.anthropic.core.http.HttpResponse;

try (HttpResponse response = client.beta().files().download(params)) {
    Files.copy(
        response.body(),
        Paths.get(path),
        StandardCopyOption.REPLACE_EXISTING
    );
} catch (Exception e) {
    IO.println("Something went wrong!");
    throw new RuntimeException(e);
}

Ou transférer le contenu de la réponse vers n'importe quel OutputStream :

import com.anthropic.core.http.HttpResponse;

try (HttpResponse response = client.beta().files().download(params)) {
    response.body().transferTo(Files.newOutputStream(Paths.get(path)));
} catch (Exception e) {
    IO.println("Something went wrong!");
    throw new RuntimeException(e);
}

Gestion des erreurs

Le SDK lève des types d'exceptions non vérifiées personnalisés :

AnthropicServiceException - Classe de base pour les erreurs HTTP.
AnthropicIoException - Erreurs réseau d'E/S.
AnthropicRetryableException - Erreur générique indiquant un échec qui pourrait être retenté.
AnthropicInvalidDataException - Échec de l'interprétation de données analysées avec succès (par exemple, lors de l'accès à une propriété censée être requise, mais que l'API a omise de manière inattendue).
AnthropicException - Classe de base pour toutes les exceptions.

Correspondance des codes de statut

Statut	Exception
400	`BadRequestException`
401	`UnauthorizedException`
403	`PermissionDeniedException`
404	`NotFoundException`
422	`UnprocessableEntityException`
429	`RateLimitException`
5xx	`InternalServerException`
autres	`UnexpectedStatusCodeException`

SseException est levée pour les erreurs rencontrées pendant le streaming SSE après une réponse HTTP initiale réussie.

import com.anthropic.errors.*;

try {
    Message message = client.messages().create(params);
} catch (RateLimitException e) {
    IO.println("Rate limited, retry after: " + e.headers());
} catch (UnauthorizedException e) {
    IO.println("Invalid API key");
} catch (AnthropicServiceException e) {
    IO.println("API error: " + e.statusCode());
} catch (AnthropicIoException e) {
    IO.println("Network error: " + e.getMessage());
}

Identifiants de requête

Lorsque vous utilisez des réponses brutes, vous pouvez accéder à l'en-tête de réponse request-id à l'aide de la méthode requestId() :

import com.anthropic.core.http.HttpResponseFor;
import com.anthropic.models.messages.Message;

HttpResponseFor<Message> message = client.messages().withRawResponse().create(params);

Optional<String> requestId = message.requestId();

Cela peut être utilisé pour journaliser rapidement les requêtes en échec et les signaler à Anthropic. Pour plus d'informations sur le débogage des requêtes, consultez Identifiant de requête.

Nouvelles tentatives

Le SDK effectue automatiquement 2 nouvelles tentatives par défaut, avec un court délai exponentiel entre les requêtes.

Seuls les types d'erreurs suivants font l'objet de nouvelles tentatives :

Erreurs de connexion (par exemple, en raison d'un problème de connectivité réseau)
408 Request Timeout
409 Conflict
429 Rate Limit
5xx Internal

L'API peut également indiquer explicitement au SDK de retenter ou non une requête.

Pour définir un nombre personnalisé de nouvelles tentatives, configurez le client à l'aide de la méthode maxRetries :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder().fromEnv().maxRetries(4).build();

Délais d'expiration

Les requêtes expirent après 10 minutes par défaut.

Cependant, pour les méthodes qui acceptent maxTokens, si vous spécifiez une valeur maxTokens élevée et que vous utilisez le streaming, le délai d'expiration par défaut sera calculé dynamiquement à l'aide de cette formule :

Duration.ofSeconds(
    Math.min(
        60 * 60, // 1 hour max
        Math.max(
            10 * 60, // 10 minute minimum
            60 * 60 * maxTokens / 128_000
        )
    )
)

Cela donne un délai d'expiration allant jusqu'à 60 minutes, proportionnel au paramètre maxTokens, sauf s'il est remplacé.

Pour les requêtes sans streaming, le délai d'expiration dynamique varie d'un minimum de 30 secondes à un maximum de 10 minutes en fonction de maxTokens.

Pour définir un délai d'expiration personnalisé par requête :

import com.anthropic.models.messages.Message;

Message message = client
  .messages()
  .create(params, RequestOptions.builder().timeout(Duration.ofSeconds(30)).build());

Ou configurez la valeur par défaut pour tous les appels de méthode au niveau du client :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .timeout(Duration.ofSeconds(30))
  .build();

Requêtes longues

Envisagez d'utiliser le streaming pour les requêtes de longue durée.

Évitez de définir une valeur maxTokens é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 ou l'expiration de la requête sans recevoir de réponse d'Anthropic. Le SDK envoie périodiquement des pings à l'API pour maintenir la connexion active et réduire l'impact de ces réseaux.

Le SDK lève une erreur si une requête sans streaming est censée durer plus de 10 minutes. L'utilisation d'une méthode de streaming ou le remplacement du délai d'expiration au niveau du client ou de la requête désactive cette erreur.

Pagination

Le SDK offre des moyens pratiques d'accéder aux résultats paginés, soit une page à la fois, soit élément par élément sur toutes les pages.

Pagination automatique

Pour parcourir tous les résultats sur toutes les pages, utilisez la méthode autoPager(), qui récupère automatiquement des pages supplémentaires selon les besoins.

import com.anthropic.models.messages.batches.BatchListPage;
import com.anthropic.models.messages.batches.MessageBatch;

BatchListPage page = client.messages().batches().list();

// Traiter comme un Iterable
for (MessageBatch batch : page.autoPager()) {
    IO.println(batch);
}

// Traiter comme un Stream
page.autoPager()
    .stream()
    .limit(50)
    .forEach(batch -> IO.println(batch));

Lors de l'utilisation du client asynchrone, la méthode renvoie un AsyncStreamResponse :

import com.anthropic.core.http.AsyncStreamResponse;
import com.anthropic.models.messages.batches.BatchListPageAsync;
import com.anthropic.models.messages.batches.MessageBatch;

CompletableFuture<BatchListPageAsync> pageFuture = client.async().messages().batches().list();

pageFuture.thenAccept(page -> page.autoPager().subscribe(batch -> {
    IO.println(batch);
}));

// Si vous devez gérer les erreurs ou la fin du stream
pageFuture.thenAccept(page -> page.autoPager().subscribe(new AsyncStreamResponse.Handler<>() {
    @Override
    public void onNext(MessageBatch batch) {
        IO.println(batch);
    }

    @Override
    public void onComplete(Optional<Throwable> error) {
        if (error.isPresent()) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error.get());
        } else {
            IO.println("No more!");
        }
    }
}));

// Ou utilisez des futures
pageFuture.thenAccept(page -> page.autoPager()
    .subscribe(batch -> {
        IO.println(batch);
    })
    .onCompleteFuture()
    .whenComplete((unused, error) -> {
        if (error != null) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error);
        } else {
            IO.println("No more!");
        }
    }));

Pagination manuelle

Pour accéder aux éléments individuels d'une page et demander manuellement la page suivante :

import com.anthropic.models.messages.batches.BatchListPage;
import com.anthropic.models.messages.batches.MessageBatch;

BatchListPage page = client.messages().batches().list();
while (true) {
    for (MessageBatch batch : page.items()) {
        IO.println(batch);
    }

    if (!page.hasNextPage()) {
        break;
    }

    page = page.nextPage();
}

Système de types

Immuabilité et builders

Chaque classe du SDK dispose d'un builder associé pour sa construction. Chaque classe est immuable une fois construite. Si la classe dispose d'un builder associé, elle possède une méthode toBuilder(), qui peut être utilisée pour la reconvertir en builder afin de créer une copie modifiée.

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

// Créer une copie modifiée avec toBuilder()
MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build();

Comme chaque classe est immuable, la modification du builder n'affectera jamais les instances de classe déjà construites.

Requêtes et réponses

Pour envoyer une requête à l'API Claude, construisez une instance d'une classe Params et passez-la à la méthode client correspondante. Lorsque la réponse est reçue, elle est désérialisée en une instance d'une classe Java.

Par exemple, client.messages().create(...) doit être appelé avec une instance de MessageCreateParams, et il renverra une instance de Message.

Paramètres non documentés

Pour définir des paramètres non documentés, appelez les méthodes putAdditionalHeader, putAdditionalQueryParam ou putAdditionalBodyProperty sur n'importe quelle classe Params :

import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.MessageCreateParams;

MessageCreateParams params = MessageCreateParams.builder()
  .putAdditionalHeader("Secret-Header", "42")
  .putAdditionalQueryParam("secret_query_param", "42")
  .putAdditionalBodyProperty("secretProperty", JsonValue.from("42"))
  .build();

Ces valeurs sont accessibles ultérieurement sur l'objet construit à l'aide des méthodes _additionalHeaders(), _additionalQueryParams() et _additionalBodyProperties().

Les valeurs passées à ces méthodes écrasent les valeurs passées aux méthodes précédentes. Pour des raisons de sécurité, assurez-vous que ces méthodes ne sont utilisées qu'avec des données d'entrée de confiance.

Pour définir des paramètres non documentés sur des en-têtes imbriqués, des paramètres de requête ou des classes de corps :

import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Metadata;

MessageCreateParams params = MessageCreateParams.builder()
  .metadata(
    Metadata.builder().putAdditionalProperty("secretProperty", JsonValue.from("42")).build()
  )
  .build();

Ces propriétés sont accessibles ultérieurement sur l'objet imbriqué construit à l'aide de la méthode _additionalProperties().

Pour définir un paramètre ou une propriété documenté sur une valeur non documentée ou non encore prise en charge, passez un objet JsonValue à son setter :

import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(JsonValue.from(3.14))
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

Création de JsonValue

La manière la plus simple de créer un JsonValue est d'utiliser sa méthode from(...) :

import com.anthropic.core.JsonValue;

// Créer des valeurs JSON primitives
JsonValue nullValue = JsonValue.from(null);

JsonValue booleanValue = JsonValue.from(true);

JsonValue numberValue = JsonValue.from(42);

JsonValue stringValue = JsonValue.from("Hello World!");

// Créer une valeur de tableau JSON équivalente à `["Hello", "World"]`
JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));

// Créer une valeur d'objet JSON équivalente à `{ "a": 1, "b": 2 }`
JsonValue objectValue = JsonValue.from(Map.of("a", 1, "b", 2));

// Créer un JSON imbriqué arbitrairement, équivalent à :
// { "a": [1, 2], "b": [3, 4] }
JsonValue complexValue = JsonValue.from(Map.of("a", List.of(1, 2), "b", List.of(3, 4)));

Omission forcée de paramètres requis

Normalement, la méthode build d'une classe Builder lève une IllegalStateException si un paramètre ou une propriété requis n'est pas défini. Pour omettre de force un paramètre ou une propriété requis, passez JsonMissing :

import com.anthropic.core.JsonMissing;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
  .addUserMessage("Hello, world")
  .model(Model.CLAUDE_OPUS_4_8)
  .maxTokens(JsonMissing.of())
  .build();

Propriétés de réponse

Pour accéder aux propriétés de réponse non documentées, appelez la méthode _additionalProperties() :

import com.anthropic.core.JsonValue;

Map<String, JsonValue> additionalProperties = client
  .messages()
  .create(params)
  ._additionalProperties();

JsonValue secretPropertyValue = additionalProperties.get("secretProperty");

String result = secretPropertyValue.accept(new JsonValue.Visitor<>() {
    @Override
    public String visitNull() {
        return "It's null!";
    }

    @Override
    public String visitBoolean(boolean value) {
        return "It's a boolean!";
    }

    @Override
    public String visitNumber(Number value) {
        return "It's a number!";
    }

    // Les autres méthodes incluent `visitMissing`, `visitString`, `visitArray` et `visitObject`
    // L'implémentation par défaut de chaque méthode non implémentée délègue à `visitDefault`,
    // qui lève une exception par défaut, mais peut également être surchargée
});

Pour accéder à la valeur JSON brute d'une propriété, appelez sa méthode préfixée par _ :

import com.anthropic.core.JsonField;
import com.anthropic.models.messages.StopReason;

JsonField<StopReason> stopReason = client.messages().create(params)._stopReason();

if (stopReason.isMissing()) {
  // La propriété est absente de la réponse JSON
} else if (stopReason.isNull()) {
  // La propriété a été définie à null littéral
} else {
  // Vérifier si la valeur a été fournie sous forme de chaîne
  // Les autres méthodes incluent `asNumber()`, `asBoolean()`, etc.
  Optional<String> jsonString = stopReason.asString();

  // Essayer de désérialiser vers un type personnalisé
  MyClass myObject = stopReason.asUnknown().orElseThrow().convert(MyClass.class);
}

Validation des réponses

Par défaut, le SDK ne lève pas d'exception lorsque l'API renvoie une réponse qui ne correspond pas au type attendu. Il lève AnthropicInvalidDataException uniquement si vous accédez directement à la propriété.

Pour vérifier en amont que la réponse est entièrement bien typée, appelez validate() :

import com.anthropic.models.messages.Message;

Message message = client.messages().create(params).validate();

Ou configurez par requête :

import com.anthropic.models.messages.Message;

Message message = client
  .messages()
  .create(params, RequestOptions.builder().responseValidation(true).build());

Ou configurez la valeur par défaut pour tous les appels de méthode au niveau du client :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .responseValidation(true)
  .build();

Personnalisation du client HTTP

Configuration du proxy

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import java.net.Proxy;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("https://example.com", 8080)))
  .build();

Configuration HTTPS / SSL

La plupart des applications ne devraient pas appeler ces méthodes et devraient plutôt utiliser les valeurs par défaut du système. Les valeurs par défaut incluent des optimisations spéciales qui peuvent être perdues si les implémentations sont modifiées.

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .sslSocketFactory(yourSSLSocketFactory)
  .trustManager(yourTrustManager)
  .hostnameVerifier(yourHostnameVerifier)
  .build();

Client HTTP personnalisé

Le SDK se compose de trois artefacts :

anthropic-java-core - Contient la logique principale du SDK, ne dépend pas d'OkHttp. Expose AnthropicClient, AnthropicClientAsync et leurs classes d'implémentation, qui peuvent toutes fonctionner avec n'importe quel client HTTP.
anthropic-java-client-okhttp - Dépend d'OkHttp. Expose AnthropicOkHttpClient et AnthropicOkHttpClientAsync.
anthropic-java - Dépend des API de anthropic-java-core et anthropic-java-client-okhttp et les expose. N'a pas de logique propre.

Cette structure permet de remplacer le client HTTP par défaut du SDK sans importer de dépendances inutiles.

OkHttpClient personnalisé

Essayez les options réseau disponibles avant de remplacer le client par défaut.

Pour utiliser un OkHttpClient personnalisé :

Remplacez votre dépendance anthropic-java par anthropic-java-core.
Copiez la classe OkHttpClient de anthropic-java-client-okhttp dans votre code et personnalisez-la.
Construisez AnthropicClientImpl ou AnthropicClientAsyncImpl à l'aide de votre client personnalisé.

Client HTTP entièrement personnalisé

Pour utiliser un client HTTP entièrement personnalisé :

Remplacez votre dépendance anthropic-java par anthropic-java-core.
Écrivez une classe qui implémente l'interface HttpClient.
Construisez AnthropicClientImpl ou AnthropicClientAsyncImpl à l'aide de votre nouvelle classe de client.

Intégrations de plateformes

Pour des guides de configuration de plateforme détaillés avec des exemples de code, consultez :

Le SDK Java prend en charge les plateformes suivantes via des dépendances distinctes qui fournissent des implémentations Backend spécifiques à chaque plateforme :

Bedrock : com.anthropic:anthropic-java-bedrock : Utilisez BedrockMantleBackend.fromEnv() ou BedrockMantleBackend.builder() pour le point de terminaison Bedrock de l'API Messages, ou BedrockBackend.fromEnv() / BedrockBackend.builder() (chemin bedrock-runtime).
Vertex AI : com.anthropic:anthropic-java-vertex : Utilisez VertexBackend.fromEnv() ou VertexBackend.builder().
Foundry : com.anthropic:anthropic-java-foundry : Utilisez FoundryBackend.fromEnv() ou FoundryBackend.builder().
Claude Platform sur AWS : com.anthropic:anthropic-java-aws : Utilisez AwsBackend.fromEnv() (lit ANTHROPIC_AWS_WORKSPACE_ID et la chaîne de région/identifiants AWS par défaut) ou AwsBackend.builder(). Disponible en version bêta.

Utilisez BedrockMantleBackend pour les nouveaux projets ; BedrockBackend reste disponible pour les applications existantes utilisant l'API InvokeModel de Bedrock.

Chaque implémentation Backend est passée au client avec .backend() sur AnthropicOkHttpClient.builder(). Chaque backend cloud importe les classes du SDK de sa plateforme cloud respective en tant que dépendances transitives.

Utilisation avancée

Accès aux réponses brutes

Pour accéder aux en-têtes HTTP, aux codes de statut et au corps brut de la réponse, préfixez tout appel de méthode HTTP avec withRawResponse() :

import com.anthropic.core.http.Headers;
import com.anthropic.core.http.HttpResponseFor;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

HttpResponseFor<Message> message = client.messages().withRawResponse().create(params);

int statusCode = message.statusCode();

Headers headers = message.headers();

Vous pouvez toujours désérialiser la réponse en une instance d'une classe Java si nécessaire :

import com.anthropic.models.messages.Message;

Message parsedMessage = message.parse();

Journalisation

Le SDK utilise l'intercepteur de journalisation OkHttp standard.

Activez la journalisation en définissant la variable d'environnement ANTHROPIC_LOG sur info :

export ANTHROPIC_LOG=info

Ou sur debug pour une journalisation plus détaillée :

export ANTHROPIC_LOG=debug

Fonctionnalités d'API non documentées

Le SDK est typé pour une utilisation pratique de l'API documentée. Cependant, il prend également en charge l'utilisation de parties non documentées ou non encore prises en charge de l'API.

Paramètres de requête non documentés

Pour définir des paramètres de requête non documentés, utilisez les méthodes putAdditionalHeader, putAdditionalQueryParam ou putAdditionalBodyProperty comme décrit dans Paramètres non documentés.

Propriétés de réponse non documentées

Pour accéder aux propriétés de réponse non documentées, utilisez la méthode _additionalProperties() comme décrit dans Propriétés de réponse.

Valeurs d'énumération nouvelles ou non publiées

Les classes de type énumération du SDK, telles que Model et AnthropicBeta, ne sont pas des types enum Java fermés. Chacune fournit une méthode factory of(String) qui accepte n'importe quelle chaîne, vous permettant ainsi d'utiliser des valeurs qui n'ont pas encore été ajoutées au SDK, comme un modèle ou un en-tête bêta publié après votre version du SDK :

import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.messages.Model;

Model model = Model.of("some-new-model");
AnthropicBeta beta = AnthropicBeta.of("some-new-beta-2026-01-01");

Les méthodes de builder qui acceptent ces types fournissent souvent également une surcharge String qui appelle of(...) pour vous :

import com.anthropic.models.messages.MessageCreateParams;

MessageCreateParams params = MessageCreateParams.builder()
  .model("some-new-model") // same as .model(Model.of("some-new-model"))
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .build();

Privilégiez les constantes bien typées (par exemple, Model.CLAUDE_OPUS_4_7) afin de bénéficier de l'autocomplétion et des avertissements de dépréciation. Les surcharges String et of(...) servent principalement à définir le champ sur une valeur non documentée ou non encore prise en charge en attendant une version du SDK qui l'inclut.

Fonctionnalités bêta

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 construction avec Claude.

Vous pouvez accéder à la plupart des fonctionnalités bêta de l'API via la méthode beta() sur le client. Pour activer une fonctionnalité bêta particulière, ajoutez l'en-tête bêta approprié avec .addBeta() lors de la construction des paramètres du message.

Par exemple, pour utiliser l'API Files :

import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaContentBlockParam;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestDocumentBlock;
import com.anthropic.models.beta.messages.BetaTextBlockParam;
import com.anthropic.models.beta.messages.MessageCreateParams;
// ...
void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    BetaMessage message = client.beta().messages().create(
        MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_4_8)
            .maxTokens(1024L)
            .addBeta(AnthropicBeta.FILES_API_2025_04_14)
            .addUserMessageOfBetaContentBlockParams(List.of(
                BetaContentBlockParam.ofText(
                    BetaTextBlockParam.builder()
                        .text("Please summarize this document for me.")
                        .build()),
                BetaContentBlockParam.ofDocument(
                    BetaRequestDocumentBlock.builder()
                        .fileSource("file_abc123")
                        .build())))
            .build());
}

Questions fréquentes

Versionnement sémantique

Ce package suit généralement les conventions SemVer, bien que certains changements rétro-incompatibles puissent être publiés en tant que versions mineures :

Modifications des éléments internes de la bibliothèque qui sont techniquement publics mais non destinés ni documentés pour un usage externe.
Modifications qui ne devraient pas affecter la grande majorité des utilisateurs en pratique.

Ressources supplémentaires

Was this page helpful?

CLI, SDK et bibliothèquesSDK clients

SDK Java

Installez et configurez le SDK Java d'Anthropic avec les patterns builder et la prise en charge asynchrone

Installation

Prérequis

Cette bibliothèque nécessite Java 8 ou une version ultérieure.

Démarrage rapide

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

// Configure à l'aide des propriétés système `anthropic.apiKey`, `anthropic.authToken` et `anthropic.baseUrl`
// Ou configure à l'aide des variables d'environnement `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` et `ANTHROPIC_BASE_URL`
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

Message message = client.messages().create(params);

Configuration du client

Configuration de la clé API

Configurez le client à l'aide des propriétés système ou des variables d'environnement :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

// Configure à l'aide des propriétés système `anthropic.apiKey`, `anthropic.authToken` et `anthropic.baseUrl`
// Ou configure à l'aide des variables d'environnement `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` et `ANTHROPIC_BASE_URL`
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

Ou configurez manuellement :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .apiKey("my-anthropic-api-key")
  .build();

Ou utilisez une combinaison des deux approches :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  // Configure à l'aide des propriétés système ou des variables d'environnement
  .fromEnv()
  .apiKey("my-anthropic-api-key")
  .build();

Pour les options d'authentification, y compris la « Workload Identity Federation » (fédération d'identité de charge de travail), consultez Authentification.

Options de configuration

Setter	Propriété système	Variable d'environnement	Requis	Valeur par défaut
`apiKey`	`anthropic.apiKey`	`ANTHROPIC_API_KEY`	false	-
`authToken`	`anthropic.authToken`	`ANTHROPIC_AUTH_TOKEN`	false	-
`baseUrl`	`anthropic.baseUrl`	`ANTHROPIC_BASE_URL`	true	`"https://api.anthropic.com"`

Les propriétés système ont priorité sur les variables d'environnement.

Ne créez pas plus d'un client dans la même application. Chaque client dispose d'un pool de connexions et de pools de threads, qu'il est plus efficace de partager entre les requêtes.

Modification de la configuration

Pour utiliser temporairement une configuration de client modifiée tout en réutilisant les mêmes pools de connexions et de threads, appelez withOptions() sur n'importe quel client ou service :

import com.anthropic.client.AnthropicClient;

AnthropicClient clientWithOptions = client.withOptions(optionsBuilder -> {
  optionsBuilder.baseUrl("https://example.com");
  optionsBuilder.maxRetries(42);
});

La méthode withOptions() n'affecte pas le client ou le service d'origine.

Utilisation asynchrone

Le client par défaut est synchrone. Pour passer à une exécution asynchrone, appelez la méthode async() :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

CompletableFuture<Message> message = client.async().messages().create(params);

Ou créez un client asynchrone dès le départ :

import com.anthropic.client.AnthropicClientAsync;
import com.anthropic.client.okhttp.AnthropicOkHttpClientAsync;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

AnthropicClientAsync client = AnthropicOkHttpClientAsync.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

CompletableFuture<Message> message = client.messages().create(params);

Le client asynchrone prend en charge les mêmes options que le client synchrone, à ceci près que la plupart des méthodes renvoient des CompletableFuture.

Streaming

Streaming synchrone

Ces méthodes de streaming renvoient StreamResponse pour les clients synchrones :

import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.messages.RawMessageStreamEvent;

try (StreamResponse<RawMessageStreamEvent> streamResponse = client.messages().createStreaming(params)) {
    streamResponse.stream().forEach(chunk -> {
        IO.println(chunk);
    });
    IO.println("No more chunks!");
}

Streaming asynchrone

Pour les clients asynchrones, la méthode renvoie AsyncStreamResponse :

import com.anthropic.core.http.AsyncStreamResponse;
import com.anthropic.models.messages.RawMessageStreamEvent;

client.async().messages().createStreaming(params).subscribe(chunk -> {
    IO.println(chunk);
});

// Si vous devez gérer les erreurs ou la fin du stream
client.async().messages().createStreaming(params).subscribe(new AsyncStreamResponse.Handler<>() {
    @Override
    public void onNext(RawMessageStreamEvent chunk) {
        IO.println(chunk);
    }

    @Override
    public void onComplete(Optional<Throwable> error) {
        if (error.isPresent()) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error.get());
        } else {
            IO.println("No more chunks!");
        }
    }
});

// Ou utilisez des futures
client.async().messages().createStreaming(params)
    .subscribe(chunk -> {
        IO.println(chunk);
    })
    .onCompleteFuture()
    .whenComplete((unused, error) -> {
        if (error != null) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error);
        } else {
            IO.println("No more chunks!");
        }
    });

Le streaming asynchrone utilise un Executor dédié par client avec pool de threads mis en cache pour diffuser sans bloquer le thread actuel. Pour utiliser un Executor différent :

Executor executor = Executors.newFixedThreadPool(4);
client.async().messages().createStreaming(params).subscribe(
    chunk -> IO.println(chunk), executor
);

Ou configurez le client globalement à l'aide de la méthode streamHandlerExecutor :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .streamHandlerExecutor(Executors.newFixedThreadPool(4))
  .build();

Streaming avec accumulateur de messages

Pour une réponse synchrone, ajoutez un appel Stream.peek() au pipeline de flux pour accumuler chaque événement :

import com.anthropic.core.http.StreamResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.RawMessageStreamEvent;

MessageAccumulator messageAccumulator = MessageAccumulator.create();

try (StreamResponse<RawMessageStreamEvent> streamResponse =
         client.messages().createStreaming(createParams)) {
    streamResponse.stream()
            .peek(messageAccumulator::accumulate)
            .flatMap(event -> event.contentBlockDelta().stream())
            .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
            .forEach(textDelta -> IO.print(textDelta.text()));
}

Message message = messageAccumulator.message();

Pour une réponse asynchrone, ajoutez le MessageAccumulator à l'appel subscribe() :

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.Message;

MessageAccumulator messageAccumulator = MessageAccumulator.create();

client.async().messages()
        .createStreaming(createParams)
        .subscribe(event -> messageAccumulator.accumulate(event).contentBlockDelta().stream()
                .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
                .forEach(textDelta -> IO.print(textDelta.text())))
        .onCompleteFuture()
        .join();

Message message = messageAccumulator.message();

Un BetaMessageAccumulator est également disponible pour l'accumulation d'un objet BetaMessage. Il s'utilise de la même manière que le MessageAccumulator.

Sorties structurées

Pour la documentation complète sur les sorties structurées, y compris des exemples Java, consultez Sorties structurées.

Utilisation d'outils

Définition d'outils avec des annotations

import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;

enum Unit {
  CELSIUS,
  FAHRENHEIT;

  public String toString() {
    switch (this) {
      case CELSIUS:
        return "C";
      case FAHRENHEIT:
      default:
        return "F";
    }
  }

  public double fromKelvin(double temperatureK) {
    switch (this) {
      case CELSIUS:
        return temperatureK - 273.15;
      case FAHRENHEIT:
      default:
        return (temperatureK - 273.15) * 1.8 + 32.0;
    }
  }
}

@JsonClassDescription("Get the weather in a given location")
static class GetWeather {

  @JsonPropertyDescription("The city and state, e.g. San Francisco, CA")
  public String location;

  @JsonPropertyDescription("The unit of temperature")
  public Unit unit;

  public Weather execute() {
    double temperatureK;
    switch (location) {
      case "San Francisco, CA":
        temperatureK = 300.0;
        break;
      case "New York, NY":
        temperatureK = 310.0;
        break;
      case "Dallas, TX":
        temperatureK = 305.0;
        break;
      default:
        temperatureK = 295;
        break;
    }
    return new Weather(String.format("%.0f%s", unit.fromKelvin(temperatureK), unit));
  }
}

static class Weather {

  public String temperature;

  public Weather(String temperature) {
    this.temperature = temperature;
  }
}

Appel des outils

Après avoir appelé l'outil, utilisez BetaToolResultBlockParam.Builder.contentAsJson(Object) pour renvoyer le résultat de l'outil au modèle d'IA :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.*;
import com.anthropic.models.messages.Model;

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams.Builder createParamsBuilder = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_8)
        .maxTokens(2048)
        .addTool(GetWeather.class)
        .addUserMessage("What's the temperature in New York?");

client.beta().messages().create(createParamsBuilder.build()).content().stream()
        .flatMap(contentBlock -> contentBlock.toolUse().stream())
        .forEach(toolUseBlock -> createParamsBuilder
              // Ajoutez un message indiquant que l'utilisation d'outils a été demandée.
              .addAssistantMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder()
                              .name(toolUseBlock.name())
                              .id(toolUseBlock.id())
                              .input(toolUseBlock._input())
                              .build())))
              // Ajoutez un message avec le résultat de l'utilisation d'outils demandée.
              .addUserMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolResult(BetaToolResultBlockParam.builder()
                              .toolUseId(toolUseBlock.id())
                              .contentAsJson(callTool(toolUseBlock))
                              .build()))));

client.beta().messages().create(createParamsBuilder.build()).content().stream()
        .flatMap(contentBlock -> contentBlock.text().stream())
        .forEach(textBlock -> IO.println(textBlock.text()));

private static Object callTool(BetaToolUseBlock toolUseBlock) {
  if (!"get_weather".equals(toolUseBlock.name())) {
    throw new IllegalArgumentException("Unknown tool: " + toolUseBlock.name());
  }

  GetWeather tool = toolUseBlock.input(GetWeather.class);
  return tool != null ? tool.execute() : new Weather("unknown");
}

Conversion des noms d'outils

Validation locale du schéma JSON des outils

MessageCreateParams.Builder createParamsBuilder = MessageCreateParams.builder()
  .model(Model.CLAUDE_OPUS_4_8)
  .maxTokens(2048)
  .addTool(GetWeather.class, JsonSchemaLocalValidation.NO)
  .addUserMessage("What's the temperature in New York?");

Annotation des classes d'outils

Vous pouvez utiliser des annotations pour ajouter des informations supplémentaires sur les outils aux schémas JSON :

@JsonClassDescription - Ajoute une description à une classe d'outil détaillant quand et comment utiliser cet outil.
@JsonTypeName - Définit le nom de l'outil sur une valeur autre que le nom simple de la classe converti en snake case.
@JsonPropertyDescription - Ajoute une description détaillée à un paramètre d'outil.
@JsonIgnore - Exclut un champ public ou une méthode getter du schéma JSON généré pour les paramètres d'un outil.
@JsonProperty - Inclut un champ non public ou une méthode getter dans le schéma JSON généré pour les paramètres d'un outil.

Lots de messages

Le SDK prend en charge le traitement par lots sous l'espace de noms client.messages().batches(). Consultez Pagination pour savoir comment lister et paginer les lots.

Téléversement de fichiers

Le SDK définit des méthodes qui acceptent des fichiers via la classe MultipartField :

import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;

FileUploadParams params = FileUploadParams.builder()
  .file(
    MultipartField.<InputStream>builder()
      .value(Files.newInputStream(Paths.get("/path/to/file.pdf")))
      .contentType("application/pdf")
      .build()
  )
  .build();

FileMetadata fileMetadata = client.beta().files().upload(params);

Ou à partir d'un InputStream :

import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;

FileUploadParams params = FileUploadParams.builder()
  .file(
    MultipartField.<InputStream>builder()
      .value(new URL("https://example.com/path/to/file").openStream())
      .filename("document.pdf")
      .contentType("application/pdf")
      .build()
  )
  .build();

FileMetadata fileMetadata = client.beta().files().upload(params);

Ou à partir d'octets en mémoire :

import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;

FileUploadParams params = FileUploadParams.builder()
  .file(
    MultipartField.<InputStream>builder()
      .value(new ByteArrayInputStream("content".getBytes()))
      .filename("document.txt")
      .contentType("text/plain")
      .build()
  )
  .build();

FileMetadata fileMetadata = client.beta().files().upload(params);

Réponses binaires

Le SDK définit des méthodes qui renvoient des réponses binaires pour les réponses d'API qui ne sont pas nécessairement analysées en JSON :

import com.anthropic.core.http.HttpResponse;

HttpResponse response = client.beta().files().download("file_id");

Pour enregistrer le contenu de la réponse dans un fichier :

import com.anthropic.core.http.HttpResponse;

try (HttpResponse response = client.beta().files().download(params)) {
    Files.copy(
        response.body(),
        Paths.get(path),
        StandardCopyOption.REPLACE_EXISTING
    );
} catch (Exception e) {
    IO.println("Something went wrong!");
    throw new RuntimeException(e);
}

Ou transférer le contenu de la réponse vers n'importe quel OutputStream :

import com.anthropic.core.http.HttpResponse;

try (HttpResponse response = client.beta().files().download(params)) {
    response.body().transferTo(Files.newOutputStream(Paths.get(path)));
} catch (Exception e) {
    IO.println("Something went wrong!");
    throw new RuntimeException(e);
}

Gestion des erreurs

Le SDK lève des types d'exceptions non vérifiées personnalisés :

AnthropicServiceException - Classe de base pour les erreurs HTTP.
AnthropicIoException - Erreurs réseau d'E/S.
AnthropicRetryableException - Erreur générique indiquant un échec qui pourrait être retenté.
AnthropicInvalidDataException - Échec de l'interprétation de données analysées avec succès (par exemple, lors de l'accès à une propriété censée être requise, mais que l'API a omise de manière inattendue).
AnthropicException - Classe de base pour toutes les exceptions.

Correspondance des codes de statut

Statut	Exception
400	`BadRequestException`
401	`UnauthorizedException`
403	`PermissionDeniedException`
404	`NotFoundException`
422	`UnprocessableEntityException`
429	`RateLimitException`
5xx	`InternalServerException`
autres	`UnexpectedStatusCodeException`

SseException est levée pour les erreurs rencontrées pendant le streaming SSE après une réponse HTTP initiale réussie.

import com.anthropic.errors.*;

try {
    Message message = client.messages().create(params);
} catch (RateLimitException e) {
    IO.println("Rate limited, retry after: " + e.headers());
} catch (UnauthorizedException e) {
    IO.println("Invalid API key");
} catch (AnthropicServiceException e) {
    IO.println("API error: " + e.statusCode());
} catch (AnthropicIoException e) {
    IO.println("Network error: " + e.getMessage());
}

Identifiants de requête

Lorsque vous utilisez des réponses brutes, vous pouvez accéder à l'en-tête de réponse request-id à l'aide de la méthode requestId() :

import com.anthropic.core.http.HttpResponseFor;
import com.anthropic.models.messages.Message;

HttpResponseFor<Message> message = client.messages().withRawResponse().create(params);

Optional<String> requestId = message.requestId();

Cela peut être utilisé pour journaliser rapidement les requêtes en échec et les signaler à Anthropic. Pour plus d'informations sur le débogage des requêtes, consultez Identifiant de requête.

Nouvelles tentatives

Le SDK effectue automatiquement 2 nouvelles tentatives par défaut, avec un court délai exponentiel entre les requêtes.

Seuls les types d'erreurs suivants font l'objet de nouvelles tentatives :

Erreurs de connexion (par exemple, en raison d'un problème de connectivité réseau)
408 Request Timeout
409 Conflict
429 Rate Limit
5xx Internal

L'API peut également indiquer explicitement au SDK de retenter ou non une requête.

Pour définir un nombre personnalisé de nouvelles tentatives, configurez le client à l'aide de la méthode maxRetries :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder().fromEnv().maxRetries(4).build();

Délais d'expiration

Les requêtes expirent après 10 minutes par défaut.

Duration.ofSeconds(
    Math.min(
        60 * 60, // 1 hour max
        Math.max(
            10 * 60, // 10 minute minimum
            60 * 60 * maxTokens / 128_000
        )
    )
)

Cela donne un délai d'expiration allant jusqu'à 60 minutes, proportionnel au paramètre maxTokens, sauf s'il est remplacé.

Pour les requêtes sans streaming, le délai d'expiration dynamique varie d'un minimum de 30 secondes à un maximum de 10 minutes en fonction de maxTokens.

Pour définir un délai d'expiration personnalisé par requête :

import com.anthropic.models.messages.Message;

Message message = client
  .messages()
  .create(params, RequestOptions.builder().timeout(Duration.ofSeconds(30)).build());

Ou configurez la valeur par défaut pour tous les appels de méthode au niveau du client :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .timeout(Duration.ofSeconds(30))
  .build();

Requêtes longues

Envisagez d'utiliser le streaming pour les requêtes de longue durée.

Pagination

Le SDK offre des moyens pratiques d'accéder aux résultats paginés, soit une page à la fois, soit élément par élément sur toutes les pages.

Pagination automatique

Pour parcourir tous les résultats sur toutes les pages, utilisez la méthode autoPager(), qui récupère automatiquement des pages supplémentaires selon les besoins.

import com.anthropic.models.messages.batches.BatchListPage;
import com.anthropic.models.messages.batches.MessageBatch;

BatchListPage page = client.messages().batches().list();

// Traiter comme un Iterable
for (MessageBatch batch : page.autoPager()) {
    IO.println(batch);
}

// Traiter comme un Stream
page.autoPager()
    .stream()
    .limit(50)
    .forEach(batch -> IO.println(batch));

Lors de l'utilisation du client asynchrone, la méthode renvoie un AsyncStreamResponse :

import com.anthropic.core.http.AsyncStreamResponse;
import com.anthropic.models.messages.batches.BatchListPageAsync;
import com.anthropic.models.messages.batches.MessageBatch;

CompletableFuture<BatchListPageAsync> pageFuture = client.async().messages().batches().list();

pageFuture.thenAccept(page -> page.autoPager().subscribe(batch -> {
    IO.println(batch);
}));

// Si vous devez gérer les erreurs ou la fin du stream
pageFuture.thenAccept(page -> page.autoPager().subscribe(new AsyncStreamResponse.Handler<>() {
    @Override
    public void onNext(MessageBatch batch) {
        IO.println(batch);
    }

    @Override
    public void onComplete(Optional<Throwable> error) {
        if (error.isPresent()) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error.get());
        } else {
            IO.println("No more!");
        }
    }
}));

// Ou utilisez des futures
pageFuture.thenAccept(page -> page.autoPager()
    .subscribe(batch -> {
        IO.println(batch);
    })
    .onCompleteFuture()
    .whenComplete((unused, error) -> {
        if (error != null) {
            IO.println("Something went wrong!");
            throw new RuntimeException(error);
        } else {
            IO.println("No more!");
        }
    }));

Pagination manuelle

Pour accéder aux éléments individuels d'une page et demander manuellement la page suivante :

import com.anthropic.models.messages.batches.BatchListPage;
import com.anthropic.models.messages.batches.MessageBatch;

BatchListPage page = client.messages().batches().list();
while (true) {
    for (MessageBatch batch : page.items()) {
        IO.println(batch);
    }

    if (!page.hasNextPage()) {
        break;
    }

    page = page.nextPage();
}

Système de types

Immuabilité et builders

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

// Créer une copie modifiée avec toBuilder()
MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build();

Comme chaque classe est immuable, la modification du builder n'affectera jamais les instances de classe déjà construites.

Requêtes et réponses

Par exemple, client.messages().create(...) doit être appelé avec une instance de MessageCreateParams, et il renverra une instance de Message.

Paramètres non documentés

Pour définir des paramètres non documentés, appelez les méthodes putAdditionalHeader, putAdditionalQueryParam ou putAdditionalBodyProperty sur n'importe quelle classe Params :

import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.MessageCreateParams;

MessageCreateParams params = MessageCreateParams.builder()
  .putAdditionalHeader("Secret-Header", "42")
  .putAdditionalQueryParam("secret_query_param", "42")
  .putAdditionalBodyProperty("secretProperty", JsonValue.from("42"))
  .build();

Ces valeurs sont accessibles ultérieurement sur l'objet construit à l'aide des méthodes _additionalHeaders(), _additionalQueryParams() et _additionalBodyProperties().

Pour définir des paramètres non documentés sur des en-têtes imbriqués, des paramètres de requête ou des classes de corps :

import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Metadata;

MessageCreateParams params = MessageCreateParams.builder()
  .metadata(
    Metadata.builder().putAdditionalProperty("secretProperty", JsonValue.from("42")).build()
  )
  .build();

Ces propriétés sont accessibles ultérieurement sur l'objet imbriqué construit à l'aide de la méthode _additionalProperties().

Pour définir un paramètre ou une propriété documenté sur une valeur non documentée ou non encore prise en charge, passez un objet JsonValue à son setter :

import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(JsonValue.from(3.14))
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

Création de JsonValue

La manière la plus simple de créer un JsonValue est d'utiliser sa méthode from(...) :

import com.anthropic.core.JsonValue;

// Créer des valeurs JSON primitives
JsonValue nullValue = JsonValue.from(null);

JsonValue booleanValue = JsonValue.from(true);

JsonValue numberValue = JsonValue.from(42);

JsonValue stringValue = JsonValue.from("Hello World!");

// Créer une valeur de tableau JSON équivalente à `["Hello", "World"]`
JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));

// Créer une valeur d'objet JSON équivalente à `{ "a": 1, "b": 2 }`
JsonValue objectValue = JsonValue.from(Map.of("a", 1, "b", 2));

// Créer un JSON imbriqué arbitrairement, équivalent à :
// { "a": [1, 2], "b": [3, 4] }
JsonValue complexValue = JsonValue.from(Map.of("a", List.of(1, 2), "b", List.of(3, 4)));

Omission forcée de paramètres requis

import com.anthropic.core.JsonMissing;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
  .addUserMessage("Hello, world")
  .model(Model.CLAUDE_OPUS_4_8)
  .maxTokens(JsonMissing.of())
  .build();

Propriétés de réponse

Pour accéder aux propriétés de réponse non documentées, appelez la méthode _additionalProperties() :

import com.anthropic.core.JsonValue;

Map<String, JsonValue> additionalProperties = client
  .messages()
  .create(params)
  ._additionalProperties();

JsonValue secretPropertyValue = additionalProperties.get("secretProperty");

String result = secretPropertyValue.accept(new JsonValue.Visitor<>() {
    @Override
    public String visitNull() {
        return "It's null!";
    }

    @Override
    public String visitBoolean(boolean value) {
        return "It's a boolean!";
    }

    @Override
    public String visitNumber(Number value) {
        return "It's a number!";
    }

    // Les autres méthodes incluent `visitMissing`, `visitString`, `visitArray` et `visitObject`
    // L'implémentation par défaut de chaque méthode non implémentée délègue à `visitDefault`,
    // qui lève une exception par défaut, mais peut également être surchargée
});

Pour accéder à la valeur JSON brute d'une propriété, appelez sa méthode préfixée par _ :

import com.anthropic.core.JsonField;
import com.anthropic.models.messages.StopReason;

JsonField<StopReason> stopReason = client.messages().create(params)._stopReason();

if (stopReason.isMissing()) {
  // La propriété est absente de la réponse JSON
} else if (stopReason.isNull()) {
  // La propriété a été définie à null littéral
} else {
  // Vérifier si la valeur a été fournie sous forme de chaîne
  // Les autres méthodes incluent `asNumber()`, `asBoolean()`, etc.
  Optional<String> jsonString = stopReason.asString();

  // Essayer de désérialiser vers un type personnalisé
  MyClass myObject = stopReason.asUnknown().orElseThrow().convert(MyClass.class);
}

Validation des réponses

Pour vérifier en amont que la réponse est entièrement bien typée, appelez validate() :

import com.anthropic.models.messages.Message;

Message message = client.messages().create(params).validate();

Ou configurez par requête :

import com.anthropic.models.messages.Message;

Message message = client
  .messages()
  .create(params, RequestOptions.builder().responseValidation(true).build());

Ou configurez la valeur par défaut pour tous les appels de méthode au niveau du client :

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .responseValidation(true)
  .build();

Personnalisation du client HTTP

Configuration du proxy

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import java.net.Proxy;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("https://example.com", 8080)))
  .build();

Configuration HTTPS / SSL

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

AnthropicClient client = AnthropicOkHttpClient.builder()
  .fromEnv()
  .sslSocketFactory(yourSSLSocketFactory)
  .trustManager(yourTrustManager)
  .hostnameVerifier(yourHostnameVerifier)
  .build();

Client HTTP personnalisé

Le SDK se compose de trois artefacts :

anthropic-java-core - Contient la logique principale du SDK, ne dépend pas d'OkHttp. Expose AnthropicClient, AnthropicClientAsync et leurs classes d'implémentation, qui peuvent toutes fonctionner avec n'importe quel client HTTP.
anthropic-java-client-okhttp - Dépend d'OkHttp. Expose AnthropicOkHttpClient et AnthropicOkHttpClientAsync.
anthropic-java - Dépend des API de anthropic-java-core et anthropic-java-client-okhttp et les expose. N'a pas de logique propre.

Cette structure permet de remplacer le client HTTP par défaut du SDK sans importer de dépendances inutiles.

OkHttpClient personnalisé

Essayez les options réseau disponibles avant de remplacer le client par défaut.

Pour utiliser un OkHttpClient personnalisé :

Remplacez votre dépendance anthropic-java par anthropic-java-core.
Copiez la classe OkHttpClient de anthropic-java-client-okhttp dans votre code et personnalisez-la.
Construisez AnthropicClientImpl ou AnthropicClientAsyncImpl à l'aide de votre client personnalisé.

Client HTTP entièrement personnalisé

Pour utiliser un client HTTP entièrement personnalisé :

Remplacez votre dépendance anthropic-java par anthropic-java-core.
Écrivez une classe qui implémente l'interface HttpClient.
Construisez AnthropicClientImpl ou AnthropicClientAsyncImpl à l'aide de votre nouvelle classe de client.

Intégrations de plateformes

Pour des guides de configuration de plateforme détaillés avec des exemples de code, consultez :

Le SDK Java prend en charge les plateformes suivantes via des dépendances distinctes qui fournissent des implémentations Backend spécifiques à chaque plateforme :

Bedrock : com.anthropic:anthropic-java-bedrock : Utilisez BedrockMantleBackend.fromEnv() ou BedrockMantleBackend.builder() pour le point de terminaison Bedrock de l'API Messages, ou BedrockBackend.fromEnv() / BedrockBackend.builder() (chemin bedrock-runtime).
Vertex AI : com.anthropic:anthropic-java-vertex : Utilisez VertexBackend.fromEnv() ou VertexBackend.builder().
Foundry : com.anthropic:anthropic-java-foundry : Utilisez FoundryBackend.fromEnv() ou FoundryBackend.builder().
Claude Platform sur AWS : com.anthropic:anthropic-java-aws : Utilisez AwsBackend.fromEnv() (lit ANTHROPIC_AWS_WORKSPACE_ID et la chaîne de région/identifiants AWS par défaut) ou AwsBackend.builder(). Disponible en version bêta.

Utilisez BedrockMantleBackend pour les nouveaux projets ; BedrockBackend reste disponible pour les applications existantes utilisant l'API InvokeModel de Bedrock.

Utilisation avancée

Accès aux réponses brutes

Pour accéder aux en-têtes HTTP, aux codes de statut et au corps brut de la réponse, préfixez tout appel de méthode HTTP avec withRawResponse() :

import com.anthropic.core.http.Headers;
import com.anthropic.core.http.HttpResponseFor;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .model(Model.CLAUDE_OPUS_4_8)
  .build();

HttpResponseFor<Message> message = client.messages().withRawResponse().create(params);

int statusCode = message.statusCode();

Headers headers = message.headers();

Vous pouvez toujours désérialiser la réponse en une instance d'une classe Java si nécessaire :

import com.anthropic.models.messages.Message;

Message parsedMessage = message.parse();

Journalisation

Le SDK utilise l'intercepteur de journalisation OkHttp standard.

Activez la journalisation en définissant la variable d'environnement ANTHROPIC_LOG sur info :

export ANTHROPIC_LOG=info

Ou sur debug pour une journalisation plus détaillée :

export ANTHROPIC_LOG=debug

Fonctionnalités d'API non documentées

Le SDK est typé pour une utilisation pratique de l'API documentée. Cependant, il prend également en charge l'utilisation de parties non documentées ou non encore prises en charge de l'API.

Paramètres de requête non documentés

Propriétés de réponse non documentées

Pour accéder aux propriétés de réponse non documentées, utilisez la méthode _additionalProperties() comme décrit dans Propriétés de réponse.

Valeurs d'énumération nouvelles ou non publiées

import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.messages.Model;

Model model = Model.of("some-new-model");
AnthropicBeta beta = AnthropicBeta.of("some-new-beta-2026-01-01");

Les méthodes de builder qui acceptent ces types fournissent souvent également une surcharge String qui appelle of(...) pour vous :

import com.anthropic.models.messages.MessageCreateParams;

MessageCreateParams params = MessageCreateParams.builder()
  .model("some-new-model") // same as .model(Model.of("some-new-model"))
  .maxTokens(1024L)
  .addUserMessage("Hello, Claude")
  .build();

Fonctionnalités bêta

Par exemple, pour utiliser l'API Files :

import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaContentBlockParam;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestDocumentBlock;
import com.anthropic.models.beta.messages.BetaTextBlockParam;
import com.anthropic.models.beta.messages.MessageCreateParams;
// ...
void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    BetaMessage message = client.beta().messages().create(
        MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_4_8)
            .maxTokens(1024L)
            .addBeta(AnthropicBeta.FILES_API_2025_04_14)
            .addUserMessageOfBetaContentBlockParams(List.of(
                BetaContentBlockParam.ofText(
                    BetaTextBlockParam.builder()
                        .text("Please summarize this document for me.")
                        .build()),
                BetaContentBlockParam.ofDocument(
                    BetaRequestDocumentBlock.builder()
                        .fileSource("file_abc123")
                        .build())))
            .build());
}

Questions fréquentes

Versionnement sémantique

Ce package suit généralement les conventions SemVer, bien que certains changements rétro-incompatibles puissent être publiés en tant que versions mineures :

Modifications des éléments internes de la bibliothèque qui sont techniquement publics mais non destinés ni documentés pour un usage externe.
Modifications qui ne devraient pas affecter la grande majorité des utilisateurs en pratique.

Ressources supplémentaires

Was this page helpful?

Installation

Prérequis

Démarrage rapide

Configuration du client

Configuration de la clé API

Options de configuration

Modification de la configuration

Utilisation asynchrone

Streaming

Streaming synchrone

Streaming asynchrone

Streaming avec accumulateur de messages

Sorties structurées

Utilisation d'outils

Définition d'outils avec des annotations

Appel des outils

Conversion des noms d'outils

Validation locale du schéma JSON des outils

Annotation des classes d'outils

Lots de messages

Téléversement de fichiers

Réponses binaires

Gestion des erreurs

Correspondance des codes de statut

Identifiants de requête

Nouvelles tentatives

Délais d'expiration

Requêtes longues

Pagination

Pagination automatique

Pagination manuelle

Système de types

Immuabilité et builders

Requêtes et réponses

Paramètres non documentés

Création de JsonValue

Omission forcée de paramètres requis

Propriétés de réponse

Validation des réponses

Personnalisation du client HTTP

Configuration du proxy

Configuration HTTPS / SSL

Client HTTP personnalisé

OkHttpClient personnalisé

Client HTTP entièrement personnalisé

Intégrations de plateformes

Utilisation avancée

Accès aux réponses brutes

Journalisation

Compatibilité Jackson

Configuration ProGuard/R8

Fonctionnalités d'API non documentées

Paramètres de requête non documentés

Propriétés de réponse non documentées

Valeurs d'énumération nouvelles ou non publiées

Fonctionnalités bêta

Questions fréquentes

Pourquoi le SDK n'utilise-t-il pas de classes enum simples ?

Pourquoi les champs sont-ils représentés avec JsonField<T> au lieu de simplement T ?

Pourquoi le SDK n'utilise-t-il pas de data classes ?

Pourquoi le SDK n'utilise-t-il pas d'exceptions vérifiées ?

Versionnement sémantique

Ressources supplémentaires

Installation

Prérequis

Démarrage rapide

Configuration du client

Configuration de la clé API

Options de configuration

Modification de la configuration

Utilisation asynchrone

Streaming

Streaming synchrone

Streaming asynchrone

Streaming avec accumulateur de messages

Sorties structurées

Utilisation d'outils

Définition d'outils avec des annotations

Appel des outils

Conversion des noms d'outils