Quick Start

1. Create an API key - Get credentials to authenticate with our API
2. Set up your development environment - Install SDK and create project files
3. Generate your first image - Make an API call and download the result (costs ~100 credits)

​

1. Create your API key

1. Visit the Magic Hour Developer Hub and sign in.
2. Name the key (e.g., “My First Project”), then click Create key.
3. Copy the API key immediately - you won’t be able to see it again.

​

Save your API key securely

# Add to your ~/.bashrc or ~/.zshrc file
export MAGIC_HOUR_API_KEY="your_api_key_here"

# Reload your shell
source ~/.bashrc  # or source ~/.zshrc

​

2. Set up your development environment

​

Create your project directory

# Create and navigate to project directory
mkdir magic-hour-quickstart
cd magic-hour-quickstart

# Create outputs directory (prevents FileNotFoundError)
mkdir outputs

# Create your Python file
touch main.py

​

Install the SDK

pip install magic_hour

​

3. Generate your first image

1. Queue your job and return a project ID
2. Process your request (usually takes 30-60 seconds)
3. Make the result available for download

• image_count: 1 - Generate one image (costs 5 credits)
• orientation: "landscape" - 16:9 aspect ratio
• wait_for_completion: true - SDK polls until done
• download_outputs: true - Automatically download to local disk
• download_directory: "outputs" - Save to the outputs folder we created

​

Copy the code and run it

1. Copy the code from your preferred language tab below
2. Paste it into your file (main.py, main.js, main.go, etc.)
3. Run the code:

# Make sure you're in your project directory
cd magic-hour-quickstart

# Run the script
python main.py

queued image with id clx1234567890, spent 5 credits
render complete!
created image with id clx1234567890, spent 5 credits. Outputs are saved at ['outputs/output-1.png']

from magic_hour import Client
import time
import os
import urllib.request

# Use environment variable for security
client = Client(token=os.getenv("MAGIC_HOUR_API_KEY"))

result = client.v1.ai_image_generator.generate(
    image_count=1,
    orientation="landscape",
    style={
        "prompt": "Epic anime art of wizard casting a cosmic spell in the sky that says 'Magic Hour'"
    },
    wait_for_completion=True, # wait for the render to complete
    download_outputs=True, # download the outputs to local disk
    download_directory="outputs", # save the outputs to the "outputs" directory
)

print(f"created image with id {result.id}, spent {result.credits_charged} credits. Outputs are saved at {result.downloaded_paths}")

from magic_hour import Client
import time
import os
import urllib.request

# Use environment variable for security
client = Client(token=os.getenv("MAGIC_HOUR_API_KEY"))

result = client.v1.face_swap.generate(
    name="Swap Tom Cruise into Iron Man scene",
    assets={
        "image_file_path": "https://videos.magichour.ai/api-assets/sample/tom-cruise.png",
        "video_file_path": "https://videos.magichour.ai/api-assets/sample/iron-man.mp4",
        "video_source": "file",
    },
    start_seconds=2.3,
    end_seconds=8.5,
    wait_for_completion=True, # wait for the render to complete
    download_outputs=True, # download the outputs to local disk
    download_directory=".", # save the outputs to the current directory
)

print(f"created face swap video with id {result.id}, spent {result.credits_charged} credits. Outputs are saved at {result.downloaded_paths}")

​

Troubleshooting

​

Common Issues

mkdir outputs

export MAGIC_HOUR_API_KEY="your_api_key_here"

​

HTTP Error Codes

​

Next Steps

• Explore the API Reference: Learn how to generate and edit videos and images programmatically. API Reference →
• Try All APIs in Google Colab: Run our complete cookbook with sample code for all 22 APIs. Just add your API key and start experimenting.
• Use the Web App: Try more tools and experiment interactively at magichour.ai.
• Handle Results at Scale: Set up webhooks to process results async and avoid polling.
• Join the Community: Get help, share projects, and see what others are building in Discord.
• Stay Updated: Check out the Changelog for new products and API updates.