IBM watsonx.ai Java SDK
The IBM watsonx.ai Java SDK is an open-source client library for IBM watsonx.ai, an enterprise-grade AI platform for building, training, and deploying AI models at scale. It provides a unified Java interface to the watsonx.ai ecosystem and works with both IBM Cloud and CP4D (on-premises deployments).
Prerequisites
- Java 17 or higher
- Maven or Gradle
- A watsonx.ai service instance (IBM Cloud or on-premises)
The samples in this documentation reference values such as an API key, a Project ID, and (for some services) Cloud Object Storage details. If you don't have these yet, the Setup & Prerequisites page walks through obtaining each one.
Installation
Add the SDK to your Maven project:
<dependency>
<groupId>com.ibm.watsonx</groupId>
<artifactId>watsonx-ai</artifactId>
<version>0.40.0</version>
</dependency>
Or for Gradle:
implementation 'com.ibm.watsonx:watsonx-ai:0.40.0'
Quick Start
ChatService chatService = ChatService.builder()
.apiKey(WATSONX_API_KEY)
.projectId(WATSONX_PROJECT_ID)
.baseUrl(CloudRegion.DALLAS)
.modelId("ibm/granite-4-h-small")
.build();
AssistantMessage response = chatService.chat("Tell me a joke").toAssistantMessage();
System.out.println(response.content());
Next steps
- Setup & Prerequisites - obtain an API key, Project ID, and the other values used in samples
- Authentication - configure
IBMCloudAuthenticatororCP4DAuthenticator - Services - explore the full list of available services
Available services
Inference
| Service | Description |
|---|---|
| Chat | Conversational AI - synchronous and streaming, tool calling, vision, reasoning, structured output |
| Embedding | Convert text to dense vectors for semantic search, similarity, and RAG |
| Rerank | Score and sort a list of candidate passages against a query |
| Time Series | Forecast time series data using IBM Granite TTM models |
| Deployment | Target a deployed model by deploymentId for chat and forecasting |
| Foundation Model | Browse the model catalog - filter by provider, task, function, lifecycle |
Model Gateway
Proxy layer that routes requests to third-party foundation models (OpenAI, Anthropic, Azure, Mistral, and others) through a single IBM-managed endpoint.
| Service | Description |
|---|---|
| Chat | Synchronous and streaming chat completions to any configured model |
| Catalog | List and retrieve models configured in the gateway |
| Embedding | Generate vector embeddings from text using any configured embedding model |
| Image Generation | Generate images from text prompts using any configured image model |
Document processing
| Service | Description |
|---|---|
| Create Schema | Generate a key-value extraction schema from sample documents |
| Improve Schema | Refine an existing schema using additional examples |
| Merge Schema | Consolidate multiple schemas into one |
| Cluster Schema | Group a set of schemas into semantically similar clusters |
| Text Extraction | Extract structured key-value pairs from documents in COS |
| Text Classification | Classify documents stored in COS |
Utilities
| Service | Description |
|---|---|
| Tool | Invoke IBM-hosted utility tools (search, weather, Python interpreter, RAG) |
| Tokenization | Count tokens and retrieve the individual token strings for a given model |
| Detection | Detect harmful content (HAP), PII, and safety violations |
| File | Upload, list, retrieve, and delete files used as batch job inputs |
| Batch | Submit high-volume asynchronous inference jobs from JSONL files |
Framework integrations
The SDK integrates seamlessly with popular Java frameworks: