qiming/qiming-mcp-proxy/voice-cli/API_DOCUMENTATION.md

Voice CLI API Documentation

Overview

The Voice CLI API provides speech-to-text transcription services using OpenAI's Whisper models. The service supports multiple audio formats, automatic format conversion, and various Whisper model sizes for different accuracy/speed trade-offs.

Base URL

• Development: http://localhost:8080
• Production: https://api.voice-cli.dev

Interactive Documentation

Once the server is running, you can access the interactive Swagger UI documentation at:

• Swagger UI: http://localhost:8080/swagger-ui/
• OpenAPI JSON: http://localhost:8080/api-docs/openapi.json

Authentication

Currently, the API does not require authentication. This may change in future versions.

Supported Audio Formats

The API supports the following audio formats with automatic conversion:

• MP3 (.mp3)
• WAV (.wav) - preferred format
• FLAC (.flac)
• M4A (.m4a)
• AAC (.aac)
• OGG (.ogg)

Whisper Models

The following Whisper models are supported:

Model	Size	Languages	Speed	Accuracy	Use Case
tiny	~39 MB	EN/Multi	Fastest	Lowest	Real-time, low-resource
tiny.en	~39 MB	English	Fastest	Lowest	Real-time English only
base	~142 MB	EN/Multi	Fast	Good	General purpose
base.en	~142 MB	English	Fast	Good	General English
small	~244 MB	EN/Multi	Medium	Better	Higher accuracy needs
small.en	~244 MB	English	Medium	Better	Higher accuracy English
medium	~769 MB	EN/Multi	Slow	High	Professional transcription
medium.en	~769 MB	English	Slow	High	Professional English
large-v1	~1.5 GB	Multi	Slowest	Highest	Best quality multilingual
large-v2	~1.5 GB	Multi	Slowest	Highest	Best quality multilingual
large-v3	~1.5 GB	Multi	Slowest	Highest	Latest best quality

API Endpoints

1. Health Check

GET /health

Returns the current health status of the service.

Response Example:

{
  \"status\": \"healthy\",
  \"models_loaded\": [\"base\", \"small\"],
  \"uptime\": 3600,
  \"version\": \"0.1.0\"
}

cURL Example:

curl -X GET http://localhost:8080/health

2. List Models

GET /models

Returns information about available and loaded models.

Response Example:

{
  \"available_models\": [\"tiny\", \"base\", \"small\", \"medium\", \"large-v3\"],
  \"loaded_models\": [\"base\"],
  \"model_info\": {
    \"base\": {
      \"size\": \"142 MB\",
      \"memory_usage\": \"388 MB\",
      \"status\": \"loaded\"
    }
  }
}

cURL Example:

curl -X GET http://localhost:8080/models

3. Transcribe Audio

POST /transcribe

Transcribes an audio file to text using Whisper models.

Content-Type: multipart/form-data Max File Size: 200MB

Form Parameters:

Parameter	Type	Required	Description	Example
audio	file	Yes	Audio file to transcribe	audio.mp3
model	string	No	Whisper model to use	"base"
language	string	No	Language hint (ISO 639-1)	"en"
response_format	string	No	Output format	"json"

Response Format Options:

• json (default): Structured JSON with segments
• text: Plain text only
• verbose_json: JSON with detailed information

Response Example (JSON format):

{
  \"text\": \"Hello, this is a test transcription of the audio file.\",
  \"segments\": [
    {
      \"start\": 0.0,
      \"end\": 2.5,
      \"text\": \"Hello, this is a test transcription\",
      \"confidence\": 0.95
    },
    {
      \"start\": 2.5,
      \"end\": 4.0,
      \"text\": \"of the audio file.\",
      \"confidence\": 0.92
    }
  ],
  \"language\": \"en\",
  \"duration\": 4.0,
  \"processing_time\": 1.2
}

cURL Examples:

Basic transcription:

curl -X POST http://localhost:8080/transcribe \\n  -F \"audio=@example.mp3\"

With specific model and language:

curl -X POST http://localhost:8080/transcribe \\n  -F \"audio=@example.wav\" \\n  -F \"model=small\" \\n  -F \"language=en\"

Text-only response:

curl -X POST http://localhost:8080/transcribe \\n  -F \"audio=@example.flac\" \\n  -F \"response_format=text\"

JavaScript/Fetch Example:

const formData = new FormData();
formData.append('audio', audioFile);
formData.append('model', 'base');
formData.append('language', 'en');

fetch('http://localhost:8080/transcribe', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(data => {
  console.log('Transcription:', data.text);
  console.log('Processing time:', data.processing_time);
})
.catch(error => console.error('Error:', error));

Python Example:

import requests

with open('audio.mp3', 'rb') as audio_file:
    files = {'audio': audio_file}
    data = {
        'model': 'base',
        'language': 'en',
        'response_format': 'json'
    }
    
    response = requests.post(
        'http://localhost:8080/transcribe',
        files=files,
        data=data
    )
    
    if response.status_code == 200:
        result = response.json()
        print(f\"Transcription: {result['text']}\")
        print(f\"Processing time: {result['processing_time']}s\")
    else:
        print(f\"Error: {response.status_code} - {response.text}\")

Error Responses

All endpoints return structured error responses:

{
  \"error\": \"Error description\",
  \"status\": 400
}

Common Error Codes:

• 400 Bad Request: Missing required fields, invalid parameters
• 413 Payload Too Large: File exceeds 200MB limit
• 415 Unsupported Media Type: Unsupported audio format
• 500 Internal Server Error: Server-side processing error

Rate Limits

Currently, there are no rate limits imposed. This may change in future versions based on usage patterns.

Best Practices

1. Audio Quality: Use high-quality audio (16kHz or higher) for better transcription accuracy
2. File Size: Keep files under 200MB for optimal performance
3. Model Selection:
   • Use tiny or base for real-time applications
   • Use small or medium for better accuracy
   • Use large-v3 for the highest quality transcription
4. Language Hints: Provide language hints when known for better accuracy
5. Format: WAV format is preferred for fastest processing

Language Support

Whisper supports 99+ languages. Common language codes:

• en - English
• zh - Chinese
• es - Spanish
• fr - French
• de - German
• ja - Japanese
• ko - Korean
• pt - Portuguese
• ru - Russian
• ar - Arabic

Troubleshooting

Common Issues

1. "File too large" error: Ensure your audio file is under 200MB
2. "Unsupported format" error: Use supported audio formats (MP3, WAV, FLAC, etc.)
3. Slow processing: Try using a smaller model like tiny or base
4. Poor accuracy: Use a larger model and provide language hints

Server Logs

Check server logs for detailed error information:

# View real-time logs
tail -f logs/voice-cli.log

# Check service status
voice-cli server status

SDK and Libraries

Official SDKs and community libraries:

• JavaScript/TypeScript: Coming soon
• Python: Coming soon
• Go: Coming soon
• cURL: Use examples above

Support

For support and questions:

• GitHub Issues: Voice CLI Issues
• Documentation: This API documentation
• Email: support@voice-cli.dev

Changelog

v0.1.0 (Current)

• Initial API release
• Basic transcription functionality
• Support for multiple audio formats
• Whisper model management
• OpenAPI documentation