Skip to main content

Magic Hour Python SDK

PyPI - Version

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:

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.ai_clothes_changer

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

v1.ai_face_editor

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

v1.ai_voice_generator

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

v1.animation

v1.audio_projects

v1.audio_to_video

v1.auto_subtitle_generator

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

v1.body_swap

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

v1.face_swap_photo

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

v1.files

v1.files.upload_urls

  • create - Generate asset upload urls

v1.head_swap

v1.image_background_remover

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

v1.image_projects

v1.image_to_video

v1.lip_sync

v1.photo_colorizer

  • create - Photo Colorizer
  • generate - Photo Colorizer Generate Workflow

v1.text_to_video

v1.video_projects

v1.video_to_video

Metadata

Release files for magic-hour 0.75.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.75.0
File Size Uploaded Provenance Actions
magic_hour-0.75.0.tar.gz 140.3 kB Without provenance Details for magic_hour-0.75.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for magic-hour 0.75.0
File Interpreter ABI Platform Actions
magic_hour-0.75.0-py3-none-any.whl Python 3 none any Details for magic_hour-0.75.0-py3-none-any.whl

Total release size: 446.0 kB

Release files / magic_hour-0.75.0.tar.gz

Download URL magic_hour-0.75.0.tar.gz
Size 140.3 kB
Tags Source
SHA-256 checksum
How to use checksums
f915c600338bab32f677a02229c40f11f180b25b1bd3fad15a8fdd76d577f3ad
BLAKE2b-256 checksum
How to use checksums
bc974835735f1bf55b7fb4b70a89cb333654db3b8fcf1296911e39747d87fc8f
Upload date
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.75.0-py3-none-any.whl

Download URL magic_hour-0.75.0-py3-none-any.whl
Size 305.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dc14531b395596232d8fa0ddd8bfe4b982be12ecd4b1fcdcf82ce57b274e28c8
BLAKE2b-256 checksum
How to use checksums
e24a40fcb513fdcdc748012ab165f0bf6ec39be4ba74fab48958bd216ff19139
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.5 CPython/3.8.18 Linux/6.6.141

Security for magic-hour 0.75.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.75.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page