Empire Union logoEmpire UnionDev

Looking for your key, usage or limits?

Everything account-related lives in the console.

AIM API · beta

AIM API reference

Programmatic access to AIM: chat completions (OpenAI-compatible or native), web search, timers and reminders, image generation, text-to-speech, speech-to-text, vision, document and video analysis, and PDF generation — all billed from one prepaid credit wallet.

Base URL

Every endpoint below is relative to this base, except the top-up-initiate route under Wallet & billing, which lives at the host root — versioning otherwise lives in the path, so a future v2 will not break the calls you write today.

https://aimbot.up.railway.app/v1

Authentication

Every request is authenticated with a bearer token. Create a key in your API console and keep it server-side — never ship it in a browser bundle, a mobile app or a public repository. The raw key is shown exactly once, at creation; AIM never displays it again. A brand-new key has a $0 wallet balance, so use Verify a key to confirm it's live before spending anything.

Authorization: Bearer aim_live_xxxxxxxxxxxxxxxxxxxxxxxx

Credits & pricing

AIM API is prepaid. One credit = $0.01. Every modality debits the same wallet.

ModalityCost
Chat — aim-fast60 credits / 1M input tokens, 240 / 1M output
Chat — aim-pro174 credits / 1M input tokens, 348 / 1M output
Image generation13.6 credits / image
Text-to-speech6 credits / 1,000 characters
Speech-to-text0.74 credits / minute of audio
Vision (image understanding)0.24 credits / image
Document analysisFlat, per document
Video analysisFlat, per video
PDF generationFlat, nominal — covers abuse-guard, not real backend cost
Web search, timers, stopwatches, remindersFree — rate-limited instead (200/day per key)

Errors & limits

