CLI、SDK、ライブラリクライアントSDK

Java SDK

ビルダーパターンと非同期サポートを備えたAnthropic Java SDKのインストールと設定

Anthropic Java SDKは、Javaで記述されたアプリケーションからAnthropic REST APIへの便利なアクセスを提供します。リクエストの作成にはビルダーパターンを使用し、同期操作と非同期操作の両方をサポートしています。

コード例を含むAPI機能のドキュメントについては、APIリファレンスを参照してください。このページでは、Java固有のSDK機能と設定について説明します。

インストール

要件

このライブラリにはJava 8以降が必要です。

SDKはJava 8以降をサポートしています。このドキュメントのコード例は、JDK 25のコンパクトソースファイルとして記述されており、エントリポイントとして単純なvoid main()を使用し、出力にはIO.println()を使用しています。API呼び出し自体はサポートされているすべてのJDKで同一です。以前のバージョンで例をコンパイルするには、IO.println(...)をSystem.out.println(...)に置き換え、本体をクラス内のpublic static void main(String[] args)の中に配置してください。

クイックスタート

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;

// `anthropic.apiKey`、`anthropic.authToken`、`anthropic.baseUrl` システムプロパティを使用して設定します
// または `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`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);

クライアント設定

APIキーのセットアップ

システムプロパティまたは環境変数を使用してクライアントを設定します。

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

// `anthropic.apiKey`、`anthropic.authToken`、`anthropic.baseUrl` システムプロパティを使用して設定します
// または `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL` 環境変数を使用して設定します
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

または手動で設定します。

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

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

または両方のアプローチを組み合わせて使用します。

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

AnthropicClient client = AnthropicOkHttpClient.builder()
  // システムプロパティまたは環境変数を使用して設定します
  .fromEnv()
  .apiKey("my-anthropic-api-key")
  .build();

Workload Identity Federationを含む認証オプションについては、認証を参照してください。

設定オプション

セッター	システムプロパティ	環境変数	必須	デフォルト値
`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"`

システムプロパティは環境変数よりも優先されます。

同じアプリケーション内で複数のクライアントを作成しないでください。各クライアントにはコネクションプールとスレッドプールがあり、これらはリクエスト間で共有する方が効率的です。

設定の変更

同じコネクションプールとスレッドプールを再利用しながら、一時的に変更されたクライアント設定を使用するには、任意のクライアントまたはサービスでwithOptions()を呼び出します。

import com.anthropic.client.AnthropicClient;

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

withOptions()メソッドは、元のクライアントやサービスには影響しません。

非同期の使用

デフォルトのクライアントは同期型です。非同期実行に切り替えるには、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);

または最初から非同期クライアントを作成します。

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);

非同期クライアントは同期クライアントと同じオプションをサポートしますが、ほとんどのメソッドがCompletableFutureを返す点が異なります。

ストリーミング

SDKは、レスポンスの「チャンク」ストリームを返すメソッドを定義しています。各チャンクは、完全なレスポンスを待つことなく、到着次第個別に処理できます。

同期ストリーミング

これらのストリーミングメソッドは、同期クライアントに対してStreamResponseを返します。

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!");
}

非同期ストリーミング

非同期クライアントの場合、メソッドはAsyncStreamResponseを返します。

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

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

// ストリームのエラーや完了を処理する必要がある場合
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!");
        }
    }
});

// または 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!");
        }
    });

非同期ストリーミングは、現在のスレッドをブロックせずにストリーミングするために、クライアントごとの専用キャッシュスレッドプールExecutorを使用します。別のExecutorを使用するには、次のようにします。

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

または、streamHandlerExecutorメソッドを使用してクライアントをグローバルに設定します。

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

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

メッセージアキュムレータを使用したストリーミング

MessageAccumulatorは、レスポンス内のイベントストリームが処理される際にそれらを記録し、非ストリーミングAPIが返すものと同様のMessageオブジェクトを蓄積できます。

同期レスポンスの場合、ストリームパイプラインにStream.peek()呼び出しを追加して各イベントを蓄積します。

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();

非同期レスポンスの場合、subscribe()呼び出しにMessageAccumulatorを追加します。

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();

