Joule Cloud docs

SDK quickstart: Java

OpenAI's official Java SDK works against our endpoint. Maven & Gradle below.

Dependency

<!-- Maven -->
<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>LATEST</version>
</dependency>
// Gradle (Kotlin DSL)
implementation("com.openai:openai-java:LATEST")

Hello world

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatCompletion;
import com.openai.models.ChatCompletionCreateParams;
import com.openai.models.ChatCompletionUserMessageParam;

public class Hello {
  public static void main(String[] args) {
    OpenAIClient client = OpenAIOkHttpClient.builder()
      .baseUrl("https://api.greenjoules.cloud/v1")
      .apiKey(System.getenv("JC_API_KEY"))
      .build();

    ChatCompletion r = client.chat().completions().create(
      ChatCompletionCreateParams.builder()
        .model("auto")
        .addMessage(ChatCompletionUserMessageParam.builder().content("hi").build())
        .build()
    );
    System.out.println(r.choices().get(0).message().content().orElse(""));
  }
}

Streaming

import com.openai.core.http.StreamResponse;
import com.openai.models.ChatCompletionChunk;

try (StreamResponse<ChatCompletionChunk> stream =
       client.chat().completions().createStreaming(params)) {
  stream.stream().forEach(chunk -> {
    chunk.choices().stream()
      .map(c -> c.delta().content().orElse(""))
      .forEach(System.out::print);
  });
}

Embeddings + tool use

import com.openai.models.EmbeddingCreateParams;
import com.openai.models.embeddings.CreateEmbeddingResponse;

CreateEmbeddingResponse e = client.embeddings().create(
  EmbeddingCreateParams.builder()
    .model("text-embedding-3-small")
    .input(EmbeddingCreateParams.Input.ofArrayOfStrings(List.of("a", "b")))
    .build()
);

// tools: ChatCompletionTool + ChatCompletionFunctionTool — see SDK docs

Joule headers

The official SDK does not currently expose raw response headers in its high-level API. Two options:

  1. Drop down to OkHttp directly for that call.
  2. Pull the same data from the receipt API: GET /v1/receipts/<X-Receipt-Id>.

Errors

import com.openai.errors.RateLimitException;
import com.openai.errors.OpenAIError;

try {
  client.chat().completions().create(params);
} catch (RateLimitException e) {
  // 429 — energy budget hit
} catch (OpenAIError e) {
  if (e.statusCode() == 402) {
    // insufficient balance, top up
  } else throw e;
}

Spring Boot

Bind the OpenAIClient as a Spring bean and inject it into your services. The OpenAI Java SDK has a Spring Boot starter under com.openai:openai-java-spring-boot-starter that auto-configures from application.properties:

# application.properties
openai.base-url=https://api.greenjoules.cloud/v1
openai.api-key=${JC_API_KEY}

Next

For object store via software.amazon.awssdk:s3, the AWS Java SDK works against our endpoint. See Migrate from AWS S3.