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

# 创建翻译配音任务

> 在**与 vmeg.ai 相同的链路**上创建视频/音频翻译配音任务。首轮即产出配音成片：轮询[查询任务状态](/zh/api-reference/app-synced/tasks/get-task-detail)直到 `status` 为 `finished`，再读取 `result.outputs[0]`。任务会出现在网站**我的任务**中，打开 `editorUrl` 可继续编辑并重新导出。积分按网站规则扣除。

与独立版的差异：`options` 可省略；`source` 接受 `materialId` 或 `youtubeUrl`（不支持 `sourceUrl`）；`taskType` 必须与素材一致（`vt` 视频、`at` 音频）；`title` 设置网站上显示的任务名；传 `output`、`extraData` 返回 `400`；烧录字幕用 `options.subtitle`（替代 `text`）；结果需轮询获取，不走 Webhook。其他未知字段会被忽略。



## OpenAPI

````yaml /zh/api-reference/app-synced.json post /openapi/v1/app/task/media-translation/create-async
openapi: 3.1.0
info:
  title: VMEG 开放 API（应用同源版）
  description: >-
    与独立版协议一致，但任务、素材、克隆音色都在你的 VMEG 网站账号里：任务出现在**我的任务**，可在编辑器继续编辑并重新导出。结果通过轮询 `GET
    /openapi/v1/app/tasks/detail` 获取（无
    Webhook）。见[独立版与应用同源版的区别](/zh/guides/app-synced/comparison)。


    文中链接的指南按独立版编写，步骤相同，把路径前缀 `/openapi/v1` 换成 `/openapi/v1/app` 即可。
  version: 1.0.0
servers:
  - url: https://api.vmeg.ai
    description: 生产环境
security:
  - apiKeyAuth: []
tags:
  - name: 媒体翻译
    x-group: 视频与音频翻译配音
    description: >-
      在与 vmeg.ai 相同的链路上翻译配音已上传的视频/音频或 YouTube
      链接。首轮即产出配音成片，任务同时出现在**我的任务**，可继续编辑并重新导出。结果请轮询[查询任务状态](/zh/api-reference/app-synced/tasks/get-task-detail)。
  - name: 声音克隆
    x-group: 声音克隆
    description: 用一段短录音克隆音色。音色保存到网站**我的音色**，返回 `cv_*`，可用于翻译配音任务。
  - name: 任务管理
    x-group: 任务状态与历史
    description: 列出、查看或删除你 VMEG 账号下的视频/音频翻译任务，包括在网站创建的任务。
  - name: 资产 - 素材
    x-group: 上传文件（素材）
    description: 上传并管理网站素材库（**我的资产**）里的文件。完成上传（单文件或分片）后，把 `materialId` 传给 create-async。
  - name: 资产 - 音色
    x-group: 音色（预设与克隆）
    description: 列出系统预设音色（`sv_*`），管理你的克隆音色（`cv_*`，与网站**我的音色**相同）。
paths:
  /openapi/v1/app/task/media-translation/create-async:
    post:
      tags:
        - 媒体翻译
      summary: 创建翻译配音任务
      description: >-
        在**与 vmeg.ai
        相同的链路**上创建视频/音频翻译配音任务。首轮即产出配音成片：轮询[查询任务状态](/zh/api-reference/app-synced/tasks/get-task-detail)直到
        `status` 为 `finished`，再读取 `result.outputs[0]`。任务会出现在网站**我的任务**中，打开
        `editorUrl` 可继续编辑并重新导出。积分按网站规则扣除。


        与独立版的差异：`options` 可省略；`source` 接受 `materialId` 或 `youtubeUrl`（不支持
        `sourceUrl`）；`taskType` 必须与素材一致（`vt` 视频、`at` 音频）；`title` 设置网站上显示的任务名；传
        `output`、`extraData` 返回 `400`；烧录字幕用 `options.subtitle`（替代
        `text`）；结果需轮询获取，不走 Webhook。其他未知字段会被忽略。
      operationId: appMediaTranslationCreateAsync
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppMediaTranslationCreateRequest'
      responses:
        '200':
          description: 任务已受理。`editorUrl` 为该任务的网站编辑器地址。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppMediaTranslationAcceptedResponse'
