Galactic Radio MusicGen API

Register a new user. Returns an API key (shown once).

Request Body

curl -X POST http://localhost:8216/api/v1/users/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret123"}'

Response (201)

{
  "uid": "abc123",
  "email": "user@example.com",
  "api_key": "grm_xxxxxxxxxxxx",
  "credits_balance": 3,
  "message": "Account created. Store this API key securely..."
}

OAuth sign-in callback. Provisions profile and API key for new users.

curl -X POST http://localhost:8216/api/v1/users/oauth-signin \
  -H "Authorization: Bearer <firebase_id_token>"

Response (200)

{
  "uid": "firebase_uid",
  "email": "user@gmail.com",
  "display_name": "John Doe",
  "api_key": "grm_xxxxxxxxxxxx",  // only for new users
  "credits_balance": 3,
  "is_new_user": true
}

Get current user profile.

curl http://localhost:8216/api/v1/users/me \
  -H "X-API-Key: grm_xxxxxxxxxxxx"

Response (200)

{
  "uid": "abc123",
  "email": "user@example.com",
  "display_name": "John",
  "bio": "Music enthusiast",
  "avatar_url": "https://...",
  "role": "user",
  "credits_balance": 3,
  "api_key_count": 1,
  "created_at": "2026-04-17T12:00:00+00:00"
}

Update profile fields (display_name, bio).

Request Body

curl -X PATCH http://localhost:8216/api/v1/users/me \
  -H "X-API-Key: grm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "DJ Nebula", "bio": "Making cosmic beats"}'

Get aggregated play statistics for the current user's songs.

curl http://localhost:8216/api/v1/users/me/stats \
  -H "X-API-Key: grm_xxxxxxxxxxxx"

Response (200)

{
  "total_songs": 12,
  "total_plays": 150,
  "plays_by_location": {"web-player": 100, "discord-bot": 50},
  "top_songs": [
    {"song_id": "song_abc123", "title": "Hit Track", "play_count": 42}
  ]
}

Generate a new API key. The raw key is returned once.

curl -X POST http://localhost:8216/api/v1/users/api-keys \
  -H "X-API-Key: grm_xxxxxxxxxxxx"

Response (200)

{
  "api_key": "grm_new_key_here",
  "message": "Store this key securely — it will not be shown again"
}

Revoke an API key by its hash prefix.

curl -X DELETE http://localhost:8216/api/v1/users/api-keys/abc123 \
  -H "X-API-Key: grm_xxxxxxxxxxxx"

Upload a custom avatar image. Max 2MB, JPEG or PNG only.

curl -X POST http://localhost:8216/api/v1/users/me/avatar \
  -H "X-API-Key: grm_xxxxxxxxxxxx" \
  -F "file=@avatar.jpg"

Response (200)

{
  "uid": "abc123",
  "email": "user@example.com",
  "display_name": "John",
  "avatar_url": "https://storage.googleapis.com/.../avatar.jpg",
  ...
}

Generate a new song via Google Lyria 3 API. Costs credits.

Request Body

curl -X POST http://localhost:8216/api/v1/songs/generate \
  -H "X-API-Key: grm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cosmic Dawn",
    "genre": "ambient electronic",
    "mood": "ethereal",
    "artist_name": "DJ Nebula",
    "generation_type": "full_song"
  }'

Response (201)

Returns the full Song object.

Generate across multiple providers in one request. Same body as /generate plus an optional providers array (defaults to all). A failure in one provider never aborts the others.

Providers

curl -X POST http://localhost:8216/api/v1/songs/generate-multi \
  -H "X-API-Key: grm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cosmic Dawn",
    "genre": "ambient electronic",
    "mood": "ethereal",
    "providers": ["suno", "lyria", "elevenlabs"]
  }'

Response (201)

{
  "title": "Cosmic Dawn",
  "credits_charged": 2,
  "credits_balance": 8,
  "results": [
    {"provider": "lyria", "kind": "audio", "status": "completed", "song": { /* Song */ }},
    {"provider": "elevenlabs", "kind": "audio", "status": "completed", "song": { /* Song */ }},
    {"provider": "suno", "kind": "audio", "status": "completed", "song": { /* Song (variation 1) */ }},
    {"provider": "suno", "kind": "audio", "status": "completed", "song": { /* Song (variation 2) */ }}
  ]
}

