DJ Library

Create

Name *

Summary

Personality Profile

Generate Accent with AI

Accent Name

Description

Authentication

All authenticated endpoints require either a Firebase ID token or an API key.

GET Firebase Google Sign-In

Browser authentication uses Firebase Google Sign-In. After signing in, the Firebase ID token is sent as a Bearer token in the Authorization header.

Authorization: Bearer <firebase-id-token>

GET API Key Authentication

For programmatic access, use an API key in the X-API-Key header. Create keys in the API Keys tab.

X-API-Key: djb_your_api_key_here

DJ Management

POST /djs/submit AUTH

Submit a new DJ profile with character data.

{
  "json_data": {
    "character_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "DJ Awesome",
    "sex": "Non-binary",
    "age": 28,
    "summary": "An amazing DJ with unique style",
    "species": "Human",
    "appearance": "Tall with colorful hair",
    "personality": "Energetic and creative"
  }
}

GET /djs

List all DJ profiles with optional filtering.

Parameter	Type	Description
search	string	Filter by name, species, or summary
limit	integer	Maximum results to return (default: 100)
offset	integer	Number of results to skip (pagination)

GET /djs/count

Get total number of DJ profiles in the system.

GET /djs/{character_uuid}

Retrieve detailed information for a specific DJ by UUID.

GET /djs/{character_uuid}/pretty

Get DJ details as formatted HTML for display purposes.

PUT /djs/{character_uuid} AUTH

Update an existing DJ profile.

DELETE /djs/{character_uuid} AUTH

Permanently delete a DJ profile and all associated data.

// 200
{ "message": "DJ deleted successfully" }

// 404
{ "detail": "DJ not found" }

Voice Accents

Manage voice accent profiles for character audio generation.

GET /accents

List all available voice accents.

POST /accents AUTH

Create a new voice accent profile.

{
  "accent_name": "Southern American",
  "accent_description_short": "Warm Southern drawl",
  "accent_description_long": "A distinctive Southern American accent with elongated vowels and gentle rhythm",
  "accent_notes": "Popular in country music and storytelling",
  "tags": ["american", "southern", "warm", "storytelling"]
}

PUT /accents/{accent_id} AUTH

Update an existing voice accent.

DELETE /accents/{accent_id} AUTH

Delete a voice accent profile permanently.

// 200
{ "message": "Accent deleted successfully" }

POST /accents/generate AUTH

Generate a new voice accent using AI based on description.

{
  "description": "Create a mysterious Eastern European accent suitable for a vampire character"
}

GET /accents/{accent_id}/json

Get accent data in JSON format for API consumption.

GET /accents/{accent_id}/pretty

Get accent as formatted HTML for display.

GET /accents/{accent_id}/download

Download accent data as a file.

GET /accents/pretty

Get all accents as formatted HTML page.

GET /accents/download

Download all accent data as export file.

Voice Modifiers

Manage voice modifier effects and processing options.

GET /voice-modifiers

List all available voice modifiers.

POST /voice-modifiers AUTH

Create a new voice modifier.

{
  "modifier_name": "Robotic Effect",
  "modifier_description_short": "Mechanical voice processing",
  "modifier_description_long": "Adds robotic metallic effect with digital distortion and monotone delivery",
  "modifier_notes": "Great for AI character voices",
  "tags": ["robotic", "mechanical", "sci-fi", "digital"]
}

PUT /voice-modifiers/{modifier_id} AUTH

Update an existing voice modifier.

DELETE /voice-modifiers/{modifier_id} AUTH

Delete a voice modifier permanently.

// 200
{ "message": "Voice modifier deleted successfully" }

POST /voice-modifiers/generate AUTH

Generate a new voice modifier using AI.

{
  "description": "Create an ethereal angelic voice modifier with reverb and harmony"
}

GET /voice-modifiers/{modifier_id}/json

Get voice modifier data in JSON format.

GET /voice-modifiers/{modifier_id}/pretty

Get voice modifier as formatted HTML.

GET /voice-modifiers/{modifier_id}/download

Download voice modifier data.

GET /voice-modifiers/pretty

Get all voice modifiers as formatted HTML.

GET /voice-modifiers/download

Download all voice modifier data.

Voice Generation