components:
  parameters:
    IdempotencyKeyRequired:
      name: X-Idempotency-Key
      in: header
      required: true
      description: 创建任务或修改持久化数据的 `POST` 必填（最长 64 字符）。见 [幂等](/zh/guides/idempotency)。
      schema:
        type: string
        maxLength: 64
  schemas:
    AppMediaTranslationCreateRequest:
      type: object
      required:
        - taskType
        - source
        - language
      properties:
        taskType:
          $ref: '#/components/schemas/AppTaskType'
          description: '`vt` 视频翻译 | `at` 音频翻译。必须与素材类型一致，否则返回 `400`。'
        source:
          $ref: '#/components/schemas/AppMediaTranslationSource'
        language:
          $ref: '#/components/schemas/OpenApiMediaTranslationLanguage'
          description: 本地化源语言与目标语言
        options:
          $ref: '#/components/schemas/AppMediaTranslationOptions'
        title:
          type: string
          maxLength: 255
          description: '**我的任务**中显示的任务名（最多 255 个字符）。不传时取文件名或 YouTube 视频标题。'
    AppMediaTranslationAcceptedResponse:
      allOf:
        - $ref: '#/components/schemas/OpenApiResponseBase'
        - type: object
          properties:
            data:
              allOf:
                - $ref: '#/components/schemas/OpenApiMediaTranslationAcceptedData'
                - type: object
                  properties:
                    editorUrl:
                      type: string
                      description: 该任务的网站编辑器地址（登录同一 VMEG 账号）
    AppTaskType:
      type: string
      enum:
        - vt
        - at
      description: '`vt` 视频翻译 | `at` 音频翻译'
    AppMediaTranslationSource:
      type: object
      description: '`materialId` 与 `youtubeUrl` 二选一'
      properties:
        materialId:
          type: string
          description: >-
            素材
            ID，来自[应用同源版上传](/zh/api-reference/app-synced/assets/materials/gen-upload-url)或[素材列表](/zh/api-reference/app-synced/assets/materials/list-materials)
        youtubeUrl:
          type: string
          description: 'YouTube 视频链接（配合 `taskType: vt`）'
        subtitleMaterialId:
          type: string
          description: 可选，源语言字幕的 `.srt` 素材。其他文件类型返回 `400`。
        targetSubtitleMaterialId:
          type: string
          description: 可选，译文字幕的 `.srt` 素材。其他文件类型返回 `400`。
    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: 本地化源语言与目标语言
    AppMediaTranslationOptions:
      type: object
      required: []
      description: >-
        处理选项（均可省略）。音色规则与网站一致：`voiceClone.style`
        选择自动配音方式；`voiceSpeakers.selectedVoicesList` 手动指定音色（`sv_*` 系统音色、`cv_*`
        你的克隆音色），不能与 `voiceClone` 同时传。`dubbingVersion: V2` 不能与这两者同时使用。指定音色时请不要传
        `voiceSpeakers.timbreMethod`，传了且与音色设置冲突返回 `400`。
      properties:
        dubbingVersion:
          type: string
          enum:
            - V1
            - V2
          default: V1
          description: >-
            配音版本，与网站一致。`V1`（默认）：成熟稳定，可自动匹配或手动选择音色。`V2`：声音更自然、情感更丰富，音色自动选择，不能与
            `voiceClone`、`voiceSpeakers.selectedVoicesList` 同时传。
        subtitle:
          $ref: '#/components/schemas/AppMediaTranslationSubtitle'
        voiceClone:
          $ref: '#/components/schemas/AppMediaTranslationVoiceClone'
        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'
          description: >-
            对成片做口型同步。与网站一致，要求视频宽、高均不低于 360 像素，否则返回 `400`。YouTube
            来源不做预校验，请自行确保视频不低于 360p。
        voiceSpeakers:
          $ref: '#/components/schemas/OpenApiMediaTranslationVoiceSpeakers'
    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: 任务 ID（与网站任务 ID 相同）
        taskType:
          $ref: '#/components/schemas/AppTaskType'
        status:
          type: string
          enum:
            - running
            - failed
            - finished
          example: running
          description: 受理后的任务状态（`running`、`failed` 或 `finished`）
        createdAt:
          type: string
          description: 任务创建时间（ISO 8601）
    AppMediaTranslationSubtitle:
      type: object
      description: 烧录字幕（仅视频翻译）。省略时不烧录，与网站默认一致。替代独立版的 `text` 字段，传 `text` 返回 `400`。
      properties:
        type:
          type: string
          enum:
            - none
            - target
            - origin
            - multi
          description: >-
            `none` 不烧录 | `target` 译文 | `origin` 原文 | `multi` 双语。不传时：有
            `templateId` 为 `target`，否则为 `none`。音频翻译只接受 `none`。
        templateId:
          type: string
          description: >-
            字幕样式，来自[字幕模板列表](/zh/api-reference/app-synced/media-translation/list-subtitle-templates)。不传时使用网站默认样式（列表第一个）。
    AppMediaTranslationVoiceClone:
      type: object
      required: []
      description: 自动配音设置（可省略），省略时使用网站默认值。
      properties:
        style:
          type: string
          enum:
            - emotional
            - consistent
            - auto
            - tutorial
            - drama
            - smart
          default: emotional
          description: >-
            `emotional`（默认）| `consistent` 克隆原声；`auto` 由 VMEG 自动选择；`tutorial` /
            `drama` 为内容类型预设；`smart` 匹配预置音色。
        mode:
          type: string
          enum:
            - role
            - mix
            - sentence
          example: role
          description: role | mix | sentence。仅 `emotional` / `consistent` 可用，可省略。
        provider:
          type: string
          enum:
            - V1
            - V2
            - V3
            - V4
            - V5
          description: >-
            克隆引擎（`V1`–`V5`）。仅 `emotional` / `consistent`
            可用，可省略。见[支持的克隆方式](/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` — 智能匹配音色'
    OpenApiMediaTranslationSelectedVoice:
      type: object
      description: 为配音选定的系统或克隆音色
      properties:
        provider:
          type: string
          example: S1
          description: >-
            选用系统预设音色时可附带档位代号（`S1`、`S2`、…）。克隆音色为 `V1`–`V5`。见
            [音色](/zh/guides/app-synced/comparison)。
        voiceId:
          type: string
          description: >-
            `sv_*`
            来自[系统音色列表](/zh/api-reference/app-synced/assets/voices/list-system-voices)，`cv_*`
            来自[克隆音色列表](/zh/api-reference/app-synced/assets/voices/list-cloned-voices)
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        在 **`Authorization`** 请求头中传入 API Key（`Bearer <api_key>`）。见
        [鉴权](/zh/guides/authentication)。

````