Magic Hour Node SDK – v0.37.0 (August 25, 2025)

🚀 Highlights

All image and video clients added support for a .generate function. This function handles everything to get your output:

upload files locally to Magic Hour storage
trigger the create call to start generation
poll the details API to check for status
download the results.

Below is an example of the new code

import Client from "magic-hour";

const client = new Client({ token: process.env["API_TOKEN"]!! });
const res = await client.v1.imageToVideo.generate(
  {
    assets: { imageFilePath: "/path/to/image.png" },
    endSeconds: 5.0,
    name: "Image To Video video",
    resolution: "720p",
  },
  {
    waitForCompletion: true,
    downloadOutputs: true,
    downloadDirectory: "outputs",
  },
);

Click here to see what the code used to look like. (it's much longer than the new code)

import * as fs from "fs";
import Client from "magic-hour";

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

const response = await client.v1.files.uploadUrls.create({
  items: [{ extension: "png", type: "image" }],
});

const local_path = "/path/to/image.png";
const file = fs.readFileSync(local_path);

await fetch(response.items[0].uploadUrl, {
  method: "PUT",
  body: file,
});

const filePath = response.items[0].filePath;

const createRes = await client.v1.imageToVideo.create({
  assets: { imageFilePath: filePath },
  endSeconds: 5.0,
  name: "Image To Video video",
});

let downloads = [];

const projectId = createRes.id;
while (true) {
  const res = await client.v1.videoProjects.get({ id: projectId });
  if (res.status === "complete") {
    console.log("render complete");
    downloads = res.downloads;
    break;
  } else if (res.status === "error") {
    console.log("render failed");
  } else {
    console.log("render in progress");
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

for (let i = 0; i < downloads.length; i++) {
  const download = downloads[i];
  const res = await fetch(download.url);
  const buffer = await res.arrayBuffer();
  fs.writeFileSync(`output-${i}.mp4`, Buffer.from(buffer));
}

If you need finer control over each step, we also added the following functions:

client.v1.imageProjects.checkResult(...) - takes an id and poll until a complete status. Also can download file.
client.v1.videoProjects.checkResult(...) - takes an id and poll until a complete status. Also can download file.
client.v1.files.uploadFile("/path/to/your/image.jpg") - to upload a file in one convenient step.

What's Changed

chore: replace-prettier-with-biome by @davidhu2000 in #98
Revert "chore: replace-prettier-with-biome" by @davidhu2000 in #99
feat: create new uploadFile function to make it easier to upload files by @davidhu2000 in #93
feat: add checkResult function to image project client by @davidhu2000 in #100
feat: add checkResult function to Video client by @davidhu2000 in #101
feat: add .generate function to ai cloth changer by @davidhu2000 in #102
feat: create inject-generate script, and add generate function to all clients by @davidhu2000 in #103
chore: regenerate sdk to pick up latest readme updates by @davidhu2000 in #104
chore: update resource readmes to move custom doc to the top by @davidhu2000 in #105
chore: build script to inject readme for generate function by @davidhu2000 in #106
chore: update readme for clients that aren't directly running generations by @davidhu2000 in #107
chore: add simple console logger for generate functions by @davidhu2000 in #108
feat: update types for optional assets by @davidhu2000 in #109
feat: upload-new-faces for face swap when face mappings exist by @davidhu2000 in #110
chore: update main readme with information on generate function by @davidhu2000 in #111
chore(deps): bump form-data from 4.0.1 to 4.0.4 by @dependabot[bot] in #112
fix: error log to print out the actual error instead of [object Object] by @davidhu2000 in #113
chore: add-error-handling to readme by @davidhu2000 in #114
chore: release v0.37.0 by @davidhu2000 in #115