Rate limit: 5 req/sec burst, 120 req/min sustained, per tenant. Exceeding returns 429 Too Many Requests. All requests require Authorization: Bearer vsk_....Docs →

Sonex Labs API reference: endpoint index

Every endpoint of the Sonex Labs API at https://api.sonexlabs.com. Authenticate with Authorization: Bearer vsk_.... The machine-readable spec is at /openapi.json.

Text-to-Speech

POST /v1/speech · Synthesize speech

Convert text to speech and return the complete audio file in the response body.

  • text (required): Text to synthesize. Maximum 5,000 characters for POST /v1/speech and 20,000 characters for POST /v1/speech/stream. Longer text is rejected with 422.
  • voice_id: Voice to synthesize with, from GET /v1/voices. Omit to use the default platform voice. An unrecognized value is not rejected: the default voice is used and X-Voice-Fallback is set to true on the response.
  • language: Language of the input text. Panini detects the language automatically, so auto is the default and the recommended value. Other values are accepted but have no effect.
  • speed: Speaking rate multiplier. Values outside 0.5 to 2.0 are clamped to that range rather than rejected.
  • output_format: Audio format of the response. opus is Opus in an Ogg container and is typically 10 to 20 times smaller than wav for the same speech. Ignored by POST /v1/speech/stream, which always returns WAV/PCM.
  • sample_rate: Output sample rate in Hz. Defaults to 24000. Use 8000 or 16000 for telephony and speech-recognition pipelines. Unsupported values fall back to the default.
{
  "text": "Hello, welcome to Sonex Labs.",
  "voice_id": "9b8fsavyez",
  "output_format": "mp3"
}

POST /v1/speech/stream · Stream synthesized speech

Convert text to speech and stream the audio back as a chunked HTTP response. Audio is synthesized sentence by sentence, so the first chunk arrives before the full text is complete.

  • text (required): Text to synthesize. Maximum 5,000 characters for POST /v1/speech and 20,000 characters for POST /v1/speech/stream. Longer text is rejected with 422.
  • voice_id: Voice to synthesize with, from GET /v1/voices. Omit to use the default platform voice. An unrecognized value is not rejected: the default voice is used and X-Voice-Fallback is set to true on the response.
  • language: Language of the input text. Panini detects the language automatically, so auto is the default and the recommended value. Other values are accepted but have no effect.
  • speed: Speaking rate multiplier. Values outside 0.5 to 2.0 are clamped to that range rather than rejected.
  • output_format: Audio format of the response. opus is Opus in an Ogg container and is typically 10 to 20 times smaller than wav for the same speech. Ignored by POST /v1/speech/stream, which always returns WAV/PCM.
  • sample_rate: Output sample rate in Hz. Defaults to 24000. Use 8000 or 16000 for telephony and speech-recognition pipelines. Unsupported values fall back to the default.

Voices

GET /v1/voices · List voices

Retrieve every voice available to your account, including platform voices and your own cloned voices.

POST /v1/voices/clone · Clone a voice

Create a custom voice from a reference recording.

  • name (required)
  • file: Reference audio file (WAV or MP3, min 10 seconds). Provide this OR audio_url, not both.
  • audio_url: Alternative to file: a publicly accessible URL to the reference audio. Provide this OR file, not both.

GET /v1/voices/{voice_id} · Retrieve a voice

Retrieve a single platform voice or custom voice by ID.

  • voice_id (path, required): The voice identifier, returned as id by GET /v1/voices.

DELETE /v1/voices/{voice_id} · Delete a voice

Permanently delete one of your cloned voices. This cannot be undone. Platform voices cannot be deleted.

  • voice_id (path, required): The voice identifier, returned as id by GET /v1/voices.

GET /v1/voices/{voice_id}/preview · Preview a voice

Retrieve sample audio for a voice. This is the address returned as preview_url on every voice object.

  • voice_id (path, required): The voice identifier, returned as id by GET /v1/voices.
  • redirect (query): Set to false to receive the link as JSON instead of being redirected to the audio.

Billing

GET /v1/balance · Retrieve balance

Retrieve your current prepaid wallet balance and remaining service credits.

GET /v1/usage · Retrieve usage summary

Retrieve total spend for a period, broken down by service and by time bucket.

  • from (query): Start of the period. A date (YYYY-MM-DD) or an ISO 8601 timestamp. A bare date covers the whole day in timezone. Defaults to 30 days ago.
  • to (query): End of the period, inclusive. Same formats as from. Defaults to the current time.
  • group_by (query): How to break down the period. none returns totals only.
  • timezone (query): IANA timezone used to interpret the period and align daily buckets. Set your local timezone so that late-evening usage is counted on the correct day. Defaults to UTC.

Calls

GET /v1/calls · List calls

Retrieve your calls, most recent first.

  • limit (query): Number of calls per page.
  • cursor (query): The next_cursor value from the previous response. Omit for the first page.
  • agent_id (query): Return only calls handled by this agent.
  • status (query): Return only calls in this state, for example completed.
  • direction (query): Return only inbound or only outbound calls.
  • phone_number (query): Return calls where this E.164 number is either the caller or the number called.
  • started_after (query): Return calls that started at or after this ISO 8601 timestamp.
  • started_before (query): Return calls that started at or before this ISO 8601 timestamp.

GET /v1/calls/{call_id} · Retrieve a call

Retrieve the complete record for one call, including the models used, itemized cost, transcript, and every tool the agent invoked.

  • call_id (path, required): The provider call SID, returned as id by GET /v1/calls. The internal call UUID is also accepted.
  • include (query): Comma-separated list of optional sections to include: transcript, tool_calls. Pass an empty value to return summary fields only.

GET /v1/calls/{call_id}/transcript · Retrieve a call transcript

Retrieve the transcript for one call, as individual turns and as a single block of text. Equivalent to GET /v1/calls/{call_id}?include=transcript without the rest of the record.

  • call_id (path, required): The provider call SID, returned as id by GET /v1/calls.

GET /v1/calls/{call_id}/recording · Retrieve a call recording

Retrieve the audio recording of a call.

  • call_id (path, required): The provider call SID, returned as id by GET /v1/calls.
  • redirect (query): Set to false to receive the link as JSON instead of being redirected to the audio.

Speech-to-Text

POST /v1/transcribe · Transcribe audio

Convert a complete audio recording to text.

  • file (required): The audio file.

GET /v1/transcribe/stream · Stream transcription

Transcribe live audio over a WebSocket connection, receiving results as they are recognized.

  • api_key (query): API key, for clients that cannot set WebSocket headers. Prefer the Authorization header where your client supports it.

LLM

POST /v1/chat/completions · Create a chat completion

Generate the next assistant message for a conversation.

  • model
  • messages (required)
  • max_tokens: Most tokens to generate. Reduced to what fits in the context window. max_completion_tokens is accepted too.
  • temperature
  • top_p
  • stop
  • stream: Return the answer as server-sent events, ending with data: [DONE].
  • stream_options
  • tools: Functions the model may call, in OpenAI's format.
  • tool_choice: auto, none, required, or a specific function.
  • response_format: For example {"type": "json_object"}.
  • seed
  • presence_penalty
  • frequency_penalty
  • user
{
  "model": "vyas",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Name three Indian rivers in one line."
    }
  ],
  "max_tokens": 60
}

GET /v1/models · List models

List the models available to your account, in OpenAI's format. Today that is vyas.