tools-only OpenAI-Compatible API Endpoints
For voice-mode, we exclusively use OpenAI-compatible API endpoints to ensure consistency and compatibility across different TTS/STT providers.
Documentation Endpoints
OpenAPI/Swagger
/docs- Interactive Swagger UI (FastAPI default)/redoc- Alternative ReDoc UI documentation/openapi.json- Raw OpenAPI 3.0 specification/swagger.json- Legacy Swagger 2.0 specification/api-docs- Common alternative path/api/docs- Another common variant
GraphQL
/graphql- GraphQL playground/graphiql- GraphQL IDE/__graphql- Apollo Server default
Discovery & Health Endpoints
Service Information
/- Root endpoint, often lists available resources/health- Basic health check/healthz- Kubernetes-style health check/readyor/readyz- Readiness check/status- Detailed service status/ping- Simple connectivity check/version- API version information/info- General service information
API Resources
/api- API root, lists versions/v1- Version-specific root/api/v1- Combined API version root
OpenAI-Compatible Endpoints (Used by voice-mode)
These are the standard OpenAI API endpoints we use:
Core Endpoints
/v1/models- List available models/v1/models/{model}- Get specific model details
Audio Endpoints
/v1/audio/speech- Text-to-speech generation/v1/audio/transcriptions- Speech-to-text transcription
Health/Status
/health- Basic health check (provider-specific)
Note: We intentionally avoid provider-specific endpoints like /v1/audio/voices to maintain compatibility across different providers.
Examples
Kokoro TTS
# Documentation
curl http://127.0.0.1:8880/docs
curl http://127.0.0.1:8880/openapi.json
# API endpoints
curl http://127.0.0.1:8880/v1/models
curl http://127.0.0.1:8880/v1/audio/voices
curl http://127.0.0.1:8880/health
OpenAI API
# Models
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
Tips
- Always check
/docsfirst - Most modern APIs provide interactive documentation - Look for OpenAPI spec -
/openapi.jsonprovides machine-readable API definition - Try without authentication first - Many discovery endpoints don't require auth
- Check response headers - Often contain API version and rate limit info
- Use browser for UI endpoints -
/docs,/redoc,/graphqlare meant for browsers