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

# Create Video Translation

> Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video_translation_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality.



## OpenAPI

````yaml /openapi/external-api.json post /v3/video-translations
openapi: 3.1.0
info:
  title: HeyGen External API
  version: 1.0.0
  description: >-
    HeyGen's external API for programmatic AI video creation. See
    https://docs.heygen.com for full documentation.
  contact:
    name: HeyGen Product Infra
    url: https://heygen.com
servers:
  - url: https://api.heygen.com
    description: Production
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Video Agent
    description: Create videos from text prompts using AI
  - name: Videos
    description: Create, list, retrieve, and delete videos
  - name: Templates
    description: Generate videos from reusable templates by replacing their variables
  - name: Audio
    description: Search the background-music and sound-effects catalog
  - name: Video Translate
    description: Translate videos into other languages
  - name: AI Clipping
    description: Turn long-form videos into ready-to-share short clips with captions
  - name: Batches
    description: Create and track batches of videos.
  - name: Video Translation Batches
    description: Create and track batches of video translations.
  - name: Lipsync Batches
    description: Create and track batches of lipsyncs.
  - name: Asset Batches
    description: Create and track batches of direct-to-S3 asset uploads.
  - name: User
    description: Account information and billing
  - name: API Keys
    description: Inspect the API key authenticating the current request
  - name: Avatars
    description: List and manage avatars and looks
  - name: Assets
    description: Upload files for use in video creation
  - name: Folders
    description: >-
      Create folders to organize videos and translations in the workspace, and
      look up any folder, Assets library folders included, by id
  - name: Webhooks
    description: Manage webhook endpoints and events
  - name: Lipsync
    description: Dub or replace audio on existing videos
  - name: Brand
    description: >-
      Brand-related resources — brand kits (colors, fonts, logos) and brand
      glossaries (custom term translations)
  - name: HyperFrames
    description: Render HyperFrames composition zips into video — separate from /v3/videos
  - name: Models
    description: ''
  - name: Filler Word Removal
    description: ''
