Java SDK

Official Java client — build from GitHub Release v1.0.0.

On this page

Installation
Quickstart
caedral.chat().completions().create(request)
Streaming (Iterator)
Streaming (callback)
caedral.models().list()
caedral.usage().get()
caedral.embeddings().create(request)
caedral.images().generate(request)
caedral.audio().speech().create(request)
caedral.rerank().create(request)
Errors

Official Java client (builder pattern, Jackson POJOs, streaming). Prefer TypeScript, Python, Go, or n8n when a package registry install is enough; use Java when you need a first-party JVM client.

#Installation

shell

1git clone https://github.com/trycaedral/caedral-java.git2cd caedral-java3git checkout v1.0.04mvn clean install

#Quickstart

Main.javajava

1import com.caedral.sdk.Caedral;2import com.caedral.sdk.model.ChatCompletionRequest;3import com.caedral.sdk.model.ChatMessage;4import java.util.List;5 6Caedral caedral = Caedral.builder()7    .apiKey("cd_live_...")8    .baseUrl("http://localhost:5001")9    .build();10 11var completion = caedral.chat().completions().create(12    new ChatCompletionRequest(13        "anthropic/claude-haiku-4.5",14        List.of(new ChatMessage("user", "Hello!"))15    )16);17 18System.out.println(completion.getChoices().get(0).getMessage().get("content"));

Repository and releases: https://github.com/trycaedral/caedral-java

Builder method	Default	Description
apiKey(String)	required	API key (cd_live_...)
baseUrl(String)	https://api.caedral.com	Gateway base URL
timeout(Duration)	120s	HTTP timeout
maxRetries(int)	3	Retries for idempotent GET
httpClient(OkHttpClient)	built-in	Custom OkHttp client
objectMapper(ObjectMapper)	built-in	Custom Jackson mapper

#caedral.chat().completions().create(request)

java

1ChatCompletion completion = caedral.chat().completions().create(request);

#Streaming (Iterator)

java

1try (ChatCompletionStream stream = caedral.chat().completions().createStream(request)) {2    while (stream.hasNext()) {3        var chunk = stream.next();4// handle chunk5    }6}

#Streaming (callback)

java

1caedral.chat().completions().createStream(request, chunk -> {2    System.out.print(chunk.getChoices().get(0).getDelta().get("content"));3});

#caedral.models().list()

java

1ModelListResponse models = caedral.models().list();

#caedral.usage().get()

java

1UsageSummary usage = caedral.usage().get();2System.out.println(usage.getAccountStatus());3// pools.caedral / pools.external carry usedMilli, limitMilli and percentUsed

#caedral.embeddings().create(request)

java

1caedral.embeddings().create(2    new EmbeddingCreateRequest("caedral-embed", "Hello world")3);

#caedral.images().generate(request)

java

1caedral.images().generate(2    new ImageGenerateRequest("A minimal logo on dark, dark background")3);

#caedral.audio().speech().create(request)

java

1AudioGenerateRequest req = new AudioGenerateRequest("Welcome to Caedral.");2req.setModel("caedral-voice-1");3req.setVoice("caedral-f1");4req.setSpeed(1.0);5SpeechAudio audio = caedral.audio().speech().create(req);6Files.write(Path.of("welcome.wav"), audio.getBytes());

#caedral.rerank().create(request)

java

1RerankCreateRequest req = new RerankCreateRequest(2    "billing",3    List.of("Caedral pricing", "Gateway port 5001")4);5req.setTopN(2);6caedral.rerank().create(req);

#Errors

java

1try {2    caedral.chat().completions().create(request);3} catch (CaedralAPIException ex) {4    System.err.printf("status=%d type=%s msg=%s%n",5        ex.getStatusCode(), ex.getType(), ex.getMessage());6}

#Quickstart

Main.javajava

1import com.caedral.sdk.Caedral;2import com.caedral.sdk.model.ChatCompletionRequest;3import com.caedral.sdk.model.ChatMessage;4import java.util.List;5 6Caedral caedral = Caedral.builder()7    .apiKey("cd_live_...")8    .baseUrl("http://localhost:5001")9    .build();10 11var completion = caedral.chat().completions().create(12    new ChatCompletionRequest(13        "anthropic/claude-haiku-4.5",14        List.of(new ChatMessage("user", "Hello!"))15    )16);17 18System.out.println(completion.getChoices().get(0).getMessage().get("content"));

Repository and releases: https://github.com/trycaedral/caedral-java

Builder method	Default	Description
apiKey(String)	required	API key (cd_live_...)
baseUrl(String)	https://api.caedral.com	Gateway base URL
timeout(Duration)	120s	HTTP timeout
maxRetries(int)	3	Retries for idempotent GET
httpClient(OkHttpClient)	built-in	Custom OkHttp client
objectMapper(ObjectMapper)	built-in	Custom Jackson mapper

#caedral.chat().completions().create(request)

java

1ChatCompletion completion = caedral.chat().completions().create(request);

#Streaming (Iterator)

java

1try (ChatCompletionStream stream = caedral.chat().completions().createStream(request)) {2    while (stream.hasNext()) {3        var chunk = stream.next();4// handle chunk5    }6}

#Streaming (callback)

java

1caedral.chat().completions().createStream(request, chunk -> {2    System.out.print(chunk.getChoices().get(0).getDelta().get("content"));3});

1AudioGenerateRequest req = new AudioGenerateRequest("Welcome to Caedral.");2req.setModel("caedral-voice-1");3req.setVoice("caedral-f1");4req.setSpeed(1.0);5SpeechAudio audio = caedral.audio().speech().create(req);6Files.write(Path.of("welcome.wav"), audio.getBytes());

1try {2 caedral.chat().completions().create(request);3} catch (CaedralAPIException ex) {4 System.err.printf("status=%d type=%s msg=%s%n",5 ex.getStatusCode(), ex.getType(), ex.getMessage());6}