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

`ts
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

$3

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)

`ts
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});
`

$3

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

`ts
// 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
`

$3

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.

$3

`ts
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

$3

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

$3

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

`bash
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

$3

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

$3

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

$3

- create - AI GIF Generator
- generate - AI Gif Generator Generate Workflow

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

- create - AI Voice Cloner
- generate - AI Voice Cloner Workflow

$3

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

$3

- create - Animation
- generate - Animation Generate Workflow

$3

- check-result - Check results
- delete - Delete audio
- get - Get audio details

$3

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

$3

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

$3

- create - Face Swap Video
- generate - Face Swap Generate Workflow

$3

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

$3

- upload-file - Upload File

$3

- create - Generate asset upload urls

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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