DEVELOPER DOCUMENTATION

Build with Sovereign AI

Integrate sovereign AI inference into your applications. SSE streaming, zero external dependencies, OpenAI-compatible API surface.

Quick Start

Choose a Model

Select from Edge models (free, sovereign) or Luxury tier (GPU-accelerated, admin-locked).

Send a Request

POST to /api/v1/sovereign/generate with your prompt and model ID.

Stream the Response

Enable stream: true for real-time SSE token streaming with <100ms first-token latency.

Code Examples

# Standard generation
curl -X POST https://sovereign.drpcoa.com/api/v1/sovereign/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "s-sonic-edge-nexus",
    "prompt": "Explain quantum computing in simple terms",
    "parameters": {
      "max_tokens": 512,
      "temperature": 0.7,
      "stream": false
    }
  }'

# SSE Streaming (recommended)
curl -N -X POST https://sovereign.drpcoa.com/api/v1/sovereign/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "s-sonic-edge-nexus",
    "prompt": "Write a Python fibonacci function",
    "parameters": { "stream": true }
  }'

API Endpoints

Generate text, code, or structured output from any Edge model. Supports SSE token streaming.

Parameter	Type	Required	Description
model_id	string	required	Model identifier (e.g. s-sonic-edge-nexus)
prompt	string	required	Input prompt for generation
parameters.stream	boolean	optional	Enable SSE token streaming (recommended)
parameters.max_tokens	number	optional	Maximum tokens to generate (default: 2048)
parameters.temperature	number	optional	Sampling temperature 0-2 (default: 0.7)

Available Models

Model ID	Name	Engine	Type	Tier	Status
s-sonic-edge-nexus	Edge Nexus	S-Sonic Edge	Text/Code	Free+	Active
s-sonic-edge-echo	Edge Echo	S-Sonic Edge	Voice	Edge+	Configured
s-sonic-edge-vision	Edge Vision	S-Sonic Edge	Image	Edge+	Configured
s-sonic-edge-motion	Edge Motion	S-Sonic Edge	Video	Edge+	Configured
s-sonic-v5-text	V5 Architect	S-Sonic V5	Text	Luxury	Circuit Breaker
s-sonic-v5-flow	V5 Flow	S-Sonic V5	Text	Luxury	Circuit Breaker
s-sonic-v5-physics	V5 Physics	S-Sonic V5	Text	Luxury	Circuit Breaker

Architecture

Circuit Breaker

All requests route through the Circuit Breaker. S-Sonic V5 Luxury tier is disabled by default — all inference runs on sovereign S-Sonic infrastructure at zero cost. Admin can toggle S-Sonic V5 via the SSONIC_V5_ENABLED environment variable.

SSE Token Streaming

Set stream: true to receive tokens via Server-Sent Events (SSE). Each chunk is a JSON object with a content field. The stream terminates with data: [DONE]. First-token latency <100ms on Nexus.

Authentication

Sovereign uses DrPCoA Passport for SSO authentication. Public endpoints (text, docs, suite) are accessible without auth. Protected endpoints require a valid session-token cookie from Passport login.

Infrastructure

Sovereign AI S-Sonic Series with 500B+ combined parameters (Q4_K_M quantization). S-Sonic Edge Vision & Motion headless for image/video generation. FastAPI for voice inference. All containerized via Docker Compose.

Response Formats

Standard Response (stream: false)

{
  "success": true,
  "data": {
    "content": "Generated text here...",
    "model": {
      "id": "s-sonic-edge-nexus",
      "name": "S-Sonic Edge Nexus",
      "engine": "ollama"
    },
    "metadata": {
      "circuit_breaker": "s-sonic",
      "cost_usd": 0,
      "tokens_used": 142,
      "latency_ms": 1832
    }
  }
}

SSE Streaming Response (stream: true)

data: {"content":"Hello"}
data: {"content":" there"}
data: {"content":"!"}
data: {"content":" How"}
data: {"content":" can"}
data: {"content":" I"}
data: {"content":" help"}
data: {"content":" you"}
data: {"content":"?"}
data: [DONE]

✦ Ignis Prime Online