BetaMessageオブジェクトの蓄積にはBetaMessageAccumulatorも利用できます。これはMessageAccumulatorと同じ方法で使用されます。

構造化出力

Javaの例を含む構造化出力の完全なドキュメントについては、構造化出力を参照してください。

ツール使用

Claudeでのツール使用により、外部ツールや関数をAIモデルのレスポンスに直接統合できます。プレーンテキストを生成する代わりに、モデルは適切な場合にツールや関数を呼び出すための指示（パラメータ付き）を出力できます。ツールのJSONスキーマを定義すると、モデルはそのスキーマを使用して、これらのツールをいつどのように使用するかを判断します。

ツール使用機能は「strict」モードをサポートしており、AIモデルからのJSON出力が入力パラメータで提供したJSONスキーマに準拠することを保証します。

SDKは、任意のJavaクラスの構造からツールとそのパラメータを自動的に導出できます。クラス名（スネークケースに変換されたもの）がツール名となり、クラスのフィールドがツールのパラメータを定義します。

ツールクラスはトップレベルクラスまたはstaticなネストクラスとして宣言してください。この要件は、SDKがツール入力をクラスインスタンスにデシリアライズするために使用するJackson Databindライブラリ（com.fasterxml.jackson.databind）に由来します。このライブラリは非staticな内部クラスをインスタンス化できません。

アノテーションによるツールの定義

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;
  }
}

ツールの呼び出し

ツールクラスを定義したら、MessageCreateParams.Builder.addTool(Class<T>)を使用してメッセージパラメータに追加し、AIモデルのレスポンスで要求された場合にそれらを呼び出します。BetaToolUseBlock.input(Class<T>)を使用して、JSON形式のツールパラメータをツール定義クラスのインスタンスにパースできます。

ツールを呼び出した後、BetaToolResultBlockParam.Builder.contentAsJson(Object)を使用してツールの結果をAIモデルに返します。

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
              // ツール使用がリクエストされたことを示すメッセージを追加します。
              .addAssistantMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder()
                              .name(toolUseBlock.name())
                              .id(toolUseBlock.id())
                              .input(toolUseBlock._input())
                              .build())))
              // リクエストされたツール使用の結果を含むメッセージを追加します。
              .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");
}

ツール名の変換

ツール名は、キャメルケースのツールクラス名（例：GetWeather）から導出され、スネークケース（例：get_weather）に変換されます。単語の境界は、現在の文字が最初の文字ではなく、大文字であり、かつ直前の文字が小文字であるか、直後の文字が小文字である場所から始まります。例えば、MyJSONParserはmy_json_parserになり、ParseJSONはparse_jsonになります。この変換は@JsonTypeNameアノテーションを使用してオーバーライドできます。

ツールJSONスキーマのローカル検証

ツールクラスから導出されたJSONスキーマがAnthropicの制約を遵守しているかどうかを確認するために、ローカル検証を実行できます。ローカル検証はデフォルトで有効ですが、無効にすることもできます。

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?");

ツールクラスへのアノテーション付与

アノテーションを使用して、JSONスキーマにツールに関する追加情報を付加できます。

@JsonClassDescription - ツールクラスに、そのツールをいつどのように使用するかを詳述する説明を追加します。
@JsonTypeName - ツール名を、スネークケースに変換されたクラスの単純名以外のものに設定します。
@JsonPropertyDescription - ツールパラメータに詳細な説明を追加します。
@JsonIgnore - ツールのパラメータ用に生成されるJSONスキーマからpublicフィールドまたはゲッターメソッドを除外します。
@JsonProperty - ツールのパラメータ用に生成されるJSONスキーマに非publicフィールドまたはゲッターメソッドを含めます。

メッセージバッチ

SDKは、client.messages().batches()名前空間の下でバッチ処理をサポートしています。バッチの一覧表示とページネーションの方法については、ページネーションを参照してください。

ファイルアップロード

SDKは、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);

または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);

またはメモリ内のバイトから：

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);

バイナリレスポンス

SDKは、必ずしもJSONとしてパースされないAPIレスポンスに対してバイナリレスポンスを返すメソッドを定義しています。

import com.anthropic.core.http.HttpResponse;

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

レスポンスの内容をファイルに保存するには：

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);
}