The OpenAI-compatible route (/v1/chat/completions, /v1/images/generations, /v1/audio/*) uses OpenAI's error shape. Native routes use a flatter shape instead. Hitting a spending limit returns 402, which means top up rather than retry.

{ "error": { "message": "...", "type": "invalid_request_error", "code": "..." } }
{ "error": "...", "code": "..." }
HTTPcodeMeaning
400invalid_request / invalid_request_errorMalformed or missing required fields
401missing_api_key / invalid_api_keyNo key, or key is wrong/revoked
402insufficient_balanceWallet is at or below zero — top up
429rate_limit_exceededOver 30 requests/minute on this key
500api_error / internal_errorSomething broke on our end

Rate limits

  • 30 requests/minute per key, across every billed endpoint.
  • 200 built-in tool calls/day per key — the abuse guard for tools that don't touch your wallet.

Getting started

A brand-new key has a $0 wallet balance, so your first real request fails with insufficient_balance even though the key itself is fine. Verify it first.

GET/aim/verify

Verify a key

Confirms a key is live and returns its current balance, without spending anything.

curl https://aimbot.up.railway.app/v1/aim/verify \
  -H "Authorization: Bearer $EMPIRE_API_KEY"
{ "valid": true, "balance_credits": 500.0 }

Chat completions

Two request shapes, one underlying engine — pick whichever fits your stack.

POST/chat/completions

Create a chat completion (OpenAI-compatible)

Point your existing OpenAI SDK's base_url at the AIM base URL and it works unmodified, including your own client-side function-calling tools. Vision works via a standard image_url content part with a base64 data: URI — a plain http(s) image URL returns 400 (fetching arbitrary remote URLs server-side is an open SSRF surface not worth taking on).

Body parameters

NameTypeDescription
modelstringaim-fast (default) or aim-pro.
messages*arrayStandard OpenAI-shaped messages array, oldest first.
userstringYour own end-user id (standard OpenAI field). Only matters when aim_tools is true: it scopes timers, reminders and stopwatches per person using your app, instead of pooling them under one bucket per API key.
streambooleanStandard OpenAI-shaped SSE. Genuine token-by-token when no tools fire; when a tool fires, the answer is generated fully server-side first, then delivered as a fast streamed sequence.
toolsarrayYour own function-calling tools — AIM returns tool_calls for you to execute yourself, exactly like a plain OpenAI-compatible endpoint.
aim_toolsbooleanSet true to let AIM use its own built-in tools (web search, timers, stopwatches, reminders) mid-request. Additive and separate from your own tools — see Built-in tools below.
curl https://aimbot.up.railway.app/v1/chat/completions \
  -H "Authorization: Bearer $EMPIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aim-fast",
    "messages": [{"role": "user", "content": "What is the capital of Nigeria?"}]
  }'
{
  "id": "aimcmpl-...",
  "object": "chat.completion",
  "model": "aim-fast",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Abuja."}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 14, "completion_tokens": 4, "total_tokens": 18, "cost_credits": 0.0106}
}
POST/aim/chat

Create a chat completion (native)

A simpler shape for a single turn — no role-array ceremony if you don't need one.

Body parameters

NameTypeDescription
inputstringThe message text. Use this or messages, not both.
messagesarrayConversation history, if you need multi-turn. Use this or input.
userstringYour own end-user id, so timers/reminders/stopwatches are scoped per person using your app, not pooled under one bucket per key.
toolsboolean | arrayOmit for all built-in tools on (default). Pass false to disable all, or a list of specific tool names to enable only those.
webhook_urlstringWhere AIM POSTs a completion event when a timer or reminder fires later.
streambooleanNewline-delimited JSON (application/x-ndjson) — one {"type": "delta", "text": "..."} object per line, then a terminal {"type": "done", ...} object.
curl https://aimbot.up.railway.app/v1/aim/chat \
  -H "Authorization: Bearer $EMPIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "What is the capital of Nigeria?"}'
{
  "output": "Abuja.",
  "model": "aim-fast",
  "tools_used": [],
  "usage": {"input_tokens": 14, "output_tokens": 4, "cost_credits": 0.0106}
}

Built-in tools

Free, server-executed, rate-limited (200 calls/day/key) rather than wallet-billed: web_search, create_timer, manage_stopwatch, and create_reminder. Enable them with aim_tools: true (OpenAI-compatible route) or the default-on tools behavior (native route) — AIM decides when to use them based on your prompt, you don't call them directly. Timers and reminders fire later; poll for the result or pass a webhook_url.

GET/aim/tools/{resource_id}

Poll a tool resource

Check the status of a timer or reminder. If you passed a webhook_url on the original request, AIM also POSTs a completion event to it when the resource is due — this endpoint is the fallback for when you didn't.

curl https://aimbot.up.railway.app/v1/aim/tools/<resource_id> \
  -H "Authorization: Bearer $EMPIRE_API_KEY"
{ "id": "...", "type": "timer", "status": "finished", "label": "...", "target_time": "...", "webhook_delivered": true }

Media

Images, speech, transcription, documents and video — priced per the table above.

POST/images/generations

Generate an image

Create an image from a text prompt. Returns base64 image bytes only in this version — no hosted URL yet (that needs object storage; base64 needed zero new infrastructure to ship first).

Body parameters

NameTypeDescription
prompt*stringWhat the image should show.
curl https://aimbot.up.railway.app/v1/images/generations \
  -H "Authorization: Bearer $EMPIRE_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "a red bicycle in a field, watercolor style"}'
{ "created": 1234567890, "data": [{"b64_json": "<base64 PNG bytes>"}] }
POST/audio/speech

Text to speech

Convert text into spoken audio. Returns raw audio bytes directly (audio/mpeg), not JSON — same as OpenAI's own /v1/audio/speech.

Body parameters

NameTypeDescription
input*stringThe text to read aloud.
curl https://aimbot.up.railway.app/v1/audio/speech \
  -H "Authorization: Bearer $EMPIRE_API_KEY" -H "Content-Type: application/json" \
  -d '{"input": "Hello, welcome to AIM."}' --output speech.mp3
POST/audio/transcriptions

Speech to text

Transcribe an audio file. Send it as multipart/form-data, not JSON.

Body parameters

NameTypeDescription
file*fileThe audio file to transcribe.
curl https://aimbot.up.railway.app/v1/audio/transcriptions \
  -H "Authorization: Bearer $EMPIRE_API_KEY" \
  -F file=@recording.ogg
{ "text": "this is what was said in the recording" }
POST/documents/generate

Generate a PDF

Returns raw PDF bytes directly (application/pdf), not JSON.

Body parameters

NameTypeDescription
title*stringDocument title.
content*stringDocument body content.
curl https://aimbot.up.railway.app/v1/documents/generate \
  -H "Authorization: Bearer $EMPIRE_API_KEY" -H "Content-Type: application/json" \
  -d '{"title": "Weekly Report", "content": "..."}' --output report.pdf
POST/documents/analyze

Analyze a document

Send a document plus an instruction. Multipart/form-data, not JSON.

Body parameters

NameTypeDescription
file*fileThe document to analyze.
prompt*stringWhat to extract or summarize from it.
curl https://aimbot.up.railway.app/v1/documents/analyze \
  -H "Authorization: Bearer $EMPIRE_API_KEY" \
  -F file=@invoice.pdf -F prompt="Extract the total amount due"
{ "text": "The total amount due is $1,240.00." }
POST/video/analyze

Analyze a video

Send a video plus an instruction. Multipart/form-data, not JSON.

Body parameters

NameTypeDescription
file*fileThe video to analyze.
prompt*stringWhat to look for or describe.
curl https://aimbot.up.railway.app/v1/video/analyze \
  -H "Authorization: Bearer $EMPIRE_API_KEY" \
  -F file=@clip.mp4 -F prompt="What is happening in this video?"
{ "text": "A person is demonstrating how to..." }

Key management

Called from your OWN authenticated dashboard/session, not from arbitrary requests — pass your signed-in user_id, no API key needed for these three.

POST/aim/keys

Create a key

Returns the raw key exactly once — store it immediately, AIM never displays it again.

Body parameters

NameTypeDescription
user_id*stringYour signed-in user id.
labelstringOptional display label.
curl -X POST https://aimbot.up.railway.app/v1/aim/keys \
  -H "Content-Type: application/json" \
  -d '{"user_id": "...", "label": "optional"}'
GET/aim/keys

List keys

Returns prefix and metadata only — never the raw key or its hash.

Query parameters

NameTypeDescription
user_id*stringYour signed-in user id (query param).
curl "https://aimbot.up.railway.app/v1/aim/keys?user_id=..."
DELETE/aim/keys/{key_id}

Revoke a key

Revokes immediately — any service still using it stops working right away.

Query parameters

NameTypeDescription
user_id*stringYour signed-in user id (query param).
curl -X DELETE "https://aimbot.up.railway.app/v1/aim/keys/<key_id>?user_id=..."

Wallet & billing

Check your balance or start a top-up. Top-ups convert at a pure $0.01/credit exchange rate — no markup on money coming in; the markup is only in what usage costs.

GET/aim/wallet

Get wallet

Returns your current balance in credits, plus the live model pricing table.

Query parameters

NameTypeDescription
user_id*stringYour signed-in user id (query param).
curl "https://aimbot.up.railway.app/v1/aim/wallet?user_id=..."
POST/api/billing/flutterwave/aim-api/initiate

Start a top-up

Note: this route lives at the host root, not under /v1, since it sits alongside this backend's other billing routes. Returns a Flutterwave hosted checkout link.

Body parameters

NameTypeDescription
user_id*stringYour signed-in user id.
amount_usd*numberMinimum $5.
return_url*stringWhere to send the user after checkout.
curl -X POST https://aimbot.up.railway.app/api/billing/flutterwave/aim-api/initiate \
  -H "Content-Type: application/json" \
  -d '{"user_id": "...", "amount_usd": 5, "return_url": "https://developer.empireunion.xyz/account/billing"}'

What's not in the API (yet)

A few things the consumer AIM product has that aren't exposed here, either because they're genuinely out of scope for a third-party API or because the underlying account model doesn't map cleanly.

Persistent conversation memory

Every request is stateless — include prior turns yourself via messages.

GitHub / Calendar / Gmail actions

These run against a signed-in AIM user's own OAuth connections. An API customer's end-users have no equivalent connection on file, so this isn't available until a multi-tenant OAuth flow exists.

Custom multi-step background tasks (RUN_WORKFLOW)

Planned, not yet built.

Empire Learn and daily subscriptions

Chess/language/tutoring, plus Word of the Day, news and verse — consumer-product features with no API equivalent.