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

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",
        "source/image": "/path/to/target/image.png",
    },
    name="Face Swap image",
    wait_for_completion=True,
    download_outputs=True,
    download_directory="./outputs/",
)
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="./outputs/",
)
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

v1.ai_clothes_changer

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

v1.ai_face_editor

v1.ai_gif_generator

v1.ai_headshot_generator

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

v1.ai_image_editor

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

v1.ai_image_generator

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_photo_editor

  • create - AI Photo Editor
  • generate - Ai Photo Editor Generate Workflow

v1.ai_qr_code_generator

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

v1.ai_talking_photo

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

v1.ai_voice_generator

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

v1.animation

v1.audio_projects

v1.auto_subtitle_generator

  • create - Auto Subtitle Generator
  • generate - Auto Subtitle Generator 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.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.43.1

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.43.1
File Size Uploaded Provenance Actions
magic_hour-0.43.1.tar.gz 96.1 kB Without provenance Details for magic_hour-0.43.1.tar.gz

Built distribution (wheel)

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

Total release size: 333.6 kB

Release files / magic_hour-0.43.1.tar.gz

Download URL magic_hour-0.43.1.tar.gz
Size 96.1 kB
Tags Source
SHA-256 checksum
How to use checksums
3b6ba203fa442c3b491d863c20d59fc5bf1f6870f4305741354d5b847325f84c
BLAKE2b-256 checksum
How to use checksums
1d301310f88a6bf520d26e4be9a4a82c2c46ad57dd2c193b1234d014b5827687
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.5 CPython/3.8.18 Linux/6.11.0-1018-azure

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

Download URL magic_hour-0.43.1-py3-none-any.whl
Size 237.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c0b24a488796a955ddd17c334ad4fba2ae1b48cdf9b64e3a4170caf42e1dafd0
BLAKE2b-256 checksum
How to use checksums
1c8b7b3773ab0e3d80c4b5d936c70eb8e4319b45702845ed47ba134956c38f3e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.5 CPython/3.8.18 Linux/6.11.0-1018-azure

Security for magic-hour 0.43.1

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