Java SDK

Anthropic Java SDK menyediakan akses yang mudah ke Anthropic REST API dari aplikasi yang ditulis dalam Java. SDK ini menggunakan pola "builder" (pembangun) untuk membuat permintaan dan mendukung operasi sinkron maupun asinkron.

Untuk dokumentasi fitur API dengan contoh kode, lihat referensi API. Halaman ini membahas fitur dan konfigurasi SDK yang spesifik untuk Java.

Instalasi

Persyaratan

Library ini memerlukan Java 8 atau yang lebih baru.

SDK ini mendukung Java 8 dan yang lebih baru. Contoh kode dalam dokumentasi ini ditulis sebagai file sumber ringkas JDK 25, menggunakan titik masuk void main() sederhana dan IO.println() untuk output. Pemanggilan API itu sendiri identik pada setiap JDK yang didukung; untuk mengompilasi contoh pada versi yang lebih lama, ganti IO.println(...) dengan System.out.println(...) dan tempatkan isinya di dalam public static void main(String[] args) dalam sebuah kelas.

Mulai cepat

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;

// Mengonfigurasi menggunakan properti sistem `anthropic.apiKey`, `anthropic.authToken`, dan `anthropic.baseUrl`
// Atau mengonfigurasi menggunakan variabel lingkungan `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, dan `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);

Konfigurasi klien

Pengaturan kunci API

Konfigurasikan klien menggunakan properti sistem atau variabel lingkungan:

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

// Mengonfigurasi menggunakan properti sistem `anthropic.apiKey`, `anthropic.authToken`, dan `anthropic.baseUrl`
// Atau mengonfigurasi menggunakan variabel lingkungan `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, dan `ANTHROPIC_BASE_URL`
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

Atau konfigurasikan secara manual:

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

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

Atau gunakan kombinasi kedua pendekatan:

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

AnthropicClient client = AnthropicOkHttpClient.builder()
  // Mengonfigurasi menggunakan properti sistem atau variabel lingkungan
  .fromEnv()
  .apiKey("my-anthropic-api-key")
  .build();

Untuk opsi autentikasi termasuk Workload Identity Federation, lihat Autentikasi.

Opsi konfigurasi

Setter	Properti sistem	Variabel lingkungan	Wajib	Nilai default
`apiKey`	`anthropic.apiKey`	`ANTHROPIC_API_KEY`	false	-
`authToken`	`anthropic.authToken`	`ANTHROPIC_AUTH_TOKEN`	false	-
`baseUrl`	`anthropic.baseUrl`	`ANTHROPIC_BASE_URL`	true

Properti sistem memiliki prioritas lebih tinggi daripada variabel lingkungan.

Jangan membuat lebih dari satu klien dalam aplikasi yang sama. Setiap klien memiliki connection pool dan thread pool, yang lebih efisien jika dibagikan antar permintaan.

Memodifikasi konfigurasi

Untuk menggunakan konfigurasi klien yang dimodifikasi secara sementara sambil tetap menggunakan kembali connection pool dan thread pool yang sama, panggil withOptions() pada klien atau layanan mana pun:

import com.anthropic.client.AnthropicClient;

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

Metode withOptions() tidak memengaruhi klien atau layanan asli.

Penggunaan async

Klien default bersifat sinkron. Untuk beralih ke eksekusi asinkron, panggil metode 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);

Atau buat klien asinkron sejak awal:

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

Klien asinkron mendukung opsi yang sama dengan klien sinkron, kecuali sebagian besar metode mengembalikan CompletableFuture.

Streaming

SDK mendefinisikan metode yang mengembalikan stream "chunk" (potongan) respons, di mana setiap chunk dapat diproses secara individual segera setelah tiba alih-alih menunggu respons lengkap.

Streaming sinkron

Metode streaming ini mengembalikan StreamResponse untuk klien sinkron:

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 asinkron

Untuk klien asinkron, metode ini mengembalikan AsyncStreamResponse:

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

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

