Documentation

Bulk Video Translation

Need to translate a backlog of videos? Follow the below guide for an easy workflow that requires minimal coding experience and allows for efficient translation of hundreds of videos with the HeyGen API.

Suggest Edits

Bulk Video Translation Script Guide

This guide will walk you through setting up Python, updating the script for your bulk video translation needs, and running it to generate a results CSV file with translation IDs.

1. Installing Python

Before running the script, ensure that Python is installed on your system.

Windows

  • Download Python: Visit python.org/downloads and download the latest version of Python for Windows.
  • Install: Run the installer and check the box “Add Python to PATH” during installation.
  • Verify Installation: Open Command Prompt and type: 
    python --version
    You should see a version number indicating Python is installed.

macOS

  • Download Python: Go to python.org/downloads and download the latest version for macOS.
  • Install: Open the downloaded package and follow the installation instructions.
  • Verify Installation: Open Terminal and run: 
    python3 --version

Linux

  • Using Package Manager: Most Linux distributions come with Python pre-installed. To check, open Terminal and type: 
    python3 --version
  • If not installed: Use your package manager (e.g., on Ubuntu): 
    sudo apt update
sudo apt install python3

2. Preparing the Script

You can copy the below code and save it to your computer as a text file. Name it 'BulkTranslationScript.py', as the rest of the guide assumes that that is the name of the script file.

import os
import csv
import requests

print("Current working directory:", os.getcwd())

def main():
    csv_file = "bulk_translation_csv_template.csv"
    output_csv_file = "bulk_translation_results.csv"
    api_url = "https://api.heygen.com/v2/video_translate"
    api_key = "YOUR_API_KEY_HERE"
    
    headers = {
        "accept": "application/json",
        "content-type": "application/json",
        "x-api-key": api_key,
    }
    
    results = []  # List to store each row's result
    
    with open(csv_file, mode="r", newline="", encoding="utf-8") as file:
        reader = csv.DictReader(file)
        # Prepare fieldnames for the output CSV, ensuring "translation_id" is included.
        fieldnames = reader.fieldnames + ["translation_id"] if reader.fieldnames else ["translation_id"]
        
        for row in reader:
            title = row["title"]
            output_language = row["output_language"]
            video_url = row["url"]
            folder_id = row.get("folder_id", "").strip()  # Optional folder_id
            
            # Build the payload without filtering by a specific language
            payload = {
                "video_url": video_url,
                "title": title,
                "output_language": output_language,
                "translate_audio_only": False,
                "enable_dynamic_duration": "true"
            }
            
            # Include folder_id in the payload only if provided
            if folder_id:
                payload["folder_id"] = folder_id
            
            try:
                response = requests.post(api_url, headers=headers, json=payload)
                response.raise_for_status()  # Raise an exception for HTTP errors
                response_data = response.json()
                translation_id = response_data.get("translation_id", "")
                print(f"Success for video '{title}':", response_data)
            except requests.exceptions.RequestException as e:
                translation_id = ""
                print(f"Error processing video '{title}':", e)
            
            # Add the translation_id to the row and store it in results
            row["translation_id"] = translation_id
            results.append(row)
    
    # Write the results to a new CSV file
    with open(output_csv_file, mode="w", newline="", encoding="utf-8") as outfile:
        writer = csv.DictWriter(outfile, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(results)
    
    print(f"Results saved to {output_csv_file}")

if __name__ == "__main__":
    main()

Modifying the Script File

📘

HeyGen API Key Credits

Each minute of video translated consumes 3 HeyGen API Credits. Go to www.heygen.com/api-pricing to find the API plan that has enough API credits to meet your content translation needs.

3. Setting Up Your CSV File

The Translation Script will run based off of values that you provide in a csv file.

  • You can copy this Google Sheet template to go off of.
  • Ensure your CSV template (named bulk_translation_csv_template.csv) includes at least the following columns:
    • title: The title of the video.
    • output_language: The language for the translation.
    • url: The URL of the video.
    • folder_id: (Optional) The folder ID to group translations.
  • The url field needs to be a public video download url. This can be in a location like Google Drive, or YouTube, or AWS S3 bucket. However, it needs to be public; that is, if you copy this URL and enter it in an incognito browser window, the video should open up without any log-in or password necessary.

Example CSV row:

title,output_language,url,folder_id
"Sample Video","Spanish","https://example.com/video.mp4","12345"

4. Installing Required Python Libraries

The script uses the built-in csv and os modules and the requests library. If you don’t have requests installed, run:

pip install requests

5. Running the Script

  1. Navigate to the Script Directory:

    • Open your Command Prompt (Windows) or Terminal (macOS/Linux).
    • Change to the directory where your script is located: 
      cd path/to/your/script

  2. Execute the Script:

    • Run the script using Python: 
      python BulkTranslationScript.py
      On macOS or Linux, if necessary: 
      python3 BulkTranslationScript.py

  3. Script Execution:

    • The script will read the CSV template, send translation requests for each video, and print the API responses.
    • All responses will be recorded with an added "translation_id" column.

  4. Reviewing Results:

    • After execution, check the newly created file bulk_translation_results.csv in the working directory. It contains all the original CSV data along with the new "translation_id" from the API response.

6. Troubleshooting & Additional Tips

  • Error Messages: If you encounter errors, check that all dependencies are installed and that your CSV file is correctly formatted.
  • Environment Variables: For better security, consider storing your actual API key in an environment variable rather than modifying the script.
  • Script Customization: Backup the original script before making any changes.
  • Help & Community: If you run into issues, online communities such as Stack Overflow can provide helpful advice.

By following this guide, you can efficiently use the Bulk Video Translation Script to process your videos, obtain translation IDs, and have your results neatly saved in a CSV file. Enjoy your streamlined translation workflow!

Updated 5 days ago