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

# Create translate and dub job

> Start an async **translate and dub** pipeline for uploaded video or audio: transcribe speech → translate script → generate AI dubbing (voice clone or presets) → render dubbed output. Optional subtitles and lip sync via `options`. The HTTP response only confirms acceptance (`taskId`). Dubbed video/audio URLs arrive in your [Webhook](/guides/webhooks) callback (`event`: `openapi-media-translation`).

If you request audio translation (`taskType`: `at`) but the material is video, the server may run video translation (`vt`) instead — check `taskType` in the acceptance response.



## OpenAPI

````yaml /api-reference/openapi.json post /openapi/v1/task/media-translation/create-async
openapi: 3.1.0
info:
  title: VMEG Open API
  description: >-
    Integrate VMEG into your product: translate and dub video or audio,
    synthesize speech, clone voices, translate plain text, and manage API-side
    files. All responses use `{ code, message, data }`; `code === 200` means
    success.
  version: 1.0.0
servers:
  - url: https://api.vmeg.ai
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Media translation
    x-group: Video & audio translate and dub
    description: >-
      Localize uploaded video or audio end-to-end: transcribe speech, translate
      the script, generate AI dubbing (cloned or preset voices), and return new
      dubbed media. Optional subtitles and lip sync. **Async only** — dubbed
      files arrive via [Webhook](/guides/webhooks). This is not plain text
      translation; see [Media translation](/guides/products/media-translation).
  - name: TTS
    x-group: Text to speech (TTS)
    description: >-
      Turn text into natural speech with preset or cloned voices. **Sync**
      returns audio URLs in the HTTP response; **async** delivers results via
      [Webhook](/guides/webhooks). See [Text to
      speech](/guides/products/text-to-speech).
  - name: Voice clone
    x-group: Voice cloning
    description: >-
      Create a reusable voice from a short reference recording. Returns a
      `voiceId` you can pass to TTS or translate-and-dub jobs. See [Voice
      clone](/guides/products/voice-clone).
  - name: Text translation
    x-group: Text translation (text only)
    description: >-
      Translate plain text segments — no audio or video processing. For spoken
      content in media files, use **Video & audio translate and dub** instead.
      See [Text translation](/guides/products/text-translation).
  - name: Task management
    x-group: Task status and history
    description: >-
      List, inspect, or delete jobs created through any product API. Poll `GET
      .../tasks/detail` when you cannot rely on webhooks. Scoped to your **API
      Key**. See [Products overview](/guides/products/overview).
  - name: Assets - Materials
    x-group: Upload files (materials)
    description: >-
      Upload and manage video/audio files used as input for translate-and-dub
      jobs. Flow: finish the full upload (presigned or multipart → register) →
      pass the registered `materialId` to create-async. See [Material
      upload](/guides/assets/material-upload).
  - name: Assets - Voices
    x-group: Voices (presets and clones)
    description: >-
      List preset voices for TTS, or manage voices you cloned. Cloned voices are
      created via **Voice cloning**. See [Voices](/guides/assets/voices).
