openapi: 3.0.3
info:
  title: Unreal Speech 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: Speech
    description: Synchronous text-to-speech returning an MP3 and timestamp URLs.
  - name: Stream
    description: Low-latency HTTP streaming synthesis returning audio bytes.
  - name: Synthesis Tasks
    description: Asynchronous synthesis for long-form audio via submit-and-poll.
paths:
  /speech:
    post:
      operationId: createSpeech
      tags:
        - Speech
      summary: Synthesize speech (synchronous)
      description: >-
        Converts up to 3,000 characters of text into speech and returns JSON
        containing an MP3 audio URL plus word- or sentence-level timestamp URLs.
        Use for medium-length, non-time-critical synthesis.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeechRequest'
      responses:
        '200':
          description: Synthesis result with audio and timestamp URLs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeechResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /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'
  /synthesisTasks:
    post:
      operationId: createSynthesisTask
      tags:
        - Synthesis Tasks
      summary: Create an asynchronous synthesis task
      description: >-
        Submits up to 500,000 characters of text for asynchronous synthesis and
        immediately returns a TaskId. Optimized for long-form audio such as
        audiobooks and articles. Provide an optional CallbackUrl to be notified
        of status changes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SynthesisTaskRequest'
      responses:
        '200':
          description: The created synthesis task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SynthesisTask'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    get:
      operationId: getSynthesisTask
      tags:
        - Synthesis Tasks
      summary: Get synthesis task status
      description: >-
        Polls the status of a previously submitted synthesis task by TaskId.
        Returns the current status and, when complete, the output audio URI(s).
      parameters:
        - name: TaskId
          in: query
          required: true
          description: The identifier returned when the task was created.
          schema:
            type: string
      responses:
        '200':
          description: The synthesis task and its current status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SynthesisTask'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No task found for the supplied TaskId.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key issued from the Unreal Speech dashboard, sent as
        Authorization: Bearer <API_KEY>.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
    RateLimited:
      description: Too many requests - the per-plan request-rate limit was exceeded.
  schemas:
    SpeechRequest:
      type: object
      required:
        - Text
        - VoiceId
      properties:
        Text:
          type: string
          description: The text to synthesize (up to 3,000 characters).
          maxLength: 3000
          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'
        TimestampType:
          type: string
          description: Granularity of the returned timestamps.
          enum: [word, sentence]
          default: sentence
    SpeechResponse:
      type: object
      properties:
        OutputUri:
          type: string
          format: uri
          description: URL to the synthesized MP3 audio file.
        TimestampsUri:
          type: string
          format: uri
          description: URL to the JSON timestamps file.
    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
    SynthesisTaskRequest:
      type: object
      required:
        - Text
        - VoiceId
      properties:
        Text:
          type: string
          description: The text to synthesize (up to 500,000 characters). May also be supplied as a list of strings.
          example: This is a long-form 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'
        TimestampType:
          type: string
          description: Granularity of the returned timestamps.
          enum: [word, sentence]
          default: sentence
        CallbackUrl:
          type: string
          format: uri
          description: Optional webhook URL that Unreal Speech posts task status updates to.
    SynthesisTask:
      type: object
      properties:
        TaskId:
          type: string
          description: Identifier for the synthesis task.
        TaskStatus:
          type: string
          description: Current status of the task (for example scheduled, inProgress, completed, or failed).
        OutputUri:
          type: string
          format: uri
          description: URL to the synthesized MP3 audio file, present when the task is complete.
        TimestampsUri:
          type: string
          format: uri
          description: URL to the JSON timestamps file, present when the task is complete.
        CreationTime:
          type: string
          description: When the task was created.