またはレスポンスの内容を任意の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);
}

エラー処理

SDKはカスタムの非チェック例外型をスローします。

AnthropicServiceException - HTTPエラーの基底クラス。
AnthropicIoException - I/Oネットワークエラー。
AnthropicRetryableException - 再試行可能な失敗を示す汎用エラー。
AnthropicInvalidDataException - 正常にパースされたデータの解釈に失敗した場合（例：必須であるはずのプロパティにアクセスしたが、APIが予期せずそれを省略した場合）。
AnthropicException - すべての例外の基底クラス。

ステータスコードのマッピング

ステータス	例外
400	`BadRequestException`
401	`UnauthorizedException`
403	`PermissionDeniedException`
404	`NotFoundException`
422	`UnprocessableEntityException`
429	`RateLimitException`
5xx	`InternalServerException`
その他	`UnexpectedStatusCodeException`

SseExceptionは、初期HTTPレスポンスが成功した後のSSEストリーミング中に発生したエラーに対してスローされます。

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());
}

リクエストID

生のレスポンスを使用する場合、requestId()メソッドを使用してrequest-idレスポンスヘッダーにアクセスできます。

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();

これは、失敗したリクエストを迅速にログに記録し、Anthropicに報告するために使用できます。リクエストのデバッグに関する詳細については、リクエストIDを参照してください。

再試行

SDKはデフォルトで自動的に2回再試行し、リクエスト間に短い指数バックオフを挟みます。

再試行されるのは以下のエラータイプのみです。

接続エラー（例：ネットワーク接続の問題による）
408 Request Timeout
409 Conflict
429 Rate Limit
5xx Internal

APIは、SDKにリクエストを再試行するかしないかを明示的に指示することもあります。

カスタムの再試行回数を設定するには、maxRetriesメソッドを使用してクライアントを設定します。

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

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

タイムアウト

リクエストはデフォルトで10分後にタイムアウトします。

ただし、maxTokensを受け入れるメソッドで、大きなmaxTokens値を指定してストリーミングしている場合、デフォルトのタイムアウトは次の式を使用して動的に計算されます。

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

これにより、オーバーライドされない限り、maxTokensパラメータによってスケーリングされた最大60分のタイムアウトになります。

非ストリーミングリクエストの場合、動的タイムアウトはmaxTokensに基づいて最小30秒から最大10分までスケーリングされます。

リクエストごとにカスタムタイムアウトを設定するには：

import com.anthropic.models.messages.Message;

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

またはクライアントレベルですべてのメソッド呼び出しのデフォルトを設定するには：

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

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

長時間のリクエスト

長時間実行されるリクエストにはストリーミングの使用を検討してください。

ストリーミングを使用せずに大きなmaxTokens値を設定することは避けてください。一部のネットワークでは、一定時間経過後にアイドル接続が切断されることがあり、Anthropicからのレスポンスを受信せずにリクエストが失敗したりタイムアウトしたりする可能性があります。SDKは定期的にAPIにpingを送信して接続を維持し、これらのネットワークの影響を軽減します。

非ストリーミングリクエストが10分以上かかると予想される場合、SDKはエラーをスローします。ストリーミングメソッドを使用するか、クライアントまたはリクエストレベルでタイムアウトをオーバーライドすると、このエラーは無効になります。

ページネーション

SDKは、ページネーションされた結果に一度に1ページずつ、またはすべてのページにわたって項目ごとにアクセスする便利な方法を提供します。

自動ページネーション

すべてのページにわたってすべての結果を反復処理するには、必要に応じて自動的に追加のページを取得するautoPager()メソッドを使用します。

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

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

// Iterableとして処理
for (MessageBatch batch : page.autoPager()) {
    IO.println(batch);
}

// Streamとして処理
page.autoPager()
    .stream()
    .limit(50)
    .forEach(batch -> IO.println(batch));

非同期クライアントを使用する場合、メソッドは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);
}));

// ストリームのエラーや完了を処理する必要がある場合
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!");
        }
    }
}));

// または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!");
        }
    }));

手動ページネーション

個々のページ項目にアクセスし、次のページを手動でリクエストするには：

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();
}

型システム

不変性とビルダー