Generate audio using various voice synthesis engines.

POST /voice/generate AUTH

Generate voice audio with specified configuration.

Request Body:

{
  "text": "Hello, this is a test of the voice generation system!",
  "voice_factory": "elevenlabs_v3",
  "voice_id": "pNInz6obpgDQGcFmaJgB",
  "voice_settings": {
    "stability": 0.75,
    "similarity_boost": 0.75,
    "style": 0.5
  }
}

Response:

{
  "audio_url": "https://storage.googleapis.com/bucket/generated_audio_123.mp3",
  "duration": 3.2,
  "character_count": 52,
  "generation_time": 1.8
}

POST /voice/test AUTH

Test voice configuration with sample text.

GET /voice/presets

Get available voice presets and configurations.

{
  "elevenlabs_v3": {
    "voices": [
      {
        "voice_id": "pNInz6obpgDQGcFmaJgB",
        "name": "Adam",
        "gender": "Male",
        "description": "Deep, authoritative voice"
      }
    ]
  },
  "gemini": {
    "voices": [
      {
        "voice_id": "en-US-Journey-D",
        "name": "Journey",
        "gender": "Male",
        "description": "Natural, conversational"
      }
    ]
  }
}

GET /voice/factory-config/{factory}

Get configuration options for specific voice factory.

POST /voice/save-configuration/{dj_id} AUTH

Save voice configuration to a DJ profile.

File Upload

Upload and manage media files for DJ profiles.

POST /photo AUTH

Upload photo files for DJ profiles.

Parameter	Type	Description
file	multipart/form-data	Image file (JPEG, PNG, GIF, WebP)
character_uuid	string	UUID of the DJ to associate with

// Response 200
{
  "message": "Photo uploaded successfully",
  "photo_url": "https://storage.googleapis.com/bucket/photos/uuid_photo.jpg",
  "file_size": 1024576,
  "dimensions": "1920x1080"
}

POST /audio AUTH

Upload audio files for DJ profiles.

Parameter	Type	Description
file	multipart/form-data	Audio file (MP3, WAV, OGG, WebM)
character_uuid	string	UUID of the DJ to associate with

DELETE /file AUTH

Delete uploaded file from storage.

{
  "file_url": "https://storage.googleapis.com/bucket/files/filename.jpg"
}

API Keys

Manage API keys for programmatic access.

GET /api-keys AUTH

List all API keys for the authenticated user.

POST /api-keys AUTH

Create a new API key.

{
  "name": "Production App",
  "description": "Used by the mobile app",
  "rate_limit": 60
}

DELETE /api-keys/{key_id} AUTH

Revoke and delete an API key.

PUT /api-keys/{key_id}/toggle AUTH

Toggle an API key between active and revoked status.

System

System utilities and helper endpoints.

POST /proxy/fetch-and-upload AUTH

Fetch external content and upload to storage.

{
  "url": "https://example.com/image.jpg",
  "character_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

GET /system/info

Get system information and status.

{
  "version": "1.0.0",
  "environment": "production",
  "database_status": "healthy",
  "storage_status": "healthy",
  "uptime": 86400
}

GET /health

Health check endpoint for monitoring.

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z"
}

GET /media/{path:path}

Serve media files (images, audio) with proper headers.

GET /

Main application page - DJ listing and management interface.

GET /edit

DJ editing page with voice generation tools.

Access Management

Name	Key Prefix	Rate Limit	Status	Created	Actions

TTS System

TTS Factories

Loading factories...

TTS System

TTS Models

Loading models...

TTS System

TTS Voices

Demo Script Note: page needs to refresh to take effect

Emotions:

Audio Events:

Overall Direction:

Loading voices...

TTS System

TTS Overview

Loading hierarchy...

System Architecture

Galactic Radio DJs — How It All Works

Complete technical reference. Covers the full stack: DJ creation, voice synthesis, authentication, API endpoints, and deployment.

System Overview

High-level architecture and how each layer connects

Galactic Radio DJs is a FastAPI service for building and managing AI radio DJ personalities. Users create DJ profiles with names, personalities, and photos, then configure voices using the TTS management system. The service supports voice demo generation, accent/modifier management, and a full REST API.

FrameworkFastAPI

