Magic Hour Python SDK

The Magic Hour Python Library provides convenient access to the Magic Hour API. This library offers both synchronous and asynchronous clients powered by httpx.

Documentation

For full documentation of all APIs, please visit https://docs.magichour.ai

If you have any questions, please reach out to us via discord.

Install

pip install magic_hour

Cookbook

For end-to-end examples demonstrating all available Magic Hour APIs, check out our interactive Google Colab cookbook:

Interactive Notebook: Magic Hour API Cookbook

The cookbook includes:

Setup instructions
Examples for all available APIs (image generation, face swap, lip sync, video generation, and more)
Display helpers for previewing outputs
Production-ready patterns and best practices

Synchronous Client Usage

from magic_hour import Client

# generate your API Key at https://magichour.ai/developer
client = Client(token="my api key")

response = client.v1.face_swap_photo.generate(
    assets={
        "face_swap_mode": "all-faces",
        "source_file_path": "/path/to/source/image.png",
        "target_file_path": "/path/to/target/image.png",
    },
    name="Face Swap image",
    wait_for_completion=True,
    download_outputs=True,
    download_directory=".",
)
print(f"Project ID: {response.id}")
print(f"Status: {response.status}")
print(f"Downloaded files: {response.downloaded_paths}")

Asynchronous Client Usage

from magic_hour import AsyncClient

# generate your API Key at https://magichour.ai/developer
client = AsyncClient(token="my api key")

response = await client.v1.face_swap_photo.generate(
    assets={
        "face_swap_mode": "all-faces",
        "source_file_path": "/path/to/source/image.png",
        "target_file_path": "/path/to/target/image.png",
    },
    name="Face Swap image",
    wait_for_completion=True,
    download_outputs=True,
    download_directory=".",
)
print(f"Project ID: {response.id}")
print(f"Status: {response.status}")
print(f"Downloaded files: {response.downloaded_paths}")

Client Functions

Most resources that generate media content support two methods:

generate() - A high-level convenience method that handles the entire workflow
create() - A low-level method that only initiates the generation process

Generate Function

The generate() function provides a complete end-to-end solution:

Uploads local file to Magic Hour storage
Calls the API to start generation
Automatically polls for completion
Downloads generated files to your local machine
Returns both API response data and local file paths

Additional Parameters:

wait_for_completion (bool, default True): Whether to wait for the project to complete.
download_outputs (bool, default True): Whether to download the generated files
download_directory (str, optional): Directory to save downloaded files (defaults to current directory)

# Generate function - handles everything automatically
response = client.v1.ai_image_generator.generate(
    style={"prompt": "A beautiful sunset over mountains"},
    name="Sunset Image",
    wait_for_completion=True,       # Wait for status to be complete/error/canceled
    download_outputs=True,          # Download files automatically
    download_directory="./outputs/" # Where to save files
)

# You get both the API response AND downloaded file paths
print(f"Project ID: {response.id}")
print(f"Status: {response.status}")
print(f"Downloaded files: {response.downloaded_paths}")

Create Function

The create() function provides granular control:

Only calls the API to start the generation process
Returns immediately with a project ID and amount of credits used
Requires manual status checking and file downloading

# Create function - only starts the process
create_response = client.v1.ai_image_generator.create(
    style={"prompt": "A beautiful sunset over mountains"},
    name="Sunset Image"
)

# You get just the project ID and initial response
project_id = create_response.id
print(f"Started project: {project_id}")

# You must handle the rest:
# 1. Poll for completion. We provide a helper function to handle polling for you
result = client.v1.image_projects.check_status(
    wait_for_completion=True,
    download_outputs=False,
)
# 2. Download files using the download URLs
download_urls = result.downloads
# download the files using your preferred way

Choosing Between Which Function to use

Use generate() when:

You want a simple, one-call solution
You're building a straightforward application
You don't need custom polling or download logic

Use create() when:

You need custom status checking logic
You're integrating with existing job processing systems
You want to separate generation initiation from completion handling
You need fine-grained control over the entire workflow

Module Documentation and Snippets

v1.account

list - Get account details

v1.ai_clothes_changer

create - AI Clothes Changer
generate - AI Clothes Changer Generate Workflow

v1.ai_face_editor

