Skip to main content

​
Overview

Cloud-hosted models like Gemini and OpenAI require API keys for authentication. This guide covers all methods for setting up and managing your API keys.
On-device models and local LLMs (like Ollama) don’t require API keys. See the Model Providers guide for local model setup.

​
Getting API Keys

Obtain API keys from these providers:

​
Configuration Methods

LangExtract supports four methods for providing API keys, listed from most to least recommended for production use. Set the LANGEXTRACT_API_KEY environment variable: 
export LANGEXTRACT_API_KEY="your-api-key-here"
Then use LangExtract without specifying the API key: 
import langextract as lx

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash"
    # API key automatically loaded from LANGEXTRACT_API_KEY
)
Create a .env file in your project root to keep API keys secure and out of version control.
1

Create .env File

Add your API key to a .env file:
# Add API key to .env file
cat >> .env << 'EOF'
LANGEXTRACT_API_KEY=your-api-key-here
EOF
2

Add .env to .gitignore

Prevent accidentally committing your API key:
# Keep your API key secure
echo '.env' >> .gitignore
3

Use in Python

The API key is automatically loaded:
import langextract as lx

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash"
)
Always add .env to your .gitignore file to prevent committing API keys to version control.
Provide the API key directly in your code: 
import langextract as lx

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash",
    api_key="your-api-key-here"  # Only use for testing/development
)
Security Risk: Hard-coded API keys in source code can be accidentally committed to version control or exposed. Only use this method for testing and development.

​
Option 4: Vertex AI (Service Accounts)

For enterprise deployments, use Vertex AI with service account authentication: 
import langextract as lx

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash",
    language_model_params={
        "vertexai": True,
        "project": "your-project-id",
        "location": "global"  # or regional endpoint like "us-central1"
    }
)
Authentication methods:
  • Application Default Credentials (ADC)
  • Service account JSON key file
  • Workload Identity (for GKE)
Vertex AI authentication doesn’t require an API key in the traditional sense. Instead, it uses Google Cloud authentication mechanisms. See the Vertex AI documentation for setup details.

​
Provider-Specific Keys

​
Gemini (AI Studio)

Using the default LANGEXTRACT_API_KEY: 
import langextract as lx
import os

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash",
    api_key=os.environ.get('LANGEXTRACT_API_KEY')
)

​
OpenAI

Using OPENAI_API_KEY: 
import langextract as lx
import os

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gpt-4o",
    api_key=os.environ.get('OPENAI_API_KEY'),
    fence_output=True,
    use_schema_constraints=False
)
OpenAI models require fence_output=True and use_schema_constraints=False.

​
Docker Configuration

Pass API keys to Docker containers using environment variables: 
docker build -t langextract .
docker run --rm -e LANGEXTRACT_API_KEY="your-api-key" langextract python your_script.py
Or use a .env file: 
docker run --rm --env-file .env langextract python your_script.py

​
Security Best Practices

1

Never Commit API Keys

  • Add .env to .gitignore
  • Use environment variables for production
  • Rotate keys regularly
2

Restrict API Key Permissions

  • Use least-privilege access
  • Set API key restrictions (IP allowlists, referrer restrictions)
  • Monitor API key usage
3

Use Separate Keys for Environments

  • Development keys for testing
  • Production keys for live deployments
  • Different keys per team member when possible
4

Monitor and Rotate

  • Set up billing alerts
  • Monitor API usage patterns
  • Rotate keys periodically
  • Revoke compromised keys immediately

​
Troubleshooting

​
No API Key Found

If you see an error about missing API keys: 
ValueError: No API key provided or found in environment variables.
Solutions:
  1. Check that LANGEXTRACT_API_KEY is set: echo $LANGEXTRACT_API_KEY
  2. Verify your .env file exists and contains the key
  3. Ensure the environment variable is exported (not just set)
  4. Restart your IDE/terminal after setting environment variables

​
Invalid API Key

If authentication fails: 
AuthenticationError: Invalid API key
Solutions:
  1. Verify the API key is correct (no extra spaces)
  2. Check that the API key is enabled in the provider’s console
  3. Ensure the API key has the necessary permissions
  4. Try generating a new API key

​
Rate Limits

If you hit rate limits: 
RateLimitError: Too many requests
Solutions:
  1. Reduce max_workers to slow down concurrent requests
  2. Upgrade to a higher tier (e.g., Tier 2 for Gemini)
  3. Add retry logic with exponential backoff
  4. Monitor your quota usage
For large-scale or production use, a Tier 2 Gemini quota is suggested to increase throughput and avoid rate limits. See the rate-limit documentation for details.

​
Cost Management

API keys are tied to billing accounts. Monitor and control costs:

​
Cost Factors

  • Token volume: Most APIs charge by tokens processed
  • Model selection: Different models have different costs
  • extraction_passes: Multiple passes reprocess tokens (e.g., 3 passes = 3x cost)
  • max_char_buffer: Smaller values = more API calls

​
Cost Optimization Tips

  1. Test with small samples: Estimate costs before running on full datasets
  2. Use appropriate models: gemini-2.5-flash is more economical than gemini-2.5-pro
  3. Optimize passes: Start with extraction_passes=1 and increase only if needed
  4. Use batch processing: Enable Vertex AI batch API for large-scale tasks
  5. Monitor usage: Set up billing alerts in your provider’s console
max_workers improves processing speed without increasing token costs—it only affects parallelization.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us