> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mountsea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Text to Dialogue

> Synthesize multi-speaker dialogue audio

Synthesize multi-speaker dialogue from an `inputs[]` list. Each item has `text` and `voiceId`. Maps to ElevenLabs Text to Dialogue:

* Default: `POST /v1/text-to-dialogue/stream`
* `withTimestamps=true`: `POST /v1/text-to-dialogue/stream/with-timestamps`

<Info>
  This is an async task. The response contains a `taskId` — use [Get Task Status](/api-reference/eleven/task) to poll. On success, `result` includes `audioUrl`. Billing prefers the official `characterCost`; local `textLength` is used as a fallback.
</Info>

## Constraints

* Up to **100** dialogue lines per request (`inputs`)
* Up to **10** distinct `voiceId` values
* Each line: 1–5000 characters; text may include emotion tags such as `[giggling]` or `[curious]`

## Recommended Flow

<Steps>
  <Step title="List voices">
    Call [List Voices](/api-reference/eleven/voices) to obtain `voiceId` values (and optional `previewUrl`).
  </Step>

  <Step title="Create dialogue task">
    Call `POST /eleven/dialogue` with `inputs` (and optional `model`, `outputFormat`, `withTimestamps`, etc.).
  </Step>

  <Step title="Poll for audio">
    Poll `GET /eleven/tasks?taskId=xxx` until status is `completed`, then read `result.audioUrl`.
  </Step>
</Steps>

## Models

| Model                    | Description                        |
| ------------------------ | ---------------------------------- |
| `eleven_v3`              | Default for Dialogue (recommended) |
| `eleven_multilingual_v2` | Multilingual speech                |
| `eleven_turbo_v2_5`      | Faster generation                  |
| `eleven_flash_v2_5`      | Lowest latency                     |

<Tip>
  Set `withTimestamps: true` when you need character-level timing in the result. Use `settings.stability` (0–1) to control delivery consistency.
</Tip>


## OpenAPI

````yaml POST /eleven/dialogue
openapi: 3.0.0
info:
  title: Eleven AI
  description: API documentation for Eleven AI
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.mountsea.ai
    description: API Gateway
security: []
tags:
  - name: eleven
    description: ''
paths:
  /eleven/dialogue:
    post:
      tags:
        - eleven
      summary: 多角色对话合成
      description: |-
        对应 ElevenLabs Text to Dialogue：
        - 默认：POST /v1/text-to-dialogue/stream
        - withTimestamps=true：POST /v1/text-to-dialogue/stream/with-timestamps

        入参为 inputs[]（每项 text + voiceId），最多 10 个不同音色。
        返回 taskId，使用 GET /eleven/tasks 轮询。成功结果含 audioUrl；
        计费优先使用官方 character-cost（结果字段 characterCost），本地 textLength 作兜底。
      operationId: ApiPublicController_textToDialogue
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToDialogueDto'
      responses:
        '200':
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskIdDto'
      security:
        - bearerAuth: []
components:
  schemas:
    TextToDialogueDto:
      type: object
      properties:
        inputs:
          minItems: 1
          maxItems: 100
          description: 对话台词列表，每项含 text + voiceId
          example:
            - text: '[giggling] Knock knock'
              voiceId: JBFqnCBsd6RMkjVDRZzb
            - text: '[curious] Who is there?'
              voiceId: Aw4FAjKCGjjNkVhN1Xmq
          type: array
          items:
            $ref: '#/components/schemas/DialogueInputDto'
        model:
          enum:
            - eleven_v3
            - eleven_multilingual_v2
            - eleven_turbo_v2_5
            - eleven_flash_v2_5
          type: string
          description: 模型（Dialogue 官方默认 eleven_v3）
          example: eleven_v3
        outputFormat:
          enum:
            - mp3_22050_32
            - mp3_24000_48
            - mp3_44100_32
            - mp3_44100_64
            - mp3_44100_96
            - mp3_44100_128
            - mp3_44100_192
            - pcm_8000
            - pcm_16000
            - pcm_22050
            - pcm_24000
            - pcm_32000
            - pcm_44100
            - pcm_48000
            - ulaw_8000
            - alaw_8000
            - opus_48000_32
            - opus_48000_64
            - opus_48000_96
            - opus_48000_128
            - opus_48000_192
          type: string
          description: 音频输出格式
          example: mp3_44100_128
        withTimestamps:
          type: boolean
          description: 是否返回字符级时间戳。true 时走官方 stream/with-timestamps
          example: false
          default: false
        languageCode:
          type: string
          description: 语言代码 ISO-639-1（部分模型支持）
          example: en
        settings:
          description: 对话生成设置
          allOf:
            - $ref: '#/components/schemas/DialogueSettingsDto'
        seed:
          type: number
          description: 随机种子
          example: 12345
        applyTextNormalization:
          enum:
            - auto
            - 'on'
            - 'off'
          type: string
          description: 文本归一化
          example: auto
      required:
        - inputs
    TaskIdDto:
      type: object
      properties:
        taskId:
          type: string
          description: 任务 ID，用于后续查询结果
      required:
        - taskId
    DialogueInputDto:
      type: object
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 5000
          description: 该句台词文本（可含情感标签，如 [giggling]）
          example: '[giggling] Knock knock'
        voiceId:
          type: string
          minLength: 1
          description: 该句使用的音色 ID（非枚举）
          example: JBFqnCBsd6RMkjVDRZzb
      required:
        - text
        - voiceId
    DialogueSettingsDto:
      type: object
      properties:
        stability:
          type: number
          minimum: 0
          maximum: 1
          description: 稳定性 0-1
          example: 0.5
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````