Lazaarus AI — Developer Documentation

Welcome. This is the reference for the Lazarus REST API. Every endpoint returns the same JSON envelope, authenticates the same way, and is generated from a single OpenAPI 3.1 spec so this page can never drift from the implementation.

Introduction

Lazaarus is a multimodal AI platform. The same shared AI engine powers the Telegram bot and the public REST API. Every capability — text chat, voice understanding, and image generation — is available via JSON (or multipart for voice) over HTTPS, using a single authentication scheme and response envelope.

Pricing (credits per request)

Lazarus runs on a credits-only model. Every request must have enough credit balance for the cost listed above, or you'll receive a 402 insufficient_credits before the request is processed. Daily usage is tracked for rate-limit and abuse-prevention purposes.

Authentication

Every request must include an Authorization: Bearer <api-key> header. Keys use the format LZ-RAGE-XXXXXXXXXX-XXXXXXXXXX (two 10-character blocks of uppercase alphanumeric characters). Generate your key inside the official Telegram bot: @Lazaarus_ai_bot → /account → ⚙️ Get API Key. Keys are shown once — store them somewhere safe.

Billing

Lazarus runs on a single credits-only model. Every request deducts the number of credits listed in the pricing table above. Buy more credits any time via /buycredits in the Telegram bot — including the 🚀 Dev Mode pack (1,000 credits) for heavy API use.

Poll GET /api/v1/balance to see remaining credits and today's usage.

Check your balance

Retrieve the current balance and today's usage for the authenticated API key. Perfect for showing a live meter in your own site, app, or bot.

curl "$BASE/api/v1/balance" \
  -H "Authorization: Bearer $LAZARUS_API_KEY"

// Response
{
  "success": true,
  "data": {
    "api_key": { "id": "…", "name": "my-app" },
    "balance": 87,
    "credit_pass": { "active": false, "expires_at": null },
    "trial_active": false,
    "today": { "api_requests": 12, "usage_count": 12 }
  }
}

// JavaScript
const r = await fetch(BASE + "/api/v1/balance", {
  headers: { Authorization: "Bearer " + API_KEY },
});
const { data } = await r.json();
console.log("Balance: " + data.balance + " · Today: " + data.today.api_requests + " requests");

Quick Start

curl -X POST "$BASE/api/v1/chat" \
  -H "Authorization: Bearer $LAZARUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "character_id": "b7c9e21e-7f19-4a41-8b4c-4b8c8c2d3e00",
    "message": "Hello!"
  }'

const res = await fetch(`${BASE}/api/v1/chat`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.LAZARUS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    character_id: "b7c9e21e-7f19-4a41-8b4c-4b8c8c2d3e00",
    message: "Hello!",
  }),
});
const { success, data, error } = await res.json();
if (!success) throw new Error(error.message);
console.log(data.reply);

import os, requests

r = requests.post(
    f"{BASE}/api/v1/chat",
    headers={"Authorization": f"Bearer {os.environ['LAZARUS_API_KEY']}"},
    json={
        "character_id": "b7c9e21e-7f19-4a41-8b4c-4b8c8c2d3e00",
        "message": "Hello!",
    },
)
body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["message"])
print(body["data"]["reply"])

<?php
$ch = curl_init("$BASE/api/v1/chat");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("LAZARUS_API_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "character_id" => "b7c9e21e-7f19-4a41-8b4c-4b8c8c2d3e00",
    "message" => "Hello!",
  ]),
]);
$body = json_decode(curl_exec($ch), true);
if (!$body["success"]) { throw new Exception($body["error"]["message"]); }
echo $body["data"]["reply"];

Voice Understanding

POST /api/v1/voice — transcribe an audio note and reply in-character. Multipart form fields: audio (file, required), character_id (UUID, required), conversation_id (UUID, optional). Supported formats: wav, mp3, webm, m4a, ogg, flac, aac. Max size: 20 MiB. Cost: 2 credits.

curl -X POST "$BASE/api/v1/voice" \
  -H "Authorization: Bearer $LAZARUS_API_KEY" \
  -F "audio=@note.wav" \
  -F "character_id=b7c9e21e-7f19-4a41-8b4c-4b8c8c2d3e00"

// Response
{
  "success": true,
  "data": {
    "conversation_id": "…",
    "character": { "id": "…", "name": "Nova" },
    "transcript": "Hey, what's the weather like today?",
    "reply": "Around here it's usually…",
    "credits_charged": 2,
    "duration_ms": 1420
  }
}

Image Generation

POST /api/v1/images/generations — generate an image from a text prompt. The Lazaarus platform handles model selection and failover automatically. Cost: 2 credits.

curl -X POST "$BASE/api/v1/images/generations" \
  -H "Authorization: Bearer $LAZARUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "a neon cyberpunk city at night, cinematic", "size": "1024x1024" }'

