AIM API reference

The African Intelligence Model — chat, reasoning, vision, speech and document generation behind one versioned base URL.

Base URL

Every endpoint below is relative to this base. Versioning lives in the path, so a future v2 will not break the calls you write today.

https://api.empireunion.xyz/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.

Authorization: Bearer $EMPIRE_API_KEY

Errors & limits

Failures come back with a stable machine-readable code, so you can branch on code and never parse a message string. When you are sending too fast you get a 429 plus a Retry-After header — back off for that many seconds and retry. Hitting a spending limit returns 402 instead, which means top up rather than retry.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "request_id": "req_01H..."
  }
}

Models

Discover which models your key can call, and what each one is good at.

GET/models

List models

Returns every model available to your Empire Union account, including context window and supported modalities.

curl https://api.empireunion.xyz/v1/models \
  -H "Authorization: Bearer $EMPIRE_API_KEY"

{
  "data": [
    {
      "id": "aim-alpha-1",
      "context_window": 128000,
      "modalities": ["text", "vision"],
      "languages": ["en", "pcm", "yo", "ha", "ig", "sw"]
    }
  ]
}

Chat

The core endpoint: send a conversation, get a reply.

POST/chat

Create a chat completion

Send a conversation and receive a model response. Supports token streaming over server-sent events when you pass stream: true.

Body parameters

Name	Type	Description
model*	string	Model ID, for example aim-alpha-1.
messages*	array	Conversation history, oldest first. Each item needs a role and content.
stream	boolean	Stream tokens as they are generated. Defaults to false.
temperature	number	Between 0 and 2. Lower is more deterministic. Defaults to 0.7.
max_tokens	integer	Upper bound on the length of the reply.

curl https://api.empireunion.xyz/v1/chat \
  -H "Authorization: Bearer $EMPIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aim-alpha-1",
    "messages": [
      { "role": "user", "content": "Explain compound interest in Pidgin" }
    ]
  }'

{
  "id": "chat_01H...",
  "model": "aim-alpha-1",
  "choices": [
    {
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "input_tokens": 24, "output_tokens": 186 }
}

Nebulae

Vision, image generation, speech and documents — the multimedia arm of AIM.

POST/images

Generate an image

Create an image from a text prompt. Returns a URL to the generated asset.

Body parameters

Name	Type	Description
prompt*	string	What the image should show.
size	string	Output size, for example 1024x1024.
count	integer	How many images to return. Defaults to 1.

curl https://api.empireunion.xyz/v1/images \
  -H "Authorization: Bearer $EMPIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A Lagos market at golden hour", "size": "1024x1024" }'

{
  "data": [
    { "url": "https://cdn.empireunion.xyz/..." }
  ]
}

POST/audio/speech

Text to speech

Convert text into spoken audio. Supports African English, Pidgin, Yoruba, Hausa and Igbo voice profiles.

Body parameters

Name	Type	Description
input*	string	The text to read aloud.
voice	string	Voice profile ID.
format	string	mp3 or wav. Defaults to mp3.

curl https://api.empireunion.xyz/v1/audio/speech \
  -H "Authorization: Bearer $EMPIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": "Good morning, Lagos", "voice": "aim-narrator" }'

Account

Check who you are and how much you have used this cycle.

GET/me

Get account

Returns the account tied to your key, its plan, and current billing-cycle usage.

curl https://api.empireunion.xyz/v1/me \
  -H "Authorization: Bearer $EMPIRE_API_KEY"

{
  "account_id": "eu_acct_...",
  "plan": "builder",
  "usage": { "requests_this_cycle": 1284, "tokens_this_cycle": 902331 }
}

← Back to all Empire Union APIs API console →