openapi: 3.0.3
info:
  title: Unreal Speech Stream API
  description: 'Unreal Speech is a low-cost, high-scale text-to-speech (TTS) API. It exposes a small REST surface: POST /stream for low-latency HTTP streaming of short text, POST /speech for synchronous MP3 output with word/sentence timestamps, and POST /synthesisTasks (with GET /synthesisTasks) for asynchronous long-form audio. All requests are authenticated with a Bearer API key issued from the dashboard. Note: the base host carries a version segment that has advanced over time (the Python SDK references api.v6, the live reference documents api.v7); paths are stable across versions.'
  version: v7
  contact:
    name: Unreal Speech
    url: https://unrealspeech.com
  termsOfService: https://unrealspeech.com/terms
servers:
- url: https://api.v7.unrealspeech.com
  description: Unreal Speech API (documented current host)
security:
- bearerAuth: []
tags:
- name: Stream
  description: Low-latency HTTP streaming synthesis returning audio bytes.
paths:
  /stream:
    post:
      operationId: streamSpeech
      tags:
      - Stream
      summary: Stream synthesized audio (low latency)
      description: Converts up to 1,000 characters of text into speech and streams the audio bytes back in the HTTP response (chunked transfer), typically in around 0.3 seconds. Intended for time-sensitive uses such as chatbots and voice agents. This is HTTP response streaming, not a WebSocket.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamRequest'
      responses:
        '200':
          description: Streamed audio content (chunked).
          headers:
            Transfer-Encoding:
              schema:
                type: string
              description: chunked
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    StreamRequest:
      type: object
      required:
      - Text
      - VoiceId
      properties:
        Text:
          type: string
          description: The text to synthesize (up to 1,000 characters).
          maxLength: 1000
          example: This is a test.
        VoiceId:
          type: string
          description: The voice to use.
          enum:
          - Scarlett
          - Dan
          - Liv
          - Will
          - Amy
          default: Scarlett
        Bitrate:
          type: string
          description: Output audio bitrate.
          enum:
          - 320k
          - 256k
          - 192k
          - 128k
          - 64k
          - 32k
          default: 192k
        Speed:
          type: string
          description: Playback speed adjustment, from -1.0 (slower) to 1.0 (faster).
          default: '0'
        Pitch:
          type: string
          description: Voice pitch, from 0.5 to 1.5.
          default: '1'
        Codec:
          type: string
          description: Audio codec for the streamed output.
          enum:
          - libmp3lame
          - pcm_mulaw
          - pcm_s16le
          default: libmp3lame
        Temperature:
          type: number
          format: float
          description: Sampling temperature, from 0.1 to 0.8.
          default: 0.25
  responses:
    RateLimited:
      description: Too many requests - the per-plan request-rate limit was exceeded.
    Unauthorized:
      description: Missing or invalid API key.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key issued from the Unreal Speech dashboard, sent as Authorization: Bearer <API_KEY>.'