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

# 合成语音（同步）

> 一次请求完成文本转语音。音频 URL 立即在 HTTP `data` 中返回，无需 Webhook。



## OpenAPI

````yaml /zh/api-reference/openapi.json post /openapi/v1/task/tts/create
openapi: 3.1.0
info:
  title: VMEG Open API
  description: >-
    将 VMEG 集成到产品中：翻译并配音视频或音频、语音合成、声音克隆、纯文本翻译，以及管理 API 侧文件。响应格式为 `{ code,
    message, data }`；`code === 200` 表示成功。
  version: 1.0.0
servers:
  - url: https://api.vmeg.ai
    description: 生产环境
security:
  - apiKeyAuth: []
tags:
  - name: 媒体翻译
    x-group: 视频与音频翻译配音
    description: >-
      对上传的视频或音频做端到端本地化：识别语音、翻译文稿、生成 AI 配音（克隆或预设音色），并返回配音后的媒体。可选字幕与口型同步。**仅异步** —
      配音文件通过 [Webhook](/zh/guides/webhooks) 投递。这不是纯文本翻译；见
      [媒体翻译](/zh/guides/products/media-translation)。
  - name: TTS
    x-group: 文本转语音（TTS）
    description: >-
      用预设或克隆音色将文本合成为自然语音。**同步**在 HTTP 响应中返回音频 URL；**异步**通过
      [Webhook](/zh/guides/webhooks) 投递结果。见
      [文本转语音](/zh/guides/products/text-to-speech)。
  - name: 声音克隆
    x-group: 声音克隆
    description: >-
      从短参考录音创建可复用音色，返回可用于 TTS 或翻译配音任务的 `voiceId`。见
      [声音克隆](/zh/guides/products/voice-clone)。
  - name: 文本翻译
    x-group: 文本翻译（仅文本）
    description: >-
      翻译纯文本片段，不处理音频或视频。媒体中的口语内容请使用 **视频与音频翻译配音**。见
      [文本翻译](/zh/guides/products/text-translation)。
  - name: 任务管理
    x-group: 任务状态与历史
    description: >-
      列出、查看或删除通过各产品 API 创建的任务。无法依赖 Webhook 时可轮询 `GET .../tasks/detail`。范围限定于当前
      **API Key**。见 [产品概览](/zh/guides/products/overview)。
  - name: 资产 - 素材
    x-group: 上传文件（素材）
    description: >-
      上传并管理用于翻译配音任务的视频/音频。流程：预签名上传 → 登记素材 → 将 `materialId` 传入 create-async。见
      [素材上传](/zh/guides/assets/material-upload)。
  - name: 资产 - 音色
    x-group: 音色（预设与克隆）
    description: 列出 TTS 预设音色，或管理已克隆音色。克隆音色通过 **声音克隆** 创建。见 [音色](/zh/guides/assets/voices)。
paths:
  /openapi/v1/task/tts/create:
    post:
      tags:
        - TTS
      summary: 合成语音（同步）
      description: 一次请求完成文本转语音。音频 URL 立即在 HTTP `data` 中返回，无需 Webhook。
      operationId: ttsCreateSync
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiTtsCreateRequest'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiTtsCreateResponse'
components:
  parameters:
    IdempotencyKeyRequired:
      name: X-Idempotency-Key
      in: header
      required: true
      description: 创建任务或修改持久化数据的 `POST` 必填（最长 64 字符）。见 [幂等](/zh/guides/idempotency)。
      schema:
        type: string
        maxLength: 64
  schemas:
    OpenApiTtsCreateRequest:
      type: object
      required:
        - data
      properties:
        provider:
          type: string
          deprecated: true
          description: >-
            已弃用 — 请勿传入。请在每行传入 `voiceId`。见
            [文本转语音](/zh/guides/products/text-to-speech) 与
            [支持的克隆方式](/zh/guides/supported-clone-methods#文本转语音voiceid-与组批规则)。
        language:
          type: object
          properties:
            target:
              type: string
              example: en-US
              description: 目标语言 locale（BCP-47）。见 [支持的语言](/zh/guides/supported-languages)。
          description: 合成目标语言
        trim:
          type: boolean
          default: false
          description: 为 `true` 时裁剪输出音频首尾静音
        data:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/OpenApiTtsDataItem'
          description: >-
            待合成文本（最多 50 条）。每条需 `text` 及 [音色](/zh/guides/assets/voices) 中的
            `voiceId` 或 `timbreRefAudio`
        outputFormat:
          type: string
          enum:
            - wav
            - mp3
            - m4a
          default: m4a
          description: 输出音频格式：`wav`、`mp3` 或 `m4a`
    OpenApiTtsCreateResponse:
      allOf:
        - $ref: '#/components/schemas/OpenApiResponseBase'
        - type: object
          properties:
            data:
              description: 同步 HTTP 响应中返回的合成结果。
              allOf:
                - $ref: '#/components/schemas/OpenApiTtsCreateData'
    OpenApiTtsDataItem:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: 待合成文本
        voiceId:
          type: string
          description: >-
            本行使用的系统或克隆音色 ID。见 [音色](/zh/guides/assets/voices)；也可改用
            `timbreRefAudio`
        timbreRefAudio:
          type: string
          description: 未使用 [音色](/zh/guides/assets/voices) 中 `voiceId` 时的参考音频 URL（HTTPS）
        emoWeight:
          type: number
          minimum: 0
          maximum: 1
          description: 情感强度，配合 `emoRefAudio` / `emoPrompt` 使用（0–1）
        emoRefAudio:
          type: string
          description: 用于情感或演绎风格的参考音频 URL（HTTPS）
        emoPrompt:
          type: string
          description: 描述期望情感或说话风格的文本提示
        duration:
          type: number
          description: 目标时长（秒）
    OpenApiResponseBase:
      type: object
      properties:
        code:
          type: integer
          example: 200
          description: 业务码；200 表示成功
        message:
          type: string
          example: ''
          description: 当 `code` 非成功时的说明信息
      required:
        - code
    OpenApiTtsCreateData:
      type: object
      properties:
        taskId:
          type: string
          description: Open API 任务 ID
        results:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiTtsResultItem'
          description: 合成结果条目
        createdAt:
          type: string
          description: 任务创建时间（ISO 8601）
    OpenApiTtsResultItem:
      type: object
      properties:
        uri:
          type: string
          description: 合成音频 URL（HTTPS）
        duration:
          type: number
          description: 时长（秒）
        errorMessage:
          type: string
          description: 该条合成失败时的原因
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        在 **`Authorization`** 请求头中传入 API Key（`Bearer <api_key>`）。见
        [鉴权](/zh/guides/authentication)。

````