VM
Voicemagic API

API Reference

The Voicemagic REST API lets you generate speech, manage voices, and retrieve generations programmatically. It also exposes an MCP server for AI agent integrations.

Base URLhttps://voicemagic.dev

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. Generate a key in your Settings page.

Authorization: Bearer vm_your_api_key_here

API keys are scoped to your organization. They grant access to your organization's custom voices and generations. Store them securely — you will only see the full key once when it is created.

Endpoints

GET/api/v1/voices

List all available voices — both system voices shared across all organizations, and custom voices you have created.

Response

{
  "voices": [
    {
      "id": "clx...",
      "name": "Sarah",
      "description": "Warm and conversational",
      "category": "CONVERSATIONAL",
      "language": "en-US",
      "variant": "SYSTEM"
    }
  ]
}

cURL example

curl https://voicemagic.dev/api/v1/voices \
  -H "Authorization: Bearer vm_your_api_key"
POST/api/v1/tts

Generate speech from text. Returns a generation ID and an audio URL. Consumes metered credits.

Request body

{
  "text": "Hello from Voicemagic!",
  "voiceId": "clx...",
  "temperature": 0.8,
  "topP": 0.95,
  "topK": 1000,
  "repetitionPenalty": 1.2
}

Response

{
  "id": "clx...",
  "audioUrl": "/api/v1/audio/clx..."
}

cURL example

curl -X POST https://voicemagic.dev/api/v1/tts \
  -H "Authorization: Bearer vm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from Voicemagic!",
    "voiceId": "clx..."
  }'
GET/api/v1/audio/{id}

Stream the WAV audio for a generation by its ID. Returns the raw audio bytes with Content-Type: audio/wav.

Response

<binary WAV audio stream>

cURL example

curl https://voicemagic.dev/api/v1/audio/clx... \
  -H "Authorization: Bearer vm_your_api_key" \
  --output speech.wav
GET/api/v1/generations/{id}

Retrieve metadata and the audio URL for a specific generation.

Response

{
  "id": "clx...",
  "text": "Hello from Voicemagic!",
  "voiceName": "Sarah",
  "voiceId": "clx...",
  "temperature": 0.8,
  "topP": 0.95,
  "topK": 1000,
  "repetitionPenalty": 1.2,
  "createdAt": "2026-04-21T12:00:00.000Z",
  "audioUrl": "/api/v1/audio/clx..."
}

cURL example

curl https://voicemagic.dev/api/v1/generations/clx... \
  -H "Authorization: Bearer vm_your_api_key"

MCP Server

Voicemagic exposes a Model Context Protocol (MCP) server, allowing AI agents like Claude to generate speech directly.

Endpoint

https://voicemagic.dev/api/mcp

Available tools

list_voices

Lists all available system and custom voices for your organization.

generate_speech

Generates TTS audio from text using a specified voice. Returns an audio URL.

get_generation

Retrieves generation metadata and the audio URL for a given generation ID.

Add to Claude Code (claude_code_config.json)

{
  "mcpServers": {
    "voicemagic": {
      "type": "http",
      "url": "https://voicemagic.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer vm_your_api_key"
      }
    }
  }
}
Voicemagic API — v1Back to app