Config Voice

Config Voice - Voice Profile & ASR Management

Overview

Manage voice profiles for VibeSurf. Configure ASR (Automatic Speech Recognition) providers, models, and perform speech-to-text conversion.

Supported ASR providers:

• qwen-asr - Alibaba Qwen ASR models
• openai-asr - OpenAI Whisper API
• gemini-asr - Google Gemini ASR

When to Use

• User wants to add a new voice profile for ASR
• User needs to configure speech-to-text settings
• User wants to update voice profile settings (API key, model params, etc.)
• User needs to list or manage existing voice profiles
• User wants to perform voice recognition (ASR) on an audio file
• User wants to see available voice models

API Endpoints

Base path: $VIBESURF_ENDPOINT/api/voices

Voice Profile Management

| Action | Method | Endpoint | Description | |--------|--------|----------|-------------| | List Profiles | GET | /api/voices/voice-profiles?active_only=true | List all voice profiles | | Get Profile | GET | /api/voices/{voice_profile_name} | Get specific profile details | | Create Profile | POST | /api/voices/voice-profiles | Create new voice profile | | Update Profile | PUT | /api/voices/voice-profiles/{voice_profile_name} | Update existing profile |

ASR (Speech Recognition)

| Action | Method | Endpoint | Description | |--------|--------|----------|-------------| | Perform ASR | POST | /api/voices/asr | Transcribe audio file to text |

Model Management

| Action | Method | Endpoint | Description | |--------|--------|----------|-------------| | List Models | GET | /api/voices/models | Get available voice models |

Request Examples

Create ASR Profile

POST /api/voices/voice-profiles
{
  "voice_profile_name": "my-qwen-asr",
  "voice_model_type": "asr",
  "voice_model_name": "qwen-asr",
  "api_key": "sk-...",
  "voice_meta_params": {
    "asr_model_name": "qwen-audio-asr-latest"
  },
  "description": "Qwen ASR for Chinese speech recognition"
}

Create OpenAI Whisper Profile

POST /api/voices/voice-profiles
{
  "voice_profile_name": "my-whisper",
  "voice_model_type": "asr",
  "voice_model_name": "openai-asr",
  "api_key": "sk-...",
  "voice_meta_params": {
    "asr_model_name": "whisper-1",
    "base_url": "https://api.openai.com/v1"  // Optional, for custom endpoints
  },
  "description": "OpenAI Whisper for English transcription"
}

Update Profile

PUT /api/voices/voice-profiles/my-qwen-asr
{
  "api_key": "new-api-key",
  "description": "Updated description",
  "is_active": true
}

Perform ASR (Speech Recognition)

POST /api/voices/asr
Content-Type: multipart/form-data

Form fields:
- audio_file:  (required) - Audio file to transcribe (wav, mp3, etc.)
- voice_profile_name: "my-qwen-asr" (required) - Name of the voice profile to use

Response:

{
  "success": true,
  "voice_profile_name": "my-qwen-asr",
  "voice_model_name": "qwen-asr",
  "recognized_text": "Transcribed text from audio",
  "filename": "recording.wav",
  "saved_audio_path": "/workspace/audios/asr-20250210_120000_000.wav"
}

Profile Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | voiceprofilename | string | Yes | Unique profile identifier | | voicemodeltype | string | Yes | Type: "asr" or "tts" (currently ASR is supported) | | voicemodelname | string | Yes | Model name: qwen-asr, openai-asr, gemini-asr | | apikey | string | No | API key for the provider (required for most providers) | | voicemetaparams | object | No | Model-specific parameters | | description | string | No | Profile description | | isactive | bool | No | Whether the profile is active (default: true) |

voicemetaparams by Provider

Qwen ASR: | Parameter | Type | Description | |-----------|------|-------------| | asrmodelname | string | Qwen model name, e.g., qwen-audio-asr-latest |

OpenAI Whisper: | Parameter | Type | Description | |-----------|------|-------------| | asrmodelname | string | Model name, e.g., whisper-1 | | base_url | string | Optional custom base URL for OpenAI-compatible APIs |

Gemini ASR: | Parameter | Type | Description | |-----------|------|-------------| | asrmodelname | string | Gemini model name |

Workflow

Setting up a Voice Profile

1. Get available models → GET /api/voices/models
2. Create profile → POST /api/voices/voice-profiles
3. Verify profile → GET /api/voices/{voice_profile_name}

Performing Speech Recognition

1. Ensure profile exists → GET /api/voices/voice-profiles (list active profiles)
2. Submit audio for transcription → POST /api/voices/asr with audio_file and voice_profile_name
3. Get recognized text from response recognized_text field

Error Handling

| Error | Solution | |-------|----------| | Profile not found | Verify voice_profile_name exists: GET /api/voices/voice-profiles | | Profile is inactive | Activate profile: PUT /api/voices/voice-profiles/{name} with "is_active": true | | Invalid voicemodeltype | Must be "asr" or "tts" | | Model not supported | Check available models: GET /api/voices/models | | ASR failed | Check API key is valid and audio file format is supported |

Notes

• Audio files are saved to {workspace_dir}/audios/ with timestamp-based filenames
• Supported audio formats depend on the ASR provider (typically WAV, MP3, M4A)
• The voice_profile_name parameter is required for ASR requests
• Profiles store API keys encrypted in the database

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vibesurf-ai
• Source: vibesurf-ai/claude-surf
• License: MIT

Install and usage instructions live in the source repository linked above.