Phemius API

High-quality text-to-speech API with real-time WebSocket streaming, OpenAI drop-in compatibility, and voice cloning.

Authentication

All API requests require a valid API key passed via the Authorization header. Keys are prefixed with sk_test_ (test) or sk_live_ (production). Keys are hashed server-side and cannot be recovered — store them securely after creation.

Authorization: Bearer sk_test_abc123...

Quickstart

curl -X POST https://api.phemius.dev/v1/speech \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Integrate natural sounding speech into your application with just a few lines of code. Low latency, high fidelity, and built for scale.", "voice": "shimmer", "model": "phemius-fast"}' \
  --output speech.pcm

Create Speech

Synthesize text to speech. Returns raw PCM audio (16-bit, 24kHz, mono). Characters are billed after successful synthesis.

Request Body

Response

Errors

Examples

curl -X POST https://api.phemius.dev/v1/speech \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice": "nova"}' \
  --output speech.pcm

Stream Speech (WebSocket)

Real-time streaming speech synthesis over WebSocket. Audio is delivered as binary frames as it's generated, enabling low-latency playback. Ideal for interactive applications.

Protocol Flow

{
  "api_key": "sk_test_YOUR_KEY"
}

{
  "text": "Hello world",
  "voice": "nova",
  "model": "phemius-fast",
  "speed": 1
}

{
  "done": true,
  "chars_billed": 11,
  "ttfb_ms": 245,
  "cached": false
}

Request Fields

Close Codes

Error Messages

These errors are sent as JSON messages before the connection closes — they are not WebSocket close codes.

Examples

const ws = new WebSocket('wss://api.phemius.dev/v1/speech/stream');

ws.onopen = () => {
  ws.send(JSON.stringify({ api_key: 'sk_test_YOUR_KEY' }));
  ws.send(JSON.stringify({
    text: 'Hello world',
    voice: 'nova',
    speed: 1.0,
  }));
};

const chunks = [];
ws.onmessage = (event) => {
  if (event.data instanceof Blob) {
    // Binary audio chunk — append to buffer or play immediately
    chunks.push(event.data);
  } else {
    const msg = JSON.parse(event.data);
    if (msg.done) {
      console.log(`Billed: ${msg.chars_billed} chars, TTFB: ${msg.ttfb_ms}ms`);
    } else if (msg.error) {
      console.error(`Error ${msg.code}: ${msg.error}`);
    }
  }
};

Create Speech (OpenAI Compatible)

Drop-in replacement for the OpenAI TTS API. Use your existing OpenAI SDK code — just change the base URL and API key. Always returns raw PCM audio.

Request Body

Response

Errors

Voice Mapping

OpenAI voice names are first mapped to Phemius voice names, which then resolve to Kokoro voicepacks. You can also pass Phemius voice names or raw voicepack names directly.

Examples

curl -X POST https://api.phemius.dev/v1/speech \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Integrate natural sounding speech into your application with just a few lines of code. Low latency, high fidelity, and built for scale.", "voice": "shimmer", "model": "phemius-fast"}' \
  --output speech.pcm

List Voices

List all custom voices belonging to the authenticated user.

Response

{
  "voices": [
    {
      "id": "uuid",
      "name": "string",
      "model": "phemius-fast",
      "created_at": "datetime"
    }
  ]
}

Errors

Examples

curl -H "Authorization: Bearer sk_test_YOUR_KEY" \
  https://api.phemius.dev/v1/voices

Create Voice

Create a new custom voice. Free plan is limited to 2 voices.

Request Body

Response

{
  "id": "uuid",
  "name": "string",
  "model": "string",
  "created_at": "datetime"
}

Errors

Examples

curl -X POST https://api.phemius.dev/v1/voices \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

Delete Voice

Delete a custom voice by ID. Only the owner can delete their voices.

Path Parameters

Response

Errors

Examples

curl -X DELETE https://api.phemius.dev/v1/voices/YOUR_VOICE_ID \
  -H "Authorization: Bearer sk_test_YOUR_KEY"

List Jobs

List all async jobs (voice cloning, bulk synthesis) for the authenticated user, ordered by most recent first.

Response

{
  "jobs": [
    {
      "id": "uuid",
      "type": "string",
      "status": "queued",
      "progress": "number",
      "result": "object|null",
      "error": "string|null",
      "created_at": "datetime",
      "updated_at": "datetime"
    }
  ]
}

Errors

Examples

curl -H "Authorization: Bearer sk_test_YOUR_KEY" \
  https://api.phemius.dev/v1/jobs

Get Job

Get the status and details of a specific async job.

Path Parameters

Response

{
  "id": "uuid",
  "type": "string",
  "status": "queued",
  "progress": "number",
  "result": "object|null",
  "error": "string|null",
  "created_at": "datetime",
  "updated_at": "datetime"
}

Errors

Examples

curl -H "Authorization: Bearer sk_test_YOUR_KEY" \
  https://api.phemius.dev/v1/jobs/YOUR_JOB_ID

OpenAI TTS Migration

Phemius is a drop-in replacement for the OpenAI TTS API. Change two lines — base URL and API key — and your existing code works immediately.

from openai import OpenAI
client = OpenAI(api_key="sk-...")

response = client.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="Hello world",
)
response.stream_to_file("speech.pcm")

from openai import OpenAI
client = OpenAI(
    api_key="sk_test_YOUR_PHEMIUS_KEY",
    base_url="https://api.phemius.dev/v1",
)

response = client.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="Hello world",
)
response.stream_to_file("speech.pcm")

Key Differences

• Only tts-1 model is supported (tts-1-hd is not available)
• All six OpenAI voices are mapped to Kokoro equivalents
• Both endpoints return raw PCM audio — no format conversion
• Same speed range: 0.25x to 4.0x
• Higher character limit per request: 10,000 chars (vs OpenAI's 4,096)

Audio Formats

Native Endpoint /v1/speech

The native /v1/speech endpoint always returns raw PCM audio (16-bit signed, 24kHz, mono). There is no response_format parameter — the output is always PCM. To play it:

ffplay -f s16le -ar 24000 -ch_layout mono speech.pcm

OpenAI-Compatible Endpoint /v1/audio/speech

The OpenAI-compatible /v1/audio/speech endpoint also always returns raw PCM audio. There is no response_format parameter.

WebSocket Streaming

The WebSocket endpoint at /v1/speech/stream enables real-time audio streaming with low time-to-first-byte. Audio chunks are sent as binary WebSocket frames as they're generated.

Audio Specification

Connection Flow

1. 1Connect to wss://api.phemius.dev/v1/speech/stream
2. 2Send JSON: {"api_key": "sk_test_..."}
3. 3Send JSON: {"text": "...", "voice": "...", ...}
4. 4Receive binary audio chunks
5. 5Receive JSON: {"done": true, "chars_billed": N, "ttfb_ms": N, "cached": bool}

Rate Limits

Rate limits are applied per API key and reset on a rolling window (requests per minute) or monthly (character limits).

Error Handling

HTTP Errors

WebSocket Close Codes

WebSocket Error Messages

Sent as JSON before the connection closes — not WebSocket close frame codes.

Built-in Voices

The following voices are available with any speech endpoint. Pass the name as the voice parameter.

Plans & Limits