Each result has kind (audio or text) and status (completed or failed, with an actionable error_message). Audio results carry a full Song; text results carry a text prompt.

Get a song by ID.

curl http://localhost:8216/api/v1/songs/song_abc123 \
  -H "X-API-Key: grm_xxxxxxxxxxxx"

List and search songs with filtering, search, and shuffle.

Query Parameters

# Search for country songs about love
curl "http://localhost:8216/api/v1/songs?q=love&genre=country&limit=10" \
  -H "X-API-Key: grm_xxxxxxxxxxxx"

# 5 random songs for radio shuffle
curl "http://localhost:8216/api/v1/songs?shuffle=true&limit=5" \
  -H "X-API-Key: grm_xxxxxxxxxxxx"

Response (200)

{
  "songs": [ ... ],  // array of Song objects
  "total": 42,
  "limit": 20,
  "offset": 0
}

Record a play event for analytics.

Request Body

curl -X POST http://localhost:8216/api/v1/songs/song_abc123/play \
  -H "X-API-Key: grm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"location": "web-player"}'

Update song metadata. Owner or admin only. At least one field required.

Request Body

curl -X PATCH http://localhost:8216/api/v1/songs/song_abc123 \
  -H "X-API-Key: grm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title", "genre": "jazz"}'

Response (200)

Returns the updated Song object.

Upload cover art for a song. Max 2MB, JPEG or PNG only. Owner or admin only.

curl -X POST http://localhost:8216/api/v1/songs/song_abc123/art \
  -H "X-API-Key: grm_xxxxxxxxxxxx" \
  -F "file=@cover.jpg"

Response (200)

{
  "cover_art_url": "https://storage.googleapis.com/.../cover.jpg",
  "song_id": "song_abc123"
}

Delete a song. Only the owner or an admin can delete.

curl -X DELETE http://localhost:8216/api/v1/songs/song_abc123 \
  -H "X-API-Key: grm_xxxxxxxxxxxx"

Get current credits balance.

curl http://localhost:8216/api/v1/credits/balance \
  -H "X-API-Key: grm_xxxxxxxxxxxx"

Response (200)

{"credits_balance": 3}

Purchase credits (AP2 placeholder — returns payment_required status).

Request Body

curl -X POST http://localhost:8216/api/v1/credits/purchase \
  -H "X-API-Key: grm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10}'

Response (200)

{
  "status": "payment_required",
  "ap2_metadata": {
    "protocol": "ap2",
    "provider": "galactic-radio-musicgen",
    "amount_requested": 10,
    "currency": "credits",
    "message": "AP2 payment integration coming soon"
  }
}

Agent discovery card. Returns service capabilities, skills, and authentication requirements.

curl http://localhost:8216/.well-known/agent.json

Skills

• generate_music — Generate a song using Lyria 3
• search_songs — Search the song catalog
• get_song — Retrieve a specific song
• purchase_credits — Purchase credits (AP2 placeholder)

JSON-RPC 2.0 endpoint for agent task execution. Supports tasks/send method.

curl -X POST http://localhost:8216/a2a \
  -H "X-API-Key: grm_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/send",
    "id": 1,
    "params": {
      "skill_id": "search_songs",
      "input": {"q": "ambient", "limit": 5}
    }
  }'

Response (200)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task-uuid",
    "status": {"state": "completed"},
    "artifacts": [{
      "parts": [{
        "type": "data",
        "data": {"songs": [...], "total": 5}
      }]
    }]
  }
}

Health check. Returns service status.

curl http://localhost:8216/api/v1/health

Response (200)

{
  "status": "ok",
  "version": "1.0.0",
  "environment": "development",
  "services": {
    "firestore": "connected",
    "music_gen": "configured"
  }
}

Server name, version, and environment.

curl http://localhost:8216/api/v1/info

View current runtime config (models, credits, storage).

curl http://localhost:8216/api/v1/config \
  -H "X-API-Key: grm_admin_key"

Update runtime config values (in-memory, not persisted to .env).

curl -X PATCH http://localhost:8216/api/v1/config \
  -H "X-API-Key: grm_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"lyria_pro_model": "lyria-3-pro-v2", "credits_per_full_song": 2}'