openapi: 3.0.3
info:
  title: Narakeet Account Text to Speech API
  description: The Narakeet API turns text and Markdown scripts into narrated audio and video programmatically. It exposes a text-to-speech endpoint (returning MP3, M4A, or WAV) in two modes - a short-content streaming mode that returns audio bytes directly, and a long-content JSON polling mode that returns a status URL to poll while a longer build runs asynchronously - plus a Markdown-to-video build workflow (upload a zip of the script and assets, trigger a build, then poll for the finished MP4), a voice listing endpoint, and an account credits endpoint. All build requests authenticate with an `x-api-key` header. API access requires a top-up or metered commercial Narakeet account; free and unmetered accounts cannot use the API. The default quota is 86,400 requests per day (1 per second). Pre-signed status and result URLs returned by the polling and video workflows do not require the API key.
  version: '1.0'
  contact:
    name: Narakeet
    url: https://www.narakeet.com
    email: contact@narakeet.com
servers:
- url: https://api.narakeet.com
  description: Narakeet API
security:
- apiKeyAuth: []
tags:
- name: Text to Speech
  description: Build narrated audio (MP3, M4A, WAV) from text, SubRip, or WebVTT input.
paths:
  /text-to-speech/{format}:
    post:
      operationId: buildTextToSpeech
      tags:
      - Text to Speech
      summary: Build speech audio from text
      description: 'Converts text (or SubRip / WebVTT subtitle input) into narrated audio. Two modes are selected by the `Accept` header. With `Accept: application/octet-stream` the endpoint operates as a short-content streaming API - input is limited to about 1 KB and the audio bytes are returned directly in the response, with the duration in the `x-duration-seconds` response header (WAV is not available in this mode). Without that Accept header the endpoint operates as a long-content polling API - input up to about 1024 KB is accepted and the response is a JSON object containing a `statusUrl` to poll. Use `Accept: application/zip` with multi-scene input (scenes separated by `---`) for batch audio, or `Accept: application/json+vtt` to also receive subtitle result URLs.'
      parameters:
      - name: format
        in: path
        required: true
        description: Output audio format. WAV is only available via the polling API.
        schema:
          type: string
          enum:
          - mp3
          - m4a
          - wav
      - name: voice
        in: query
        required: false
        description: Name of the voice to use (see the Voices endpoint for valid names).
        schema:
          type: string
          example: mickey
      - name: voice-speed
        in: query
        required: false
        description: Reading speed multiplier (1.2 = 20% faster, 0.8 = 20% slower).
        schema:
          type: number
          example: 1.1
      - name: voice-volume
        in: query
        required: false
        description: Relative loudness of the narration.
        schema:
          type: string
          example: soft
      requestBody:
        required: true
        description: The script to narrate. Content-Type text/plain for plain text, application/x-subrip (or text/srt) for SubRip, or text/vtt for WebVTT.
        content:
          text/plain:
            schema:
              type: string
              example: Hello from the Narakeet text to speech API.
      responses:
        '200':
          description: Streaming mode returns the audio bytes directly. Polling mode returns a JSON object with a statusUrl to poll for the build result.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/BuildTask'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /status:
    get:
      operationId: pollBuildStatus
      tags:
      - Text to Speech
      summary: Poll a build status URL
      description: Represents polling the pre-signed `statusUrl` returned by the polling audio build and the video build. The actual URL is time-limited and pre-signed, so no API key is required. Poll until `finished` is true, then read the `result` download URL. This path is illustrative; always use the exact statusUrl returned in the build response.
      responses:
        '200':
          description: Current build status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildStatus'
components:
  schemas:
    BuildTask:
      type: object
      description: Response from a polling audio build or a video build.
      properties:
        statusUrl:
          type: string
          format: uri
          description: Pre-signed URL to poll for build progress and the final result.
    BuildStatus:
      type: object
      description: The state of an asynchronous build, returned when polling the status URL.
      properties:
        message:
          type: string
          description: Status or error message.
        finished:
          type: boolean
          description: True when the build has completed (successfully or not).
        succeeded:
          type: boolean
          description: True when the build finished successfully.
        percent:
          type: integer
          description: Build progress from 0 to 100.
        result:
          type: string
          format: uri
          description: Download URL for the finished audio or video (valid for a limited time).
        poster:
          type: string
          format: uri
          description: Poster image URL for a finished video (video builds only).
        durationInSeconds:
          type: integer
          description: Duration of the produced media in seconds.
  responses:
    Unauthorized:
      description: Missing or invalid API key, or the account is not eligible for API access.
    TooManyRequests:
      description: The daily request quota (default 86,400 per day, 1 per second) was exceeded.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key