Introduction

Apiarium provides a unified REST API to access multiple AI models under a single API key. No need to manage separate accounts for OpenAI, Anthropic, Google or other providers.

Coming from OpenRouter or LiteLLM? See how OpenRouter migration works · or LiteLLM →

Base URL:

Authentication

All requests must include your API key in the Authorization header using the Bearer scheme.

You can find your API key in your dashboard. Keep it secret — never expose it in client-side code.

Credits

Credits are Apiarium's unit of consumption. Each request deducts credits based on the model used and the size of the task. Your balance is always visible in your dashboard.

Your account has two credit balances: plan credits (included with your subscription, reset monthly for paid plans) and extra credits (purchased separately via credit packs — see below). Plan credits are used first; extra credits are used automatically once your plan credits run out.

Text generation cost depends on the number of tokens processed and the model used. Credits are calculated as: model_multiplier × (input_tokens × 0.75 + output_tokens × 4.50) / 1000, with a minimum of 1 credit per request. The multiplier reflects each model's real cost (gpt-4o-mini = 1x, claude-haiku = 7.5x, gemini = 12.5x, gpt-4o = 16.5x, claude-sonnet = 22.5x) — this is why models cost proportionally more, not just a flat token count.

Credit Packs

Need more credits without waiting for your monthly reset? You can buy credit packs at any time — no subscription required. Purchased credits never expire before 12 months and are used automatically once your plan credits run out.

There are two pricing tiers, applied automatically based on your account:

List active packs

Returns your active (non-expired, non-refunded) credit packs, along with the total extra balance. Requires a Supabase session token, not an API key — this endpoint is used by the dashboard, not for programmatic API usage.

{
  "packs": [
    {
      "id": "74da67c7-...",
      "source": "payasyougo",
      "credits_original": 1714,
      "credits_remaining": 1618,
      "expires_at": "2027-07-02T13:14:13.969+00:00",
      "created_at": "2026-07-02T13:14:14.382553+00:00",
      "refunded": false,
      "expired": false
    }
  ],
  "total_extra": 1618
}

Multi-currency

Apiarium supports billing in 10 currencies: EUR, USD, GBP, CAD, INR, AUD, BRL, MXN, JPY, and SGD. Currency is detected automatically based on your location when you visit the pricing page.

Subscription prices are fixed per currency (not a live conversion) — each plan has a dedicated price for each supported currency. Pay-as-you-go and top-up purchases calculate the exact credit amount at checkout time based on the amount and currency you choose.

All amounts sent to the API (subscription checkout, credit pack purchases) must include a currency field matching one of the supported codes below, in lowercase:

Rate Limits

Each endpoint has its own rate limit. /llm, /tts, and /transcribe are applied per IP address. /image is different: it's a shared capacity pool across every Apiarium user, because it's constrained by our upstream AI providers' own account-wide limits rather than by any single user's traffic. If you exceed a limit, requests return a 429 status until capacity frees up.

Because /image capacity is shared across all users rather than tied to your IP, a busy moment for Apiarium overall — not just your own usage — can occasionally result in a 429 on that endpoint. Retry after a few seconds.

/llm, /tts, and /transcribe responses include standard rate limit headers so you can track your usage:

RateLimit-Limit: 30
RateLimit-Remaining: 27
RateLimit-Reset: 42  // seconds until the window resets

Errors

Apiarium uses standard HTTP status codes. All errors return a JSON object with an error field.

Example error response:

{
  "error": "Model \"claude-haiku\" is not available on your plan (starter). Upgrade to access more models.",
  "available_models": ["gpt-4o-mini"]
}

Provider errors

When a request fails on the AI provider's side (rate limits, overload, downtime), the response includes error_class and provider fields so you can branch your retry logic on the failure type, not on which provider was called.

Example provider error response:

{
  "error": "AI provider error. Please try again.",
  "error_class": "overloaded",
  "provider": "anthropic"
}

LLM — Text Generation

Generate text using GPT, Claude, or Gemini models. Send a list of messages in chat format and receive a completion. Streaming is not supported — the full response is returned at once.

