Magic Hour Node SDK

The Magic Hour Node SDK provides convenient access to the Magic Hour API via server-side TypeScript or JavaScript.

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

npm install magic-hour

Usage

import Client from "magic-hour";
// generate your API Key at https://magichour.ai/developer
const client = new Client({ token: process.env["API_TOKEN"]!! });
const res = await client.v1.faceSwapPhoto.generate(
  {
    assets: {
      faceSwapMode: "all-faces",
      sourceFilePath: "/path/to/source/image.png",
      targetFilePath: "/path/to/target/image.png",
    },
    name: "Face Swap image",
  },
  {
    waitForCompletion: true,
    downloadOutputs: true,
    downloadDirectory: "outputs",
  },
);

console.log(`Project ID: ${response.id}`)
console.log(`Status: ${response.status}`)
console.log(`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 files 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:

• waitForCompletion (boolean, default true): Whether to wait for the project to complete
• downloadOutputs (boolean, default true): Whether to download the generated files
• downloadDirectory (string, optional): Directory to save downloaded files (defaults to current directory)

const response = await client.v1.faceSwapPhoto.generate(
  {
    assets: {
      faceSwapMode: "all-faces",
      sourceFilePath: "/path/to/source/image.png",
      targetFilePath: "/path/to/target/image.png",
    },
    name: "Face Swap image",
  },
  {
    waitForCompletion: true,       // Wait for status to be complete/error/canceled
    downloadOutputs: true,         // Download files automatically
    downloadDirectory: "./outputs/" // Where to save files
  }
);

// You get both the API response AND downloaded file paths
console.log(`Project ID: ${response.id}`);
console.log(`Status: ${response.status}`);
console.log(`Downloaded files: ${response.downloadedPaths}`);

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

// upload the files to Magic Hour's storage or you can use direct URLs
const sourceFilePath = await client.v1.files.uploadFile("/path/to/source/image.png")
const targetFilePath = await client.v1.files.uploadFile("/path/to/target/image.png")

// Create function - only starts the process
const createResponse = await client.v1.faceSwapPhoto.create({
  assets: {
    faceSwapMode: "all-faces",
    sourceFilePath: sourceFilePath,
    targetFilePath: targetFilePath,
  },
  name: "Face Swap image"
});

// You get just the project ID and initial response
const projectId = createResponse.id;
console.log(`Started project: ${projectId}`);

// You must handle the rest:
// 1. Poll for completion using the image/video projects API
const result = await client.v1.imageProjects.checkResults(projectId, {
  waitForCompletion: true,
  downloadOutputs: false,
});

// 2. Download files using the download URLs
const downloadUrls = result.downloads;
// Download the files using your preferred method

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

Error Handling

The Magic Hour SDK includes the ApiError class, which includes the request and response data.

Basic Error Handling

try {
  await client.v1.imageToVideo.generate(
    {
      assets: {
        imageFilePath: "/Users/dhu/Desktop/test-files/suit.jpg",
      },
      endSeconds: 0,
    },
  );
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`API Error: ${error.message}`); // API Error: 400 was returned from post /v1/image-to-video

    try {
      const errorData = await error.response.json();
      console.error(`Error Message: ${errorData.message}`); // Error Message: end_seconds must be at least 5
    } catch (parseError) {
      console.error("Could not parse error response");
    }
  } else {
    console.error("Unexpected error:", error);
  }
}

Logging

Logging Levels

• none - Disable all logging
• error - Only error messages
• warn - Warnings and errors
• info - Info, warnings, and errors
• debug - All messages including request/response details

Environment Variable Configuration

You can also configure the logging level using the MAGIC_HOUR_LOG_LEVEL environment variable:

export MAGIC_HOUR_LOG_LEVEL=debug  # Enable debug logging
# or
export MAGIC_HOUR_LOG_LEVEL=error  # Only show errors

Valid values are: none, error, warn, info, debug (case insensitive). If not set, defaults to info.

Module Documentation and Snippets

v1

v1.aiClothesChanger

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

v1.aiFaceEditor

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

v1.aiGifGenerator

• create - AI GIFs
• generate - AI Gif Generator Generate Workflow

v1.aiHeadshotGenerator

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

v1.aiImageEditor

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

v1.aiImageGenerator

• create - AI Images
• generate - AI Image Generator Generate Workflow

v1.aiImageUpscaler

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

v1.aiMemeGenerator

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

v1.aiPhotoEditor

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

v1.aiQrCodeGenerator

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

v1.aiTalkingPhoto

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

v1.aiVoiceGenerator

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

v1.animation

• create - Animation
• generate - Animation Generate Workflow

v1.audioProjects

• delete - Delete audio
• get - Get audio details

v1.autoSubtitleGenerator

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

v1.faceDetection

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

v1.faceSwap

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

v1.faceSwapPhoto

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

v1.files

• upload-file - Upload File

v1.files.uploadUrls

• create - Generate asset upload urls

v1.imageBackgroundRemover

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

v1.imageProjects

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

v1.imageToVideo

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

v1.lipSync

• create - Lip Sync
• generate - Lip Sync Generate Workflow

v1.photoColorizer

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

v1.textToVideo

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

v1.videoProjects

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

v1.videoToVideo

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