How to Configure the ELEVENLABS_API_KEY and Manage Environment Variables in video-use

You can configure the ELEVENLABS_API_KEY for video-use either by setting an environment variable or by creating a .env file in the repository root, which the load_api_key() function in helpers/transcribe.py automatically discovers and parses.

The browser-use/video-use repository requires an Eleven Labs API key to power its transcription helper. Properly managing this credential through environment variables ensures secure access to the speech-to-text functionality without hardcoding sensitive data into your scripts.

Configuration Methods for video-use

The transcription helper supports two primary methods for supplying your Eleven Labs API key. Both approaches are handled by the load_api_key() function located in helpers/transcribe.py.

Using a .env File (Recommended)

Create a .env file in the repository root or in the parent directory of helpers/transcribe.py. The installer provides an example template at .env.example that demonstrates the required format.

cp .env.example .env

Edit the file to include your actual key:

ELEVENLABS_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX

Using Environment Variables

Export the key directly in your shell before running any video-use commands. This method is ideal for CI/CD pipelines and production deployments where secret management is handled by the platform.

export ELEVENLABS_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX

How the API Key Loading Works

The load_api_key() function implements a fallback mechanism that prioritizes .env files over environment variables. According to the source code in helpers/transcribe.py (lines 33-46), the function performs the following steps:

1. Scans for .env files in two locations: the script's parent directory and the repository root
2. Parses each line, skipping comments and empty lines
3. Extracts the value associated with ELEVENLABS_API_KEY
4. Falls back to os.environ if no .env entry is found
5. Exits with an error message if the key is still missing

def load_api_key() -> str:
    for candidate in [Path(__file__).resolve().parent.parent / ".env", Path(".env")]:
        if candidate.exists():
            for line in candidate.read_text().splitlines():
                line = line.strip()
                if not line or line.startswith("#") or "=" not in line:
                    continue
                k, v = line.split("=", 1)
                if k.strip() == "ELEVENLABS_API_KEY":
                    return v.strip().strip('"').strip("'")
    v = os.environ.get("ELEVENLABS_API_KEY", "")
    if not v:
        sys.exit("ELEVENLABS_API_KEY not found in .env or environment")
    return v

If the key is not found in either location, the script aborts with the error: ELEVENLABS_API_KEY not found in .env or environment.

Step-by-Step Setup Guide

1. Copy the example file – The repository ships with .env.example showing the required format.

2. Insert your key – Edit .env and replace the placeholder with your actual Eleven Labs API key.

3. Verify configuration – Test that the key loads correctly before running transcription:

   python -c "import helpers.transcribe as t; print(t.load_api_key())"

4. Run the helper – The key will be automatically read when you invoke the transcription script:

   python helpers/transcribe.py path/to/video.mp4

Code Examples

Setting the Key via .env File

# Create the .env file from the example

cp .env.example .env

# Add your Eleven Labs key (replace the placeholder)

echo "ELEVENLABS_API_KEY=sk-abc123def456ghi789" >> .env

# Verify the key can be loaded

python -c "import helpers.transcribe as t; print('Loaded key:', t.load_api_key())"

# Run the transcription helper

python helpers/transcribe.py videos/lecture.mp4

Setting the Key via Environment Variable

# Export the key for the current shell session

export ELEVENLABS_API_KEY=sk-abc123def456ghi789

# Run the helper – no .env file needed

python helpers/transcribe.py videos/lecture.mp4

Using the Key in a Custom Script

If you embed the transcription functionality in another Python script, call load_api_key() directly:

from helpers.transcribe import load_api_key, transcribe_one
from pathlib import Path

api_key = load_api_key()          # pulls from .env or env var

video_path = Path("videos/lecture.mp4")
edit_dir = Path("edits")          # where transcripts will be stored

transcript_path = transcribe_one(
    video=video_path,
    edit_dir=edit_dir,
    api_key=api_key,
    language="en",
    num_speakers=2,
)
print("Transcript saved to:", transcript_path)

Summary

• Two configuration methods: Use a .env file for local development or environment variables for production deployments.
• Automatic discovery: The load_api_key() function in helpers/transcribe.py checks both .env files and os.environ automatically.
• Security best practice: Add .env to .gitignore to prevent committing API keys to version control.
• Clear error handling: The script exits with a descriptive message if ELEVENLABS_API_KEY is not found in either location.

Frequently Asked Questions

What happens if I forget to set the ELEVENLABS_API_KEY?

The script will terminate immediately with the error message ELEVENLABS_API_KEY not found in .env or environment. This occurs in helpers/transcribe.py when load_api_key() cannot find the key in either the .env file or the environment variables.

Can I use video-use without creating a .env file?

Yes. You can export the ELEVENLABS_API_KEY directly in your shell using export ELEVENLABS_API_KEY=your-key. The load_api_key() function falls back to checking os.environ when no .env file is present, making this approach suitable for Docker containers and cloud deployments.

Where should I place the .env file for video-use to find it?

Place the .env file either in the repository root or in the parent directory of helpers/transcribe.py. The load_api_key() function specifically searches these two locations: Path(__file__).resolve().parent.parent / ".env" and Path(".env").

Does video-use validate the API key before making transcription requests?

The source code in helpers/transcribe.py only verifies that the key exists and is not empty. It does not perform pre-flight validation against the Eleven Labs API. Invalid keys will result in authentication errors when the actual transcription request is made.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}