/aim/verifyVerify 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 }Looking for your key, usage or limits?
Everything account-related lives in the console.
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.
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/v1Every 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_xxxxxxxxxxxxxxxxxxxxxxxxAIM API is prepaid. One credit = $0.01. Every modality debits the same wallet.
| Modality | Cost |
|---|---|
| Chat — aim-fast | 60 credits / 1M input tokens, 240 / 1M output |
| Chat — aim-pro | 174 credits / 1M input tokens, 348 / 1M output |
| Image generation | 13.6 credits / image |
| Text-to-speech | 6 credits / 1,000 characters |
| Speech-to-text | 0.74 credits / minute of audio |
| Vision (image understanding) | 0.24 credits / image |
| Document analysis | Flat, per document |
| Video analysis | Flat, per video |
| PDF generation | Flat, nominal — covers abuse-guard, not real backend cost |
| Web search, timers, stopwatches, reminders | Free — rate-limited instead (200/day per key) |
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": "..." }| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_request / invalid_request_error | Malformed or missing required fields |
| 401 | missing_api_key / invalid_api_key | No key, or key is wrong/revoked |
| 402 | insufficient_balance | Wallet is at or below zero — top up |
| 429 | rate_limit_exceeded | Over 30 requests/minute on this key |
| 500 | api_error / internal_error | Something broke on our end |
Rate limits
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.
/aim/verifyConfirms 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 }Two request shapes, one underlying engine — pick whichever fits your stack.
/chat/completionsPoint 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).
| Name | Type | Description |
|---|---|---|
| model | string | aim-fast (default) or aim-pro. |
| messages* | array | Standard OpenAI-shaped messages array, oldest first. |
| user | string | Your 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. |
| stream | boolean | Standard 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. |
| tools | array | Your own function-calling tools — AIM returns tool_calls for you to execute yourself, exactly like a plain OpenAI-compatible endpoint. |
| aim_tools | boolean | Set 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}
}/aim/chatA simpler shape for a single turn — no role-array ceremony if you don't need one.
| Name | Type | Description |
|---|---|---|
| input | string | The message text. Use this or messages, not both. |
| messages | array | Conversation history, if you need multi-turn. Use this or input. |
| user | string | Your own end-user id, so timers/reminders/stopwatches are scoped per person using your app, not pooled under one bucket per key. |
| tools | boolean | array | Omit for all built-in tools on (default). Pass false to disable all, or a list of specific tool names to enable only those. |
| webhook_url | string | Where AIM POSTs a completion event when a timer or reminder fires later. |
| stream | boolean | Newline-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}
}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.
/aim/tools/{resource_id}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 }Images, speech, transcription, documents and video — priced per the table above.
/images/generationsCreate 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).
| Name | Type | Description |
|---|---|---|
| prompt* | string | What 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>"}] }/audio/speechConvert text into spoken audio. Returns raw audio bytes directly (audio/mpeg), not JSON — same as OpenAI's own /v1/audio/speech.
| Name | Type | Description |
|---|---|---|
| input* | string | The 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/audio/transcriptionsTranscribe an audio file. Send it as multipart/form-data, not JSON.
| Name | Type | Description |
|---|---|---|
| file* | file | The 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" }/documents/generateReturns raw PDF bytes directly (application/pdf), not JSON.
| Name | Type | Description |
|---|---|---|
| title* | string | Document title. |
| content* | string | Document 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/documents/analyzeSend a document plus an instruction. Multipart/form-data, not JSON.
| Name | Type | Description |
|---|---|---|
| file* | file | The document to analyze. |
| prompt* | string | What 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." }/video/analyzeSend a video plus an instruction. Multipart/form-data, not JSON.
| Name | Type | Description |
|---|---|---|
| file* | file | The video to analyze. |
| prompt* | string | What 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..." }Called from your OWN authenticated dashboard/session, not from arbitrary requests — pass your signed-in user_id, no API key needed for these three.
/aim/keysReturns the raw key exactly once — store it immediately, AIM never displays it again.
| Name | Type | Description |
|---|---|---|
| user_id* | string | Your signed-in user id. |
| label | string | Optional display label. |
curl -X POST https://aimbot.up.railway.app/v1/aim/keys \
-H "Content-Type: application/json" \
-d '{"user_id": "...", "label": "optional"}'/aim/keysReturns prefix and metadata only — never the raw key or its hash.
| Name | Type | Description |
|---|---|---|
| user_id* | string | Your signed-in user id (query param). |
curl "https://aimbot.up.railway.app/v1/aim/keys?user_id=..."/aim/keys/{key_id}Revokes immediately — any service still using it stops working right away.
| Name | Type | Description |
|---|---|---|
| user_id* | string | Your signed-in user id (query param). |
curl -X DELETE "https://aimbot.up.railway.app/v1/aim/keys/<key_id>?user_id=..."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.
/aim/walletReturns your current balance in credits, plus the live model pricing table.
| Name | Type | Description |
|---|---|---|
| user_id* | string | Your signed-in user id (query param). |
curl "https://aimbot.up.railway.app/v1/aim/wallet?user_id=..."/api/billing/flutterwave/aim-api/initiateNote: 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.
| Name | Type | Description |
|---|---|---|
| user_id* | string | Your signed-in user id. |
| amount_usd* | number | Minimum $5. |
| return_url* | string | Where 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"}'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.