SemaCache Java SDK

Official Java client for semacache.io — semantic caching for LLM APIs.

Zero dependencies beyond java.net.http (Java 11+).

Installation

Maven

<dependency>
    <groupId>io.semacache</groupId>
    <artifactId>semacache-java</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle

implementation 'io.semacache:semacache-java:0.1.0'

Quick Start

import io.semacache.SemaCacheClient;
import io.semacache.SemaCacheClient.*;
import java.util.List;

SemaCacheClient client = SemaCacheClient.create("sc-your-key");

ChatCompletionResponse response = client.createChatCompletion(
    new ChatCompletionRequest("gpt-4o",
        List.of(new Message("user", "What is semantic caching?"))));

System.out.println(response.choices().get(0).message().content());

// Cache metadata is always available
System.out.println(response.cache().matchType());   // "EXACT", "SEMANTIC", or null
System.out.println(response.cache().confidence());   // 0.991 (for semantic hits)

Configuration

SemaCacheClient client = SemaCacheClient.builder()
    .apiKey("sc-your-key")
    .upstreamApiKey("sk-your-openai-key")   // optional: pass inline instead of dashboard
    .similarityThreshold(0.90)              // optional: override default (0.95)
    .cacheTtl(3600)                         // optional: cache for 1 hour
    .build();

Image Generation

MediaResponse image = client.generateImage(new ImageGenerateRequest("A sunset over mountains"));
System.out.println(image.data().get(0).url());
System.out.println(image.cache().matchType());

Video Generation

MediaResponse video = client.generateVideo(new VideoGenerateRequest("A drone flyover of a city"));
System.out.println(video.data().get(0).url());
System.out.println(video.cache().matchType());

Passthrough params

Each request record takes an optional Map<String, Object> extras argument. Anything in that map is merged into the JSON body verbatim and forwarded to the upstream provider. New OpenAI / Gemini / xAI params work the moment the provider ships them. Use "extra_body" for provider-specific extensions.

import java.util.List;
import java.util.Map;

// Chat — forward temperature, reasoning_effort, response_format, …
ChatCompletionResponse chat = client.createChatCompletion(
    new ChatCompletionRequest(
        "gpt-5.4",
        List.of(new Message("user", "Summarize SemCache in one line")),
        Map.of(
            "temperature", 0.2,
            "reasoning_effort", "high",
            "response_format", Map.of("type", "json_object")
        )
    )
);

// Image — forward seed, negative_prompt, aspect_ratio, …
MediaResponse image = client.generateImage(
    new ImageGenerateRequest(
        "A red square on a white background",
        "imagen-4.0-generate-001",
        Map.of(
            "seed", 42,
            "negative_prompt", "blurry, low quality",
            "aspect_ratio", "16:9"
        )
    )
);

// Video — forward resolution, enhance_prompt, …
MediaResponse video = client.generateVideo(
    new VideoGenerateRequest(
        "A drone flyover of a city",
        "veo-3.0-generate-001",
        Map.of(
            "resolution", "1080p",
            "enhance_prompt", true
        )
    )
);

// Gemini-specific escape hatch
ChatCompletionResponse safe = client.createChatCompletion(
    new ChatCompletionRequest(
        "gemini-2.5-flash",
        List.of(new Message("user", "Hello")),
        Map.of("extra_body", Map.of(
            "safety_settings", List.of(
                Map.of("category", "HARM_CATEGORY_HATE_SPEECH", "threshold", "BLOCK_NONE")
            )
        ))
    )
);

Supported Models

All models supported by semacache.io work through this SDK:

Chat

• OpenAI: gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, o3, o3-mini, o4-mini
• Gemini: gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-3.1-flash-lite-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite
• xAI: grok-4.20, grok-4, grok-4-fast, grok-3, grok-3-mini, grok-3-fast

Images

• OpenAI: gpt-image-1.5, gpt-image-1, gpt-image-1-mini, dall-e-3, dall-e-2
• Google Imagen: imagen-4.0-generate-001, imagen-4.0-ultra-generate-001, imagen-4.0-fast-generate-001
• xAI: grok-imagine-image, grok-imagine-image-pro

Videos

• Google Veo: veo-3.1-generate-preview, veo-3.1-fast-generate-preview, veo-3.1-lite-generate-preview, veo-3.0-generate-001, veo-3.0-fast-generate-001, veo-2.0-generate-001
• xAI: grok-imagine-video

Custom: any OpenAI-compatible endpoint registered in the dashboard

Links

• semacache.io
• Documentation
• Dashboard