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

# 创建翻译配音任务

> 为已上传的视频或音频启动异步 **翻译配音** 流水线：识别语音 → 翻译文稿 → 生成 AI 配音（克隆或预设音色）→ 渲染输出。可通过 `options` 配置字幕与口型同步。HTTP 仅返回受理信息（`taskId`）。配音后视频/音频 URL 通过 [Webhook](/zh/guides/webhooks) 回调投递（`event`: `openapi-media-translation`）。

若请求音频翻译（`taskType`: `at`）但素材为视频，服务端可能按视频翻译（`vt`）执行 — 请以受理响应中的 `taskType` 为准。



## OpenAPI

````yaml /zh/api-reference/openapi.json post /openapi/v1/task/media-translation/create-async
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/media-translation/create-async:
    post:
      tags:
        - 媒体翻译
      summary: 创建翻译配音任务
      description: >-
        为已上传的视频或音频启动异步 **翻译配音** 流水线：识别语音 → 翻译文稿 → 生成 AI 配音（克隆或预设音色）→ 渲染输出。可通过
        `options` 配置字幕与口型同步。HTTP 仅返回受理信息（`taskId`）。配音后视频/音频 URL 通过
        [Webhook](/zh/guides/webhooks) 回调投递（`event`:
        `openapi-media-translation`）。


        若请求音频翻译（`taskType`: `at`）但素材为视频，服务端可能按视频翻译（`vt`）执行 — 请以受理响应中的 `taskType`
        为准。
      operationId: mediaTranslationCreateAsync
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiMediaTranslationCreateRequest'
      responses:
        '200':
          description: >-
            仅返回受理信息（`taskId`、`taskType`、`status`、`createdAt`）。最终生成结果在
            [Webhook](/zh/guides/webhooks) 回调请求体中。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiMediaTranslationAcceptedResponse'
      callbacks:
        taskCompleted:
          https://{yourWebhookUrl}:
            post:
              summary: '异步任务完成时的 Webhook（`event`: `openapi-media-translation`）'
              description: >-
                音视频翻译异步任务完成时的 Webhook **请求体**；`event` 为
                `openapi-media-translation`。见 [Webhook
                请求体](/zh/guides/webhook-request)。完整
                schema：[创建媒体翻译（异步）](/zh/api-reference/media-translation/create-media-translation-async)
                → **Callbacks**。
              parameters:
                - $ref: '#/components/parameters/CallbackTimestamp'
                - $ref: '#/components/parameters/CallbackSignature'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: >-
                        #/components/schemas/OpenApiMediaTranslationTaskCompletedCallback
              responses:
                '200':
                  description: 请尽快返回 2xx 以停止重试
              method: post
              type: path
            path: https://{yourWebhookUrl}