// Jika Anda perlu menangani error atau penyelesaian 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!");
        }
    }
});

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

Streaming async menggunakan Executor thread pool cache khusus per-klien untuk melakukan streaming tanpa memblokir thread saat ini. Untuk menggunakan Executor yang berbeda:

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

Atau konfigurasikan klien secara global menggunakan metode streamHandlerExecutor:

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

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

Streaming dengan akumulator pesan

MessageAccumulator dapat merekam stream event dalam respons saat diproses dan mengakumulasikan objek Message yang serupa dengan apa yang akan dikembalikan oleh API non-streaming.

Untuk respons sinkron, tambahkan pemanggilan Stream.peek() ke pipeline stream untuk mengakumulasikan setiap event:

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

Untuk respons asinkron, tambahkan MessageAccumulator ke pemanggilan 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();

BetaMessageAccumulator juga tersedia untuk akumulasi objek BetaMessage. Ini digunakan dengan cara yang sama seperti MessageAccumulator.

Output terstruktur

Untuk dokumentasi lengkap tentang output terstruktur termasuk contoh Java, lihat Output terstruktur.

Penggunaan alat

Penggunaan alat dengan Claude memungkinkan Anda mengintegrasikan alat dan fungsi eksternal langsung ke dalam respons model AI. Alih-alih menghasilkan teks biasa, model dapat menghasilkan instruksi (dengan parameter) untuk memanggil alat atau fungsi ketika sesuai. Anda mendefinisikan skema JSON untuk alat, dan model menggunakan skema tersebut untuk menentukan kapan dan bagaimana menggunakan alat-alat ini.

Fitur penggunaan alat mendukung mode "strict" yang menjamin bahwa output JSON dari model AI akan sesuai dengan skema JSON yang Anda berikan dalam parameter input.

SDK dapat menurunkan alat dan parameternya secara otomatis dari struktur kelas Java arbitrer: nama kelas (dikonversi ke snake case) menyediakan nama alat, dan field kelas mendefinisikan parameter alat.

Deklarasikan kelas alat Anda sebagai kelas tingkat atas atau kelas bersarang static. Persyaratan ini berasal dari library Jackson Databind (com.fasterxml.jackson.databind), yang digunakan SDK untuk mendeserialisasi input alat ke dalam instance kelas Anda dan tidak dapat menginstansiasi kelas dalam non-static.

Mendefinisikan alat dengan anotasi

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

Memanggil alat

Ketika kelas alat Anda telah didefinisikan, tambahkan ke parameter pesan menggunakan MessageCreateParams.Builder.addTool(Class<T>) lalu panggil jika diminta dalam respons model AI. BetaToolUseBlock.input(Class<T>) dapat digunakan untuk mem-parse parameter alat dalam bentuk JSON menjadi instance dari kelas pendefinisi alat Anda.

Setelah memanggil alat, gunakan BetaToolResultBlockParam.Builder.contentAsJson(Object) untuk meneruskan hasil alat kembali ke model 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
              // Tambahkan pesan yang menunjukkan bahwa penggunaan alat diminta.
              .addAssistantMessageOfBetaContentBlockParams(
                      List.of(BetaContentBlockParam.ofToolUse(BetaToolUseBlockParam.builder()
                              .name(toolUseBlock.name())
                              .id(toolUseBlock.id())
                              .input(toolUseBlock._input())
                              .build())))
              // Tambahkan pesan dengan hasil dari penggunaan alat yang diminta.
              .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");
}

Konversi nama alat

Nama alat diturunkan dari nama kelas alat dalam camel case (misalnya, GetWeather) dan dikonversi ke snake case (misalnya, get_weather). Batas kata dimulai ketika karakter saat ini bukan karakter pertama, berupa huruf kapital, dan karakter sebelumnya adalah huruf kecil, atau karakter berikutnya adalah huruf kecil. Misalnya, MyJSONParser menjadi my_json_parser dan ParseJSON menjadi parse_json. Konversi ini dapat ditimpa menggunakan anotasi @JsonTypeName.