paths:
  /v3/video-translations:
    post:
      tags:
        - Video Translate
      summary: Create Video Translation
      description: >-
        Translates a video into one or more target languages with voice cloning
        and lip-sync. Returns one video_translation_id per language. Use mode:
        'speed' (default) for fast turnaround or 'precision' for higher lip-sync
        quality.
      operationId: createVideoTranslationV3
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVideoTranslationRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/VideoTranslationCreateResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: invalid_parameter
                  message: '''video_url'' is required.'
                  param: video_url
                  doc_url: null
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired API key. Verify your x-api-key header.
                  param: null
                  doc_url: null
        '409':
          $ref: '#/components/responses/IdempotencyInProgress'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    Too many requests. Retry after the duration specified in the
                    Retry-After header.
                  param: null
                  doc_url: null
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional client-supplied key for safely retrying mutations. Subsequent
        calls within 24 hours that share this key replay the original response —
        even if the request body differs slightly (a warning is logged). A retry
        that arrives while the original is still in flight gets a 409
        `request_in_progress`. Keys must be 1–255 characters from
        `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and
        per-resource: the same key on a different route or path parameter is
        independent.
      schema:
        type: string
        pattern: ^[A-Za-z0-9_\-:.]{1,255}$
        maxLength: 255
        minLength: 1
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    CreateVideoTranslationRequest:
      additionalProperties: false
      description: Request body for POST /v3/video-translations.
      properties:
        video:
          description: >-
            Source video — provide as {type: 'url', url: '...'} or {type:
            'asset_id', asset_id: '...'}
          discriminator:
            mapping:
              asset_id: '#/components/schemas/AssetId'
              url: '#/components/schemas/AssetUrl'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/AssetUrl'
            - $ref: '#/components/schemas/AssetId'
          title: Video
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Title for the translation job
          title: Title
        output_languages:
          description: >-
            Target language names (e.g. 'Chinese (Cantonese, Traditional)',
            'Spanish (Spain)', 'English'). Use GET
            /v3/video-translations/languages for valid values. Use one for
            single translation, multiple for batch.
          items:
            type: string
          minItems: 1
          title: Output Languages
          type: array
          x-mcp-schema:
            description: >-
              Target language names, e.g. 'English', 'Spanish', 'Hindi'. Use a
              name from the available_on_current_plan field of GET
              /v3/video-translations/languages. Most premium dialect voices have
              a region in brackets (e.g. 'Hindi (India)') and aren't on the free
              plan, so prefer the plain name unless the user asked for a
              specific accent. Use one for single translation, multiple for
              batch.
        audio:
          anyOf:
            - discriminator:
                mapping:
                  asset_id: '#/components/schemas/AssetId'
                  url: '#/components/schemas/AssetUrl'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/AssetUrl'
                - $ref: '#/components/schemas/AssetId'
            - type: 'null'
          default: null
          description: >-
            Custom audio for dubbing — provide as {type: 'url', url: '...'} or
            {type: 'asset_id', asset_id: '...'}
          title: Audio
        input_language:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Source language name, e.g. 'English' (auto-detected if omitted)
          title: Input Language
          x-mcp-visible: false
        translate_audio_only:
          default: false
          description: Only translate audio, keep original video
          title: Translate Audio Only
          type: boolean
        speaker_num:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: Number of speakers (improves speaker separation)
          title: Speaker Num
        mode:
          $ref: '#/components/schemas/VideoTranslationMode'
          default: speed
          description: >-
            Translation quality mode: 'speed' (faster) or 'precision' (higher
            quality, uses avatar inference)
        callback_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Webhook URL for completion notifications
          title: Callback Url
        callback_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: ID included in webhook payload
          title: Callback Id
        output_uploads:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/OutputUploadRequest'
              type: object
            - type: 'null'
          default: null
          description: >-
            Upload each translated video's files straight into your own storage,
            keyed by a language from output_languages. Give a presigned PUT URL
            per file, for Amazon S3, Google Cloud Storage or Azure Blob Storage;
            HeyGen uploads each file when that language finishes. Languages
            without an entry are not uploaded. Not available with audio input or
            in batches. Available to enabled workspaces.
          title: Output Uploads
          x-cli-visible: false
          x-mcp-visible: false
        enable_caption:
          default: false
          deprecated: true
          description: >-
            Deprecated and ignored: captions are always generated; whether to
            display them is a download-side choice.
          title: Enable Caption
          type: boolean
        keep_the_same_format:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: Preserve the source video's encoding specs (resolution, bitrate).
          title: Keep The Same Format
        enable_dynamic_duration:
          default: true
          description: Allow dynamic duration adjustment
          title: Enable Dynamic Duration
          type: boolean
        disable_music_track:
          default: false
          description: Remove background music
          title: Disable Music Track
          type: boolean
        enable_speech_enhancement:
          default: false
          description: Enhance speech quality
          title: Enable Speech Enhancement
          type: boolean
        enable_watermark:
          default: false
          description: Add watermark to output
          title: Enable Watermark
          type: boolean
        start_time:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Start time in seconds for partial translation
          title: Start Time
        end_time:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: End time in seconds for partial translation
          title: End Time
        brand_voice_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          deprecated: true
          description: >-
            Brand glossary ID for custom term translations. Legacy field name
            for `brand_glossary_id` — both are accepted and resolve to the same
            workspace record. Discover IDs via GET /v3/brand-glossaries.
          title: Brand Voice Id
        brand_glossary_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Brand glossary ID for custom term translations (e.g. translate
            'Reformer' as the Pilates equipment, not 'political activist').
            Alias for the legacy `brand_voice_id` field. Discover IDs via GET
            /v3/brand-glossaries.
          title: Brand Glossary Id
        stock_voice_config:
          anyOf:
            - $ref: '#/components/schemas/StockVoiceConfig'
            - type: 'null'
          default: null
          description: >-
            Use a preset stock voice for the translation instead of recreating
            the original speaker's voice. By default, Video Translation clones
            the original speaker so the result sounds like them; with this
            enabled, the translation is spoken by a natural preset voice
            optimized for clear pronunciation and accent in the target language
            (the result will not sound like the original speaker). Enterprise
            feature, available for selected accounts and languages by request —
            contact your HeyGen account team.
          x-mcp-visible: false
        srt:
          anyOf:
            - discriminator:
                mapping:
                  asset_id: '#/components/schemas/AssetId'
                  url: '#/components/schemas/AssetUrl'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/AssetUrl'
                - $ref: '#/components/schemas/AssetId'
            - type: 'null'
          default: null
          description: >-
            Custom subtitle file — provide as {type: 'url', url: '...'} or
            {type: 'asset_id', asset_id: '...'}.
          title: Srt
        srt_role:
          anyOf:
            - enum:
                - input
                - output
              type: string
            - type: 'null'
          default: null
          description: >-
            Which video the subtitle applies to: 'input' (source) or 'output'
            (translated).
          title: Srt Role
        fps_mode:
          anyOf:
            - enum:
                - vfr
                - cfr
                - passthrough
              type: string
            - type: 'null'
          default: null
          description: >-
            Frame rate mode for the output video. 'vfr' = variable frame rate,
            'cfr' = constant frame rate, 'passthrough' = match the source. Only
            takes effect when a custom 'audio' track is provided.
          title: Fps Mode
        folder_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Destination folder ID in the caller's workspace, for example one
            returned by POST /v3/folders. Omit, pass null, or pass an empty
            string to place the result at the workspace root. The id must name a
            folder that is not in the trash and that the caller can write to.
            Assets library folders are accepted, but the HeyGen app files only
            assets in them, so a result placed there may not appear in the
            Assets library view. An unknown id, a folder in another workspace, a
            project of another kind such as a brand kit, or a trashed folder is
            rejected with 404 before anything is created.
          title: Folder Id
      required:
        - video
        - output_languages
      title: CreateVideoTranslationRequest
      type: object
    VideoTranslationCreateResponse:
      description: Response for POST /v3/video-translations.
      properties:
        video_translation_ids:
          description: Video translation IDs, one per target language
          items:
            type: string
          title: Video Translation Ids
          type: array
        warnings:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          description: >-
            Changes made to the request before it was accepted, e.g. a target
            language replaced by the one the plan includes
          title: Warnings
      required:
        - video_translation_ids
      title: VideoTranslationCreateResponse
      type: object
    StandardAPIError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: invalid_parameter
        message:
          type: string
          description: Human-readable error message
          example: Video not found
        param:
          type:
            - string
            - 'null'
          description: Which request field caused the error
        doc_url:
          type:
            - string
            - 'null'
          description: Link to error documentation
        errors:
          type: array
          description: >-
            Per-item error details for batch/multi-node failures (e.g. graph
            compilation errors by node).
          items:
            $ref: '#/components/schemas/StandardAPIErrorDetail'
        request_id:
          type: string
          description: >-
            Request identifier, also returned in the X-HeyGen-Request-Id
            response header. Include it when contacting support.
          example: 8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40
      required:
        - code
        - message
    AssetId:
      additionalProperties: false
      description: Asset input via HeyGen asset ID from the asset upload endpoint.
      properties:
        type:
          const: asset_id
          description: Input type discriminator
          title: Type
          type: string
        asset_id:
          description: >-
            HeyGen asset ID from an asset upload or import; not a third-party
            file ID.
          title: Asset Id
          type: string
      required:
        - type
        - asset_id
      title: AssetId
      type: object
    AssetUrl:
      additionalProperties: false
      description: Asset input via publicly accessible HTTPS URL.
      properties:
        type:
          const: url
          description: Input type discriminator
          title: Type
          type: string
        url:
          description: >-
            Public http(s) URL HeyGen can download without auth or redirects.
            Not a local or sandbox path (/mnt/data/..., file://, sandbox:);
            upload such files and pass asset_id.
          title: Url
          type: string
      required:
        - type
        - url
      title: AssetUrl
      type: object
    VideoTranslationMode:
      enum:
        - speed
        - precision
      title: VideoTranslationMode
      type: string
    OutputUploadRequest:
      additionalProperties: false
      description: Where the finished files go. Each file needs its own URL.
      properties:
        video:
          $ref: '#/components/schemas/UploadTargetRequest'
          description: Upload target for the finished video file.
        captions:
          anyOf:
            - $ref: '#/components/schemas/UploadTargetRequest'
            - type: 'null'
          default: null
          description: Upload target for the caption file, when the video has captions.
        thumbnail:
          anyOf:
            - $ref: '#/components/schemas/UploadTargetRequest'
            - type: 'null'
          default: null
          description: Upload target for the thumbnail image.
      required:
        - video
      title: OutputUploadRequest
      type: object
    StockVoiceConfig:
      additionalProperties: false
      description: >-
        Stock-voice options for a video translation request.


        Use a preset HeyGen voice for the translation instead of recreating the
        original

        speaker's voice. Enterprise feature, available for selected accounts and
        languages

        by request. See the ``stock_voice_config`` request field for usage.
      properties:
        use_stock_voice:
          default: false
          description: >-
            Set to true to use a preset stock voice instead of cloning the
            original speaker.
          title: Use Stock Voice
          type: boolean
        preferred_stock_voice_ids:
          description: >-
            Optional. Pin specific stock voice IDs to draw from. If omitted, the
            target language's default stock-voice pool is used.
          items:
            type: string
          title: Preferred Stock Voice Ids
          type: array
      title: StockVoiceConfig
      type: object
    StandardAPIErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: unknown_node_type
        message:
          type: string
          description: Human-readable error message
          example: Unknown node type
        node_id:
          type: string
          description: Graph node id this error pertains to, if applicable
        port:
          type: string
          description: Port name on the node this error pertains to, if applicable
        path:
          type: string
          description: Field path within the item this error pertains to, if applicable
      required:
        - code
        - message
    UploadTargetRequest:
      additionalProperties: false
      properties:
        url:
          description: >-
            A presigned PUT URL for Amazon S3, Google Cloud Storage or Azure
            Blob Storage, signed for the object key this file should land at. It
            must stay valid for at least one hour; 24 hours or more is
            recommended, because the file is uploaded when the video finishes.
          maxLength: 4096
          title: Url
          type: string
        headers:
          additionalProperties:
            type: string
          description: >-
            Headers the URL was signed with, sent exactly as given. Allowed:
            Content-Type, Content-MD5, Content-Disposition, Content-Encoding,
            Content-Language, Cache-Control, and x-amz-*, x-goog-* or x-ms-*
            headers.
          title: Headers
          type: object
      required:
        - url
      title: UploadTargetRequest
      type: object
  responses:
    IdempotencyInProgress:
      description: >-
        A prior request with this Idempotency-Key is still in progress. Wait for
        the original request to complete, then retry.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                $ref: '#/components/schemas/StandardAPIError'
          example:
            error:
              code: request_in_progress
              message: >-
                A request with this Idempotency-Key is already in progress.
                Retry shortly.
              param: null
              doc_url: null
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: HeyGen API key. Obtain from your HeyGen dashboard.
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.