SDKの各クラスには、それを構築するための関連ビルダーがあります。各クラスは構築後は不変です。クラスに関連ビルダーがある場合、toBuilder()メソッドがあり、これを使用して変更されたコピーを作成するためのビルダーに戻すことができます。

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

// toBuilder() を使用して変更されたコピーを作成
MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build();

各クラスは不変であるため、ビルダーの変更は既に構築されたクラスインスタンスには影響しません。

リクエストとレスポンス

Claude APIにリクエストを送信するには、何らかのParamsクラスのインスタンスを構築し、対応するクライアントメソッドに渡します。レスポンスを受信すると、Javaクラスのインスタンスにデシリアライズされます。

例えば、client.messages().create(...)はMessageCreateParamsのインスタンスで呼び出す必要があり、Messageのインスタンスを返します。

ドキュメント化されていないパラメータ

ドキュメント化されていないパラメータを設定するには、任意のParamsクラスでputAdditionalHeader、putAdditionalQueryParam、またはputAdditionalBodyPropertyメソッドを呼び出します。

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();

これらは、構築されたオブジェクトで後から_additionalHeaders()、_additionalQueryParams()、および_additionalBodyProperties()メソッドを使用してアクセスできます。

これらのメソッドに渡された値は、以前のメソッドに渡された値を上書きします。セキュリティ上の理由から、これらのメソッドは信頼できる入力データでのみ使用されるようにしてください。

ネストされたヘッダー、クエリパラメータ、またはボディクラスにドキュメント化されていないパラメータを設定するには：

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();

これらのプロパティは、ネストされた構築済みオブジェクトで後から_additionalProperties()メソッドを使用してアクセスできます。

ドキュメント化されたパラメータまたはプロパティを、ドキュメント化されていない値またはまだサポートされていない値に設定するには、そのセッターにJsonValueオブジェクトを渡します。

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();

JsonValueの作成

JsonValueを作成する最も簡単な方法は、そのfrom(...)メソッドを使用することです。

import com.anthropic.core.JsonValue;

// プリミティブなJSON値を作成します
JsonValue nullValue = JsonValue.from(null);

JsonValue booleanValue = JsonValue.from(true);

JsonValue numberValue = JsonValue.from(42);

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

// `["Hello", "World"]` と同等のJSON配列値を作成します
JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));

// `{ "a": 1, "b": 2 }` と同等のJSONオブジェクト値を作成します
JsonValue objectValue = JsonValue.from(Map.of("a", 1, "b", 2));

// 以下と同等の任意にネストされたJSONを作成します：
// { "a": [1, 2], "b": [3, 4] }
JsonValue complexValue = JsonValue.from(Map.of("a", List.of(1, 2), "b", List.of(3, 4)));

必須パラメータの強制的な省略

通常、Builderクラスのbuildメソッドは、必須パラメータまたはプロパティが未設定の場合にIllegalStateExceptionをスローします。必須パラメータまたはプロパティを強制的に省略するには、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();

レスポンスプロパティ

ドキュメント化されていないレスポンスプロパティにアクセスするには、_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!";
    }

    // 他のメソッドには `visitMissing`、`visitString`、`visitArray`、`visitObject` があります
    // 未実装の各メソッドのデフォルト実装は `visitDefault` に委譲します。
    // `visitDefault` はデフォルトで例外をスローしますが、オーバーライドすることも可能です
});

プロパティの生のJSON値にアクセスするには、_プレフィックス付きのメソッドを呼び出します。

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

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

if (stopReason.isMissing()) {
  // プロパティがJSONレスポンスに存在しません
} else if (stopReason.isNull()) {
  // プロパティがリテラルのnullに設定されていました
} else {
  // 値が文字列として提供されたかどうかを確認します
  // 他のメソッドには `asNumber()`、`asBoolean()` などがあります
  Optional<String> jsonString = stopReason.asString();

  // カスタム型へのデシリアライズを試みます
  MyClass myObject = stopReason.asUnknown().orElseThrow().convert(MyClass.class);
}

レスポンス検証

デフォルトでは、APIが期待される型と一致しないレスポンスを返した場合、SDKは例外をスローしません。プロパティに直接アクセスした場合にのみAnthropicInvalidDataExceptionをスローします。