Validasi skema JSON alat secara lokal

Anda dapat melakukan validasi lokal untuk memeriksa bahwa skema JSON yang diturunkan dari kelas alat Anda mematuhi batasan Anthropic. Validasi lokal diaktifkan secara default, tetapi dapat dinonaktifkan:

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

Menganotasi kelas alat

Anda dapat menggunakan anotasi untuk menambahkan informasi lebih lanjut tentang alat ke skema JSON:

@JsonClassDescription - Menambahkan deskripsi ke kelas alat yang merinci kapan dan bagaimana menggunakan alat tersebut.
@JsonTypeName - Mengatur nama alat menjadi sesuatu selain nama sederhana kelas yang dikonversi ke snake case.
@JsonPropertyDescription - Menambahkan deskripsi terperinci ke parameter alat.
@JsonIgnore - Mengecualikan field public atau metode getter dari skema JSON yang dihasilkan untuk parameter alat.
@JsonProperty - Menyertakan field non-public atau metode getter dalam skema JSON yang dihasilkan untuk parameter alat.

Batch pesan

SDK menyediakan dukungan untuk Pemrosesan batch di bawah namespace client.messages().batches(). Lihat Paginasi untuk cara membuat daftar dan melakukan paginasi melalui batch.

Unggahan file

SDK mendefinisikan metode yang menerima file melalui kelas 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);

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

Atau dari byte dalam memori:

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

Respons biner

SDK mendefinisikan metode yang mengembalikan respons biner untuk respons API yang tidak selalu di-parse sebagai JSON:

import com.anthropic.core.http.HttpResponse;

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

Untuk menyimpan konten respons ke file:

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

Atau mentransfer konten respons ke OutputStream mana pun:

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

Penanganan error

SDK melempar tipe exception unchecked kustom:

AnthropicServiceException - Kelas dasar untuk error HTTP.
AnthropicIoException - Error jaringan I/O.
AnthropicRetryableException - Error generik yang menunjukkan kegagalan yang dapat dicoba ulang.
AnthropicInvalidDataException - Kegagalan menginterpretasikan data yang berhasil di-parse (misalnya, saat mengakses properti yang seharusnya wajib, tetapi API secara tak terduga menghilangkannya).
AnthropicException - Kelas dasar untuk semua exception.

Pemetaan kode status

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

SseException dilempar untuk error yang ditemui selama streaming SSE setelah respons HTTP awal yang berhasil.

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 Permintaan

Saat menggunakan respons mentah, Anda dapat mengakses header respons request-id menggunakan metode 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();

Ini dapat digunakan untuk mencatat permintaan yang gagal dengan cepat dan melaporkannya kembali ke Anthropic. Untuk informasi lebih lanjut tentang debugging permintaan, lihat ID Permintaan.

Percobaan ulang

SDK secara otomatis mencoba ulang 2 kali secara default, dengan exponential backoff singkat di antara permintaan.

Hanya tipe error berikut yang dicoba ulang:

Error koneksi (misalnya, karena masalah konektivitas jaringan)
408 Request Timeout
409 Conflict
429 Rate Limit
5xx Internal

API juga dapat secara eksplisit menginstruksikan SDK untuk mencoba ulang atau tidak mencoba ulang suatu permintaan.

Untuk mengatur jumlah percobaan ulang kustom, konfigurasikan klien menggunakan metode maxRetries:

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

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

Timeout

Permintaan mengalami timeout setelah 10 menit secara default.

Namun, untuk metode yang menerima maxTokens, jika Anda menentukan nilai maxTokens yang besar dan menggunakan streaming, maka timeout default akan dihitung secara dinamis menggunakan rumus ini:

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

Ini menghasilkan timeout hingga 60 menit, diskalakan oleh parameter maxTokens, kecuali ditimpa.