DatabaseSQLite

AuthFirebase

TTSElevenLabs

DeployCloud Run

Python3.12+

DJ Creation Pipeline

How a DJ goes from concept to broadcast-ready personality

Create DJ

Submit a new DJ profile with a name. The system assigns a UUID and creates a database record.

POST /djs/submit

Set Profile

Add personality traits, summary, appearance notes, species, age, and tags.

PUT /djs/{character_uuid}

Upload Photos

Upload character photos or fetch from external URLs. Stored in Google Cloud Storage.

POST /upload/photo

Configure Voice

Select a TTS factory and voice. Configure stability, similarity boost, and style. Assign accents and modifiers.

POST /api/voice/save-configuration/{dj_id}

Generate Test Audio

Generate a test audio clip using the configured voice. Preview how the DJ sounds.

POST /api/voice/generate

Ready to Broadcast

The DJ is fully configured. Ready to be used by downstream services like Galactic Radio Weather.

Voice & TTS System

How TTS factories, models, and voices relate

The TTS system is organized in a three-level hierarchy. Factories represent TTS providers (like ElevenLabs), models represent specific engine versions within a factory, and voices are the individual voice identities that produce audio.

TTS Management: Manage factories, models, and voices from the Factories, Models, and Voices tabs in the sidebar.

Modifiers System

How accents and voice modifiers shape DJ voices

The modifier system provides two types of voice customization that can be layered onto any DJ voice configuration:

Voice Accents

Accent profiles define how a DJ's speech patterns should sound — Southern drawl, British RP, Brooklyn, etc. Each accent includes descriptions for display and TTS prompting. Accents can be manually created or AI-generated.

Voice Modifiers

Voice modifiers are processing effects — robotic effect, whisper mode, echo, etc. Like accents, they include descriptions and can be AI-generated.

Authentication

Two auth methods serving different client types

Web UI

Firebase Google Sign-In

Browser authentication uses Firebase Google Sign-In. The Firebase ID token is sent as a Bearer token in the Authorization header.

Programmatic

API Key

For programmatic access, users generate API keys (prefixed djb_) from the API Keys tab. Keys are sent via the X-API-Key header.

API Reference

REST endpoints and their purpose

Method	Endpoint	Description	Auth
DJ Management
POST	`/djs/submit`	Create a new DJ profile	Required
GET	`/djs`	List all DJ profiles	None
PUT	`/djs/{uuid}`	Update DJ profile	Required
DELETE	`/djs/{uuid}`	Delete DJ and all data	Required
Voice Generation
POST	`/api/voice/generate`	Generate voice audio	Required
GET	`/api/voice/presets`	List voice presets	None
TTS Management
GET	`/api/tts/factories`	List TTS factories	Required
GET	`/api/tts/voices`	List TTS voices	Required
GET	`/api/tts/factory-hierarchy`	Full factory/model/voice tree	Required
System
GET	`/health`	Health check	None
GET	`/system/info`	System information	None

Tech Stack

Every tool and service in the system

Backend

FastAPIWeb framework

SQLiteDatabase

UvicornASGI server

AI / Voice

ElevenLabsTTS synthesis

GeminiAI generation

Google Cloud

Cloud RunContainer hosting

Cloud StorageAudio & photo files

Firebase AuthOAuth + tokens

Frontend

Vanilla JSNo framework

CSS VariablesGlass morphism

Galactic Radio DJs

No DJs Found

Generate Accent with AI

No Voice Accents

Generate Voice Modifier with AI

No Voice Modifiers

Edit

Authentication

DJ Management

Voice Accents

Voice Modifiers

Voice Generation

File Upload

API Keys

System

No API Keys

Create API Key

API Key Created

TTS Factories

TTS Models

TTS Voices

TTS Overview

Galactic Radio DJs — How It All Works

System Overview

DJ Creation Pipeline

Create DJ

Set Profile

Upload Photos

Configure Voice

Generate Test Audio

Ready to Broadcast

Voice & TTS System

Modifiers System

Voice Accents

Voice Modifiers

Authentication

Firebase Google Sign-In

API Key

API Reference

Tech Stack

Backend

AI / Voice

Google Cloud

Frontend

DJ Details

Add Factory

Add Model

Add Voice