// Response
{
  "success": true,
  "data": {
    "image": { "b64_json": "iVBORw0…", "url": null, "revised_prompt": null },
    "credits_charged": 2,
    "duration_ms": 4210
  }
}

Image Analysis

POST /api/v1/images/analyze — describe, OCR, and reason about an image. Send either a public image_url or a base64 payload in image_b64 (with optional mime). Optional prompt lets you ask a specific question. Cost: 1 credit (refunded automatically if analysis fails).

// cURL
curl -X POST "$BASE/api/v1/images/analyze" \
  -H "Authorization: Bearer $LAZARUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.com/photo.jpg", "prompt": "What is happening here?" }'

// JavaScript (fetch)
const r = await fetch(BASE + "/api/v1/images/analyze", {
  method: "POST",
  headers: { Authorization: "Bearer " + KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ image_url: "https://example.com/photo.jpg" })
});
const { data } = await r.json();

// Python (requests)
import requests
r = requests.post(BASE + "/api/v1/images/analyze",
  headers={"Authorization": "Bearer " + KEY},
  json={"image_url": "https://example.com/photo.jpg"})
print(r.json())

// PHP (curl)
$ch = curl_init("$BASE/api/v1/images/analyze");
curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer $KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["image_url" => "https://example.com/photo.jpg"]) ]);
echo curl_exec($ch);

// Response
{
  "success": true,
  "data": {
    "analysis": {
      "description": "A neon-lit city street at night with heavy rain.",
      "objects": ["car", "pedestrian", "street sign", "puddle"],
      "scene": "cityscape",
      "text_ocr": "OPEN 24H",
      "reasoning": "Reflections and blur suggest a long-exposure shot in wet conditions."
    },
    "credits_charged": 1,
    "duration_ms": 2380
  }
}

Multilingual Responses

Lazarus AI automatically detects the language of each user message and replies in that same language, including regional variants such as Nigerian Pidgin, Yoruba, Igbo, Hausa, and Swahili. No API changes are required — it just works.

To pin a conversation to a specific language, pass an optional language string on /api/v1/chat. It is stored on the conversation and applied to every subsequent message automatically.

curl -X POST "$BASE/api/v1/chat" \
  -H "Authorization: Bearer $LAZARUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "character_id": "…", "message": "How you dey?", "language": "Nigerian Pidgin" }'

Characters API

GET /api/v1/characters — returns the current list of active characters, ordered by sort order. The list is live: whenever an admin creates, edits, enables, disables, or removes a character, the next call reflects the change immediately. Connected apps and bots automatically pick up the new list by polling this endpoint on load.

curl "$BASE/api/v1/characters" -H "Authorization: Bearer $LAZARUS_API_KEY"

// Response
{ "success": true, "data": { "characters": [
  { "id": "…", "name": "Nova", "uncensored": true,  "sort_order": 1 },
  { "id": "…", "name": "Atlas", "uncensored": false, "sort_order": 2 }
]}}

Capabilities (Models endpoint)

GET /api/v1/models — returns the provider-agnostic capability catalog for the Lazaarus platform. Use this to discover which features (chat, character chat, voice understanding, image generation, multimodal) are available, along with the endpoint that exposes each one and its credit cost. Internal AI infrastructure is never exposed.

curl "$BASE/api/v1/models" -H "Authorization: Bearer $LAZARUS_API_KEY"

// Response
{
  "success": true,
  "data": {
    "capabilities": [
      { "id": "lazarus-chat-v1",    "capability": "chat",                "label": "Chat",                "endpoint": "/api/v1/chat",               "credits_per_request": 1 },
      { "id": "lazarus-voice-v1",   "capability": "voice_understanding", "label": "Voice Understanding", "endpoint": "/api/v1/voice",              "credits_per_request": 2 },
      { "id": "lazarus-imagine-v1", "capability": "image_generation",    "label": "Image Generation",    "endpoint": "/api/v1/images/generations", "credits_per_request": 2 }
    ],
    "models": [
      { "provider": "lazarus", "id": "lazarus-chat-v1", "role": "chat" }
    ]
  }
}

Migration note: the legacy models array is preserved for backward compatibility. It now contains Lazaarus capability profiles (provider is always "lazarus") instead of third-party provider names. Please migrate to the capabilities array; the legacy field will be removed in a future major version.

Response Envelope

Every response follows one of two shapes.

// Success
{
  "success": true,
  "data": { /* endpoint-specific payload */ }
}

// Error
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "status": 422,
    "details": { "fields": [{ "field": "message", "message": "Required non-empty string" }] }
  }
}

Error Codes

Changelog

API Reference

The interactive reference below is generated from the OpenAPI spec. Every endpoint, request body, response, and status code is documented there.