Development and Testing - Magic Hour API Docs

Overview

Developing with APIs that charge per request requires careful testing strategies. This guide shows you how to build and test your Magic Hour integration effectively while minimizing costs and avoiding production issues.

Testing Without Using Credits

Mock Server (Recommended for Development)

The Magic Hour SDKs can use a hosted mock server that returns sample data without processing jobs or charging credits:

from magic_hour import Client
from magic_hour.environment import Environment

# Use mock server for development
client = Client(
    token="YOUR_API_KEY",  # Can use any value for mock mode
    environment=Environment.MOCK_SERVER
)

# All API calls return mock data instantly
result = client.v1.ai_image_generator.create(
    image_count=1,
    aspect_ratio="16:9",
    resolution="1k",
    style={"prompt": "Test image", "tool": "ai-anime-generator"}
)

print(f"Job ID: {result.id}")  # Returns mock ID
# No credits charged, no actual processing

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

// Use mock server for development
const client = new Client({
  token: "YOUR_API_KEY", // Can use any value for mock mode
  environment: Environment.MockServer,
});

// All API calls return mock data instantly
const result = await client.v1.aiImageGenerator.create({
  imageCount: 1,
  aspectRatio: "16:9",
  resolution: "1k",
  style: { prompt: "Test image", tool: "ai-anime-generator" },
});

console.log(`Job ID: ${result.id}`); // Returns mock ID
// No credits charged, no actual processing

style.tool is optional. It selects an art-style preset; ai-anime-generator requests an anime look. Omit it to use the default general style.

The mock server validates SDK wiring, not real generation quality, account eligibility, credit deductions, or webhook delivery. Its sample project is not a real job; do not wait for it to progress through rendering. Verify those behaviors separately against the real API. Benefits:

✅ No credit consumption
✅ Instant responses (no waiting)
✅ Realistic sample data
✅ Test error scenarios
✅ Validate integration logic

When to use:

Unit testing
Integration testing
Local development
CI/CD pipelines
Prototyping new features

Environment Configuration

Use environment variables to switch between mock and production:

import os
from magic_hour import Client
from magic_hour.environment import Environment

# Switch environments based on ENV variable
# Environment.ENVIRONMENT is the production API (https://api.magichour.ai)
env = Environment.MOCK_SERVER if os.getenv("ENV") == "development" else Environment.ENVIRONMENT

client = Client(
    token=os.getenv("MAGIC_HOUR_API_KEY"),
    environment=env
)

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

// Switch environments based on NODE_ENV
// Environment.Environment is the production API (https://api.magichour.ai)
const environment =
  process.env.NODE_ENV === "development" ? Environment.MockServer : Environment.Environment;

const client = new Client({
  token: process.env.MAGIC_HOUR_API_KEY,
  environment,
});

Development Workflow: Use mock server during development, then switch to production environment for final testing and deployment.

Error Handling Best Practices

Handling API Errors

Implement comprehensive error handling for all API calls:

from magic_hour import ApiError, Client

client = Client(token="YOUR_API_KEY")

try:
    result = client.v1.ai_image_generator.create(
        image_count=1,
        aspect_ratio="16:9",
        resolution="1k",
        style={"prompt": "Test"},
    )

except ApiError as e:
    code = e.status_code
    detail = e.response.text[:300]

    if code == 401:
        print("❌ Invalid API key. Check your credentials.")
    elif code == 402:
        print("❌ Payment required. Add credits, subscribe, or upgrade the plan named by the error code.")
    elif code in (400, 422):
        print(f"❌ Invalid parameters: {detail}")
    elif code == 404:
        print("❌ Route or project not found. Check the resource ID.")
    elif code >= 500:
        print("❌ Server error. Check for an accepted project before retrying this creation request.")
    else:
        print(f"❌ API error ({code}): {detail}")

except Exception as e:
    print(f"❌ Unexpected error: {e}")

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

const client = new Client({ token: "YOUR_API_KEY" });

try {
  const result = await client.v1.aiImageGenerator.create({
    imageCount: 1,
    aspectRatio: "16:9",
    resolution: "1k",
    style: { prompt: "Test" },
  });
} catch (error) {
  if (!(error instanceof ApiError)) throw error;
  const statusCode = error.response.status;
  if (statusCode === 401) {
    console.log("❌ Invalid API key. Check your credentials.");
  } else if (statusCode === 402) {
    console.log(
      "❌ Payment required. Add credits, subscribe, or upgrade the plan named by the error code."
    );
  } else if (statusCode === 400 || statusCode === 422) {
    console.log(`❌ Invalid parameters: ${error.message}`);
    // Fix your request parameters
  } else if (statusCode === 404) {
    console.log("❌ Route or project not found. Check the resource ID.");
  } else if (statusCode >= 500) {
    console.log(
      "❌ Server error. Check for an accepted project before retrying this creation request."
    );
  } else {
    console.log(`❌ API error: ${error.message}`);
    // Log error and alert monitoring system
  }
}

