{
  "openapi": "3.1.0",
  "info": {
    "title": "Sonex Labs API",
    "description": "Synthesize speech, transcribe audio, generate text with Vyas, our OpenAI-compatible LLM, manage voices, and retrieve call records, usage, and balance. One API key authenticates every endpoint.\n\n**Base URL**\n\n```\nhttps://api.sonexlabs.com\n```\n\n**Authentication**\n\nSend your API key as a bearer token on every request. Keys are created in the [dashboard](https://www.sonexlabs.com/dashboard).\n\n```\nAuthorization: Bearer vsk_...\n```\n\n**Rate limits**\n\n5 requests per second and 120 requests per minute, per tenant. Requests beyond either limit return `429 Too Many Requests` with a `Retry-After` header.\n\n**Billing**\n\nSpeech synthesis is billed per character, transcription per second of audio, and Vyas (the LLM) per token. Service credits are consumed before the wallet balance. Failed requests are not billed.",
    "version": "1.2.0"
  },
  "servers": [
    {
      "url": "https://api.sonexlabs.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Pass your API key as a Bearer token. Get yours from the [Sonex Labs dashboard](https://www.sonexlabs.com/dashboard).\n\n```\nAuthorization: Bearer vsk_...\n```"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "RateLimitError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "rate_limit_exceeded"
          },
          "message": {
            "type": "string",
            "example": "Rate limit exceeded (5 requests/sec). Retry after 1 second(s)."
          },
          "limit_type": {
            "type": "string",
            "enum": [
              "burst",
              "sustained"
            ],
            "description": "`burst` for the per-second limit, `sustained` for the per-minute limit."
          },
          "limit": {
            "type": "integer",
            "example": 5
          },
          "retry_after_seconds": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "SpeechRequest": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "example": "Hello, welcome to Sonex Labs.",
            "description": "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": {
            "type": "string",
            "example": "v_abc123",
            "description": "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": {
            "type": "string",
            "default": "auto",
            "example": "auto",
            "description": "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": {
            "type": "number",
            "default": 1.0,
            "minimum": 0.5,
            "maximum": 2.0,
            "description": "Speaking rate multiplier. Values outside 0.5 to 2.0 are clamped to that range rather than rejected."
          },
          "output_format": {
            "type": "string",
            "enum": [
              "wav",
              "mp3",
              "ogg",
              "opus",
              "mulaw"
            ],
            "default": "wav",
            "description": "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": {
            "type": "integer",
            "enum": [
              8000,
              16000,
              22050,
              24000,
              44100,
              48000
            ],
            "default": 24000,
            "description": "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."
          }
        }
      },
      "Voice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "v_abc123"
          },
          "name": {
            "type": "string",
            "example": "Priya (Hindi)"
          },
          "language": {
            "type": "string",
            "nullable": true,
            "example": "Hindi",
            "description": "Human-readable language name, not a BCP-47 code. Set for platform voices only. `null` for cloned voices, which detect language from the input text."
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Hindi"
            ],
            "description": "The same information as `language`, as a list. Empty for cloned voices."
          },
          "gender": {
            "type": "string",
            "nullable": true,
            "enum": [
              "female",
              "male",
              "neutral",
              null
            ],
            "description": "Set for platform voices only. `null` for cloned voices."
          },
          "provider": {
            "type": "string",
            "example": "panini",
            "description": "Synthesis engine. `panini` for platform voices, `custom` for voices cloned by your tenant."
          },
          "type": {
            "type": "string",
            "enum": [
              "platform",
              "custom"
            ],
            "description": "`platform` for a built-in Sonex Labs voice, `custom` for a voice created with `POST /v1/voices/clone`."
          },
          "preview_url": {
            "type": "string",
            "nullable": true,
            "format": "uri",
            "example": "https://api.sonexlabs.com/v1/voices/9b8fsavyez/preview",
            "description": "Sample audio for the voice. Requires no API key, so it can be used directly as the `src` of an audio element. `null` for cloned voices."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Indian",
              "Natural, Professional"
            ],
            "description": "Descriptive tags such as accent or tone. `[\"custom\", \"cloned\"]` for cloned voices."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the voice was created. `null` for platform voices."
          }
        }
      },
      "ClonedVoice": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Voice"
          },
          {
            "type": "object",
            "example": {
              "id": "v_xyz789",
              "name": "My Custom Voice",
              "language": null,
              "languages": [],
              "gender": null,
              "provider": "custom",
              "type": "custom",
              "preview_url": "https://storage.sonexlabs.com/voice-profiles/v_xyz789/ref_audio.wav",
              "tags": [
                "custom",
                "cloned"
              ],
              "created_at": "2026-08-05T18:19:22.468Z"
            }
          }
        ]
      },
      "PaginatedMeta": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          }
        }
      },
      "Balance": {
        "type": "object",
        "properties": {
          "wallet": {
            "type": "object",
            "properties": {
              "balance": {
                "type": "number",
                "example": 5.0,
                "description": "Remaining prepaid wallet balance, charged after service credits are exhausted."
              },
              "currency": {
                "type": "string",
                "example": "USD"
              }
            }
          },
          "credits": {
            "type": "array",
            "description": "Service credit grants, consumed before the wallet balance. Empty when none remain.",
            "items": {
              "type": "object",
              "properties": {
                "service": {
                  "type": "string",
                  "example": "tts"
                },
                "available": {
                  "type": "number",
                  "example": 50000,
                  "description": "Remaining credit units for this service (characters, for tts)."
                },
                "next_expiry": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "When the soonest-expiring credit grant for this service expires. `null` if the grant never expires."
                }
              }
            }
          }
        }
      },
      "CallSummary": {
        "type": "object",
        "description": "The compact representation returned by the list endpoint.",
        "properties": {
          "id": {
            "type": "string",
            "example": "CA7f3a1b90c24e4d02",
            "description": "Call identifier. This is the provider call SID, so it matches the identifier in your telephony provider's logs."
          },
          "status": {
            "type": "string",
            "example": "completed",
            "description": "Lifecycle state of the call, such as `in_progress`, `completed`, `failed`, or `no_answer`."
          },
          "direction": {
            "type": "string",
            "enum": [
              "inbound",
              "outbound"
            ],
            "example": "outbound"
          },
          "agent": {
            "type": "object",
            "description": "The agent that handled the call.",
            "properties": {
              "id": {
                "type": "string",
                "example": "3f0c9d18-1c4a-4a3a-9a75-7e1c2b6f42aa"
              },
              "name": {
                "type": "string",
                "example": "Support Line"
              }
            }
          },
          "from": {
            "type": "string",
            "example": "+14155550142",
            "description": "Caller number in E.164 format. `null` for web calls."
          },
          "to": {
            "type": "string",
            "example": "+916301979825",
            "description": "Number called, in E.164 format. `null` for web calls."
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-20T11:42:07.482Z"
          },
          "ended_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-20T11:42:56.117Z"
          },
          "duration_secs": {
            "type": "integer",
            "example": 49
          },
          "cost_usd": {
            "type": "number",
            "example": 0.014226,
            "description": "Total charge for the call in USD, rounded to six decimal places."
          },
          "has_recording": {
            "type": "boolean",
            "example": true,
            "description": "Whether `GET /v1/calls/{call_id}/recording` returns audio for this call."
          },
          "has_transcript": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "TranscriptTurn": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "agent",
              "caller"
            ],
            "example": "caller"
          },
          "content": {
            "type": "string",
            "example": "I would like to reschedule my appointment."
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-20T11:42:14.902Z",
            "description": "When the turn was completed."
          }
        }
      },
      "CallToolCall": {
        "type": "object",
        "description": "One tool invoked by the agent during the call, in the order it ran.",
        "properties": {
          "name": {
            "type": "string",
            "example": "check_availability"
          },
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ],
            "example": "success"
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-20T11:42:21.338Z"
          },
          "duration_ms": {
            "type": "integer",
            "example": 412
          },
          "arguments": {
            "type": "object",
            "description": "Arguments supplied by the model.",
            "example": {
              "date": "2026-09-24"
            }
          },
          "result": {
            "description": "Value returned to the model. Present when `status` is `success`.",
            "example": {
              "slots": [
                "10:00",
                "14:30"
              ]
            }
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Failure reason. Present when `status` is `error`.",
            "example": null
          }
        }
      },
      "CallDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CallSummary"
          },
          {
            "type": "object",
            "properties": {
              "campaign_id": {
                "type": "string",
                "nullable": true,
                "description": "The outbound campaign this call belongs to, if any."
              },
              "provider": {
                "type": "string",
                "example": "vobiz",
                "description": "Telephony provider that carried the call."
              },
              "models": {
                "type": "object",
                "nullable": true,
                "description": "The models used on the call, under their Sonex Labs product names.",
                "properties": {
                  "llm": {
                    "type": "string",
                    "example": "Sonex Multilingual LLM"
                  },
                  "transcription": {
                    "type": "string",
                    "example": "Soniox Real-time v5"
                  },
                  "voice": {
                    "type": "string",
                    "example": "Panini TTS"
                  }
                }
              },
              "cost": {
                "type": "object",
                "description": "Itemized charges in USD. `total_usd` is always present. The component keys depend on which services the call used, so treat them as an open set rather than a fixed schema.",
                "properties": {
                  "total_usd": {
                    "type": "number",
                    "example": 0.014226
                  }
                },
                "additionalProperties": {
                  "type": "number"
                },
                "example": {
                  "total_usd": 0.014226,
                  "llm": 0.002104,
                  "stt": 0.0049,
                  "tts": 0.005122,
                  "telephony": 0.0021
                }
              },
              "transcript": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TranscriptTurn"
                },
                "description": "Turn by turn transcript. Returned only when `transcript` is in `include`."
              },
              "transcript_text": {
                "type": "string",
                "description": "The same conversation as a single block of text. Returned only when `transcript` is in `include`.",
                "example": "Agent: Thanks for calling.\nCaller: I would like to reschedule my appointment."
              },
              "tool_calls": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CallToolCall"
                },
                "description": "Returned only when `tool_calls` is in `include`."
              }
            }
          }
        ]
      },
      "CallList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CallSummary"
            }
          },
          "has_more": {
            "type": "boolean",
            "example": true,
            "description": "Whether further calls exist beyond this page."
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "example": "WyIyMDI2LTA5LTIwVDExOjQyOjA3WiIsIjhkMWEiXQ",
            "description": "Pass as `cursor` to retrieve the next page. `null` on the last page."
          }
        }
      },
      "CallTranscript": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "CA7f3a1b90c24e4d02"
          },
          "transcript": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TranscriptTurn"
            }
          },
          "transcript_text": {
            "type": "string"
          }
        }
      },
      "CallRecording": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "CA7f3a1b90c24e4d02"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Time-limited link to the audio file. Stream or download it before `expires_at` rather than storing the link.",
            "example": "https://storage.sonexlabs.com/storage/v1/object/sign/call-recordings/..."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-20T12:12:56.117Z",
            "description": "When the link stops working. Links are valid for 15 minutes."
          },
          "duration_secs": {
            "type": "integer",
            "example": 49
          }
        }
      },
      "CallError": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "example": "No call with that id."
          }
        }
      },
      "UsageCost": {
        "type": "object",
        "description": "The same components a call reports, so a period's figures add up to the calls it covers.",
        "properties": {
          "llm": {
            "type": "number",
            "example": 0.412885
          },
          "stt": {
            "type": "number",
            "example": 1.093446
          },
          "tts": {
            "type": "number",
            "example": 4.127882
          },
          "telephony": {
            "type": "number",
            "example": 0.55
          }
        }
      },
      "UsageBucket": {
        "type": "object",
        "properties": {
          "cost_usd": {
            "type": "number",
            "example": 0.462104,
            "description": "Total for this row, in USD."
          },
          "cost": {
            "$ref": "#/components/schemas/UsageCost"
          },
          "calls": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "example": 31
              },
              "connected": {
                "type": "integer",
                "example": 29,
                "description": "Calls that reached the completed state."
              },
              "duration_secs": {
                "type": "integer",
                "example": 1544
              }
            }
          },
          "speech": {
            "type": "object",
            "description": "Synthesis requested through `POST /v1/speech`. Omitted when grouping by agent, because synthesis requests are not associated with an agent.",
            "properties": {
              "requests": {
                "type": "integer",
                "example": 96
              },
              "characters": {
                "type": "integer",
                "example": 61230
              }
            }
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "period": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-01T00:00:00+00:00"
              },
              "to": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-30T23:59:59.999999+00:00"
              },
              "timezone": {
                "type": "string",
                "example": "Asia/Kolkata"
              }
            },
            "description": "The period covered, returned in UTC along with the timezone used to measure it."
          },
          "totals": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UsageBucket"
              },
              {
                "type": "object",
                "properties": {
                  "calls": {
                    "type": "object",
                    "properties": {
                      "by_status": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "integer"
                        },
                        "example": {
                          "completed": 389,
                          "no-answer": 18,
                          "failed": 5
                        }
                      },
                      "by_direction": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "integer"
                        },
                        "example": {
                          "inbound": 161,
                          "outbound": 251
                        }
                      }
                    }
                  }
                }
              }
            ]
          },
          "group_by": {
            "type": "string",
            "enum": [
              "day",
              "agent",
              "none"
            ],
            "example": "day"
          },
          "breakdown": {
            "type": "array",
            "description": "One row per day or per agent. Empty when `group_by` is `none`.",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/UsageBucket"
                },
                {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string",
                      "format": "date",
                      "example": "2026-09-20",
                      "description": "Present when grouping by day."
                    },
                    "agent": {
                      "type": "object",
                      "description": "Present when grouping by agent.",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "Transcription": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "description": "The transcript. Empty when no speech was recognized."
          },
          "duration_seconds": {
            "type": "number",
            "description": "Duration of the audio in seconds. This is the quantity billed."
          },
          "model": {
            "type": "string",
            "examples": [
              "valmiki"
            ],
            "description": "Transcription model used."
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier. Quote it in support requests."
          },
          "seconds_billed": {
            "type": "number",
            "description": "Seconds billed for this request. `0` when an `Idempotency-Key` replay resulted in no new charge."
          }
        },
        "required": [
          "text",
          "duration_seconds",
          "model",
          "request_id"
        ]
      },
      "ChatMessage": {
        "type": "object",
        "required": [
          "role",
          "content"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "user",
              "assistant",
              "tool"
            ]
          },
          "content": {
            "type": [
              "string",
              "null"
            ],
            "description": "The message text."
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Tool calls made by the assistant, as returned in an earlier response."
          },
          "tool_call_id": {
            "type": "string",
            "description": "For a `tool` message: the id of the tool call it answers."
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "enum": [
              "vyas"
            ],
            "default": "vyas"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            },
            "minItems": 1
          },
          "max_tokens": {
            "type": "integer",
            "description": "Most tokens to generate. Reduced to what fits in the context window. `max_completion_tokens` is accepted too."
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2
          },
          "top_p": {
            "type": "number"
          },
          "stop": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "Return the answer as server-sent events, ending with `data: [DONE]`."
          },
          "stream_options": {
            "type": "object",
            "properties": {
              "include_usage": {
                "type": "boolean",
                "description": "Send a final chunk with token usage."
              }
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Functions the model may call, in OpenAI's format."
          },
          "tool_choice": {
            "description": "`auto`, `none`, `required`, or a specific function."
          },
          "response_format": {
            "type": "object",
            "description": "For example `{\"type\": \"json_object\"}`."
          },
          "seed": {
            "type": "integer"
          },
          "presence_penalty": {
            "type": "number"
          },
          "frequency_penalty": {
            "type": "number"
          },
          "user": {
            "type": "string"
          }
        },
        "description": "OpenAI's chat completions request. Parameters outside this list are ignored, and `n` is always 1."
      },
      "ChatCompletionUsage": {
        "type": "object",
        "properties": {
          "prompt_tokens": {
            "type": "integer",
            "example": 21
          },
          "completion_tokens": {
            "type": "integer",
            "example": 18
          },
          "total_tokens": {
            "type": "integer",
            "example": 39
          }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "chatcmpl-8f47d347a3a4e001"
          },
          "object": {
            "type": "string",
            "example": "chat.completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string",
            "example": "vyas"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "type": "object",
                  "properties": {
                    "role": {
                      "type": "string",
                      "example": "assistant"
                    },
                    "content": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "example": "The Ganges, Yamuna, and Brahmaputra are three major rivers in India."
                    },
                    "tool_calls": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                },
                "finish_reason": {
                  "type": "string",
                  "enum": [
                    "stop",
                    "length",
                    "tool_calls"
                  ]
                }
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/ChatCompletionUsage"
          }
        }
      },
      "ChatCompletionChunk": {
        "type": "object",
        "description": "One server-sent event of a streamed answer, sent as `data: {json}`.",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "example": "chat.completion.chunk"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string",
            "example": "vyas"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "delta": {
                  "type": "object",
                  "properties": {
                    "role": {
                      "type": "string"
                    },
                    "content": {
                      "type": "string"
                    }
                  }
                },
                "finish_reason": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/ChatCompletionUsage"
          }
        }
      },
      "OpenAIError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "This model's maximum context length is 16384 tokens. Your messages are 17013 tokens."
              },
              "type": {
                "type": "string",
                "example": "invalid_request_error"
              },
              "param": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "messages"
              },
              "code": {
                "type": "string",
                "example": "context_length_exceeded"
              }
            }
          }
        },
        "description": "OpenAI's error shape, so OpenAI client libraries raise the matching exception."
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "example": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "vyas"
                },
                "object": {
                  "type": "string",
                  "example": "model"
                },
                "created": {
                  "type": "integer"
                },
                "owned_by": {
                  "type": "string",
                  "example": "sonexlabs"
                },
                "context_window": {
                  "type": "integer",
                  "example": 16384
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Text-to-Speech",
      "description": "Convert text to speech with Panini, the Sonex Labs synthesis engine. 250+ languages, with a measured audio-generation latency of 250 to 300 ms.\n\nBilled per character of synthesized text."
    },
    {
      "name": "Speech-to-Text",
      "description": "Convert speech to text with Valmiki, the Sonex Labs transcription engine. 100+ languages, detected automatically, with punctuated output. Recordings that switch between languages are handled without configuration.\n\nUse `POST /v1/transcribe` for a complete recording, or `WS /v1/transcribe/stream` for live audio with results returned as they are recognized.\n\nBilled per second of audio. Audio rejected before transcription is not billed."
    },
    {
      "name": "LLM",
      "description": "Generate text with Vyas, the Sonex Labs language model. Compatible with OpenAI's chat completions API: point any OpenAI client library at `https://api.sonexlabs.com/v1` and use the model `vyas`.\n\nBilled per input and output token."
    },
    {
      "name": "Voices",
      "description": "List the platform voices available to your account and manage your own cloned voices."
    },
    {
      "name": "Billing",
      "description": "Retrieve your wallet balance, remaining service credits, and itemized usage."
    },
    {
      "name": "Calls",
      "description": "Retrieve calls handled by your voice agents, with transcripts, tool calls, itemized costs, and recordings. Responses are scoped to the tenant that owns the API key."
    }
  ],
  "paths": {
    "/v1/speech": {
      "post": {
        "tags": [
          "Text-to-Speech"
        ],
        "summary": "Synthesize speech",
        "operationId": "synthesizeSpeech",
        "description": "Convert text to speech and return the complete audio file in the response body.\n\nFor text longer than a few sentences, use `POST /v1/speech/stream` to begin playback before synthesis finishes.\n\n**Response headers**\n\n| Header | Description |\n|---|---|\n| `X-Chars-Billed` | Characters billed for this request. |\n| `X-Request-Id` | Unique request identifier. Quote it in support requests. |\n| `X-Voice-Fallback` | `true` when `voice_id` was not recognized and the default voice was used. |\n| `X-Voice-Fallback-Reason` | Present when `X-Voice-Fallback` is `true`. |\n\n**Billing**\n\nBilled per character of `text`, charged after synthesis completes. Failed and timed-out requests are not billed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpeechRequest"
              },
              "example": {
                "text": "Hello, welcome to Sonex Labs.",
                "voice_id": "9b8fsavyez",
                "output_format": "mp3"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audio file binary. Tip: the in-page player below shows MP3 responses (`output_format: \"mp3\"`); WAV and OGG responses are offered as a download.",
            "content": {
              "audio/wav": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/ogg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient wallet balance."
          },
          "422": {
            "description": "Invalid request: empty `text`, `text` over the length limit, unsupported `output_format`, or unsupported `sample_rate`."
          },
          "429": {
            "description": "Rate limit exceeded. See the `Retry-After` header (seconds) and response body for details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/speech/stream": {
      "post": {
        "tags": [
          "Text-to-Speech"
        ],
        "summary": "Stream synthesized speech",
        "operationId": "synthesizeSpeechStream",
        "description": "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.\n\nAccepts the same request body as `POST /v1/speech`, with two differences: the response is always WAV/PCM, so `output_format` is ignored, and `text` is limited to 20,000 characters. `sample_rate` is honored.\n\n**Response headers**\n\nSame as `POST /v1/speech`. `X-Chars-Billed` reports the authorized character count, known before streaming begins.\n\n**Billing**\n\nThe full request is authorized against your balance before any audio is generated, so a request you cannot afford is rejected up front.\n\nA stream that completes is billed the full character count. A stream that disconnects early is billed for the audio delivered before the disconnect, derived from bytes sent and capped at the authorized amount. The final charge appears in your usage ledger.\n\nTo retry safely after a disconnect, resend the request with the same `Idempotency-Key`. Retries within 10 minutes are not billed again.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpeechRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chunked audio stream (WAV header on first chunk, raw PCM thereafter).",
            "content": {
              "audio/wav": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient wallet balance."
          },
          "422": {
            "description": "Invalid request: empty `text`, `text` over the length limit, or unsupported `sample_rate`."
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voices": {
      "get": {
        "tags": [
          "Voices"
        ],
        "summary": "List voices",
        "operationId": "listVoices",
        "description": "Retrieve every voice available to your account, including platform voices and your own cloned voices.",
        "responses": {
          "200": {
            "description": "Array of voices.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Voice"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/v1/voices/clone": {
      "post": {
        "tags": [
          "Voices"
        ],
        "summary": "Clone a voice",
        "operationId": "createVoiceClone",
        "description": "Create a custom voice from a reference recording.\n\n**Request**\n\nProvide exactly one of `file`, an uploaded recording, or `audio_url`, a link to a hosted recording. Uploading the file directly is recommended.\n\n**Response**\n\nCloning is synchronous. The response contains the completed voice, ready to use with `POST /v1/speech`. No polling is required.\n\nEach plan includes a fixed number of custom voices. Requests beyond that limit are rejected.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "My Custom Voice"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Reference audio file (WAV or MP3, min 10 seconds). Provide this OR audio_url, not both."
                  },
                  "audio_url": {
                    "type": "string",
                    "description": "Alternative to `file`: a publicly accessible URL to the reference audio. Provide this OR file, not both.",
                    "example": "https://cdn.example.com/reference.wav"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Voice cloned and ready to use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClonedVoice"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "422": {
            "description": "Missing/empty name, missing or ambiguous audio source (need exactly one of file/audio_url), or the audio could not be read/fetched."
          },
          "429": {
            "description": "Custom-voice quota exceeded for this account."
          }
        }
      }
    },
    "/v1/voices/{voice_id}": {
      "get": {
        "tags": [
          "Voices"
        ],
        "summary": "Retrieve a voice",
        "operationId": "getVoice",
        "description": "Retrieve a single platform voice or custom voice by ID.",
        "parameters": [
          {
            "name": "voice_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "v_abc123",
            "description": "The voice identifier, returned as `id` by `GET /v1/voices`."
          }
        ],
        "responses": {
          "200": {
            "description": "Voice details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Voice"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "Voice not found."
          }
        }
      },
      "delete": {
        "tags": [
          "Voices"
        ],
        "summary": "Delete a voice",
        "operationId": "deleteVoice",
        "description": "Permanently delete one of your cloned voices. This cannot be undone. Platform voices cannot be deleted.",
        "parameters": [
          {
            "name": "voice_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "v_abc123",
            "description": "The voice identifier, returned as `id` by `GET /v1/voices`."
          }
        ],
        "responses": {
          "200": {
            "description": "Voice deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "Voice not found."
          }
        }
      }
    },
    "/v1/balance": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Retrieve balance",
        "operationId": "getBalance",
        "description": "Retrieve your current prepaid wallet balance and remaining service credits.\n\nUsage is charged against matching service credits first, then the wallet balance.",
        "responses": {
          "200": {
            "description": "Current balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Balance"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Retrieve usage summary",
        "operationId": "getUsage",
        "description": "Retrieve total spend for a period, broken down by service and by time bucket.\n\nCosts are calculated from the same components and rounded the same way as individual calls, so a bucket total equals the sum of the calls it contains in `GET /v1/calls`.\n\nThis endpoint reports spend only. Use `GET /v1/balance` for remaining funds.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "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.",
            "example": "2026-09-01"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "End of the period, inclusive. Same formats as `from`. Defaults to the current time.",
            "example": "2026-09-30"
          },
          {
            "name": "group_by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "agent",
                "none"
              ],
              "default": "day"
            },
            "description": "How to break down the period. `none` returns totals only."
          },
          {
            "name": "timezone",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "UTC"
            },
            "description": "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.",
            "example": "Asia/Kolkata"
          }
        ],
        "responses": {
          "200": {
            "description": "The summary.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              }
            }
          },
          "400": {
            "description": "An unreadable date, an unknown timezone, a period that ends before it starts, or one longer than 366 days."
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/v1/calls": {
      "get": {
        "tags": [
          "Calls"
        ],
        "summary": "List calls",
        "operationId": "listCalls",
        "description": "Retrieve your calls, most recent first.\n\n**Pagination**\n\nResults are paginated with a cursor. Request the first page without a `cursor`, then pass `next_cursor` from each response until `has_more` is `false`. Cursor pagination keeps results stable while new calls arrive, which offset pagination does not.\n\nOnly calls belonging to the tenant that owns the API key are returned.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            },
            "description": "Number of calls per page."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The `next_cursor` value from the previous response. Omit for the first page."
          },
          {
            "name": "agent_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Return only calls handled by this agent."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Return only calls in this state, for example `completed`."
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "inbound",
                "outbound"
              ]
            },
            "description": "Return only inbound or only outbound calls."
          },
          {
            "name": "phone_number",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Return calls where this E.164 number is either the caller or the number called.",
            "example": "+14155550142"
          },
          {
            "name": "started_after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Return calls that started at or after this ISO 8601 timestamp."
          },
          {
            "name": "started_before",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Return calls that started at or before this ISO 8601 timestamp."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of calls.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallList"
                }
              }
            }
          },
          "400": {
            "description": "The `cursor` value is not valid. Omit it to start from the newest call.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    },
    "/v1/calls/{call_id}": {
      "get": {
        "tags": [
          "Calls"
        ],
        "summary": "Retrieve a call",
        "operationId": "getCall",
        "description": "Retrieve the complete record for one call, including the models used, itemized cost, transcript, and every tool the agent invoked.\n\nUse the `include` parameter to control the response size. Pass `include=` with no value to omit optional sections when polling for status.",
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The provider call SID, returned as `id` by `GET /v1/calls`. The internal call UUID is also accepted.",
            "example": "CA7f3a1b90c24e4d02"
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "transcript,tool_calls"
            },
            "description": "Comma-separated list of optional sections to include: `transcript`, `tool_calls`. Pass an empty value to return summary fields only."
          }
        ],
        "responses": {
          "200": {
            "description": "The call.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallDetail"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "No call with that id, or the call belongs to another tenant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/transcript": {
      "get": {
        "tags": [
          "Calls"
        ],
        "summary": "Retrieve a call transcript",
        "operationId": "getCallTranscript",
        "description": "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.",
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "CA7f3a1b90c24e4d02",
            "description": "The provider call SID, returned as `id` by `GET /v1/calls`."
          }
        ],
        "responses": {
          "200": {
            "description": "The transcript.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallTranscript"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "No call with that id, or the call belongs to another tenant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/recording": {
      "get": {
        "tags": [
          "Calls"
        ],
        "summary": "Retrieve a call recording",
        "operationId": "getCallRecording",
        "description": "Retrieve the audio recording of a call.\n\nResponds with `302 Found` and a `Location` header pointing to the audio, so the URL can be used directly as the `src` of an audio element. Set `redirect=false` to receive the link as JSON with its expiry time.\n\nLinks expire after 15 minutes. Store the `call_id` and request a new link when needed rather than storing the link itself. This endpoint is the stable address for a recording, so underlying storage can change without affecting your integration.",
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "CA7f3a1b90c24e4d02",
            "description": "The provider call SID, returned as `id` by `GET /v1/calls`."
          },
          {
            "name": "redirect",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Set to `false` to receive the link as JSON instead of being redirected to the audio."
          }
        ],
        "responses": {
          "200": {
            "description": "The link to the audio, returned when `redirect=false`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallRecording"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the audio file. Returned by default.",
            "headers": {
              "Location": {
                "description": "Time limited link to the audio.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "No call with that id, or the call has no recording.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voices/{voice_id}/preview": {
      "get": {
        "tags": [
          "Voices"
        ],
        "summary": "Preview a voice",
        "operationId": "getVoicePreview",
        "description": "Retrieve sample audio for a voice. This is the address returned as `preview_url` on every voice object.\n\nResponds with `302 Found` and a `Location` header pointing to the audio, so the URL can be used directly as the `src` of an audio element. Set `redirect=false` to receive the link as JSON instead.\n\nThis endpoint does not require authentication, so previews can be embedded in a public page without exposing an API key.",
        "security": [],
        "parameters": [
          {
            "name": "voice_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "9b8fsavyez",
            "description": "The voice identifier, returned as `id` by `GET /v1/voices`."
          },
          {
            "name": "redirect",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Set to `false` to receive the link as JSON instead of being redirected to the audio."
          }
        ],
        "responses": {
          "200": {
            "description": "The link to the audio, returned when `redirect=false`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "example": "9b8fsavyez"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the audio file. Returned by default.",
            "headers": {
              "Location": {
                "description": "Link to the sample audio.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "404": {
            "description": "No voice with that id, or the voice has no sample audio."
          }
        }
      }
    },
    "/v1/transcribe": {
      "post": {
        "tags": [
          "Speech-to-Text"
        ],
        "summary": "Transcribe audio",
        "operationId": "transcribeAudio",
        "description": "Convert a complete audio recording to text.\n\n**Request**\n\nSend the audio as the raw request body with a matching `Content-Type`, or as `multipart/form-data` in a `file` field.\n\n| Property | Value |\n|---|---|\n| Formats | WAV, MP3, FLAC, OGG, Opus, WebM, AAC, M4A |\n| Maximum size | 10 MB |\n| Maximum duration | 10 minutes |\n\nFor longer audio, split the file or use `WS /v1/transcribe/stream`.\n\nThe language is detected automatically, including recordings that switch between languages mid-sentence. There is nothing to configure.\n\n**Response**\n\nReturns the transcript and the duration of the audio. A recording containing no intelligible speech returns an empty `text` value rather than an error.\n\n**Billing**\n\nBilled per second of audio, measured from the recording and returned as `duration_seconds`. Audio rejected for format, size, duration, or corruption is not billed.\n\nSend an `Idempotency-Key` header to make retries safe. A repeat within 10 minutes returns the original transcript and `request_id` immediately, with `seconds_billed` set to `0`.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The audio file."
                  }
                },
                "required": [
                  "file"
                ]
              }
            },
            "audio/wav": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "audio/mpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "audio/flac": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "audio/ogg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "audio/webm": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The transcript.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transcription"
                }
              }
            }
          },
          "400": {
            "description": "No audio, or audio that could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient wallet balance."
          },
          "413": {
            "description": "Audio is larger than 10 MB or longer than 10 minutes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported audio format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitError"
                }
              }
            }
          },
          "503": {
            "description": "Transcription is temporarily unavailable or busy. Retry shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/transcribe/stream": {
      "get": {
        "tags": [
          "Speech-to-Text"
        ],
        "summary": "Stream transcription",
        "operationId": "transcribeStream",
        "description": "Transcribe live audio over a WebSocket connection, receiving results as they are recognized.\n\nThis endpoint accepts a WebSocket upgrade, not a standard GET request.\n\n```\nwss://api.sonexlabs.com/v1/transcribe/stream\n```\n\n**Authentication**\n\nSend `Authorization: Bearer vsk_...` or the `X-Api-Key` header. Clients that cannot set WebSocket headers, including browsers, may pass the key as the `api_key` query parameter. A key in a URL is visible to proxies, logs, and browser history: issue a short-lived key from your own backend for this case.\n\n**Sending audio**\n\nSend binary frames of 16 kHz mono 16-bit PCM, little-endian. Frames of approximately 100 ms are recommended.\n\nSend audio at the rate it is spoken. This endpoint is built for live microphone input; audio arriving faster than real time is paced before it reaches the engine. To transcribe a recording you already have, use `POST /v1/transcribe`, which is faster and more accurate for that case.\n\nAudio sent before the `ready` message is held and delivered once the session opens, so nothing is lost if you begin sending immediately.\n\nSend `{\"type\":\"end\"}` when the speaker has finished. The final utterance is completed, a `done` message is sent, and the connection closes.\n\n**Messages received**\n\nAll messages are JSON text frames.\n\n| `type` | Description |\n|---|---|\n| `ready` | The session is open. Includes `model` and `sample_rate`. |\n| `partial` | An in-progress transcript in `text`. Superseded by later messages. |\n| `final` | A completed utterance in `text`. |\n| `error` | An error description in `message`. |\n| `done` | The session has ended. Includes `request_id` and `seconds_billed`. |\n\n**Close codes**\n\n| Code | Meaning |\n|---|---|\n| `4401` | Missing or invalid API key. |\n| `4402` | Insufficient balance. |\n| `4408` | Maximum session duration of 10 minutes reached. |\n| `4409` | No speech recognized for 30 seconds. |\n\n**Billing**\n\nBilled per second for the duration the connection is open, including silence and the time spent opening the session. The total is returned as `seconds_billed` in the `done` message. Close the connection when you have finished sending audio.",
        "responses": {
          "101": {
            "description": "Switching Protocols. The WebSocket session is open."
          },
          "401": {
            "description": "Missing or invalid API key (WebSocket close code 4401)."
          },
          "402": {
            "description": "Insufficient wallet balance (WebSocket close code 4402)."
          }
        },
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "API key, for clients that cannot set WebSocket headers. Prefer the `Authorization` header where your client supports it."
          }
        ]
      }
    },
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "LLM"
        ],
        "summary": "Create a chat completion",
        "operationId": "createChatCompletion",
        "description": "Generate the next assistant message for a conversation.\n\nSet `stream` to `true` to receive the answer as server-sent events, each `data: {ChatCompletionChunk}`, ending with `data: [DONE]`.\n\n**Request**\n\n| Property | Value |\n|---|---|\n| Model | `vyas` |\n| Context window | 16,384 tokens, prompt and answer together |\n\nA prompt longer than the context window is refused with `context_length_exceeded`, and `max_tokens` is reduced to what fits.\n\n**Billing**\n\nBilled per input and output token, as reported in `usage`. Requests refused before the model runs are not billed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "example": {
                "model": "vyas",
                "messages": [
                  {
                    "role": "system",
                    "content": "You are a helpful assistant."
                  },
                  {
                    "role": "user",
                    "content": "Name three Indian rivers in one line."
                  }
                ],
                "max_tokens": 60
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The completion. With `stream: true`, a `text/event-stream` of `ChatCompletionChunk` events instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletion"
                }
              },
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionChunk"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, or the prompt is longer than the context window (`context_length_exceeded`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient balance (`insufficient_quota`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            }
          },
          "404": {
            "description": "Unknown model (`model_not_found`). Use `vyas`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (`rate_limit_exceeded`), or the model is busy (`capacity_exceeded`). Retry after the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            }
          },
          "503": {
            "description": "The model is temporarily unavailable (`upstream_unavailable`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "tags": [
          "LLM"
        ],
        "summary": "List models",
        "operationId": "listModels",
        "description": "List the models available to your account, in OpenAI's format. Today that is `vyas`.",
        "responses": {
          "200": {
            "description": "Available models.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          }
        }
      }
    }
  }
}