レスポンスが完全に正しく型付けされていることを事前に確認するには、validate()を呼び出します。

import com.anthropic.models.messages.Message;

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

またはリクエストごとに設定します。

import com.anthropic.models.messages.Message;

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

またはクライアントレベルですべてのメソッド呼び出しのデフォルトを設定します。

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

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

HTTPクライアントのカスタマイズ

プロキシ設定

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();

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();

カスタムHTTPクライアント

SDKは3つのアーティファクトで構成されています。

anthropic-java-core - コアSDKロジックを含み、OkHttpに依存しません。AnthropicClient、AnthropicClientAsync、およびそれらの実装クラスを公開しており、これらはすべて任意のHTTPクライアントで動作します。
anthropic-java-client-okhttp - OkHttpに依存します。AnthropicOkHttpClientとAnthropicOkHttpClientAsyncを公開します。
anthropic-java - anthropic-java-coreとanthropic-java-client-okhttpの両方に依存し、それらのAPIを公開します。独自のロジックは持ちません。

この構造により、不要な依存関係を取り込むことなく、SDKのデフォルトHTTPクライアントを置き換えることができます。

カスタマイズされたOkHttpClient

デフォルトクライアントを置き換える前に、利用可能なネットワークオプションを試してください。

カスタマイズされたOkHttpClientを使用するには：

anthropic-java依存関係をanthropic-java-coreに置き換えます。
anthropic-java-client-okhttpのOkHttpClientクラスをコードにコピーしてカスタマイズします。
カスタマイズしたクライアントを使用してAnthropicClientImplまたはAnthropicClientAsyncImplを構築します。

完全にカスタムなHTTPクライアント

完全にカスタムなHTTPクライアントを使用するには：

anthropic-java依存関係をanthropic-java-coreに置き換えます。
HttpClientインターフェースを実装するクラスを作成します。
新しいクライアントクラスを使用してAnthropicClientImplまたはAnthropicClientAsyncImplを構築します。

プラットフォーム統合

コード例を含む詳細なプラットフォームセットアップガイドについては、以下を参照してください。

Java SDKは、プラットフォーム固有のBackend実装を提供する個別の依存関係を通じて、以下のプラットフォームをサポートしています。

Bedrock： com.anthropic:anthropic-java-bedrock：Messages-API BedrockエンドポイントにはBedrockMantleBackend.fromEnv()またはBedrockMantleBackend.builder()を使用し、bedrock-runtimeパスにはBedrockBackend.fromEnv() / BedrockBackend.builder()を使用します。
Vertex AI： com.anthropic:anthropic-java-vertex：VertexBackend.fromEnv()またはVertexBackend.builder()を使用します。
Foundry： com.anthropic:anthropic-java-foundry：FoundryBackend.fromEnv()またはFoundryBackend.builder()を使用します。
AWS上のClaude Platform： com.anthropic:anthropic-java-aws：AwsBackend.fromEnv()（ANTHROPIC_AWS_WORKSPACE_IDとAWSのデフォルトリージョン/認証情報チェーンを読み取ります）またはAwsBackend.builder()を使用します。ベータ版で利用可能です。

新規プロジェクトにはBedrockMantleBackendを使用してください。BedrockBackendは、BedrockのInvokeModel APIを使用している既存のアプリケーション向けに残されています。

各Backend実装は、AnthropicOkHttpClient.builder()の.backend()でクライアントに渡されます。各クラウドバックエンドは、それぞれのクラウドプラットフォームSDKクラスを推移的依存関係として取り込みます。

高度な使用方法

生のレスポンスへのアクセス

HTTPヘッダー、ステータスコード、および生のレスポンスボディにアクセスするには、任意のHTTPメソッド呼び出しの前に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();

必要に応じて、レスポンスをJavaクラスのインスタンスにデシリアライズすることもできます。

import com.anthropic.models.messages.Message;

Message parsedMessage = message.parse();

ロギング

SDKは標準のOkHttpロギングインターセプターを使用します。

ANTHROPIC_LOG環境変数をinfoに設定してロギングを有効にします。

export ANTHROPIC_LOG=info

またはより詳細なロギングにはdebugに設定します。