Untuk permintaan non-streaming, timeout dinamis diskalakan dari minimum 30 detik hingga maksimum 10 menit berdasarkan maxTokens.

Untuk mengatur timeout kustom per-permintaan:

import com.anthropic.models.messages.Message;

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

Atau konfigurasikan default untuk semua pemanggilan metode di tingkat klien:

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

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

Permintaan panjang

Pertimbangkan untuk menggunakan streaming untuk permintaan yang berjalan lebih lama.

Hindari mengatur nilai maxTokens yang besar tanpa menggunakan streaming. Beberapa jaringan mungkin memutus koneksi idle setelah periode waktu tertentu, yang dapat menyebabkan permintaan gagal atau timeout tanpa menerima respons dari Anthropic. SDK secara berkala melakukan ping ke API untuk menjaga koneksi tetap aktif dan mengurangi dampak dari jaringan tersebut.

SDK melempar error jika permintaan non-streaming diperkirakan memakan waktu lebih dari 10 menit. Menggunakan metode streaming atau menimpa timeout di tingkat klien atau permintaan akan menonaktifkan error tersebut.

Paginasi

SDK menyediakan cara yang mudah untuk mengakses hasil yang dipaginasi baik satu halaman pada satu waktu atau item demi item di seluruh halaman.

Paginasi otomatis

Untuk melakukan iterasi melalui semua hasil di seluruh halaman, gunakan metode autoPager(), yang secara otomatis mengambil lebih banyak halaman sesuai kebutuhan.

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

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

// Proses sebagai Iterable
for (MessageBatch batch : page.autoPager()) {
    IO.println(batch);
}

// Proses sebagai Stream
page.autoPager()
    .stream()
    .limit(50)
    .forEach(batch -> IO.println(batch));

Saat menggunakan klien asinkron, metode ini mengembalikan 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);
}));

// Jika Anda perlu menangani error atau penyelesaian 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!");
        }
    }
}));

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

Paginasi manual

Untuk mengakses item halaman individual dan meminta halaman berikutnya secara manual:

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

Sistem tipe

Immutability dan builder

Setiap kelas dalam SDK memiliki builder terkait untuk mengonstruksinya. Setiap kelas bersifat immutable setelah dikonstruksi. Jika kelas memiliki builder terkait, maka kelas tersebut memiliki metode toBuilder(), yang dapat digunakan untuk mengonversinya kembali ke builder untuk membuat salinan yang dimodifikasi.

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

// Buat salinan yang dimodifikasi menggunakan toBuilder()
MessageCreateParams modified = params.toBuilder().maxTokens(2048L).build();

Karena setiap kelas bersifat immutable, modifikasi builder tidak akan pernah memengaruhi instance kelas yang sudah dibangun.

Permintaan dan respons

Untuk mengirim permintaan ke Claude API, bangun instance dari suatu kelas Params dan teruskan ke metode klien yang sesuai. Ketika respons diterima, respons tersebut dideserialisasi menjadi instance dari kelas Java.

Misalnya, client.messages().create(...) harus dipanggil dengan instance dari MessageCreateParams, dan akan mengembalikan instance dari Message.

Parameter tidak terdokumentasi

Untuk mengatur parameter yang tidak terdokumentasi, panggil metode putAdditionalHeader, putAdditionalQueryParam, atau putAdditionalBodyProperty pada kelas Params mana pun:

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

Ini dapat diakses pada objek yang telah dibangun nanti menggunakan metode _additionalHeaders(), _additionalQueryParams(), dan _additionalBodyProperties().

Nilai yang diteruskan ke metode ini menimpa nilai yang diteruskan ke metode sebelumnya. Untuk alasan keamanan, pastikan metode ini hanya digunakan dengan data input yang tepercaya.

Untuk mengatur parameter yang tidak terdokumentasi pada header bersarang, query param, atau kelas body:

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

Properti ini dapat diakses pada objek bersarang yang telah dibangun nanti menggunakan metode _additionalProperties().

