API Documentation

📚 L.U.N.A. API Documentation

Endpoints

Authentication

API key authentication

All API endpoints (except /health and /version) require authentication via the X-API-Key header.

X-API-Key: your-api-key-here

POST /auth

Verify API key and get user role.

Request

curl -X POST https://test.sanvil.net/auth \
  -H "X-API-Key: your-api-key"

Response

{
  "status": "ok",
  "role": "user"
}

Voice

Speech-to-Text and Text-to-Speech endpoints

POST /voice

Full voice pipeline: Audio → STT → LLM → TTS → Audio

Parameters

Name	Type	Description
`audio` required	file	Audio file (WebM, OGG, WAV, MP4, M4A)
`model` optional	string	Whisper model: tiny, base, small

Request

curl -X POST https://test.sanvil.net/voice \
  -H "X-API-Key: your-api-key" \
  -F "audio=@recording.webm" \
  -o response.wav

Response

Returns WAV audio file. Transcript in header:

X-Transcript: Ciao, come stai?
Content-Type: audio/wav

POST /stt

Speech-to-Text only. Transcribe audio to text.

Request

curl -X POST https://test.sanvil.net/stt \
  -H "X-API-Key: your-api-key" \
  -F "audio=@recording.wav"

Response

{
  "text": "Questo e il testo trascritto."
}

POST /tts

Text-to-Speech only. Convert text to audio.

Request

curl -X POST https://test.sanvil.net/tts \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ciao mondo"}' \
  -o output.wav

Response

Content-Type: audio/wav
# Binary WAV audio file

Chat

Text chat with LLM

POST /chat

Text chat with LLM. Returns text response.

Body (JSON)

Name	Type	Description
`text` required	string	User message

Request

curl -X POST https://test.sanvil.net/chat \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ciao, come stai?"}'

Response

{
  "reply": "Ciao! Sto bene, grazie. Come posso aiutarti?"
}

Settings

User settings and available options

GET /settings

Get user settings.

Request

curl https://test.sanvil.net/settings \
  -H "X-API-Key: your-api-key"

Response

{
  "whisper_model": "base",
  "whisper_prompt": "Luna",
  "llm_model": "openai/gpt-4o-mini",
  "system_prompt": "Sei un assistente vocale...",
  "tts_voice": "aurora"
}

PUT /settings

Update user settings.

Request

curl -X PUT https://test.sanvil.net/settings \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "whisper_model": "small",
    "llm_model": "anthropic/claude-3.5-sonnet",
    "tts_voice": "paola"
  }'

Response

{"status": "ok"}

GET /voices

List available TTS voices.

Request

curl https://test.sanvil.net/voices

Response

{
  "voices": [
    {"id": "aurora", "name": "Aurora (Community)"},
    {"id": "paola", "name": "Paola (Default)"}
  ]
}

GET /models

List available LLM models from OpenRouter.

Request

curl https://test.sanvil.net/models

Response

{
  "models": [
    {"id": "openai/gpt-4o", "name": "GPT-4o", "context_length": 128000},
    {"id": "anthropic/claude-3.5-sonnet", "name": "Claude 3.5 Sonnet"}
  ]
}

System

Health check and system info

GET /health

Health check endpoint. No authentication required.

Request

curl https://test.sanvil.net/health

Response

{"status": "ok", "service": "gateway"}

GET /version

Get L.U.N.A. version info. No authentication required.

Request

curl https://test.sanvil.net/version

Response

{
  "name": "L.U.N.A.",
  "full_name": "Language Understanding Neural Agent",
  "version": "1.0.0",
  "author": "Sanvil",
  "year": 2025
}

GET /credits

Get OpenRouter credits balance.

Request

curl https://test.sanvil.net/credits \
  -H "X-API-Key: your-api-key"

Response

{"remaining": 4.52}