paths:
  /openapi/v1/task/media-translation/create-async:
    post:
      tags:
        - Media translation
      summary: Create translate and dub job
      description: >-
        Start an async **translate and dub** pipeline for uploaded video or
        audio: transcribe speech → translate script → generate AI dubbing (voice
        clone or presets) → render dubbed output. Optional subtitles and lip
        sync via `options`. The HTTP response only confirms acceptance
        (`taskId`). Dubbed video/audio URLs arrive in your
        [Webhook](/guides/webhooks) callback (`event`:
        `openapi-media-translation`).


        If you request audio translation (`taskType`: `at`) but the material is
        video, the server may run video translation (`vt`) instead — check
        `taskType` in the acceptance response.
      operationId: mediaTranslationCreateAsync
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiMediaTranslationCreateRequest'
      responses:
        '200':
          description: >-
            Acceptance only (`taskId`, `taskType`, `status`, `createdAt`). Final
            results are in the [Webhook](/guides/webhooks) callback request
            body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiMediaTranslationAcceptedResponse'
      callbacks:
        taskCompleted:
          https://{yourWebhookUrl}:
            post:
              summary: >-
                Webhook when async task finishes (`event`:
                `openapi-media-translation`)
              description: >-
                HTTP **request body** VMEG POSTs to your
                [Webhook](/guides/webhooks) URL when a Media translation async
                task finishes. The JSON field `event` is
                `openapi-media-translation` (see [Webhook request
                body](/guides/webhook-request)). Not part of the create-async
                **Response** above. Full schema: [Create media translation
                (async)](/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: Return 2xx promptly to stop retries
              method: post
              type: path
            path: https://{yourWebhookUrl}
components:
  parameters:
    IdempotencyKeyRequired:
      name: X-Idempotency-Key
      in: header
      required: true
      description: >-
        Required on mutating `POST` requests that create tasks or change
        persisted data (max 64 characters). See
        [Idempotency](/guides/idempotency).
      schema:
        type: string
        maxLength: 64
    CallbackTimestamp:
      name: X-Timestamp
      in: header
      required: true
      description: Unix timestamp in milliseconds (string)
      schema:
        type: string
    CallbackSignature:
      name: X-Signature
      in: header
      required: true
      description: Lowercase hex HMAC-SHA256(secret, X-Timestamp + rawBody)
      schema:
        type: string
  schemas:
    OpenApiMediaTranslationCreateRequest:
      type: object
      required:
        - taskType
        - source
        - language
        - options
      properties:
        taskType:
          type: string
          enum:
            - vt
            - at
          description: >-
            vt = video translation, at = audio translation. If `at` is used with
            a video material, the job may run as video translation
        source:
          $ref: '#/components/schemas/OpenApiMediaTranslationSource'
          description: Input material for this translation job
        language:
          $ref: '#/components/schemas/OpenApiMediaTranslationLanguage'
          description: Source and target locales for localization
        options:
          $ref: '#/components/schemas/OpenApiMediaTranslationOptions'
        extraData:
          $ref: '#/components/schemas/OpenApiExtraData'
          description: Optional client metadata; echoed in the completion webhook
    OpenApiMediaTranslationAcceptedResponse:
      allOf:
        - $ref: '#/components/schemas/OpenApiResponseBase'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/OpenApiMediaTranslationAcceptedData'
    OpenApiMediaTranslationTaskCompletedCallback:
      description: >-
        Webhook callback **request body** for Media translation when `event` is
        `openapi-media-translation`. `data.result` with CDN deliverables. See
        [Webhook request body](/guides/webhook-request) and [Create media
        translation
        (async)](/api-reference/media-translation/create-media-translation-async)
        → **Callbacks**.
      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: >-
            Registered material ID from a **fully completed** [Material
            upload](/guides/assets/material-upload) (or from [List
            materials](/guides/assets/materials)). Do not use a mid-upload ID
            from gen-upload-url / multipart initiate.
      description: Input material for this translation job
    OpenApiMediaTranslationLanguage:
      type: object
      required:
        - target
      properties:
        source:
          type: string
          default: auto
          example: auto
          description: >-
            Source locale (BCP-47) or `auto` for detection. See [Supported
            languages](/guides/supported-languages).
        target:
          type: string
          example: zh-CN
          description: >-
            Target locale (BCP-47). See [Supported
            languages](/guides/supported-languages).
      description: Source and target locales for localization
    OpenApiMediaTranslationOptions:
      type: object
      required:
        - voiceClone
      description: >-
        Pipeline options: dubbing, ASR, translation, separation, lip sync, and
        captions
      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: >-
            Title and subtitle styling / burn-in configuration (product-specific
            object)
        voiceSpeakers:
          $ref: '#/components/schemas/OpenApiMediaTranslationVoiceSpeakers'
    OpenApiExtraData:
      type: object
      additionalProperties: true
      description: >-
        Optional client metadata on async submit; echoed in the completion
        webhook (`extraData` in callback body). Not used on sync create
        endpoints.
    OpenApiResponseBase:
      type: object
      properties:
        code:
          type: integer
          example: 200
          description: Business code; 200 means success
        message:
          type: string
          example: ''
          description: Human-readable detail when `code` is not success
      required:
        - code
    OpenApiMediaTranslationAcceptedData:
      type: object
      description: Immediate response for media translation async create (no deliverables)
      required:
        - taskId
      properties:
        taskId:
          type: string
          description: Open API task ID
        taskType:
          $ref: '#/components/schemas/OpenApiTaskType'
          description: >-
            Effective task type (may differ from request when audio material is
            processed as video translation)
        status:
          type: string
          enum:
            - running
            - failed
            - finished
          example: running
          description: Task status after acceptance (`running`, `failed`, or `finished`)
        createdAt:
          type: string
          description: Task creation time (ISO 8601)
    OpenApiCallbackEnvelope:
      type: object
      description: >-
        Shared top-level fields of the webhook POST body when an async task
        finishes. See [Webhook request body](/guides/webhook-request) for the
        `event` field and per-product values.
      properties:
        code:
          type: integer
          example: 200
          description: Business outcome for this delivery
        version:
          type: string
          example: v1
          description: >-
            API version of the task (e.g. `v1`, `v2`). Matches the version in
            the request path (`/openapi/v1/...`).
        event:
          type: string
          enum:
            - openapi-tts
            - openapi-translate
            - openapi-clone-voice
            - openapi-media-translation
          example: openapi-tts
          description: >-
            Which product completed. Route your handler by this value:
            `openapi-tts` (TTS), `openapi-translate` (text translation),
            `openapi-clone-voice` (voice clone), `openapi-media-translation`
            (media translation). Listed in [Webhook request
            body](/guides/webhook-request).
        pipelineKey:
          type: string
          example: a1b2c3d4e5f6789012345678901234ab
          description: >-
            Stable ID for this async completion. Deduplicate webhook handling by
            this value — see [Webhook request
            body](/guides/webhook-request#deduplicate-by-pipelinekey).
        message:
          type: string
          description: Detail when `code` is not success
        extraData:
          type: object
          additionalProperties: true
          description: Echo of `extraData` from your async submit request
    OpenApiMediaTranslationCallbackData:
      type: object
      description: >-
        Task payload inside webhook `data` when `event` is
        `openapi-media-translation`. `data.result` with CDN deliverables.
      properties:
        taskId:
          type: string
          description: Open API task ID
        taskType:
          $ref: '#/components/schemas/OpenApiTaskType'
        status:
          type: string
          enum:
            - running
            - failed
            - finished
          description: Final task status (`finished` or `failed`)
        result:
          $ref: '#/components/schemas/OpenApiMediaTranslationCustomerResult'
          description: Fixed, sanitized customer result (CDN URLs + trimmed fields).
    OpenApiMediaTranslationVoiceClone:
      type: object
      description: Dubbing / voice clone settings (required inside `options`)
      properties:
        style:
          type: string
          enum:
            - emotional
            - consistent
          default: emotional
          description: >-
            Clone style: `emotional` (expressive) or `consistent`
            (accent-consistent)
        mode:
          type: string
          enum:
            - role
            - mix
            - sentence
          example: role
          description: How voices are assigned across speakers
        provider:
          type: string
          enum:
            - V1
            - V2
            - V3
            - V4
            - V5
          description: >-
            Clone engine (`V1`–`V5`). See [Supported clone
            methods](/guides/supported-clone-methods).
    OpenApiMediaTranslationTranscribe:
      type: object
      description: Automatic speech recognition (ASR) settings
      properties:
        mode:
          type: string
          enum:
            - fast
            - normal
          default: fast
          description: ASR speed vs accuracy trade-off
        type:
          type: string
          default: default
          description: ASR profile (product default when omitted)
    OpenApiMediaTranslationTranslate:
      type: object
      description: Text translation step inside the media pipeline
      properties:
        mode:
          type: string
          enum:
            - default
            - machine
          default: default
          description: >-
            `default` — standard localization. `machine` — machine translation
            mode
        prompt:
          type: string
          description: Custom prompt for the translation step
    OpenApiMediaTranslationSeparation:
      type: object
      description: Source separation (vocals vs background)
      properties:
        mode:
          type: string
          default: auto
          example: auto
          description: Separation mode (e.g. `auto`)
    OpenApiMediaTranslationDynamicVideoLength:
      type: object
      description: Dynamic video length adjustment (video translation)
      properties:
        enable:
          type: boolean
          description: Enable dynamic length matching between source and dubbed video
    OpenApiMediaTranslationLipsync:
      type: object
      description: >-
        Lip sync (video translation only; may add credits). See
        [Pricing](/guides/pricing)
      properties:
        enable:
          type: boolean
          default: false
          description: Enable lip sync on the output video
    OpenApiMediaTranslationVoiceSpeakers:
      type: object
      description: Speaker and timbre configuration for dubbing
      properties:
        selectedVoicesList:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationSelectedVoice'
          description: Explicit voice picks per speaker slot
        speakerNum:
          type: string
          example: auto
          description: Number of speakers to detect (`auto` or a numeric string)
        timbreMethod:
          type: string
          enum:
            - clone
            - smart
          example: clone
          description: '`clone` — clone from source audio. `smart` — smart voice matching'
    OpenApiTaskType:
      type: string
      description: >-
        Open API task type code. For media translation create request, use
        `taskType` codes `vt` (video translation) or `at` (audio translation).
      enum:
        - vt
        - at
        - tts
        - cloneVoice
        - textTranslation
      example: vt
    OpenApiMediaTranslationCustomerResult:
      type: object
      description: Media translation customer result (fixed shape). CDN URLs are HTTPS.
      properties:
        compress:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OpenApiMediaTranslationMediaFile'
          description: Transcode/compress outputs keyed by profile (e.g. `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: Speaker-to-voice matching list.
        tts:
          $ref: '#/components/schemas/OpenApiMediaTranslationTtsResult'
        alignment:
          $ref: '#/components/schemas/OpenApiMediaTranslationAlignment'
        build:
          $ref: '#/components/schemas/OpenApiMediaTranslationBuild'
    OpenApiMediaTranslationSelectedVoice:
      type: object
      description: A preset or cloned voice selected for dubbing
      properties:
        provider:
          type: string
          example: S1
          description: >-
            Optional preset tier (`S1`, `S2`, …) when you pick a system voice.
            Clone voices use `V1`–`V5`. See [Voices](/guides/assets/voices).
        voiceId:
          type: string
          description: >-
            Voice ID from [List system
            voices](/api-reference/assets/voices/list-system-voices) or your
            cloned voices
    OpenApiMediaTranslationMediaFile:
      type: object
      description: Media file (video/audio/image).
      properties:
        url:
          type: string
          description: CDN URL (HTTPS).
        duration:
          type: number
          description: Duration in seconds.
        size:
          type: integer
          format: int64
          description: File size in bytes.
        resolution:
          $ref: '#/components/schemas/OpenApiMediaTranslationResolution'
        fps:
          type: integer
          description: Frames per second (when applicable).
    OpenApiMediaTranslationAsrScripts:
      type: object
      description: ASR script summary (sanitized).
      properties:
        asrResults:
          type: array
          items:
            $ref: '#/components/schemas/OpenApiMediaTranslationAsrResultLine'
        monoAudio:
          type: string
          description: Mono audio URL (HTTPS).
        speakerNum:
          type: integer
          description: Detected speaker count.
        language:
          $ref: '#/components/schemas/OpenApiMediaTranslationLanguagePair'
        category:
          type: string
        industry:
          type: string
        keywords:
          type: array
          items:
            type: string
        ctcEnabled:
          type: boolean
    OpenApiMediaTranslationAudioSeparation:
      type: object
      description: Separated audio stems (CDN URLs).
      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: Voice clone configuration (input + echoed output).
      properties:
        provider:
          type: string
          description: >-
            Clone engine (`V1`–`V5`). See [Supported clone
            methods](/guides/supported-clone-methods).
        mode:
          type: string
        refAudio:
          type: string
          description: Reference audio URL (HTTPS).
    OpenApiMediaTranslationVoiceMatch:
      type: object
      properties:
        speaker:
          type: string
        voiceId:
          type: string
        provider:
          type: string
          description: >-
            Clone engine (`V1`–`V5`). See [Supported clone
            methods](/guides/supported-clone-methods).
        exampleLanguage:
          type: string
        content:
          type: string
        audio:
          type: string
          description: Example audio 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: Final build outputs (CDN URLs).
      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: >-
            Voice tier on this line — preset `S1`, `S2`, … or clone `V1`–`V5`.
            Keep with `voiceId` when you edit or resubmit lines. See
            [Voices](/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 audio URL (HTTPS).
        provider:
          type: string
          description: >-
            Voice tier on this line — preset `S1`, `S2`, … or clone `V1`–`V5`.
            Keep with `voiceId` when you edit or resubmit lines. See
            [Voices](/guides/assets/voices).
        voiceId:
          type: string
        duration:
          type: integer
          format: int64
        cloneMode:
          type: string
    OpenApiMediaTranslationAlignmentTrack:
      type: object
      properties:
        file:
          type: string
          description: Track file 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: >-
        Send your API Key in the **`Authorization`** header (`Bearer
        <api_key>`). See [Authentication](/guides/authentication).

````