> ## 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.

# 多角色对话合成

> 合成多角色对话音频

通过 `inputs[]` 列表合成多角色对话，每项包含 `text` 与 `voiceId`。对应 ElevenLabs Text to Dialogue：

* 默认：`POST /v1/text-to-dialogue/stream`
* `withTimestamps=true`：`POST /v1/text-to-dialogue/stream/with-timestamps`

<Info>
  这是一个异步任务。响应中包含 `taskId` — 使用[获取任务状态](/zh/api-reference/eleven/task)轮询。成功时 `result` 含 `audioUrl`。计费优先使用官方 `characterCost`，本地 `textLength` 作兜底。
</Info>

## 限制

* 每次请求最多 **100** 条台词（`inputs`）
* 最多 **10** 个不同的 `voiceId`
* 每行文本 1–5000 字符；可含情感标签，如 `[giggling]`、`[curious]`

## 推荐流程

<Steps>
  <Step title="获取音色">
    调用[获取音色列表](/zh/api-reference/eleven/voices)拿到 `voiceId`（以及可选的 `previewUrl`）。
  </Step>

  <Step title="创建对话任务">
    调用 `POST /eleven/dialogue`，传入 `inputs`（以及可选的 `model`、`outputFormat`、`withTimestamps` 等）。
  </Step>

  <Step title="轮询音频结果">
    轮询 `GET /eleven/tasks?taskId=xxx` 直至状态为 `completed`，再读取 `result.audioUrl`。
  </Step>
</Steps>

## 模型

| 模型                       | 说明                |
| ------------------------ | ----------------- |
| `eleven_v3`              | Dialogue 默认模型（推荐） |
| `eleven_multilingual_v2` | 多语言语音             |
| `eleven_turbo_v2_5`      | 更快生成              |
| `eleven_flash_v2_5`      | 更低延迟              |

<Tip>
  需要字符级时间戳时设置 `withTimestamps: true`。可用 `settings.stability`（0–1）控制表达稳定性。
</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

````