SDK examples

Axium exposes each provider's native wire protocol under a proxy app, so you keep using the official SDKs and only change two things: the base URL and the API key. The examples below are taken from the examples/ folder of this repository and run against a local core on http://localhost:3000.

Replace <app-id> with your proxy app id and ax_… with an API key created in the console. See Proxy apps & gateways for the URL layout and Authentication for the key format.

OpenAI SDK

The OpenAI gateway lives at …/proxy-apps/<app-id>/openai. The SDK appends /responses, /chat/completions, /files, … to it.

JavaScriptPythoncurl

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'ax_…',
  baseURL: 'http://localhost:3000/v1/proxy-apps/<app-id>/openai',
});

const response = await client.responses.create({
  model: 'gpt-4o-mini',
  input: 'Name three colours',
});
console.log(response.output_text);

from openai import OpenAI

client = OpenAI(
    api_key="ax_…",
    base_url="http://localhost:3000/v1/proxy-apps/<app-id>/openai",
)

response = client.responses.create(model="gpt-4o-mini", input="Name three colours")
print(response.output_text)

curl http://localhost:3000/v1/proxy-apps/<app-id>/openai/responses \
  -H "Authorization: Bearer ax_…" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","input":"Name three colours"}'

Structured outputs (text.format with a JSON schema), tool calls, streaming and file uploads work exactly as against OpenAI. The examples/sdk-js/openai.js file in the repository exercises each of them.

Google Gen AI SDK (Gemini API)

The Gemini gateway lives at …/proxy-apps/<app-id>/gemini. The SDK appends /v1beta/models/<model>:<verb>.

Authentication header

Google's SDK sends the key as x-goog-api-key, which Axium accepts, so apiKey: 'ax_…' is enough. Adding Authorization: Bearer ax_… as a default header is harmless and makes the intent explicit; if both are present, Authorization wins.

JavaScriptPython

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
  apiKey: 'ax_…',
  httpOptions: {
    baseUrl: 'http://localhost:3000/v1/proxy-apps/<app-id>/gemini',
    headers: { Authorization: 'Bearer ax_…' },
  },
});

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Name three colours',
});
console.log(response.text);

from google import genai
from google.genai import types

client = genai.Client(
    api_key="ax_…",
    http_options=types.HttpOptions(
        base_url="http://localhost:3000/v1/proxy-apps/<app-id>/gemini",
        headers={"Authorization": "Bearer ax_…"},
    ),
)

response = client.models.generate_content(model="gemini-2.5-flash", contents="Name three colours")
print(response.text)

Google Gen AI SDK (Vertex AI)

The Vertex gateway lives at …/proxy-apps/<app-id>/vertex. The SDK builds /v1beta1/projects/<project>/locations/<location>/publishers/<publisher>/models/<model>:<verb> on top of it.

Two things to know:

• project is ignored. Axium replaces it with the project configured in the provider. Any value works.
• location counts. It decides the Google region the request is sent to (global, europe-west1, …).
• Model names are publisher models. google/gemini-2.5-flash-lite becomes publishers/google/models/gemini-2.5-flash-lite. Without a slash the SDK assumes publishers/google.

JavaScriptJava (google-genai)Java (LangChain4j)Java (Spring AI)

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
  vertexai: true,
  project: 'ignored-by-axium',
  location: 'global',
  apiKey: 'ax_…',          // keeps the SDK away from ADC
  httpOptions: {
    baseUrl: 'http://localhost:3000/v1/proxy-apps/<app-id>/vertex',
  },
});

const response = await ai.models.generateContent({
  model: 'google/gemini-2.5-flash-lite',
  contents: 'Which model are you?',
  config: { seed: 42 },
});
console.log(response.text);

In Java .apiKey() is mutually exclusive with .project()/.location(), and with only .apiKey() the SDK enters Vertex express mode and changes the path to /v1/publishers/google/models/…, which the proxy answers with 404 Route not found. Pass the key as a static credential instead: it is sent as Authorization: Bearer ax_… and never refreshed.

import com.google.auth.oauth2.AccessToken;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.genai.Client;
import com.google.genai.types.HttpOptions;

Client ai = Client.builder()
    .vertexAI(true)
    .project("ignored-by-axium")
    .location("global")
    .credentials(GoogleCredentials.create(new AccessToken("ax_…", null)))
    .httpOptions(HttpOptions.builder()
        .baseUrl("https://axium-api.your-domain.com/v1/proxy-apps/<app-id>/vertex")
        .build())
    .build();

var response = ai.models.generateContent("google/gemini-2.5-flash-lite", "Which model are you?", null);
System.out.println(response.text());

.apiEndpoint() accepts the full proxy URL, host and path, so no manual client is needed:

GoogleGenAiChatModel model = GoogleGenAiChatModel.builder()
    .googleCredentials(GoogleCredentials.create(new AccessToken("ax_…", null)))
    .projectId("ignored-by-axium")
    .location("global")
    .apiEndpoint("https://axium-api.your-domain.com/v1/proxy-apps/<app-id>/vertex")
    .modelName("google/gemini-2.5-flash-lite")
    .build();

Use the spring-ai-google-genai module (not the starter) and build the com.google.genai.Client yourself as in the google-genai tab, then hand it to GoogleGenAiChatModel. If you prefer the starter, set spring.ai.model.chat=none so its auto-configured model does not try ADC. ChatOptions does not expose seed.

Complete, runnable Docker projects for the three Java variants are in examples/vertex-java/.

OpenAI SDK against Gemini (OpenAI-compatible facade)

Google AI Studio serves its models in OpenAI format under /v1beta/openai. Axium exposes the same facade inside the Gemini gateway for google-aistudio providers, so the OpenAI SDK only changes its base URL:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'ax_…',
  baseURL: 'http://localhost:3000/v1/proxy-apps/<app-id>/gemini/v1beta/openai',
});

const r = await client.chat.completions.create({
  model: 'gemini-2.5-flash',
  messages: [{ role: 'user', content: 'Name three colours' }],
});
console.log(r.choices[0].message.content);

This facade exposes chat.completions and models only; there is no Responses API on it.

Running the repository examples

cd examples/sdk-js
npm install
node openai.js 1      # test number, see the file for the list
node gemini.js 2
node vertex.js 3

The Java examples each have a Dockerfile; no local Java or Maven needed:

cd examples/vertex-java/java-google-genai
docker build -t genai-test . && docker run --rm genai-test