Sona API Reference

Natural text-to-speech, multi-speaker conversations, and voice cloning. One base URL, one key.

Base URL: https://sona.pyonair.com. All requests are HTTPS. Audio is returned as audio/mpeg (MP3).

Authentication

Every request needs your private API key, sent in a header. You may use either form:

# either
X-API-Key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY

Keys are per customer. Each customer receives their own key so usage can be tracked and managed independently. Keep your key secret, never put it in client-side code or a public page. A missing or invalid key returns 401.

Rate limits

Each key has a per-minute request limit. Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers. Exceeding the limit returns 429 with a Retry-After header.

Text to speech

POST/v1/tts

Convert text to speech. Returns an MP3.

Field	Type	Notes
`text` required	string	The text to speak.
`voice` optional	string	Voice name (default `heart`). See voices.
`speed` optional	number	0.5–2.0 (default 1.0).
`lang` optional	string	Language hint (e.g. `en`, `en-gb`).

curl -X POST https://sona.pyonair.com/v1/tts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Sona.","voice":"heart","speed":1.0}' \
  --output speech.mp3

Multi-speaker conversation

POST/v1/tts/conversation

Provide a script of turns with different speakers; Sona returns a single stitched MP3.

Field	Type	Notes
`script` required	array	List of `{speaker, text, speed?}` turns.
`gap_ms` optional	number	Silence between turns, in ms.
`crossfade_ms` optional	number	Crossfade between turns, in ms.

curl -X POST https://sona.pyonair.com/v1/tts/conversation \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script":[
        {"speaker":"sarah","text":"Welcome to Pyonair."},
        {"speaker":"george","text":"Two voices, one API."}
      ]}' \
  --output conversation.mp3

Voice cloning

POST/v1/clone

Upload a short reference clip plus the text to speak in that voice. Sent as multipart/form-data.

Field	Type	Notes
`reference_audio` required	file	A clean voice sample (~30s recommended).
`text` required	string	Text to speak in the cloned voice.

curl -X POST https://sona.pyonair.com/v1/clone \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "reference_audio=@sample.wav" \
  -F "text=This is my cloned voice." \
  --output cloned.mp3

List voices

GET/v1/voices

Returns the available voices, grouped by type.

curl https://sona.pyonair.com/v1/voices \
  -H "X-API-Key: YOUR_API_KEY"

Health

GET/health

Service status (no key required). Returns each backend's state.

curl https://sona.pyonair.com/health
# {"status":"ok","backends":{"tts":"ok","clone":"ok","conversation":"ok"}}

Errors

Status	Meaning
`401`	Missing or invalid API key.
`429`	Rate limit exceeded. See `Retry-After`.
`400`	Bad request (missing required field).
`502`	A voice backend is temporarily unavailable.