Handling Job Errors

Check for errors during job processing:

import time

download_url = None

job_id = "your_job_id" # Change this to your job ID
deadline = time.monotonic() + 180

while time.monotonic() < deadline:
    status = client.v1.image_projects.get(id=job_id)

    if status.status == "complete":
        download_url = status.downloads[0].url
        break

    if status.status in ("error", "canceled"):
        err = status.error
        error_code = getattr(err, "code", "unknown")
        error_msg = getattr(err, "message", "Unknown error")

        if error_code == "no_source_face":
            print("❌ No face detected. Use an image with a visible face.")
        elif error_code == "invalid_file_format":
            print("❌ Unsupported file format. Check supported formats.")
        elif error_code == "file_too_large":
            print("❌ File too large. Reduce file size or upgrade tier.")
        elif error_code == "insufficient_credits":
            print("❌ Not enough credits. Add credits to your account.")
        else:
            print(f"❌ Error ({error_code}): {error_msg}")

        break

    time.sleep(3)
else:
    raise TimeoutError(f"Job {job_id} is still pending. Resume polling this ID; do not submit a new job.")

if not download_url:
    raise RuntimeError("Job did not complete successfully; no download URL available.")

// Poll for completion with error handling
const jobId = "your_job_id";
const deadline = Date.now() + 180_000;
let downloadUrl;

while (Date.now() < deadline) {
  const status = await client.v1.imageProjects.get({ id: jobId });

  if (status.status === "complete") {
    // Success - download result
    downloadUrl = status.downloads[0].url;
    break;
  } else if (status.status === "error" || status.status === "canceled") {
    // Job failed during processing
    const errorCode = status.error?.code || "unknown";
    const errorMsg = status.error?.message || "Unknown error";

    // Handle specific error codes
    switch (errorCode) {
      case "no_source_face":
        console.log("❌ No face detected. Use an image with a visible face.");
        break;
      case "invalid_file_format":
        console.log("❌ Unsupported file format. Check supported formats.");
        break;
      case "file_too_large":
        console.log("❌ File too large. Reduce file size or upgrade tier.");
        break;
      case "insufficient_credits":
        console.log("❌ Not enough credits. Add credits to your account.");
        break;
      default:
        console.log(`❌ Error (${errorCode}): ${errorMsg}`);
    }

    throw new Error(`Job ${jobId}: ${status.status}`);
  }

  await new Promise((resolve) => setTimeout(resolve, 3000));
}

if (!downloadUrl) {
  throw new Error(
    `Job ${jobId} is still pending. Resume polling this ID; do not submit a new job.`
  );
}

Common Error Codes

Error Code	Meaning	Solution
`no_source_face`	No face detected in image	Use image with clear, visible face
`invalid_file_format`	Unsupported file type	Check supported formats list
`file_too_large`	File exceeds size limit	Compress file or upgrade tier
`insufficient_credits`	Not enough credits	Add credits to account
`invalid_parameters`	Invalid request parameters	Check API reference for valid values
`unknown_error`	Unexpected error	Contact support with job ID

Creation charges credits up front. If generation fails, those credits are refunded. A client-side timeout does not cancel the job or trigger a refund.

Retry without creating duplicate jobs

Before receiving a project ID: a network timeout or server error does not prove the creation request failed. Check your project history before submitting again. Do not assume repeated POST requests are deduplicated, or that sending an Idempotency-Key header makes them safe.
After receiving a project ID: save it immediately. Retry status reads for that same ID with bounded exponential backoff; do not create a replacement job just because polling timed out.
After completion: retry downloading the existing output. If its signed URL expired, retrieve the project again for a current download URL instead of paying for another generation.
After error or canceled: stop polling. Fix the reported input or account problem before creating a new job. Cancellation does not emit a webhook, so keep polling as a recovery path.

Status Monitoring Strategies

Polling with Smart Intervals

Adjust polling frequency based on content type:

def get_poll_interval(project_type, duration=None):
    """Return appropriate polling interval in seconds"""

    if project_type == "image":
        return 3  # Images process quickly
    elif project_type == "audio":
        return 3  # Audio processes quickly
    elif project_type == "video":
        if duration and duration > 30:
            return 10  # Longer videos need more time
        return 5  # Short videos

    return 5  # Default

# Usage
poll_interval = get_poll_interval("video", duration=60)
time.sleep(poll_interval)

Implementing Timeouts

Always implement maximum wait times:

import time

def wait_for_completion(client, job_id, timeout_minutes=10):
    """Wait for job with timeout"""

    deadline = time.monotonic() + timeout_minutes * 60

    while time.monotonic() < deadline:
        status = client.v1.image_projects.get(id=job_id)

        if status.status == "complete":
            return status
        elif status.status in ("error", "canceled"):
            raise Exception(f"Job failed: {status.error}")

        time.sleep(3)

    raise TimeoutError(f"Job {job_id} is still pending. Resume polling this ID; do not submit a new job.")

Testing Strategies

Unit Testing

Test your integration logic without hitting the API:

import unittest
from unittest.mock import Mock, patch

class TestMagicHourIntegration(unittest.TestCase):

    @patch('magic_hour.Client')
    def test_successful_image_generation(self, mock_client):
        # Mock the API responses
        mock_create = Mock(return_value=Mock(id="test123", credits_charged=5))
        mock_status = Mock(return_value=Mock(
            status="complete",
            downloads=[Mock(url="https://upload.wikimedia.org/wikipedia/commons/e/ec/Chris_Cassidy_-_Official_NASA_Astronaut_Portrait_in_EMU_%28cropped%29.jpg")]
        ))

        mock_client.v1.ai_image_generator.create = mock_create
        mock_client.v1.image_projects.get = mock_status

        # Test your integration function
        result = generate_image(mock_client, "test prompt")

        # Verify calls were made
        mock_create.assert_called_once()
        mock_status.assert_called_once()

        # Verify result
        self.assertEqual(result.id, "test123")

Integration Testing with Mock Server

from magic_hour import Client
from magic_hour.environment import Environment

def test_with_mock_server():
    client = Client(
        token="test-key",
        environment=Environment.MOCK_SERVER
    )

    # Test the full workflow
    result = client.v1.ai_image_generator.create(...)
    assert result.id is not None
    assert result.credits_charged > 0

    # Test status checking
    status = client.v1.image_projects.get(id=result.id)
    assert status.status in ["queued", "rendering", "complete"]

Production Testing

Before going live, test with minimal credits:

Use Free Tier Credits: Test with daily free credits
Small Test Jobs: Use minimum resolution/duration
Single Job Tests: Test one job at a time initially
Monitor Credits: Track credit usage during testing

# Minimal credit test
result = client.v1.ai_image_generator.create(
    image_count=1,
    aspect_ratio="1:1",
    resolution="1k",
    style={"prompt": "Simple test"}
)
# Uses ~5 credits

Development Workflow

Recommended Development Process

Phase 1: Local Development

ENV=development python main.py  # Uses mock server

Use mock server exclusively
Build integration logic
Test error handling

Phase 2: Real-API Testing

python main.py  # Any ENV value other than "development" uses the real API

Test with the real API using minimal credits (smallest resolution and duration)
Validate end-to-end workflow
Test error scenarios

Phase 3: Production

python main.py  # Uses your production API key

Deploy with production credentials
Monitor for errors
Set up logging and alerts

Logging and Debugging

Implement comprehensive logging:

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    handlers=[logging.FileHandler("magichour.log"), logging.StreamHandler()],
)
logger = logging.getLogger(__name__)

logger.info("Creating AI image job", extra={"aspect_ratio": "16:9", "image_count": 1})

result = client.v1.ai_image_generator.create(
    image_count=1,
    aspect_ratio="16:9",
    resolution="1k",
    style={"prompt": "Test"},
    name="Logging Example",
)

logger.info("Job created", extra={"job_id": result.id, "credits_charged": result.credits_charged})
print("job_id:", result.id)

Job Cancellation

Cancel video jobs to get full credit refunds (image jobs complete too quickly to cancel):

Open project details

Visit the project in your library: - Videos: https://magichour.ai/my-library?videoId= {project_id} - Images: https://magichour.ai/my-library?imageId={project_id} - Audio: https://magichour.ai/my-library?audioId={project_id}

Click cancel render

Confirm cancellation

Cancellation complete