Available models

gemini maps to Google's Gemini 3.5 Flash, their current flagship model — comparable in capability to gpt-4o and claude-sonnet, which is why it sits alongside them as a Pro-only option.

Parameters

Example

curl -X POST https://api.apiarium.dev/llm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Write a tagline for a coffee brand" }
    ],
    "model": "claude-haiku",
    "max_tokens": 256,
    "temperature": 0.7
  }'

Response

{
  "content": "Brew the moment.",
  "model": "claude-haiku",
  "credits_used": 2,
  "credits_remaining": 9998,
  "tokens": { "input": 12, "output": 9 }
}

Image Generation

Generate images from a text prompt using OpenAI or Google's image models. Free and Starter plans use gpt-image-1 by default. Starter also unlocks Gemini's gemini-flash-image. Pro plans get access to every model, including the higher-quality gpt-image-2 and gemini-pro-image. Images are returned as a public URL.

Note: /image has a shared capacity limit across all Apiarium users (see Rate Limits above), since it's bound by our upstream providers' account-wide throughput rather than per-user traffic. You may occasionally see a 429 here even under normal usage — retry after a few seconds.

Available models

gemini-flash-image (Nano Banana 2) is optimized for speed and high-volume generation. gemini-pro-image (Nano Banana Pro) is Google's highest-quality model, better suited for complex prompts, accurate text rendering, and multi-turn edits.

Parameters

Example

curl -X POST https://api.apiarium.dev/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city at sunset, digital art",
    "model": "gemini-flash-image"
  }'

Response

{
  "url": "https://saduxychstwvxqgevqxw.supabase.co/storage/v1/object/public/images/abc123.png",
  "model": "gemini-flash-image",
  "output_format": "png",
  "credits_used": 90,
  "credits_remaining": 9910
}

Some parameters only apply to specific models. If you send a parameter unsupported by the model you chose (e.g. quality with a Gemini model), the request still succeeds — the response includes a warnings field so you know it was ignored, instead of failing silently:

{
  "url": "https://.../image.png",
  "model": "gemini-flash-image",
  "credits_used": 90,
  "credits_remaining": 9910,
  "warnings": ["The following parameters are not supported by gemini-flash-image and were ignored: quality"]
}

Text to Speech

Convert text to natural-sounding audio using OpenAI or Gemini voices. Maximum input: 4,096 characters per request.

Available models

gemini-tts (Gemini 3.1 Flash TTS) is a premium option with natural-language style control — you can direct tone, pace, accent, and emotion (e.g. [whispers], [excited]) directly in the input text, and it supports 70+ languages and up to 2 distinct speakers in a single request. tts-1 (OpenAI) is the faster, lower-cost default with 6 fixed voices.

Note: gemini-tts only supports wav and pcm as response_format — it returns raw audio natively and doesn't go through OpenAI's format conversion. Use tts-1 if you need mp3, opus, aac, or flac.

Parameters

Example

curl -X POST https://api.apiarium.dev/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from Apiarium", "model": "tts-1", "voice": "nova", "speed": 1.0, "response_format": "mp3"}' \
  --output audio.mp3

Example — gemini-tts with style control

curl -X POST https://api.apiarium.dev/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "[excitedly] Hello from Apiarium!", "model": "gemini-tts", "voice": "Puck"}' \
  --output audio.wav

Response

Returns a binary audio stream. The Content-Type header reflects the requested format. Headers include:

Content-Type: audio/mpeg
X-Credits-Used: 18
X-Credits-Remaining: 9982

Transcription

Transcribe audio to text using Whisper. Send an audio file as multipart/form-data. Costs 10 credits per minute of audio. Supports 50+ languages including English, Spanish, French, German, Portuguese, Italian, Japanese, Chinese, and more.

Parameters

Example

curl -X POST https://api.apiarium.dev/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "language=en" \
  -F "prompt=Apiarium, Node.js, API"

Response

{
  "text": "Hello, this is a transcription of the audio file.",
  "credits_used": 10,
  "credits_remaining": 9990
}