API documentation

Ram AI is a pool-backed inference API (two public and three private-bot generations at a time). Use a free account and Authorization: Bearer <token> from the editor, web chat, or the endpoints below. Base URL is your deployment origin (e.g. https://ai.rambot.xyz).

100% free tier: Register or sign in on the chat homepage. Responses may wait in a shared queue when the server is busy.

Authentication

Method	When to use
`Authorization: Bearer <token>`	Login token from `/auth/login` or `/auth/register` (expires). Also sets a session cookie for web chat.
`Authorization: Bearer <api_key>` or `x-api-key`	Long-lived personal key (`ramai_…`) — create in web chat Settings → API access (password required). Does not expire until revoked.
Session cookie	Browser web chat at `/` after sign-in (HttpOnly, SameSite=Lax).

Protected routes return 403 without valid credentials.

Account endpoints

Method	Path	Description
POST	`/auth/register`	JSON: `username`, `password` (≥8), optional `email`, `enable_2fa`. Returns token or `requires_2fa`.
POST	`/auth/login`	JSON: `username`, `password`. Optional 2FA: `challenge_id`, `code`.
POST	`/auth/2fa/verify`	Complete login after email code.
POST	`/auth/2fa/settings`	Bearer required — enable/disable 2FA (`email`, `enable_2fa`, `password`).
GET	`/auth/me`	Current user (session or Bearer).
GET	`/auth/api-key`	Session — whether a personal API key exists (`prefix` only).
POST	`/auth/api-key`	Session — requires a stored date of birth showing age 18+; JSON `password`; returns new `api_key` once.
DELETE	`/auth/api-key`	Session — JSON `password`; revoke personal key.
POST	`/auth/logout`	Clear session; optional Bearer revoke.

Models

Public model ids (use in model fields). Display names are shown in the web UI and editor:

ram-ai-1-fast — Ram AI Chat 1.0 · fast
ram-ai-1-medium — Ram AI Chat 1.0 · medium
ram-ai-1-slow — Ram AI Chat 1.0 · slow
ram-ai-7b — Ram AI Code Agent 1.0 · fast (free tier default)
ram-ai-32b — Ram AI Code Agent 1.0 · slow
ram-ai-2 — Ram AI Chat 2.0 · medium (chat, tech, code — text)
ram-ai-2-fast — Ram AI Chat 2.0 · fast (short responses designed to finish quickly)
ram-ai-2-vision — Ram AI Chat 2.0 · vision (same backend; use for images / /api/describe)
ram-ai-3-smart — Ram AI Chat 3.0 · super slow (advanced reasoning and vision; responses can take a long time)
ram-ai-vision — Ram AI Vision 1.0 · medium (legacy vision; images via /api/describe)

GET /chat/api/bootstrap includes modelCatalog with label, version, and speed for each id. Add future models in ram_models.py without breaking API clients.

GET /v1/models — OpenAI-style list (data[].id). Requires auth.

Chat & completions

POST `/api/ask` (recommended for Ram Code Editor)

JSON body:

{
  "message": "Hello",
  "model": "ram-ai-7b",
  "stream": true,
  "user_id": "optional-client-id",
  "system": "You are Ram AI…",
  "messages": [],
  "max_tokens": 0
}

max_tokens: 0 (or omit) = long replies with no output cap by default. Stream idle timeouts are off by default for slow hardware. Optional caps via env — see GET /status → inference_limits. User-facing errors never name backend products.

With stream: true (default): text/plain body; lines include Proxy pulses (: ping) keep the connection alive; queue position uses GET /status. Assistant text never includes heartbeat markers. Response header X-RamAI-Task-ID is set when streaming starts.

With stream: false: JSON { "reply", "task_id", "model" }.

POST `/ask`

Plain-text streaming only. Body: raw message string or JSON with message, optional model, messages. Same queue/stream behavior as /api/ask.

POST `/v1/chat/completions`

OpenAI-compatible. JSON: messages, model, stream, temperature, max_tokens.

Streaming: Server-Sent Events (data: {…} chunks, ends with data: [DONE]).

Non-streaming: JSON completion object with choices[0].message.content.

POST `/api/describe`

Vision — JSON: image_base64, optional prompt, model (default ram-ai-vision). Returns { description, task_id, model }.

POST `/api/images/generations`

Queue a realistic image. JSON: prompt, optional size (auto, landscape, portrait, square, photo-landscape, or photo-portrait), integer seed, and steps (4–30; default 12). Auto size selects a vertical canvas for full-body and portrait prompts. Returns HTTP 202 with task_id.

Poll GET /api/images/generations/<task_id>. A completed job includes image_url, mime_type, and seed. Send DELETE to the same URL to cancel. Image generation runs one job at a time, so it may take several minutes.

Adult browser requests require an 18+ confirmation each session. Adult API requests require the authenticated API-key owner to have a stored date of birth showing age 18+. Minor and non-consensual sexual content remains blocked.

Queue & tasks

Two public chat generations and three requests authenticated with the private server key can run at once. Each pool has its own queue. Image generation has a separate serialized queue.

Method	Path	Description
GET	`/status`	`busy`, `tasks`, `active_task_id`, `active_tasks[]`, `available_models`
POST	`/task/stop`	JSON `{ "task_id" }` — cancel queued or stop running job
POST	`/task/start`	Reserve a slot (advanced)
POST	`/task/finish`	Release a task (advanced)

Web chat

Method	Path	Description
GET	`/`	Web UI (sign-in, chat)
GET	`/chat/api/bootstrap`	JSON: `enabled`, `authenticated`, `models`, `defaultModel`, `registrationOpen`, `twoFactorAvailable`

/chat redirects to /.

Examples

Sign in, then stream a reply

curl -s -X POST "https://ai.rambot.xyz/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"you","password":"your-password"}' 

# Use token from response:
curl -N -X POST "https://ai.rambot.xyz/api/ask" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"message":"Hello","model":"ram-ai-7b"}'

OpenAI-compatible (Bearer)

curl -s -X POST "https://ai.rambot.xyz/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"model":"ram-ai-7b","messages":[{"role":"user","content":"Hi"}]}'

Queue status & stop

curl -s "https://ai.rambot.xyz/status" -H "Authorization: Bearer YOUR_TOKEN"

curl -s -X POST "https://ai.rambot.xyz/task/stop" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"task_id":"TASK_ID_FROM_HEADER_OR_STREAM"}'

CORS

Set CORS_ORIGINS on the server (comma-separated) to allow browser calls from the Ram Code Editor or other frontends. Credentials are supported for account login.