export ANTHROPIC_LOG=debug

ドキュメント化されていないAPI機能

SDKは、ドキュメント化されたAPIを便利に使用できるように型付けされています。ただし、ドキュメント化されていない、またはまだサポートされていないAPIの部分を扱うこともサポートしています。

ドキュメント化されていないリクエストパラメータ

ドキュメント化されていないリクエストパラメータを設定するには、ドキュメント化されていないパラメータで説明されているputAdditionalHeader、putAdditionalQueryParam、またはputAdditionalBodyPropertyメソッドを使用します。

ドキュメント化されていないレスポンスプロパティ

ドキュメント化されていないレスポンスプロパティにアクセスするには、レスポンスプロパティで説明されている_additionalProperties()メソッドを使用します。

新規または未リリースのenum値

ModelやAnthropicBetaなどのSDK内のenumライクなクラスは、閉じたJavaのenum型ではありません。それぞれが任意の文字列を受け入れるof(String)ファクトリメソッドを提供しているため、お使いのSDKバージョンの後にリリースされたモデルやベータヘッダーなど、まだ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");

これらの型を受け取るビルダーメソッドは、多くの場合、of(...)を呼び出すStringオーバーロードも提供しています。

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();

オートコンプリートと非推奨警告を得られるため、適切に型付けされた定数（例：Model.CLAUDE_OPUS_4_7）を優先してください。Stringオーバーロードとof(...)は、主にそれを含むSDKリリースを待つ間、フィールドをドキュメント化されていない値またはまだサポートされていない値に設定するためのものです。

ベータ機能

ベータ機能は、早期フィードバックを得て新機能をテストするために、一般リリース前に利用可能です。Claudeのすべての機能とツールの利用可能性は、Claudeで構築する概要で確認できます。

ほとんどのベータAPI機能には、クライアントのbeta()メソッドを通じてアクセスできます。特定のベータ機能を有効にするには、メッセージパラメータを構築する際に.addBeta()で適切なベータヘッダーを追加します。

例えば、Files APIを使用するには：

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());
}

よくある質問

セマンティックバージョニング

このパッケージは一般的にSemVerの規約に従いますが、特定の後方互換性のない変更がマイナーバージョンとしてリリースされる場合があります。

技術的にはパブリックであるが、外部使用を意図またはドキュメント化されていないライブラリ内部への変更。
実際には大多数のユーザーに影響を与えないと予想される変更。

追加リソース

Was this page helpful?

インストール

要件

クイックスタート

クライアント設定

APIキーのセットアップ

設定オプション

設定の変更

非同期の使用

ストリーミング

同期ストリーミング

非同期ストリーミング

メッセージアキュムレータを使用したストリーミング

構造化出力

ツール使用

アノテーションによるツールの定義

ツールの呼び出し

ツール名の変換

ツールJSONスキーマのローカル検証

ツールクラスへのアノテーション付与

メッセージバッチ

ファイルアップロード

バイナリレスポンス

エラー処理

ステータスコードのマッピング

リクエストID

再試行

タイムアウト

長時間のリクエスト

ページネーション

自動ページネーション

手動ページネーション

型システム

不変性とビルダー

リクエストとレスポンス

ドキュメント化されていないパラメータ

JsonValueの作成

必須パラメータの強制的な省略

レスポンスプロパティ

レスポンス検証

HTTPクライアントのカスタマイズ

プロキシ設定

HTTPS / SSL設定

カスタムHTTPクライアント

カスタマイズされたOkHttpClient

完全にカスタムなHTTPクライアント

プラットフォーム統合

高度な使用方法

生のレスポンスへのアクセス

ロギング

Jacksonの互換性

ProGuard/R8の設定

ドキュメント化されていないAPI機能

ドキュメント化されていないリクエストパラメータ

ドキュメント化されていないレスポンスプロパティ

新規または未リリースのenum値

ベータ機能

よくある質問

なぜSDKはプレーンなenumクラスを使用しないのですか？

なぜフィールドはプレーンなTではなくJsonField<T>を使用して表現されているのですか？

なぜSDKはデータクラスを使用しないのですか？

なぜSDKはチェック例外を使用しないのですか？

セマンティックバージョニング

追加リソース