Untuk mengatur parameter atau properti yang terdokumentasi ke nilai yang tidak terdokumentasi atau belum didukung, teruskan objek JsonValue ke setter-nya:

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

Pembuatan JsonValue

Cara paling mudah untuk membuat JsonValue adalah menggunakan metode from(...):

import com.anthropic.core.JsonValue;

// Buat nilai JSON primitif
JsonValue nullValue = JsonValue.from(null);

JsonValue booleanValue = JsonValue.from(true);

JsonValue numberValue = JsonValue.from(42);

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

// Buat nilai array JSON yang setara dengan `["Hello", "World"]`
JsonValue arrayValue = JsonValue.from(List.of("Hello", "World"));

// Buat nilai objek JSON yang setara dengan `{ "a": 1, "b": 2 }`
JsonValue objectValue = JsonValue.from(Map.of("a", 1, "b", 2));

// Buat JSON bersarang secara arbitrer yang setara dengan:
// { "a": [1, 2], "b": [3, 4] }
JsonValue complexValue = JsonValue.from(Map.of("a", List.of(1, 2), "b", List.of(3, 4)));

Menghilangkan parameter wajib secara paksa

Biasanya metode build dari kelas Builder akan melempar IllegalStateException jika ada parameter atau properti wajib yang belum diatur. Untuk menghilangkan parameter atau properti wajib secara paksa, teruskan 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();

Properti respons

Untuk mengakses properti respons yang tidak terdokumentasi, panggil metode _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!";
    }

    // Metode lainnya mencakup `visitMissing`, `visitString`, `visitArray`, dan `visitObject`
    // Implementasi default dari setiap metode yang tidak diimplementasikan akan didelegasikan ke `visitDefault`,
    // yang secara default melempar exception, tetapi juga dapat di-override
});

Untuk mengakses nilai JSON mentah dari suatu properti, panggil metodenya yang berawalan _:

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

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

if (stopReason.isMissing()) {
  // Properti tidak ada dalam respons JSON
} else if (stopReason.isNull()) {
  // Properti disetel ke null literal
} else {
  // Periksa apakah nilai diberikan sebagai string
  // Metode lain termasuk `asNumber()`, `asBoolean()`, dll.
  Optional<String> jsonString = stopReason.asString();

  // Coba deserialisasi menjadi tipe kustom
  MyClass myObject = stopReason.asUnknown().orElseThrow().convert(MyClass.class);
}

Validasi respons

Secara default, SDK tidak melempar exception ketika API mengembalikan respons yang tidak cocok dengan tipe yang diharapkan. SDK melempar AnthropicInvalidDataException hanya jika Anda mengakses properti secara langsung.

Untuk memeriksa bahwa respons sepenuhnya bertipe dengan baik di awal, panggil validate():

import com.anthropic.models.messages.Message;

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

Atau konfigurasikan per-permintaan:

import com.anthropic.models.messages.Message;

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

Atau konfigurasikan default untuk semua pemanggilan metode di tingkat klien:

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

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

Kustomisasi klien HTTP

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

Konfigurasi HTTPS / SSL

Sebagian besar aplikasi tidak perlu memanggil metode ini, dan sebaiknya menggunakan default sistem. Default tersebut mencakup optimasi khusus yang dapat hilang jika implementasinya dimodifikasi.

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

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

Klien HTTP kustom

SDK terdiri dari tiga artefak:

anthropic-java-core - Berisi logika inti SDK, tidak bergantung pada OkHttp. Mengekspos AnthropicClient, AnthropicClientAsync, dan kelas implementasinya, yang semuanya dapat bekerja dengan klien HTTP apa pun.
anthropic-java-client-okhttp - Bergantung pada OkHttp. Mengekspos AnthropicOkHttpClient dan AnthropicOkHttpClientAsync.
anthropic-java - Bergantung pada dan mengekspos API dari anthropic-java-core dan anthropic-java-client-okhttp. Tidak memiliki logika sendiri.

