elevenlabs Text to Dialogue API

openapi: 3.2.0
info:
  title: ElevenLabs Text to Speech Text to Dialogue API
  description: The ElevenLabs Text to Speech API converts text into lifelike spoken audio with nuanced intonation, pacing, and emotional awareness. It supports multiple output formats including MP3, PCM, and mu-law, and offers a range of models such as Eleven v3, Flash v2.5 for ultra-low latency real-time applications, and Multilingual v2 for support across 70+ languages. Developers can select from thousands of pre-built voices or use custom cloned voices to generate speech that sounds natural and expressive.
  version: '1.0'
  contact:
    name: ElevenLabs Support
    url: https://help.elevenlabs.io
  termsOfService: https://elevenlabs.io/terms-of-service
servers:
- url: https://api.elevenlabs.io
  description: Production Server
security:
- apiKeyAuth: []
tags:
- name: Text to Dialogue
  description: Endpoints for converting text scripts with multiple speakers into dialogue audio.
paths:
  /v1/text-to-dialogue:
    post:
      operationId: createDialogue
      summary: Create dialogue
      description: Converts a dialogue script with multiple speakers into audio. Each segment of the script can be assigned a different voice, enabling multi-speaker audio generation from a single request.
      tags:
      - Text to Dialogue
      parameters:
      - $ref: '#/components/parameters/outputFormat'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToDialogueRequest'
      responses:
        '200':
          description: Dialogue audio generated successfully
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing API key
        '422':
          description: Unprocessable entity - validation error
  /v1/text-to-dialogue/with-timestamps:
    post:
      operationId: createDialogueWithTimestamps
      summary: Create dialogue with timestamps
      description: Converts a dialogue script with multiple speakers into audio and returns word-level timing information alongside the generated audio.
      tags:
      - Text to Dialogue
      parameters:
      - $ref: '#/components/parameters/outputFormat'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToDialogueRequest'
      responses:
        '200':
          description: Dialogue audio with timestamp data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimestampedAudioResponse'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing API key
        '422':
          description: Unprocessable entity - validation error
components:
  schemas:
    TextToDialogueRequest:
      type: object
      required:
      - segments
      properties:
        model_id:
          type: string
          description: The identifier of the model to use for dialogue generation.
        segments:
          type: array
          description: An array of dialogue segments, each with a speaker voice and text.
          items:
            $ref: '#/components/schemas/DialogueSegment'
    DialogueSegment:
      type: object
      required:
      - voice_id
      - text
      properties:
        voice_id:
          type: string
          description: The voice identifier for this segment of dialogue.
        text:
          type: string
          description: The text content for this segment of dialogue.
        voice_settings:
          $ref: '#/components/schemas/VoiceSettings'
    TimestampedAudioResponse:
      type: object
      properties:
        audio_base64:
          type: string
          description: Base64 encoded audio data.
        alignment:
          type: object
          description: Word-level timing information for the generated audio.
          properties:
            characters:
              type: array
              description: Array of characters with their timing information.
              items:
                type: object
                properties:
                  character:
                    type: string
                    description: The character.
                  start_time:
                    type: number
                    description: Start time in seconds.
                  end_time:
                    type: number
                    description: End time in seconds.
    VoiceSettings:
      type: object
      description: Voice settings that override the stored settings for the given voice. Applied only on the current request.
      properties:
        stability:
          type: number
          description: Controls the stability of the generated voice. Higher values produce more consistent output, lower values add variability.
          minimum: 0
          maximum: 1
        similarity_boost:
          type: number
          description: Controls how closely the AI adheres to the original voice. Higher values increase similarity to the target voice.
          minimum: 0
          maximum: 1
        style:
          type: number
          description: Controls the expressiveness and style of the speech delivery. Higher values produce more expressive speech.
          minimum: 0
          maximum: 1
          default: 0
        use_speaker_boost:
          type: boolean
          description: Enables speaker boost to increase voice clarity and reduce background artifacts.
          default: true
  parameters:
    outputFormat:
      name: output_format
      in: query
      required: false
      description: The desired output audio format. Supported values include mp3_44100_128, mp3_44100_192, pcm_16000, pcm_22050, pcm_24000, pcm_44100, ulaw_8000.
      schema:
        type: string
        default: mp3_44100_128
        enum:
        - mp3_22050_32
        - mp3_44100_32
        - mp3_44100_64
        - mp3_44100_96
        - mp3_44100_128
        - mp3_44100_192
        - pcm_16000
        - pcm_22050
        - pcm_24000
        - pcm_44100
        - ulaw_8000
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: xi-api-key
      description: ElevenLabs API key passed in the xi-api-key header for authentication.
externalDocs:
  description: ElevenLabs Text to Speech API Documentation
  url: https://elevenlabs.io/docs/api-reference/text-to-speech/convert