> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Video Translation Batch > Submit up to 100 video-translation payloads (identical in shape to POST /v3/video-translations) as a single batch. A payload targeting multiple output_languages expands to one batch item per language, and each item is created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/video-translations/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch. ## OpenAPI ````yaml /openapi/external-api.json post /v3/video-translations/batches 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: Voices description: Text-to-speech and voice management - 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: Avatars description: List and manage avatars and looks - name: Avatar Realtime description: >- Low-latency streaming avatar sessions — create a stream, poll for its HLS URL, push text, consume per-word timestamps - name: Assets description: Upload files for use in video creation - 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 paths: /v3/video-translations/batches: post: tags: - Video Translation Batches summary: Create Video Translation Batch description: >- Submit up to 100 video-translation payloads (identical in shape to POST /v3/video-translations) as a single batch. A payload targeting multiple output_languages expands to one batch item per language, and each item is created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/video-translations/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch. operationId: createVideoTranslationBatchV3 parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVideoTranslationBatchRequest' responses: '202': description: Accepted — submission acknowledged; poll for completion. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateVideoTranslationBatchResponse' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: Invalid payload(s) at index 3. param: video_translations doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: authentication_failed 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: CreateVideoTranslationBatchRequest: additionalProperties: false properties: title: anyOf: - type: string - type: 'null' default: null description: Display name for the batch, shown in the HeyGen app. title: Title callback_url: anyOf: - type: string - type: 'null' default: null description: >- Webhook URL invoked once when every item in the batch reaches a terminal state. title: Callback Url video_translations: description: >- Video-translation payloads, identical in shape to POST /v3/video-translations. A single entry targeting multiple output_languages expands to one batch item per language; the expanded item count is capped at 100. items: $ref: '#/components/schemas/CreateVideoTranslationRequest' maxItems: 100 minItems: 1 title: Video Translations type: array required: - video_translations title: CreateVideoTranslationBatchRequest type: object CreateVideoTranslationBatchResponse: properties: batch_id: description: >- Identifier of the created batch. Poll GET /v3/video-translations/batches/{batch_id} for progress. title: Batch Id type: string required: - batch_id title: CreateVideoTranslationBatchResponse 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 required: - code - message 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: $ref: '#/components/schemas/AssetId' url: $ref: '#/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 audio: anyOf: - discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' url: $ref: '#/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 code (auto-detected if omitted) title: Input Language 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 enable_caption: default: false description: Generate captions for translated video 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 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. srt: anyOf: - discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' url: $ref: '#/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: Project/folder ID to organize translation into title: Folder Id required: - video - output_languages title: CreateVideoTranslationRequest type: object 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 the asset upload endpoint 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: Publicly accessible HTTPS URL for the asset title: Url type: string required: - type - url title: AssetUrl type: object VideoTranslationMode: enum: - speed - precision title: VideoTranslationMode type: string 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 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. ````