components:
  parameters:
    IdempotencyKeyRequired:
      name: X-Idempotency-Key
      in: header
      required: true
      description: 创建任务或修改持久化数据的 `POST` 必填（最长 64 字符）。见 [幂等](/zh/guides/idempotency)。
      schema:
        type: string
        maxLength: 64
    CallbackTimestamp:
      name: X-Timestamp
      in: header
      required: true
      description: Unix 时间戳（毫秒，字符串）
      schema:
        type: string
    CallbackSignature:
      name: X-Signature
      in: header
      required: true
      description: 小写十六进制 HMAC-SHA256(secret, X-Timestamp + 原始请求体)
      schema:
        type: string
  schemas:
    OpenApiMediaTranslationCreateRequest:
      type: object
      required:
        - taskType
        - source
        - language
        - options
      properties:
        taskType:
          type: string
          enum:
            - vt
            - at
          description: vt = 视频翻译，at = 音频翻译。若 `at` 对应视频素材，任务可能按视频翻译执行
        source:
          $ref: '#/components/schemas/OpenApiMediaTranslationSource'
          description: 本任务的输入素材
        language:
          $ref: '#/components/schemas/OpenApiMediaTranslationLanguage'
          description: 本地化源语言与目标语言
        options:
          $ref: '#/components/schemas/OpenApiMediaTranslationOptions'
        extraData:
          $ref: '#/components/schemas/OpenApiExtraData'
          description: 可选客户端元数据；完成时在 Webhook 中回传
    OpenApiMediaTranslationAcceptedResponse:
      allOf:
        - $ref: '#/components/schemas/OpenApiResponseBase'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/OpenApiMediaTranslationAcceptedData'
    OpenApiMediaTranslationTaskCompletedCallback:
      description: >-
        `event` 为 `openapi-media-translation` 时的媒体翻译 Webhook
        **请求体**；`data.result` 为 CDN 交付物。
      allOf:
        - $ref: '#/components/schemas/OpenApiCallbackEnvelope'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OpenApiMediaTranslationCallbackData'
    OpenApiMediaTranslationSource:
      type: object
      required:
        - materialId
      properties:
        materialId:
          type: string
          description: >-
            已走完完整 [素材上传](/zh/guides/assets/material-upload) 流程后得到的已注册素材 ID（也可来自
            [素材列表](/zh/guides/assets/materials)）。不要使用 gen-upload-url /
            分片发起返回的进行中 ID。
      description: 本任务的输入素材
    OpenApiMediaTranslationLanguage:
      type: object
      required:
        - target
      properties:
        source:
          type: string
          default: auto
          example: auto
          description: 源语言（BCP-47）或 `auto` 自动检测。见 [支持的语言](/zh/guides/supported-languages)。
        target:
          type: string
          example: zh-CN
          description: 目标语言 locale（BCP-47）。见 [支持的语言](/zh/guides/supported-languages)。
      description: 本地化源语言与目标语言
    OpenApiMediaTranslationOptions:
      type: object
      required:
        - voiceClone
      description: 流水线选项：配音、ASR、翻译、分离、唇形同步与字幕
      properties:
        voiceClone:
          $ref: '#/components/schemas/OpenApiMediaTranslationVoiceClone'
        transcribe:
          $ref: '#/components/schemas/OpenApiMediaTranslationTranscribe'
        translate:
          $ref: '#/components/schemas/OpenApiMediaTranslationTranslate'
        separation:
          $ref: '#/components/schemas/OpenApiMediaTranslationSeparation'
        dynamicVideoLength:
          $ref: '#/components/schemas/OpenApiMediaTranslationDynamicVideoLength'
        lipsync:
          $ref: '#/components/schemas/OpenApiMediaTranslationLipsync'
        text:
          type: object
          additionalProperties: true
          description: 标题与字幕样式/烧录配置（产品结构，键值因产品而异）
        voiceSpeakers:
          $ref: '#/components/schemas/OpenApiMediaTranslationVoiceSpeakers'
    OpenApiExtraData:
      type: object
      additionalProperties: true
      description: 异步提交时的可选客户端元数据；任务完成时在 Webhook 回调体 `extraData` 中回显。同步创建接口不使用。
    OpenApiResponseBase:
      type: object
      properties:
        code:
          type: integer
          example: 200
          description: 业务码；200 表示成功
        message:
          type: string
          example: ''
          description: 当 `code` 非成功时的说明信息
      required:
        - code
    OpenApiMediaTranslationAcceptedData:
      type: object
      description: 音视频翻译异步创建的立即响应（不含交付物）
      required:
        - taskId
      properties:
        taskId:
          type: string
          description: Open API 任务 ID
        taskType:
          $ref: '#/components/schemas/OpenApiTaskType'
          description: 实际执行的任务类型（音频素材可能按视频翻译处理，可与请求不同）
        status:
          type: string
          enum:
            - running
            - failed
            - finished
          example: running
          description: 受理后的任务状态（`running`、`failed` 或 `finished`）
        createdAt:
          type: string
          description: 任务创建时间（ISO 8601）
    OpenApiCallbackEnvelope:
      type: object
      description: >-
        异步任务完成时 Webhook POST 的公共顶层字段。`event` 取值与各产品说明见 [Webhook
        请求体](/zh/guides/webhook-request)。
      properties:
        code:
          type: integer
          example: 200
          description: 本次投递的业务结果码
        version:
          type: string
          example: v1
          description: 任务的 API 版本号（如 `v1`、`v2`），与请求路径中的版本一致（如 `/openapi/v1/...`）。
        event:
          type: string
          enum:
            - openapi-tts
            - openapi-translate
            - openapi-clone-voice
            - openapi-media-translation
          example: openapi-tts
          description: >-
            已完成的产品类型。请按此值路由：`openapi-tts`（TTS）、`openapi-translate`（文本翻译）、`openapi-clone-voice`（声音克隆）、`openapi-media-translation`（音视频翻译）。详见
            [Webhook 请求体](/zh/guides/webhook-request)。
        pipelineKey:
          type: string
          example: a1b2c3d4e5f6789012345678901234ab
          description: >-
            该次异步完成的稳定标识。请用此字段对接收端去重 — 见 [Webhook
            请求体](/zh/guides/webhook-request#按-pipelinekey-去重)。
        message:
          type: string
          description: 当 `code` 非成功时的说明
        extraData:
          type: object
          additionalProperties: true
          description: 与异步提交请求中的 `extraData` 一致
    OpenApiMediaTranslationCallbackData:
      type: object
      description: >-
        Webhook 中 `event` 为 `openapi-media-translation` 时，`data`
        内的任务载荷（`data.result` 含 CDN 交付物）。
      properties:
        taskId:
          type: string
          description: Open API 任务 ID
        taskType:
          $ref: '#/components/schemas/OpenApiTaskType'
        status:
          type: string
          enum:
            - running
            - failed
            - finished
          description: 最终任务状态（`finished` 或 `failed`）
        result:
          $ref: '#/components/schemas/OpenApiMediaTranslationCustomerResult'
          description: 固定结构的交付结果（URL 已转换为可直接访问的 HTTPS/CDN，并移除内部字段）。
    OpenApiMediaTranslationVoiceClone:
      type: object
      description: 配音/音色克隆设置（`options` 内必填）
      properties:
        style:
          type: string
          enum:
            - emotional
            - consistent
          default: emotional
          description: 克隆风格：`emotional`（偏情绪表达）或 `consistent`（口音一致）
        mode:
          type: string
          enum:
            - role
            - mix
            - sentence
          example: role
          description: 多说话人下的音色分配方式
        provider:
          type: string
          enum:
            - V1
            - V2
            - V3
            - V4
            - V5
          description: 克隆引擎（`V1`–`V5`）。见 [支持的克隆方式](/zh/guides/supported-clone-methods)。
    OpenApiMediaTranslationTranscribe:
      type: object
      description: 自动语音识别（ASR）设置
      properties:
        mode:
          type: string
          enum:
            - fast
            - normal
          default: fast
          description: ASR 速度与时效的权衡
        type:
          type: string
          default: default
          description: ASR 配置档（省略时使用产品默认）
    OpenApiMediaTranslationTranslate:
      type: object
      description: 媒体流水线中的文本翻译步骤
      properties:
        mode:
          type: string
          enum:
            - default
            - machine
          default: default
          description: '`default` — 标准本地化。`machine` — 机器翻译模式'
        prompt:
          type: string
          description: 翻译步骤的自定义 prompt
    OpenApiMediaTranslationSeparation:
      type: object
      description: 声源分离（人声与背景）
      properties:
        mode:
          type: string
          default: auto
          example: auto
          description: 分离模式（如 `auto`）
    OpenApiMediaTranslationDynamicVideoLength:
      type: object
      description: 动态视频时长（视频翻译）
      properties:
        enable:
          type: boolean
          description: 启用源片与配音成片的时长动态对齐
    OpenApiMediaTranslationLipsync:
      type: object
      description: 唇形同步（仅视频翻译；可能额外扣积分）。见 [计费](/zh/guides/pricing)
      properties:
        enable:
          type: boolean
          default: false
          description: 对输出视频启用唇形同步
    OpenApiMediaTranslationVoiceSpeakers:
      type: object
      description: 配音说话人与音色配置
      properties:
        selectedVoicesList:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationSelectedVoice'
          description: 为各说话人槽位显式指定音色
        speakerNum:
          type: string
          example: auto
          description: 检测的说话人数量（`auto` 或数字字符串）
        timbreMethod:
          type: string
          enum:
            - clone
            - smart
          example: clone
          description: '`clone` — 从源音频克隆。`smart` — 智能匹配音色'
    OpenApiTaskType:
      type: string
      description: Open API 任务类型代码。媒体翻译创建请求的 `taskType` 请使用 `vt`（视频翻译）或 `at`（音频翻译）。
      enum:
        - vt
        - at
        - tts
        - cloneVoice
        - textTranslation
      example: vt
    OpenApiMediaTranslationCustomerResult:
      type: object
      description: 媒体翻译对客结果（固定结构）。CDN URL 为 HTTPS。
      properties:
        compress:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OpenApiMediaTranslationMediaFile'
          description: 转码/压缩结果（key 为 480p/360p 等档位）。
        asrScripts:
          $ref: '#/components/schemas/OpenApiMediaTranslationAsrScripts'
        audioSeparation:
          $ref: '#/components/schemas/OpenApiMediaTranslationAudioSeparation'
        translatedScripts:
          $ref: '#/components/schemas/OpenApiMediaTranslationTranslatedScripts'
        voiceClone:
          $ref: '#/components/schemas/OpenApiMediaTranslationVoiceCloneResult'
        voiceMatch:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationVoiceMatch'
          description: 说话人与音色匹配列表。
        tts:
          $ref: '#/components/schemas/OpenApiMediaTranslationTtsResult'
        alignment:
          $ref: '#/components/schemas/OpenApiMediaTranslationAlignment'
        build:
          $ref: '#/components/schemas/OpenApiMediaTranslationBuild'
    OpenApiMediaTranslationSelectedVoice:
      type: object
      description: 为配音选定的系统或克隆音色
      properties:
        provider:
          type: string
          example: S1
          description: >-
            选用系统预设音色时可附带档位代号（`S1`、`S2`、…）。克隆音色为 `V1`–`V5`。见
            [音色](/zh/guides/assets/voices)。
        voiceId:
          type: string
          description: >-
            音色 ID，来自
            [系统音色列表](/zh/api-reference/assets/voices/list-system-voices) 或您的克隆音色
    OpenApiMediaTranslationMediaFile:
      type: object
      description: 媒体文件（视频/音频/图片）。
      properties:
        url:
          type: string
          description: CDN URL（HTTPS）。
        duration:
          type: number
          description: 时长（秒）。
        size:
          type: integer
          format: int64
          description: 文件大小（字节）。
        resolution:
          $ref: '#/components/schemas/OpenApiMediaTranslationResolution'
        fps:
          type: integer
          description: 帧率（FPS，适用时）。
    OpenApiMediaTranslationAsrScripts:
      type: object
      description: ASR 脚本汇总（已裁剪）。
      properties:
        asrResults:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationAsrResultLine'
        monoAudio:
          type: string
          description: 单声道音频 URL（HTTPS）。
        speakerNum:
          type: integer
          description: 检测到的说话人数。
        language:
          $ref: '#/components/schemas/OpenApiMediaTranslationLanguagePair'
        category:
          type: string
        industry:
          type: string
        keywords:
          type: array
          items:
            type: string
        ctcEnabled:
          type: boolean
    OpenApiMediaTranslationAudioSeparation:
      type: object
      description: 音频分离结果（CDN URL）。
      properties:
        sfxUrl:
          type: string
        musicUrl:
          type: string
        vocalUrl:
          type: string
        speechUrl:
          type: string
        otherUrl:
          type: string
        mnsUrl:
          type: string
    OpenApiMediaTranslationTranslatedScripts:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationTranslatedScriptLine'
    OpenApiMediaTranslationVoiceCloneResult:
      type: object
      description: 声音克隆配置（入参 + 回显出参）。
      properties:
        provider:
          type: string
          description: 克隆引擎（`V1`–`V5`）。见 [支持的克隆方式](/zh/guides/supported-clone-methods)。
        mode:
          type: string
        refAudio:
          type: string
          description: 参考音频 URL（HTTPS）。
    OpenApiMediaTranslationVoiceMatch:
      type: object
      properties:
        speaker:
          type: string
        voiceId:
          type: string
        provider:
          type: string
          description: 克隆引擎（`V1`–`V5`）。见 [支持的克隆方式](/zh/guides/supported-clone-methods)。
        exampleLanguage:
          type: string
        content:
          type: string
        audio:
          type: string
          description: 示例音频 URL（HTTPS）。
    OpenApiMediaTranslationTtsResult:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationTtsLine'
    OpenApiMediaTranslationAlignment:
      type: object
      properties:
        audio:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationAlignmentTrack'
        subtitle:
          type: array
          items: {}
        video:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationAlignmentTrack'
    OpenApiMediaTranslationBuild:
      type: object
      description: 最终构建产物（CDN URL）。
      properties:
        video:
          $ref: '#/components/schemas/OpenApiMediaTranslationMediaFile'
        images:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationImageFile'
        audio:
          $ref: '#/components/schemas/OpenApiMediaTranslationAudioFile'
    OpenApiMediaTranslationResolution:
      type: object
      properties:
        width:
          type: integer
        height:
          type: integer
    OpenApiMediaTranslationAsrResultLine:
      type: object
      properties:
        speaker:
          type: string
        start:
          type: number
        end:
          type: number
        text:
          type: string
        locale:
          type: string
        emotion:
          type: string
        name:
          type: string
        gender:
          type: string
        age:
          type: string
        id:
          type: string
        textWithBracket:
          type: string
        textWithBreak:
          type: string
    OpenApiMediaTranslationLanguagePair:
      type: object
      properties:
        source:
          type: string
        target:
          type: string
    OpenApiMediaTranslationTranslatedScriptLine:
      type: object
      properties:
        start:
          type: number
        end:
          type: number
        sourceText:
          type: string
        text:
          type: string
        speaker:
          type: string
        locale:
          type: string
        gender:
          type: string
        id:
          type: string
        voiceId:
          type: string
        provider:
          type: string
          description: >-
            该句使用的音色档位 — 预设 `S1`、`S2`、… 或克隆 `V1`–`V5`。改句或再次提交时请与 `voiceId` 一并保存。见
            [音色](/zh/guides/assets/voices)。
        speakerDisplayName:
          type: string
        emotion:
          type: string
        age:
          type: string
        sourceSyllable:
          type: integer
        targetSyllable:
          type: integer
        mode:
          type: string
    OpenApiMediaTranslationTtsLine:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
        ttsFile:
          type: string
          description: TTS 音频 URL（HTTPS）。
        provider:
          type: string
          description: >-
            该句使用的音色档位 — 预设 `S1`、`S2`、… 或克隆 `V1`–`V5`。改句或再次提交时请与 `voiceId` 一并保存。见
            [音色](/zh/guides/assets/voices)。
        voiceId:
          type: string
        duration:
          type: integer
          format: int64
        cloneMode:
          type: string
    OpenApiMediaTranslationAlignmentTrack:
      type: object
      properties:
        file:
          type: string
          description: 轨道文件 URL（HTTPS）。
        templateId:
          type: integer
        tracksTimes:
          type: array
          items:
            type: number
        timeRange:
          type: array
          items:
            type: number
        volumeScale:
          type: number
    OpenApiMediaTranslationImageFile:
      type: object
      properties:
        url:
          type: string
        size:
          type: integer
          format: int64
        resolution:
          $ref: '#/components/schemas/OpenApiMediaTranslationResolution'
    OpenApiMediaTranslationAudioFile:
      type: object
      properties:
        url:
          type: string
        duration:
          type: number
        size:
          type: integer
          format: int64
        fps:
          type: integer
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        在 **`Authorization`** 请求头中传入 API Key（`Bearer <api_key>`）。见
        [鉴权](/zh/guides/authentication)。

````