Struktur ini memungkinkan penggantian klien HTTP default SDK tanpa menarik dependensi yang tidak perlu.

OkHttpClient yang dikustomisasi

Coba opsi jaringan yang tersedia sebelum mengganti klien default.

Untuk menggunakan OkHttpClient yang dikustomisasi:

Ganti dependensi anthropic-java Anda dengan anthropic-java-core.
Salin kelas OkHttpClient dari anthropic-java-client-okhttp ke dalam kode Anda dan kustomisasi.
Konstruksi AnthropicClientImpl atau AnthropicClientAsyncImpl menggunakan klien yang telah Anda kustomisasi.

Klien HTTP yang sepenuhnya kustom

Untuk menggunakan klien HTTP yang sepenuhnya kustom:

Ganti dependensi anthropic-java Anda dengan anthropic-java-core.
Tulis kelas yang mengimplementasikan antarmuka HttpClient.
Konstruksi AnthropicClientImpl atau AnthropicClientAsyncImpl menggunakan kelas klien baru Anda.

Integrasi platform

Untuk panduan pengaturan platform terperinci dengan contoh kode, lihat:

Java SDK mendukung platform berikut melalui dependensi terpisah yang menyediakan implementasi Backend spesifik platform:

Bedrock: com.anthropic:anthropic-java-bedrock: Gunakan BedrockMantleBackend.fromEnv() atau BedrockMantleBackend.builder() untuk endpoint Bedrock Messages-API, atau BedrockBackend.fromEnv() / BedrockBackend.builder() (jalur bedrock-runtime).
Vertex AI: com.anthropic:anthropic-java-vertex: Gunakan VertexBackend.fromEnv() atau VertexBackend.builder().
Foundry: com.anthropic:anthropic-java-foundry: Gunakan FoundryBackend.fromEnv() atau FoundryBackend.builder().
Claude Platform di AWS: com.anthropic:anthropic-java-aws: Gunakan (membaca dan rantai region/kredensial default AWS) atau . Tersedia dalam beta.

Gunakan BedrockMantleBackend untuk proyek baru; BedrockBackend tetap tersedia untuk aplikasi yang sudah ada yang menggunakan API InvokeModel Bedrock.

Setiap implementasi Backend diteruskan ke klien dengan .backend() pada AnthropicOkHttpClient.builder(). Setiap backend cloud menarik kelas SDK platform cloud masing-masing sebagai dependensi transitif.

Penggunaan lanjutan

Akses respons mentah

Untuk mengakses header HTTP, kode status, dan body respons mentah, awali pemanggilan metode HTTP apa pun dengan 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();

Anda masih dapat mendeserialisasi respons menjadi instance dari kelas Java jika diperlukan:

import com.anthropic.models.messages.Message;

Message parsedMessage = message.parse();

Logging

SDK menggunakan logging interceptor standar OkHttp.

Aktifkan logging dengan mengatur variabel lingkungan ANTHROPIC_LOG ke info:

export ANTHROPIC_LOG=info

Atau ke debug untuk logging yang lebih verbose:

export ANTHROPIC_LOG=debug

Fungsionalitas API yang tidak terdokumentasi

SDK diberi tipe untuk penggunaan yang mudah dari API yang terdokumentasi. Namun, SDK juga mendukung bekerja dengan bagian API yang tidak terdokumentasi atau belum didukung.

Parameter permintaan yang tidak terdokumentasi

Untuk mengatur parameter permintaan yang tidak terdokumentasi, gunakan metode putAdditionalHeader, putAdditionalQueryParam, atau putAdditionalBodyProperty seperti yang dijelaskan dalam Parameter tidak terdokumentasi.

Properti respons yang tidak terdokumentasi

Untuk mengakses properti respons yang tidak terdokumentasi, gunakan metode _additionalProperties() seperti yang dijelaskan dalam Properti respons.