create - AI Face Editor
generate - Ai Face Editor Generate Workflow

v1.ai_gif_generator

create - AI GIF Generator
generate - Ai Gif Generator Generate Workflow

v1.ai_headshot_generator

create - AI Headshot Generator
generate - Ai Headshot Generator Generate Workflow

v1.ai_image_editor

create - AI Image Editor
generate - Ai Image Editor Generate Workflow

v1.ai_image_generator

create - AI Image Generator
generate - Ai Image Generator Generate Workflow

v1.ai_image_upscaler

create - AI Image Upscaler
generate - Ai Image Upscaler Generate Workflow

v1.ai_meme_generator

create - AI Meme Generator
generate - Ai Meme Generator Generate Workflow

v1.ai_qr_code_generator

create - AI QR Code Generator
generate - Ai Qr Code Generator Generate Workflow

v1.ai_talking_photo

create - AI Talking Photo
generate - Ai Talking Photo Generate Workflow

v1.ai_video_editor

create - AI Video Editor
generate - AI Video Editor Generate Workflow

v1.ai_voice_cloner

create - AI Voice Cloner

v1.ai_voice_generator

create - AI Voice Generator
generate - Ai Talking Photo Generate Workflow

v1.animation

create - Animation
generate - Animation Generate Workflow

v1.audio_projects

check-result - Check results
delete - Delete audio
get - Get audio details

v1.audio_to_video

create - Audio-to-Video
generate - Audio To Video Generate Workflow

v1.auto_subtitle_generator

create - Auto Subtitle Generator
generate - Auto Subtitle Generator Generate Workflow

v1.body_swap

create - Body Swap
generate - Body Swap Generate Workflow

v1.character_replace

create - Character Replace
generate - Character Replace Generate Workflow

v1.face_detection

create - Face Detection
generate - Face Detection Generate Workflow
get - Get face detection details

v1.face_swap

create - Face Swap Video
generate - Face Swap Generate Workflow

v1.face_swap_photo

create - Face Swap Photo
generate - Face Swap Photo Generate Workflow

v1.files

upload-file - Upload File

v1.files.upload_urls

create - Generate asset upload urls

v1.head_swap

create - Head Swap
generate - Head Swap Generate Workflow

v1.image_background_remover

create - Image Background Remover
generate - Image Background Remover Generate Workflow

v1.image_projects

check-result - Check results
delete - Delete image
get - Get image details

v1.image_to_video

create - Image-to-Video
generate - Image To Video Generate Workflow

v1.lip_sync

create - Lip Sync
generate - Lip Sync Generate Workflow

v1.photo_colorizer

create - Photo Colorizer
generate - Photo Colorizer Generate Workflow

v1.saved_items

list - List saved items

v1.text_to_video

create - Text-to-Video
generate - Text To Video Generate Workflow

v1.video_projects

check-result - Check results
delete - Delete video
get - Get video details

v1.video_to_video

create - Video-to-Video
generate - Video To Video Generate Workflow

Release files for magic_hour 0.83.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for magic_hour 0.83.0
File	Size	Uploaded
magic_hour-0.83.0.tar.gz	173.4 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for magic_hour 0.83.0
File	Interpreter	ABI	Platform	Reset
magic_hour-0.83.0-py3-none-any.whl 342.0 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 515.4 kB

Release files / magic_hour-0.83.0.tar.gz

Download URL	magic_hour-0.83.0.tar.gz
Size	173.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`169f8c763599b40aca6bfd0f149785315262cec568352d786881e90952ce8ffd`
BLAKE2b-256 checksum How to use checksums	`b8656f807a14f0e358dab8a808768a6b2588178dea04ea06db8d45fa3f0085c4`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.5 CPython/3.8.18 Linux/6.6.141`

Release files / magic_hour-0.83.0-py3-none-any.whl

Download URL	magic_hour-0.83.0-py3-none-any.whl
Size	342.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ae9f074ea3763b024ade2aefdd2d9c7be5503addfec9be62e75ed8c3635677d5`
BLAKE2b-256 checksum How to use checksums	`ad2afdb598f35e92a2ddf36f581b5e599d3759d217a6ea475344c7bae449437d`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.5 CPython/3.8.18 Linux/6.6.141`