Full credit refund is provided for cancelled video jobs.

Important notes:

Image jobs cannot be cancelled (they complete too quickly)
API-based cancellation is not currently available
Full credit refund is provided for cancelled video jobs
Only works for jobs in queued or rendering status

Production Deployment Checklist

Before deploying to production:

Security

✅ API keys stored in environment variables (not hardcoded)
✅ API keys not committed to version control
✅ Different API keys for development/staging/production
✅ Webhook signatures verified (if using webhooks)

Error Handling

✅ All API calls wrapped in try/catch blocks
✅ Specific error codes handled appropriately
✅ Retry logic with exponential backoff
✅ Timeout handling for long-running jobs
✅ Logging for all errors

Monitoring

✅ Credit usage tracking
✅ Error rate monitoring
✅ Job completion time tracking
✅ Failed job alerting
✅ Download success/failure tracking

File Management

✅ Downloaded files stored in reliable storage
✅ Cleanup of old generated files
✅ Handling of download URL expiration
✅ Disk space monitoring

Performance

✅ Appropriate polling intervals implemented
✅ Concurrent job limits configured
✅ Rate limiting respected
✅ Connection pooling for multiple requests

Testing Checklist

Before deploying, verify:

Basic Functionality

✅ Job creation succeeds
✅ Status polling works correctly
✅ File downloads successfully
✅ Multiple concurrent jobs handle correctly

Error Scenarios

✅ Invalid API key handling
✅ Insufficient credits handling
✅ Invalid parameters rejection
✅ Network errors and retries
✅ Timeout handling

Edge Cases

✅ Very large files
✅ Very small files
✅ Multiple output files
✅ Expired download URLs
✅ Job cancellation

Debugging Common Issues

Issue: Jobs Stay in “queued” Status

Possible causes:

High server load
Invalid input files
Account issues

Solutions:

Check the current status and compare the job age with the endpoint’s recent typical processing time and your workload-specific timeout; the typical time is not a failure threshold
Check input file validity
Verify account has sufficient credits
Contact support if persistent

Issue: Download URLs Return 404

Possible causes:

URLs expired (24+ hours old)
Job was deleted
Invalid job ID

Solutions:

Request fresh URLs using GET endpoint
Verify job ID is correct
Download files within 24 hours of completion

Issue: High Credit Usage During Testing

Solutions:

Switch to mock server for development
Use minimum resolution/duration for tests
Implement proper cleanup of test jobs
Monitor credit usage in Developer Hub

Next Steps

First Integration

Build your first integration from scratch

Inputs & Outputs

Advanced file handling techniques

Webhooks

Set up webhooks for production

API Reference

Complete endpoint documentation

Questions? Join our Discord community or email support@magichour.ai

​Overview

​Testing Without Using Credits

​Mock Server (Recommended for Development)

​Environment Configuration

​Error Handling Best Practices

​Handling API Errors

​Handling Job Errors

​Common Error Codes

​Retry without creating duplicate jobs

​Status Monitoring Strategies

​Polling with Smart Intervals

​Implementing Timeouts

​Testing Strategies

​Unit Testing

​Integration Testing with Mock Server

​Production Testing

​Development Workflow

​Recommended Development Process

​Logging and Debugging

​Job Cancellation

​Production Deployment Checklist

​Security

​Error Handling

​Monitoring

​File Management

​Performance

​Testing Checklist

​Basic Functionality

​Error Scenarios

​Edge Cases

​Debugging Common Issues

​Issue: Jobs Stay in “queued” Status

​Issue: Download URLs Return 404

​Issue: High Credit Usage During Testing

​Next Steps

First Integration

Inputs & Outputs

Webhooks

API Reference

Overview

Testing Without Using Credits

Mock Server (Recommended for Development)

Environment Configuration

Error Handling Best Practices

Handling API Errors

Handling Job Errors

Common Error Codes

Retry without creating duplicate jobs

Status Monitoring Strategies

Polling with Smart Intervals

Implementing Timeouts

Testing Strategies

Unit Testing

Integration Testing with Mock Server

Production Testing

Development Workflow

Recommended Development Process

Logging and Debugging

Job Cancellation

Production Deployment Checklist

Security

Error Handling

Monitoring

File Management

Performance

Testing Checklist

Basic Functionality

Error Scenarios

Edge Cases

Debugging Common Issues

Issue: Jobs Stay in “queued” Status

Issue: Download URLs Return 404

Issue: High Credit Usage During Testing

Next Steps