Integration Overview

​

What is the Magic Hour API?

​

Why Use the API?

• Build AI features into your products - Embed video and image generation in your applications
• Automate content workflows - Process large batches of media without manual intervention
• Scale your operations - Handle high-volume generation with enterprise-grade infrastructure
• Integrate with existing systems - Connect AI generation to your current tech stack
• Create custom experiences - Build unique user interfaces and workflows on top of our AI models

• Social media apps that auto-generate content for users
• Marketing platforms with automated video creation
• E-commerce sites with AI product visualization
• Gaming platforms with dynamic avatar generation
• Education apps with custom learning materials

​

API vs Web App

• Full suite of 100+ AI tools and features
• User-friendly interface with templates and presets
• New features launch here first
• Perfect for creators and individual use

• Core popular tools available programmatically
• Built for developers and applications
• Same underlying AI models as web app
• Features added after web app validation

​

How the API Works

​

The Three Steps

• Send a request to create a video, image, or audio
• Receive a job ID immediately (no waiting)
• Job enters the processing queue

• Polling: Periodically check job status using the job ID
• Webhooks: Receive automatic notifications when job completes
• Track progress through status updates

• Retrieve the generated file using a secure download URL
• URLs are temporary (expire after 24 hours)
• Save the result to your storage

​

Create vs Generate

​

create() - Full Control

# Step 1: Create job
result = client.v1.ai_image_generator.create(
    image_count=1,
    orientation="landscape",
    style={"prompt": "A sunset over mountains", "tool": "ai-anime-generator"},
    name="My image"
)
job_id = result.id

# Step 2: Poll for completion (you handle this)
while True:
    status = client.v1.image_projects.get(id=job_id)
    if status.status == "complete":
        break
    time.sleep(3)

# Step 3: Download (you handle this)
download_url = status.downloads[0].url
# ... download the file yourself

• Fine-grained control over polling intervals
• Custom status monitoring logic
• Integration with existing job management systems
• Advanced error handling and retry logic

​

generate() - Simplified Workflow

# All three steps handled automatically
result = client.v1.ai_image_generator.generate(
    image_count=1,
    orientation="landscape",
    style={"prompt": "A sunset over mountains", "tool": "ai-anime-generator"},
    name="My image"
)
# Returns when complete with file automatically downloaded

• Quick integrations and prototyping
• Simple use cases with single job processing
• Applications that can wait synchronously
• Minimal boilerplate code

• Use create() for production apps with webhook integration, concurrent job processing, or custom monitoring needs
• Use generate() for scripts, simple integrations, or when you want minimal code

​

Integration Approaches

​

Approach 1: Synchronous (Simple)

• Scripts and command-line tools
• Single job processing
• Testing and development

# Using generate() - blocks until complete
result = client.v1.ai_image_generator.generate(
    image_count=1,
    orientation="landscape",
    style={"prompt": "Test image", "tool": "ai-anime-generator"}
)
print(f"Image ready: {result.downloads[0].url}")

​

Approach 2: Polling (Moderate)

• Background job processing
• Applications that can handle wait times
• Simple queue-based systems

# Using create() with polling
job = client.v1.ai_image_generator.create(
    image_count=1,
    orientation="landscape",
    style={"prompt": "Test image", "tool": "ai-anime-generator"}
)

# Check periodically in a background task
def check_status():
    status = client.v1.image_projects.get(id=job.id)
    if status.status == "complete":
        download_result(status.downloads[0].url)

​

Approach 3: Webhooks (Production)

• Production applications
• High-volume processing
• Real-time user notifications
• Efficient resource usage

# Create job
job = client.v1.ai_image_generator.create(
    image_count=1,
    orientation="landscape",
    style={"prompt": "Test image", "tool": "ai-anime-generator"}
)

# Your webhook endpoint receives notification when complete
# (See webhook integration guide for setup)

​

Development Workflow

​

Step 1: Start Simple

result = client.v1.ai_image_generator.generate(
    image_count=1,
    orientation="square",
    style={"prompt": "Test image", "tool": "ai-anime-generator"}
)

​

Step 2: Add Error Handling

try:
    result = client.v1.ai_image_generator.generate(...)
    print("Success!")
except Exception as e:
    print(f"Error: {e}")

​

Step 3: Move to Production

# Create job
job = client.v1.ai_image_generator.create(...)

# Webhook handles completion notification
# (no polling needed)

​

Testing Without Credits

from magic_hour import Client
from magic_hour.environment import Environment

# Use mock server - no credits charged
client = Client(
    token="YOUR_API_KEY",
    environment=Environment.MOCK_SERVER
)

# Returns realistic sample data instantly
result = client.v1.ai_image_generator.create(...)

import Client, { Environment } from "magic-hour";

// Use mock server - no credits charged
const client = new Client({
  token: "YOUR_API_KEY",
  environment: Environment.MockServer,
});

// Returns realistic sample data instantly
const result = await client.v1.aiImageGenerator.create({...});

​

Processing Times

​

Next Steps