TTS / STT API

Synthesize Speech

Convert text to audio.

POST /v1/synthesize

Request Body

{
  "text": "Hello world, this is a test.",
  "voiceId": "default",
  "format": "wav",
  "speed": 1.0,
  "pitch": 1.0,
  "provider": "cartesia"
}

Field	Type	Default	Description
text	string	required	Text to synthesize (1-10,000 chars)
voiceId	string	"default"	Voice identifier
format	string	"wav"	Output format: mp3, wav, ogg
speed	number	1.0	Playback speed (0.5-2.0)
pitch	number	1.0	Pitch adjustment (0.5-2.0)
provider	string	"default"	TTS provider. See providers.

Response 200

Binary audio stream with Content-Type set to the requested format.

TTS Providers

Provider	ID	Notes
Cartesia	cartesia	~40ms TTFB. Recommended for production.
ElevenLabs	elevenlabs	High quality, wide language support
Deepgram	deepgram	Fast, cost-effective
Fish Audio	fish-audio	Open-source friendly
Resemble AI	resemble-ai	Enterprise voice cloning
Inworld	inworld	Gaming/interactive focus
Chatterbox	chatterbox	Open-source, GPU-accelerated
Kokoro	kokoro	Lightweight cheap/open fallback
F5 TTS	f5-tts	Open-source
CosyVoice	cosyvoice	Multilingual
VoxCPM	voxcpm	Multilingual open voice research
Qwen TTS	qwen-tts	HuggingFace-hosted

---

Transcribe Audio

Synchronous transcription. Blocks until complete.

POST /v1/transcribe

JSON Body (URL reference)

{
  "audioUrl": "https://example.com/audio.mp3",
  "language": "en",
  "mode": "accurate",
  "diarize": true,
  "timestamps": "segment"
}

Multipart Form (file upload)

curl -X POST https://api.ph0ny.com/v1/transcribe \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -F "file=@recording.mp3" \
  -F "language=en" \
  -F "mode=accurate" \
  -F "diarize=true"

Field	Type	Default	Description
audioUrl	string	-	URL to audio file
file	binary	-	Audio file upload (multipart)
language	string	""	Language code (auto-detect if empty)
mode	string	"accurate"	accurate or fast
diarize	boolean	false	Enable speaker diarization
timestamps	string	"segment"	segment or word

Max file size: 25MB.

Response 200

{
  "text": "Hello, welcome to the meeting. Today we'll discuss...",
  "segments": [
    {
      "start": 0.0,
      "end": 2.5,
      "text": "Hello, welcome to the meeting.",
      "speaker": "Speaker 1"
    }
  ],
  "words": [
    { "start": 0.0, "end": 0.4, "word": "Hello" }
  ],
  "language": "en",
  "duration": 45.2
}

---

Async Transcribe

Start a transcription job and poll for results. Useful for large files.

POST /v1/transcribe/async

Same request body as /v1/transcribe.

Response 202

{
  "id": "job_abc123",
  "status": "processing",
  "createdAt": "2026-03-21T00:00:00.000Z"
}

Get Job

GET /v1/transcribe/:jobId

Response 200

{
  "id": "job_abc123",
  "status": "completed",
  "result": {
    "text": "...",
    "segments": [...],
    "language": "en",
    "duration": 45.2
  },
  "createdAt": "2026-03-21T00:00:00.000Z",
  "completedAt": "2026-03-21T00:00:01.500Z"
}

Status values: processing, completed, failed.

---

OpenAI-Compatible Endpoints

Drop-in replacements for OpenAI's audio API:

TTS

POST /v1/audio/speech

Same interface as OpenAI's /v1/audio/speech. Billed per character of input, at the rate of the provider that answered — including when a x-phony.fallback provider serves the request.

The response names the vendor and the model that answered, in X-Phony-Provider and X-Phony-Model. These can differ from the model you sent: ph0ny does not forward your model segment to the vendor, so tts-1 runs Cartesia's own default model.

Choosing a provider

A model id that names a vendor selects that vendor. cartesia/sonic-3 and the bare slug cartesia both name Cartesia. tts-1, tts-1-hd and every auto strategy name none, so ph0ny chooses.

ph0ny does not answer with a vendor you named on behalf of one you did not. If the vendor you named fails, the request fails with that vendor's error, and no other vendor receives your text. If you named no vendor, ph0ny falls through to another one and sets X-Phony-Fallback: true on the response.

Send X-Phony-Strict-Provider to override that default.

Value	Effect
0, false, no, off	Allow ph0ny to answer with another vendor
any other value	Refuse to answer with another vendor

A model id whose vendor ph0ny does not serve is refused with 400 unknown_provider before any vendor is called.

STT

POST /v1/audio/transcriptions

Same interface as OpenAI's /v1/audio/transcriptions. Max 25MB.

This endpoint transcribes with Deepgram, OpenAI and ElevenLabs. Send one of their model ids, or auto to let ph0ny choose. Any other model id is refused with 400 unsupported_model; ph0ny does not transcribe with a vendor you did not name.

The response carries X-Phony-Provider, X-Phony-Latency-Ms and X-Phony-Audio-Seconds — the audio length the transcription was billed on. With response_format=verbose_json, duration reports that same measured length. Transcription is billed per minute of audio, rounded up, minimum one minute.

List Models

GET /v1/audio/models

Returns available audio models for TTS and STT.