Nilai enum baru atau belum dirilis

Kelas mirip enum dalam SDK, seperti Model dan AnthropicBeta, bukan tipe enum Java tertutup. Masing-masing menyediakan metode factory of(String) yang menerima string apa pun, sehingga Anda dapat menggunakan nilai yang belum ditambahkan ke SDK, seperti model atau header beta yang dirilis setelah versi SDK Anda:

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

Metode builder yang menerima tipe ini sering kali juga menyediakan overload String yang memanggil of(...) untuk Anda:

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

Utamakan konstanta bertipe baik (misalnya, Model.CLAUDE_OPUS_4_7) agar Anda mendapatkan autocomplete dan peringatan deprecation. Overload String dan of(...) terutama untuk mengatur field ke nilai yang tidak terdokumentasi atau belum didukung sambil menunggu rilis SDK yang menyertakannya.

Fitur beta

Fitur beta tersedia sebelum rilis umum untuk mendapatkan umpan balik awal dan menguji fungsionalitas baru. Anda dapat memeriksa ketersediaan semua kemampuan dan alat Claude di ikhtisar membangun dengan Claude.

Anda dapat mengakses sebagian besar fitur API beta melalui metode beta() pada klien. Untuk mengaktifkan fitur beta tertentu, tambahkan header beta yang sesuai dengan .addBeta() saat membangun parameter pesan.

Misalnya, untuk menggunakan 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());
}

Pertanyaan yang sering diajukan

Semantic versioning

Paket ini secara umum mengikuti konvensi SemVer, meskipun perubahan tertentu yang tidak kompatibel ke belakang dapat dirilis sebagai versi minor:

Perubahan pada internal library yang secara teknis publik tetapi tidak dimaksudkan atau didokumentasikan untuk penggunaan eksternal.
Perubahan yang tidak diharapkan memengaruhi sebagian besar pengguna dalam praktiknya.

Sumber daya tambahan

AwsBackend.fromEnv()

ANTHROPIC_AWS_WORKSPACE_ID

AwsBackend.builder()

Instalasi

Persyaratan

Mulai cepat

Konfigurasi klien

Pengaturan kunci API

Opsi konfigurasi

Memodifikasi konfigurasi

Penggunaan async

Streaming

Streaming sinkron

Streaming asinkron

Streaming dengan akumulator pesan

Output terstruktur

Penggunaan alat

Mendefinisikan alat dengan anotasi

Memanggil alat

Konversi nama alat

Validasi skema JSON alat secara lokal

Menganotasi kelas alat

Batch pesan

Unggahan file

Respons biner

Penanganan error

Pemetaan kode status

ID Permintaan

Percobaan ulang

Timeout

Permintaan panjang

Paginasi

Paginasi otomatis

Paginasi manual

Sistem tipe

Immutability dan builder

Permintaan dan respons

Parameter tidak terdokumentasi

Pembuatan JsonValue

Menghilangkan parameter wajib secara paksa

Properti respons

Validasi respons

Kustomisasi klien HTTP

Konfigurasi proxy

Konfigurasi HTTPS / SSL

Klien HTTP kustom

OkHttpClient yang dikustomisasi

Klien HTTP yang sepenuhnya kustom

Integrasi platform

Penggunaan lanjutan

Akses respons mentah

Logging

Kompatibilitas Jackson

Konfigurasi ProGuard/R8

Fungsionalitas API yang tidak terdokumentasi

Parameter permintaan yang tidak terdokumentasi

Properti respons yang tidak terdokumentasi

Nilai enum baru atau belum dirilis

Fitur beta

Pertanyaan yang sering diajukan

Mengapa SDK tidak menggunakan kelas enum biasa?

Mengapa field direpresentasikan menggunakan JsonField<T> alih-alih hanya T biasa?

Mengapa SDK tidak menggunakan data class?

Mengapa SDK tidak menggunakan checked exception?

Semantic versioning

Sumber daya tambahan