From 8eac0b689c49dba4936902349288cb5d06685ad4 Mon Sep 17 00:00:00 2001 From: Runs Date: Mon, 7 Sep 2026 14:45:05 -0700 Subject: [PATCH 1/3] docs: clarify API guides and shorten the path to first usage --- billing/overview.mdx | 10 +- docs.json | 15 ++- get-started/quick-start.mdx | 14 ++- introduction.mdx | 7 +- snippets/tool-section.mdx | 58 +++++----- tools/audio/voice-cloner.mdx | 92 +++++++++------- tools/audio/voice-generator.mdx | 78 ++++++++------ tools/image/background-remover.mdx | 42 +++++--- tools/image/body-swap.mdx | 2 +- tools/image/clothes-changer.mdx | 58 +++++----- tools/image/face-editor.mdx | 110 ++++++++++--------- tools/image/face-swap-photo.mdx | 26 +++-- tools/image/gif-generator.mdx | 43 ++++---- tools/image/head-swap.mdx | 6 +- tools/image/headshot-generator.mdx | 28 ++--- tools/image/image-editor.mdx | 42 ++++---- tools/image/image-generator.mdx | 104 ++++++++++-------- tools/image/image-upscaler.mdx | 58 +++++----- tools/image/meme-generator.mdx | 74 +++++++------ tools/image/photo-colorizer.mdx | 22 ++-- tools/image/qr-code-generator.mdx | 46 ++++---- tools/video/animation.mdx | 136 +++++++++++++----------- tools/video/audio-to-video.mdx | 2 +- tools/video/auto-subtitle-generator.mdx | 30 +++--- tools/video/character-replace.mdx | 2 +- tools/video/face-swap-video.mdx | 32 +++--- tools/video/image-to-video.mdx | 35 +++--- tools/video/lip-sync.mdx | 54 +++++----- tools/video/talking-photo.mdx | 34 +++--- tools/video/text-to-video.mdx | 39 ++++--- tools/video/video-editor.mdx | 2 +- tools/video/video-to-video.mdx | 44 ++++---- 32 files changed, 769 insertions(+), 576 deletions(-) diff --git a/billing/overview.mdx b/billing/overview.mdx index 8e7e317..715f415 100644 --- a/billing/overview.mdx +++ b/billing/overview.mdx @@ -1,5 +1,6 @@ --- -title: Pricing Overview +title: Magic Hour API Pricing +sidebarTitle: Pricing Overview description: Understand API credits and choose a subscription, one-time credit packs, or usage-based billing. --- @@ -100,3 +101,10 @@ Usage-based billing is currently available by request. Contact **Not sure?** Start with the Free tier. Starter credits and account-specific rewards may be available; check your account balance, then choose a payment method after measuring real usage. + +## Make your first API request + +[Create an API key](https://magichour.ai/developer?tab=api-keys&ref=docs-billing-overview&utm_source=docs&utm_medium=referral&utm_campaign=billing), +then follow the [quickstart](/get-started/quick-start) to generate an image or video. +The [account endpoint](/api-reference/account/get-account-details) returns your credit balance and +subscription details so you can check them before submitting a job. diff --git a/docs.json b/docs.json index fd60124..9186c0a 100644 --- a/docs.json +++ b/docs.json @@ -35,8 +35,8 @@ ], "primary": { "type": "button", - "label": "Dashboard", - "href": "https://magichour.ai/developer?ref=docs-navbar&utm_source=docs&utm_medium=referral&utm_campaign=navbar" + "label": "Get API key", + "href": "https://magichour.ai/developer?tab=api-keys&ref=docs-navbar&utm_source=docs&utm_medium=referral&utm_campaign=navbar" } }, "footer": { @@ -84,6 +84,7 @@ "pages": [ "integration/overview", "integration/first-integration", + "integration/postman", "integration/adding-api-to-your-app", "integration/inputs-and-outputs", "integration/development-and-testing", @@ -273,6 +274,16 @@ ], "global": { "anchors": [ + { + "anchor": "API quickstart", + "href": "/get-started/quick-start", + "icon": "forward-fast" + }, + { + "anchor": "API pricing", + "href": "/billing/overview", + "icon": "credit-card" + }, { "anchor": "Community", "href": "https://discord.com/invite/JX5rgsZaJp", diff --git a/get-started/quick-start.mdx b/get-started/quick-start.mdx index 4ec1852..eba5455 100644 --- a/get-started/quick-start.mdx +++ b/get-started/quick-start.mdx @@ -1,10 +1,15 @@ --- -title: "Quick Start" -description: "Generate an API key and make your first call in under 3 minutes." +title: "Magic Hour API Quickstart" +sidebarTitle: "Quick Start" +description: "Create a Magic Hour API key and generate your first image or video with Python, Node.js, Go, Rust, or cURL." --- Magic Hour is an AI video and image generation platform. You submit a job, we render it, and you download the result. This guide gets you to your first output in a few minutes. +Compare [API pricing and payment options](/billing/overview) and +[per-model credit costs](/api-reference/models) before running a generation. You can use the +[account endpoint](/api-reference/account/get-account-details) to check your balance. + ## Choose your path @@ -69,7 +74,7 @@ export MAGIC_HOUR_API_KEY="your_api_key_here" ``` ```cmd Windows -setx MAGIC_HOUR_API_KEY "your_api_key_here" +set MAGIC_HOUR_API_KEY=your_api_key_here ``` ```powershell PowerShell @@ -173,6 +178,9 @@ result. Choose the example that matches what you want to build: Create an image from a text prompt. This is the cheapest way to verify your setup end to end. +See the [image generation guide](/tools/image/image-generator) for prompt examples and the +[Image Generator API reference](/api-reference/image-projects/ai-image-generator) for every request field. + **Why these parameters:** - `image_count: 1` - Generate one image (costs 5 credits) diff --git a/introduction.mdx b/introduction.mdx index c6683af..8636591 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -1,5 +1,5 @@ --- -title: Welcome to Magic Hour API +title: Magic Hour API Documentation sidebarTitle: Introduction description: Magic Hour API documentation - generate videos, images, and audio using AI. "og:title": "API Documentation | Magic Hour" @@ -8,6 +8,9 @@ description: Magic Hour API documentation - generate videos, images, and audio u Magic Hour API is an API for AI-powered video and image generation. You can run models for creating videos, images, and audio through a single REST API. +[Create an API key](https://magichour.ai/developer?tab=api-keys&ref=docs-introduction&utm_source=docs&utm_medium=referral&utm_campaign=introduction), +follow the [quickstart](/get-started/quick-start), or compare [API pricing](/billing/overview). + ## Choose how to use Magic Hour Magic Hour supports three ways to create, depending on how much control and automation you need: @@ -47,7 +50,7 @@ If you're new to Magic Hour, start here to learn the essentials and make your fi First request in 3 minutes. - + All endpoints in one place. ( <> + + + Request fields, responses, and examples + + + Install an SDK and complete your first generation + + + +

+ Check API pricing and model credit costs, then create an API key. +

+

+ To try {title} without code, use the browser tool. +

+ {outputs && outputs.length > 0 && ( {outputs.map((output, idx) => ( {type === "video" ? ( - ) : type === "audio" ? ( - )} - - - See API details - - - Learn more about {title} - - - ); diff --git a/tools/audio/voice-cloner.mdx b/tools/audio/voice-cloner.mdx index e921943..d92faf3 100644 --- a/tools/audio/voice-cloner.mdx +++ b/tools/audio/voice-cloner.mdx @@ -1,5 +1,5 @@ --- -title: AI Voice Cloner Tool - Magic Hour Docs +title: AI Voice Cloner API sidebarTitle: Voice Cloner description: Clone any voice and generate realistic speech audio from text using custom voice samples. --- @@ -117,18 +117,22 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiVoiceCloner.generate({ - assets: { - audioFilePath: "path/to/voice_sample.mp3", - }, - style: { - prompt: "Hello! This is a test of the Magic Hour voice cloner. Pretty cool, right?", +const result = await client.v1.aiVoiceCloner.generate( + { + assets: { + audioFilePath: "path/to/voice_sample.mp3", + }, + style: { + prompt: "Hello! This is a test of the Magic Hour voice cloner. Pretty cool, right?", + }, + name: "Voice Cloner audio", }, - name: "Voice Cloner audio", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Voice cloning complete!`); console.log(`Status: ${result.status}`); @@ -149,7 +153,7 @@ result = client.v1.ai_voice_cloner.generate( style={ "prompt": "Welcome to the show! Today we're going to talk about something really exciting." }, - name: "Voice Cloner audio", + name="Voice Cloner audio", wait_for_completion=True, download_outputs=True, download_directory="." @@ -166,18 +170,22 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiVoiceCloner.generate({ - assets: { - audioFilePath: "https://example.com/voice_sample.mp3", - }, - style: { - prompt: "Welcome to the show! Today we're going to talk about something really exciting.", +const result = await client.v1.aiVoiceCloner.generate( + { + assets: { + audioFilePath: "https://example.com/voice_sample.mp3", + }, + style: { + prompt: "Welcome to the show! Today we're going to talk about something really exciting.", + }, + name: "Voice Cloner audio", }, - name: "Voice Cloner audio", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` @@ -213,18 +221,22 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiVoiceCloner.generate({ - assets: { - audioFilePath: "path/to/narrator_voice.mp3", - }, - style: { - prompt: "In a world where technology meets creativity, Magic Hour brings your ideas to life.", +const result = await client.v1.aiVoiceCloner.generate( + { + assets: { + audioFilePath: "path/to/narrator_voice.mp3", + }, + style: { + prompt: "In a world where technology meets creativity, Magic Hour brings your ideas to life.", + }, + name: "Voice Cloner audio", }, - name: "Voice Cloner audio", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` @@ -288,11 +300,11 @@ print("lip_status:", lip_sync_result.status, "paths:", getattr(lip_sync_result, Voice cloning costs **0.1 credits per character** of generated text, rounded up to the nearest whole number. Inputs support up to 1,000 characters. -| Text Length | Credits | -| :-------------------------------- | :---------- | -| 100 characters (1-2 sentences) | 10 credits | -| 500 characters (a paragraph) | 50 credits | -| 1,000 characters (maximum) | 100 credits | +| Text Length | Credits | +| :----------------------------- | :---------- | +| 100 characters (1-2 sentences) | 10 credits | +| 500 characters (a paragraph) | 50 credits | +| 1,000 characters (maximum) | 100 credits | **Try this in our Google Colab Cookbook:** [Run this API with sample diff --git a/tools/audio/voice-generator.mdx b/tools/audio/voice-generator.mdx index d5c0c8f..aae4dec 100644 --- a/tools/audio/voice-generator.mdx +++ b/tools/audio/voice-generator.mdx @@ -1,5 +1,5 @@ --- -title: AI Voice Generator Tool - Magic Hour Docs +title: AI Voice Generator API sidebarTitle: Voice Generator description: Generate realistic speech audio from text using celebrity and character voices. --- @@ -122,16 +122,20 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiVoiceGenerator.generate({ - style: { - prompt: "Hello! This is a test of the Magic Hour voice generator. Pretty cool, right?", - voiceName: "Morgan Freeman", +const result = await client.v1.aiVoiceGenerator.generate( + { + style: { + prompt: "Hello! This is a test of the Magic Hour voice generator. Pretty cool, right?", + voiceName: "Morgan Freeman", + }, + name: "Voice Generator audio", }, - name: "Voice Generator audio", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Voice generation complete!`); console.log(`Status: ${result.status}`); @@ -167,16 +171,20 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiVoiceGenerator.generate({ - style: { - prompt: "Welcome to the show! Today we're going to talk about something really exciting.", - voiceName: "Joe Rogan", +const result = await client.v1.aiVoiceGenerator.generate( + { + style: { + prompt: "Welcome to the show! Today we're going to talk about something really exciting.", + voiceName: "Joe Rogan", + }, + name: "Voice Generator audio", }, - name: "Voice Generator audio", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` @@ -210,16 +218,20 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiVoiceGenerator.generate({ - style: { - prompt: "In a world where technology meets creativity, Magic Hour brings your ideas to life.", - voiceName: "Donald Trump", +const result = await client.v1.aiVoiceGenerator.generate( + { + style: { + prompt: "In a world where technology meets creativity, Magic Hour brings your ideas to life.", + voiceName: "Donald Trump", + }, + name: "Voice Generator audio", }, - name: "Voice Generator audio", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` @@ -281,11 +293,11 @@ print("lip_status:", lip_sync_result.status, "paths:", getattr(lip_sync_result, Voice generation costs **0.1 credits per character** of text, rounded up to the nearest whole number. Inputs support up to 1,000 characters. -| Text Length | Credits | -| :-------------------------------- | :---------- | -| 100 characters (1-2 sentences) | 10 credits | -| 500 characters (a paragraph) | 50 credits | -| 1,000 characters (maximum) | 100 credits | +| Text Length | Credits | +| :----------------------------- | :---------- | +| 100 characters (1-2 sentences) | 10 credits | +| 500 characters (a paragraph) | 50 credits | +| 1,000 characters (maximum) | 100 credits | **Try this in our Google Colab Cookbook:** [Run this API with sample diff --git a/tools/image/background-remover.mdx b/tools/image/background-remover.mdx index 36e4dbc..7a52357 100644 --- a/tools/image/background-remover.mdx +++ b/tools/image/background-remover.mdx @@ -1,5 +1,5 @@ --- -title: Image Background Remover Tool - Magic Hour Docs +title: Image Background Remover API sidebarTitle: Background Remover description: Automatically remove backgrounds from images with precision edge detection. --- @@ -113,15 +113,19 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.imageBackgroundRemover.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", +const result = await client.v1.imageBackgroundRemover.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + }, + name: "Product Cutout", }, - name: "Product Cutout", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Background removal complete!`); console.log(`Status: ${result.status}`); @@ -164,15 +168,19 @@ const images = [ ]; for (let i = 0; i < images.length; i++) { - const result = await client.v1.imageBackgroundRemover.generate({ - assets: { - imageFilePath: images[i], + const result = await client.v1.imageBackgroundRemover.generate( + { + assets: { + imageFilePath: images[i], + }, + name: `Product Cutout ${i + 1}`, }, - name: `Product Cutout ${i + 1}`, - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", - }); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } + ); console.log(`✅ Downloaded: ${result.downloadedPaths}`); } ``` diff --git a/tools/image/body-swap.mdx b/tools/image/body-swap.mdx index 02c6818..c1d20bb 100644 --- a/tools/image/body-swap.mdx +++ b/tools/image/body-swap.mdx @@ -1,5 +1,5 @@ --- -title: Body Swap Tool - Magic Hour Docs +title: Body Swap API sidebarTitle: Body Swap description: Place a person into a new scene with AI body replacement. --- diff --git a/tools/image/clothes-changer.mdx b/tools/image/clothes-changer.mdx index 3954b06..25fba33 100644 --- a/tools/image/clothes-changer.mdx +++ b/tools/image/clothes-changer.mdx @@ -1,5 +1,5 @@ --- -title: AI Clothes Changer Tool - Magic Hour Docs +title: AI Clothes Changer API sidebarTitle: Clothes Changer description: Virtually try on different clothing items with realistic results. --- @@ -109,19 +109,23 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiClothesChanger.generate({ - assets: { - personFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/rookiesteph.jpg", - garmentFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/bullsjersey.webp", - garmentType: "upper_body", +const result = await client.v1.aiClothesChanger.generate( + { + assets: { + personFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/rookiesteph.jpg", + garmentFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/bullsjersey.webp", + garmentType: "upper_body", + }, + name: "Clothes Changer image", }, - name: "Clothes Changer image", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Clothes change complete!`); console.log(`Status: ${result.status}`); @@ -158,19 +162,23 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiClothesChanger.generate({ - assets: { - personFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/bullsjersey.webp", - garmentFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/rookiesteph.jpg", - garmentType: "upper_body", +const result = await client.v1.aiClothesChanger.generate( + { + assets: { + personFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/bullsjersey.webp", + garmentFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/rookiesteph.jpg", + garmentType: "upper_body", + }, + name: "Clothes Changer image", }, - name: "Clothes Changer image", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` diff --git a/tools/image/face-editor.mdx b/tools/image/face-editor.mdx index b7fd65b..cab9a79 100644 --- a/tools/image/face-editor.mdx +++ b/tools/image/face-editor.mdx @@ -1,5 +1,5 @@ --- -title: AI Face Editor Tool - Magic Hour Docs +title: AI Face Editor API sidebarTitle: Face Editor description: Edit and enhance facial features with AI-powered precision and natural results. --- @@ -116,32 +116,36 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiFaceEditor.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", - }, - style: { - enhanceFace: false, - eyeGazeHorizontal: 0.0, - eyeGazeVertical: 0.0, - eyeOpenRatio: 0.0, - eyebrowDirection: 100, // Raise eyebrows - headPitch: 0.0, - headRoll: 0.0, - headYaw: 0.0, - lipOpenRatio: 0.0, - mouthGrim: 0.0, - mouthPositionHorizontal: 0.0, - mouthPositionVertical: 0.0, - mouthPout: 0.0, - mouthPurse: 0.0, - mouthSmile: 0.0, +const result = await client.v1.aiFaceEditor.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + }, + style: { + enhanceFace: false, + eyeGazeHorizontal: 0.0, + eyeGazeVertical: 0.0, + eyeOpenRatio: 0.0, + eyebrowDirection: 100, // Raise eyebrows + headPitch: 0.0, + headRoll: 0.0, + headYaw: 0.0, + lipOpenRatio: 0.0, + mouthGrim: 0.0, + mouthPositionHorizontal: 0.0, + mouthPositionVertical: 0.0, + mouthPout: 0.0, + mouthPurse: 0.0, + mouthSmile: 0.0, + }, + name: "Face Editor image", }, - name: "Face Editor image", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Face edit complete!`); console.log(`Status: ${result.status}`); @@ -193,32 +197,36 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiFaceEditor.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", - }, - style: { - enhanceFace: false, - eyeGazeHorizontal: 0.0, - eyeGazeVertical: 0.0, - eyeOpenRatio: 0.0, - eyebrowDirection: 100, // Raise eyebrows - headPitch: 0.0, - headRoll: 0.0, - headYaw: 0.0, - lipOpenRatio: 0.0, - mouthGrim: 0.0, - mouthPositionHorizontal: 0.0, - mouthPositionVertical: 0.0, - mouthPout: 100, // Make Mouth Pout - mouthPurse: 0.0, - mouthSmile: 0.0, +const result = await client.v1.aiFaceEditor.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + }, + style: { + enhanceFace: false, + eyeGazeHorizontal: 0.0, + eyeGazeVertical: 0.0, + eyeOpenRatio: 0.0, + eyebrowDirection: 100, // Raise eyebrows + headPitch: 0.0, + headRoll: 0.0, + headYaw: 0.0, + lipOpenRatio: 0.0, + mouthGrim: 0.0, + mouthPositionHorizontal: 0.0, + mouthPositionVertical: 0.0, + mouthPout: 100, // Make Mouth Pout + mouthPurse: 0.0, + mouthSmile: 0.0, + }, + name: "Face Editor image", }, - name: "Face Editor image", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Face edit complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/image/face-swap-photo.mdx b/tools/image/face-swap-photo.mdx index db6892f..040fd27 100644 --- a/tools/image/face-swap-photo.mdx +++ b/tools/image/face-swap-photo.mdx @@ -1,5 +1,5 @@ --- -title: Face Swap Photo Tool - Magic Hour Docs +title: Face Swap Photo API sidebarTitle: Face Swap Photo description: Replace faces in photos with realistic precision and natural blending. --- @@ -110,16 +110,22 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.faceSwapPhoto.generate({ - assets: { - sourceFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", - targetFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", +const result = await client.v1.faceSwapPhoto.generate( + { + assets: { + sourceFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + targetFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + }, + name: "My Face Swap", }, - name: "My Face Swap", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Face swap complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/image/gif-generator.mdx b/tools/image/gif-generator.mdx index 057ddbe..9bdd26b 100644 --- a/tools/image/gif-generator.mdx +++ b/tools/image/gif-generator.mdx @@ -1,14 +1,16 @@ --- -title: AI GIF Generator API - Magic Hour Docs +title: AI GIF Generator API sidebarTitle: GIF Generator API -description: Generate animated GIFs from images or text prompts with the Magic Hour API. +description: Generate animated GIFs from text prompts with the Magic Hour API. Includes Python and Node.js examples, output formats, and credit costs. --- import { ToolSection } from "/snippets/tool-section.mdx"; ## Overview -The AI GIF Generator API creates looping GIFs from a source image and a text prompt. Use it to add GIF generation to an application or automated media workflow. +The AI GIF Generator API creates animated GIFs from a text prompt. Use it to add GIF generation to an application or automated media workflow. The endpoint accepts `style.prompt` and an `output_format` of `gif`, `mp4`, or `webm`. + +To animate an existing image, use the [Image-to-Video API guide](/tools/video/image-to-video). The GIF endpoint does not accept an image input or a custom duration. @@ -83,19 +85,20 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiGifGenerator.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", - }, - style: { - prompt: "Create a smooth zoom and rotation animation", +const result = await client.v1.aiGifGenerator.generate( + { + style: { + prompt: "Cat fighting a lion, pixel art", + }, + outputFormat: "gif", + name: "Text-to-GIF example", }, - outputFormat: "gif", - name: "GIF Generator image", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ GIF complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/image/head-swap.mdx b/tools/image/head-swap.mdx index cd2df77..4c36016 100644 --- a/tools/image/head-swap.mdx +++ b/tools/image/head-swap.mdx @@ -1,5 +1,5 @@ --- -title: Head Swap Tool - Magic Hour Docs +title: Head Swap API sidebarTitle: Head Swap description: Replace an entire head in a photo while retaining the body and scene. --- @@ -44,8 +44,8 @@ Head Swap replaces the full head region in a body image using a separate head re ## Best Practices - **Match angle and lighting** - Similar head orientation, camera distance, and light direction produce - more natural blends. + **Match angle and lighting** - Similar head orientation, camera distance, and light direction + produce more natural blends. - **Use clear, high-resolution inputs** - Keep facial features and the full head visible diff --git a/tools/image/headshot-generator.mdx b/tools/image/headshot-generator.mdx index 9b4449e..9d566e5 100644 --- a/tools/image/headshot-generator.mdx +++ b/tools/image/headshot-generator.mdx @@ -1,5 +1,5 @@ --- -title: AI Headshot Generator Tool - Magic Hour Docs +title: AI Headshot Generator API sidebarTitle: Headshot Generator description: Generate professional-quality headshots from a single photo. --- @@ -105,18 +105,22 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiHeadshotGenerator.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", - }, - style: { - prompt: "Professional corporate headshot with neutral gray background", +const result = await client.v1.aiHeadshotGenerator.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + }, + style: { + prompt: "Professional corporate headshot with neutral gray background", + }, + name: "Professional Headshot", }, - name: "Professional Headshot", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Headshot complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/image/image-editor.mdx b/tools/image/image-editor.mdx index 8eb1b67..c811468 100644 --- a/tools/image/image-editor.mdx +++ b/tools/image/image-editor.mdx @@ -1,5 +1,5 @@ --- -title: AI Image Editor Tool - Magic Hour Docs +title: AI Image Editor API sidebarTitle: Image Editor description: Edit and modify images with AI-powered tools for comprehensive image manipulation. --- @@ -56,12 +56,12 @@ asynchronously, and duration varies with the input, selected settings, and queue ### Image Requirements -| Requirement | Details | -| :---------- | :---------------------------------- | -| Resolution | Minimum 512x512 pixels | +| Requirement | Details | +| :---------- | :---------------------------------------------------------------- | +| Resolution | Minimum 512x512 pixels | | Format | PNG, JPG, JPEG, JFIF, WEBP, HEIC, HEIF, AVIF, JP2, TIFF, TIF, BMP | -| Quality | Higher quality enables better edits | -| Clarity | Clear images edit more accurately | +| Quality | Higher quality enables better edits | +| Clarity | Clear images edit more accurately | ## Code Examples @@ -103,20 +103,24 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiImageEditor.generate({ - assets: { - imageFilePaths: [ - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", - ], - }, - style: { - prompt: "Change the background to a sunset beach scene", +const result = await client.v1.aiImageEditor.generate( + { + assets: { + imageFilePaths: [ + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + ], + }, + style: { + prompt: "Change the background to a sunset beach scene", + }, + name: "Image Editor image", }, - name: "Image Editor image", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Image edit complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/image/image-generator.mdx b/tools/image/image-generator.mdx index 3a97221..1e46555 100644 --- a/tools/image/image-generator.mdx +++ b/tools/image/image-generator.mdx @@ -1,5 +1,5 @@ --- -title: AI Image Generator Tool - Magic Hour Docs +title: AI Image Generator API sidebarTitle: Image Generator description: Create high-quality images from text descriptions using AI. --- @@ -123,18 +123,22 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiImageGenerator.generate({ - imageCount: 1, - aspectRatio: "16:9", - style: { - prompt: "A serene mountain landscape at sunset with vibrant colors", - tool: "ai-photo-generator", +const result = await client.v1.aiImageGenerator.generate( + { + imageCount: 1, + aspectRatio: "16:9", + style: { + prompt: "A serene mountain landscape at sunset with vibrant colors", + tool: "ai-photo-generator", + }, + name: "Mountain Sunset", }, - name: "Mountain Sunset", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Image complete!`); console.log(`Status: ${result.status}`); @@ -173,18 +177,22 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiImageGenerator.generate({ - imageCount: 4, // Generate 4 variations - aspectRatio: "1:1", - style: { - prompt: "Cute cat wearing sunglasses, digital art style", - tool: "ai-anime-generator", +const result = await client.v1.aiImageGenerator.generate( + { + imageCount: 4, // Generate 4 variations + aspectRatio: "1:1", + style: { + prompt: "Cute cat wearing sunglasses, digital art style", + tool: "ai-anime-generator", + }, + name: "Cat Variations", }, - name: "Cat Variations", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Image complete!`); console.log(`Status: ${result.status}`); @@ -223,18 +231,22 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiImageGenerator.generate({ - imageCount: 1, - aspectRatio: "9:16", - style: { - prompt: "Professional business woman in modern office", - tool: "ai-photo-generator", +const result = await client.v1.aiImageGenerator.generate( + { + imageCount: 1, + aspectRatio: "9:16", + style: { + prompt: "Professional business woman in modern office", + tool: "ai-photo-generator", + }, + name: "Business Portrait", }, - name: "Business Portrait", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Image complete!`); console.log(`Status: ${result.status}`); @@ -248,18 +260,18 @@ console.log(`Credits charged: ${result.creditsCharged}`); Cost depends on the `model` you choose (the default model is picked automatically and may change over time): -| Model | Credits per image (from) | Tiers | -| :------------------- | :----------------------- | :--------------------------- | -| `flux-schnell` | 5 | All (including free) | -| `flux-2-klein` | 5 | All (including free) | -| `z-image-turbo` | 5 | All (including free) | -| `seedream-v4` | 40 | Creator, Pro, Business | -| `gpt-image-2` | 50 | Creator, Pro, Business | -| `nano-banana` | 50 | Creator, Pro, Business | -| `nano-banana-2-lite` | 50 | Creator, Pro, Business | -| `seedream-v5-pro` | 75 | Creator, Pro, Business | -| `nano-banana-2` | 100 | Creator, Pro, Business | -| `nano-banana-pro` | 150 | Creator, Pro, Business | +| Model | Credits per image (from) | Tiers | +| :------------------- | :----------------------- | :--------------------- | +| `flux-schnell` | 5 | All (including free) | +| `flux-2-klein` | 5 | All (including free) | +| `z-image-turbo` | 5 | All (including free) | +| `seedream-v4` | 40 | Creator, Pro, Business | +| `gpt-image-2` | 50 | Creator, Pro, Business | +| `nano-banana` | 50 | Creator, Pro, Business | +| `nano-banana-2-lite` | 50 | Creator, Pro, Business | +| `seedream-v5-pro` | 75 | Creator, Pro, Business | +| `nano-banana-2` | 100 | Creator, Pro, Business | +| `nano-banana-pro` | 150 | Creator, Pro, Business | Higher resolutions can increase the cost — see the `model` parameter in the [API reference](/api-reference/image-projects/ai-image-generator) for supported resolutions and image counts per model. diff --git a/tools/image/image-upscaler.mdx b/tools/image/image-upscaler.mdx index fe5b69a..730d2a6 100644 --- a/tools/image/image-upscaler.mdx +++ b/tools/image/image-upscaler.mdx @@ -1,5 +1,5 @@ --- -title: AI Image Upscaler Tool - Magic Hour Docs +title: AI Image Upscaler API sidebarTitle: Image Upscaler description: Enhance image resolution and quality using AI-powered upscaling. --- @@ -116,19 +116,23 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiImageUpscaler.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/sea.jpg", - }, - scaleFactor: 2.0, - style: { - mode: "balanced", +const result = await client.v1.aiImageUpscaler.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/sea.jpg", + }, + scaleFactor: 2.0, + style: { + mode: "balanced", + }, + name: "Image Upscaler image", }, - name: "Image Upscaler image", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Upscale complete!`); console.log(`Status: ${result.status}`); @@ -168,19 +172,23 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiImageUpscaler.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/sea.jpg", - }, - scaleFactor: 4.0, - style: { - mode: "balanced", +const result = await client.v1.aiImageUpscaler.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/sea.jpg", + }, + scaleFactor: 4.0, + style: { + mode: "balanced", + }, + name: "Image Upscaler image", }, - name: "Image Upscaler image", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Upscale complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/image/meme-generator.mdx b/tools/image/meme-generator.mdx index 1c20d9a..42b4929 100644 --- a/tools/image/meme-generator.mdx +++ b/tools/image/meme-generator.mdx @@ -1,5 +1,5 @@ --- -title: AI Meme Generator Tool - Magic Hour Docs +title: AI Meme Generator API sidebarTitle: Meme Generator description: Create AI-generated memes using popular templates and custom topics. --- @@ -120,17 +120,21 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiMemeGenerator.generate({ - style: { - searchWeb: false, - template: "Drake Hotline Bling", - topic: "When the code finally works after hours of debugging", +const result = await client.v1.aiMemeGenerator.generate( + { + style: { + searchWeb: false, + template: "Drake Hotline Bling", + topic: "When the code finally works after hours of debugging", + }, + name: "Code Works Meme", }, - name: "Code Works Meme", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Meme complete!`); console.log(`Status: ${result.status}`); @@ -167,17 +171,21 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiMemeGenerator.generate({ - style: { - searchWeb: false, - template: "Drake Hotline Bling", - topic: "Developers and shiny new frameworks", +const result = await client.v1.aiMemeGenerator.generate( + { + style: { + searchWeb: false, + template: "Drake Hotline Bling", + topic: "Developers and shiny new frameworks", + }, + name: "Framework Meme", }, - name: "Framework Meme", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` @@ -212,17 +220,21 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiMemeGenerator.generate({ - style: { - searchWeb: true, - template: "Two Buttons", - topic: "Latest tech trends in AI development", +const result = await client.v1.aiMemeGenerator.generate( + { + style: { + searchWeb: true, + template: "Two Buttons", + topic: "Latest tech trends in AI development", + }, + name: "AI Trends Meme", }, - name: "AI Trends Meme", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` diff --git a/tools/image/photo-colorizer.mdx b/tools/image/photo-colorizer.mdx index fe66798..f22464a 100644 --- a/tools/image/photo-colorizer.mdx +++ b/tools/image/photo-colorizer.mdx @@ -1,5 +1,5 @@ --- -title: Photo Colorizer Tool - Magic Hour Docs +title: Photo Colorizer API sidebarTitle: Photo Colorizer description: Colorize black and white photos with AI-powered realistic color restoration. --- @@ -98,15 +98,19 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.photoColorizer.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/bw-photo.jpg", +const result = await client.v1.photoColorizer.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/bw-photo.jpg", + }, + name: "Photo Colorizer image", }, - name: "Photo Colorizer image", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Colorization complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/image/qr-code-generator.mdx b/tools/image/qr-code-generator.mdx index 25ebcb2..5e38692 100644 --- a/tools/image/qr-code-generator.mdx +++ b/tools/image/qr-code-generator.mdx @@ -1,5 +1,5 @@ --- -title: AI QR Code Generator Tool - Magic Hour Docs +title: AI QR Code Generator API sidebarTitle: QR Code Generator description: Create visually appealing, artistic QR codes that maintain functionality. --- @@ -113,16 +113,20 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiQrCodeGenerator.generate({ - content: "https://yourwebsite.com", - style: { - artStyle: "Ocean waves with blue and teal colors, flowing organic patterns", +const result = await client.v1.aiQrCodeGenerator.generate( + { + content: "https://yourwebsite.com", + style: { + artStyle: "Ocean waves with blue and teal colors, flowing organic patterns", + }, + name: "Brand QR Code", }, - name: "Brand QR Code", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ QR code complete!`); console.log(`Status: ${result.status}`); @@ -158,16 +162,20 @@ else: ``` ```javascript Node.js -const result = await client.v1.aiQrCodeGenerator.generate({ - content: "https://event.example.com/tickets", - style: { - artStyle: "Elegant gold and black art deco patterns", +const result = await client.v1.aiQrCodeGenerator.generate( + { + content: "https://event.example.com/tickets", + style: { + artStyle: "Elegant gold and black art deco patterns", + }, + name: "Event QR Code", }, - name: "Event QR Code", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` diff --git a/tools/video/animation.mdx b/tools/video/animation.mdx index 66ae72b..35342ab 100644 --- a/tools/video/animation.mdx +++ b/tools/video/animation.mdx @@ -1,5 +1,5 @@ --- -title: Animation Tool - Magic Hour Docs +title: Animation API sidebarTitle: Animation description: Transform static images into dynamic animated videos with smooth motion. --- @@ -107,26 +107,30 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.animation.generate({ - assets: { - audioSource: "none", - }, - endSeconds: 1.5, - fps: 8, - height: 256, - width: 512, - style: { - artStyle: "Studio Ghibli Film Still", - cameraEffect: "Dramatic Zoom In", - prompt: "A majestic tiger walking through a misty jungle at sunset, magical atmosphere", - promptType: "custom", - transitionSpeed: 5, +const result = await client.v1.animation.generate( + { + assets: { + audioSource: "none", + }, + endSeconds: 1.5, + fps: 8, + height: 256, + width: 512, + style: { + artStyle: "Studio Ghibli Film Still", + cameraEffect: "Dramatic Zoom In", + prompt: "A majestic tiger walking through a misty jungle at sunset, magical atmosphere", + promptType: "custom", + transitionSpeed: 5, + }, + name: "Tiger Animation", }, - name: "Tiger Animation", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Animation complete!`); console.log(`Status: ${result.status}`); @@ -173,27 +177,31 @@ else: ``` ```javascript Node.js -const result = await client.v1.animation.generate({ - assets: { - audioSource: "none", - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", - }, - endSeconds: 1.5, - fps: 8.0, - height: 288, - width: 288, - style: { - artStyle: "Van Gogh", - cameraEffect: "Spin Bounce", - prompt: "Tom Cruise in an action pose, dramatic lighting, cinematic intensity", - promptType: "custom", - transitionSpeed: 5, +const result = await client.v1.animation.generate( + { + assets: { + audioSource: "none", + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + }, + endSeconds: 1.5, + fps: 8.0, + height: 288, + width: 288, + style: { + artStyle: "Van Gogh", + cameraEffect: "Spin Bounce", + prompt: "Tom Cruise in an action pose, dramatic lighting, cinematic intensity", + promptType: "custom", + transitionSpeed: 5, + }, + name: "Tom Cruise Animation", }, - name: "Tom Cruise Animation", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` @@ -238,29 +246,33 @@ else: ``` ```javascript Node.js -const result = await client.v1.animation.generate({ - endSeconds: 2.0, - fps: 8.0, - height: 256, - width: 512, - assets: { - audioFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/you-are-just-a-line-of-code.mp3", - audioSource: "file", - }, - style: { - artStyle: "Cyberpunk", - cameraEffect: "Pulse - Audio Sync", - prompt: - "Digital code streams and neon circuits pulsing to the rhythm, futuristic tech aesthetic", - promptType: "custom", - transitionSpeed: 5, +const result = await client.v1.animation.generate( + { + endSeconds: 2.0, + fps: 8.0, + height: 256, + width: 512, + assets: { + audioFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/you-are-just-a-line-of-code.mp3", + audioSource: "file", + }, + style: { + artStyle: "Cyberpunk", + cameraEffect: "Pulse - Audio Sync", + prompt: + "Digital code streams and neon circuits pulsing to the rhythm, futuristic tech aesthetic", + promptType: "custom", + transitionSpeed: 5, + }, + name: "Code Audio Animation", }, - name: "Code Audio Animation", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Downloaded to: ${result.downloadedPaths}`); ``` diff --git a/tools/video/audio-to-video.mdx b/tools/video/audio-to-video.mdx index 1706a3d..1ad4df8 100644 --- a/tools/video/audio-to-video.mdx +++ b/tools/video/audio-to-video.mdx @@ -1,5 +1,5 @@ --- -title: Audio to Video Tool - Magic Hour Docs +title: Audio to Video API sidebarTitle: Audio to Video description: Generate a video from audio, an optional image, and a text prompt. --- diff --git a/tools/video/auto-subtitle-generator.mdx b/tools/video/auto-subtitle-generator.mdx index 3d3ce0e..eeb3c5f 100644 --- a/tools/video/auto-subtitle-generator.mdx +++ b/tools/video/auto-subtitle-generator.mdx @@ -1,5 +1,5 @@ --- -title: Auto Subtitle Generator Tool - Magic Hour Docs +title: Auto Subtitle Generator API sidebarTitle: Auto Subtitle description: Automatically generate and embed subtitles in videos with AI-powered transcription. --- @@ -99,19 +99,23 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.autoSubtitleGenerator.generate({ - assets: { - videoFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov", +const result = await client.v1.autoSubtitleGenerator.generate( + { + assets: { + videoFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov", + }, + startSeconds: 0, + endSeconds: 2, + style: { template: "karaoke" }, + name: "Subtitled Video", }, - startSeconds: 0, - endSeconds: 2, - style: { template: "karaoke" }, - name: "Subtitled Video", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Subtitles complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/video/character-replace.mdx b/tools/video/character-replace.mdx index 5ec6979..0fb3399 100644 --- a/tools/video/character-replace.mdx +++ b/tools/video/character-replace.mdx @@ -1,5 +1,5 @@ --- -title: Character Replace Tool - Magic Hour Docs +title: Character Replace API sidebarTitle: Character Replace description: Replace a person in a video with a character from a reference image. --- diff --git a/tools/video/face-swap-video.mdx b/tools/video/face-swap-video.mdx index 8604156..3bea599 100644 --- a/tools/video/face-swap-video.mdx +++ b/tools/video/face-swap-video.mdx @@ -1,5 +1,5 @@ --- -title: Face Swap Video Tool - Magic Hour Docs +title: Face Swap Video API sidebarTitle: Face Swap Video description: Replace faces in videos with frame-by-frame precision and temporal consistency. --- @@ -116,20 +116,24 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.faceSwap.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", - videoFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov", - videoSource: "file", +const result = await client.v1.faceSwap.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + videoFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov", + videoSource: "file", + }, + startSeconds: 0, + endSeconds: 2, + name: "Tom Cruise Face Swap", }, - startSeconds: 0, - endSeconds: 2, - name: "Tom Cruise Face Swap", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Face swap complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/video/image-to-video.mdx b/tools/video/image-to-video.mdx index 8464499..86cc1ab 100644 --- a/tools/video/image-to-video.mdx +++ b/tools/video/image-to-video.mdx @@ -1,5 +1,5 @@ --- -title: Image to Video Tool - Magic Hour Docs +title: Image to Video API sidebarTitle: Image to Video description: Convert static images into dynamic video content with AI-generated motion. --- @@ -37,6 +37,8 @@ asynchronously, and duration varies with the input, selected settings, and queue ## Use Cases +For a complete product demo workflow, follow the [product video starter recipe](/get-started/starter-recipes). It covers image preparation, video generation, and downloading the result. + - **Social media content** - Turn photos into engaging video posts - **Marketing videos** - Create dynamic content from product photos - **Storytelling** - Bring static images to life for narratives @@ -125,20 +127,25 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.imageToVideo.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/sunset.jpg", - }, - style: { - prompt: "Sunset landscape with subtle camera movement, gentle parallax effect, cinematic depth", +const result = await client.v1.imageToVideo.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/sunset.jpg", + }, + style: { + prompt: + "Sunset landscape with subtle camera movement, gentle parallax effect, cinematic depth", + }, + endSeconds: 5, + name: "Sunset Animation", + resolution: "480p", }, - endSeconds: 5, - name: "Sunset Animation", - resolution: "480p", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Video complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/video/lip-sync.mdx b/tools/video/lip-sync.mdx index 35ae616..4ab5f7c 100644 --- a/tools/video/lip-sync.mdx +++ b/tools/video/lip-sync.mdx @@ -1,5 +1,5 @@ --- -title: Lip Sync Tool - Magic Hour Docs +title: Lip Sync API sidebarTitle: Lip Sync description: Synchronize lip movements in videos with new audio tracks. --- @@ -37,6 +37,8 @@ asynchronously, and duration varies with the input, selected settings, and queue ## Use Cases +For a complete voice-to-video workflow, follow the [lip-sync starter recipe](/get-started/starter-recipes). It covers uploading your video and voiceover, submitting the lip-sync job, and downloading the result. + - **Dubbing and localization** - Translate videos to new languages with matching lips - **Personalized messages** - Create custom video messages with any voice - **Educational content** - Produce training videos with voiceovers @@ -118,25 +120,29 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.lipSync.generate({ - assets: { - audioFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/you-are-just-a-line-of-code.mp3", - videoFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov", - videoSource: "file", - }, - endSeconds: 2, - startSeconds: 0, - maxFpsLimit: 8, - style: { - generationMode: "lite", +const result = await client.v1.lipSync.generate( + { + assets: { + audioFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/you-are-just-a-line-of-code.mp3", + videoFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov", + videoSource: "file", + }, + endSeconds: 2, + startSeconds: 0, + maxFpsLimit: 8, + style: { + generationMode: "lite", + }, + name: "Obama Code Lip Sync", }, - name: "Obama Code Lip Sync", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Lip sync complete!`); console.log(`Status: ${result.status}`); @@ -149,11 +155,11 @@ console.log(`Downloaded to: ${result.downloadedPaths}`); Lip Sync is charged per rendered frame, and the rate depends on `style.generation_mode`: -| Generation mode | Credits per frame | Notes | -| :------------------- | :---------------- | :--------------------------------------------- | -| `lite` | 1 | Available on all tiers | -| `standard` | 1 | Creator, Pro, and Business tiers only | -| `pro` | 2 | Creator, Pro, and Business tiers only | +| Generation mode | Credits per frame | Notes | +| :-------------- | :---------------- | :------------------------------------ | +| `lite` | 1 | Available on all tiers | +| `standard` | 1 | Creator, Pro, and Business tiers only | +| `pro` | 2 | Creator, Pro, and Business tiers only | For example, a 10-second clip capped at 30 FPS in `lite` mode costs about 300 credits. Use `max_fps_limit` to lower the frame rate and reduce cost. Credits are only charged for the frames that actually render, and the completed job's `credits_charged` shows the exact cost. diff --git a/tools/video/talking-photo.mdx b/tools/video/talking-photo.mdx index 44b4587..5840674 100644 --- a/tools/video/talking-photo.mdx +++ b/tools/video/talking-photo.mdx @@ -1,5 +1,5 @@ --- -title: AI Talking Photo Tool - Magic Hour Docs +title: AI Talking Photo API sidebarTitle: Talking Photo description: Animate static photos to speak with realistic lip-sync and facial movements. --- @@ -59,8 +59,8 @@ asynchronously, and duration varies with the input, selected settings, and queue ### Audio Guidelines -| Audio Type | Best Practice | -| :--------------- | :-------------------------------------------------------------------------------- | +| Audio Type | Best Practice | +| :--------------- | :--------------------------------------------------------------------------------- | | Voice recording | Clear speech without background noise | | Generated speech | Create the audio first with the [AI Voice Generator](/tools/audio/voice-generator) | | Music/songs | Works best with clear vocals | @@ -106,19 +106,23 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.aiTalkingPhoto.generate({ - assets: { - imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", - audioFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/you-are-just-a-line-of-code.mp3", +const result = await client.v1.aiTalkingPhoto.generate( + { + assets: { + imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png", + audioFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/you-are-just-a-line-of-code.mp3", + }, + name: "Talking Photo", + startSeconds: 0, + endSeconds: 2, }, - name: "Talking Photo", - startSeconds: 0, - endSeconds: 2, - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Talking photo complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/video/text-to-video.mdx b/tools/video/text-to-video.mdx index d829dcf..31d370c 100644 --- a/tools/video/text-to-video.mdx +++ b/tools/video/text-to-video.mdx @@ -1,5 +1,5 @@ --- -title: Text to Video Tool - Magic Hour Docs +title: Text to Video API sidebarTitle: Text to Video description: Generate complete video content from text descriptions using AI. --- @@ -69,11 +69,11 @@ For best results, include these elements: ### Duration Guidelines -| Duration | Best For | -| :------------ | :----------------------------------- | -| 3-5 seconds | Social media clips, GIF-like content | -| 5-10 seconds | Short-form content, product demos | -| 10-15 seconds | Story segments, longer narratives | +| Duration | Best For | +| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 3-5 seconds | Social media clips, GIF-like content | +| 5-10 seconds | Short-form content, product demos | +| 10-15 seconds | Story segments, longer narratives | | Up to 60 seconds | Long-form scenes (model-dependent; see the `end_seconds` values supported by each model in the [API reference](/api-reference/video-projects/text-to-video)) | ## Code Examples @@ -116,18 +116,23 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.textToVideo.generate({ - endSeconds: 5, - aspectRatio: "16:9", - style: { - prompt: "A majestic lion walking through golden savanna grass at sunset, cinematic slow motion", +const result = await client.v1.textToVideo.generate( + { + endSeconds: 5, + aspectRatio: "16:9", + style: { + prompt: + "A majestic lion walking through golden savanna grass at sunset, cinematic slow motion", + }, + name: "Nature Video", + resolution: "480p", }, - name: "Nature Video", - resolution: "480p", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Video complete!`); console.log(`Status: ${result.status}`); diff --git a/tools/video/video-editor.mdx b/tools/video/video-editor.mdx index 9946eac..842230e 100644 --- a/tools/video/video-editor.mdx +++ b/tools/video/video-editor.mdx @@ -1,5 +1,5 @@ --- -title: AI Video Editor Tool - Magic Hour Docs +title: AI Video Editor API sidebarTitle: AI Video Editor description: Edit existing videos with natural-language prompts. --- diff --git a/tools/video/video-to-video.mdx b/tools/video/video-to-video.mdx index 5030d79..5471abb 100644 --- a/tools/video/video-to-video.mdx +++ b/tools/video/video-to-video.mdx @@ -1,5 +1,5 @@ --- -title: Video to Video Tool - Magic Hour Docs +title: Video to Video API sidebarTitle: Video to Video description: Transform existing videos by applying new styles, effects, and visual treatments. --- @@ -129,26 +129,30 @@ import { Client } from "magic-hour"; const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY }); -const result = await client.v1.videoToVideo.generate({ - assets: { - videoFilePath: - "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov", - videoSource: "file", - }, - endSeconds: 2, - fpsResolution: "HALF", - startSeconds: 0, - style: { - artStyle: "Studio Ghibli", - prompt: "Obama dropping the mic in anime style, soft pastel colors, whimsical and expressive", - promptType: "custom", - version: "default", +const result = await client.v1.videoToVideo.generate( + { + assets: { + videoFilePath: + "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov", + videoSource: "file", + }, + endSeconds: 2, + fpsResolution: "HALF", + startSeconds: 0, + style: { + artStyle: "Studio Ghibli", + prompt: "Obama dropping the mic in anime style, soft pastel colors, whimsical and expressive", + promptType: "custom", + version: "default", + }, + name: "Anime Mic Drop", }, - name: "Anime Mic Drop", - waitForCompletion: true, - downloadOutputs: true, - downloadDirectory: ".", -}); + { + waitForCompletion: true, + downloadOutputs: true, + downloadDirectory: ".", + } +); console.log(`✅ Video complete!`); console.log(`Status: ${result.status}`); From deff907dbc23d6836d3146505556fa5039386c09 Mon Sep 17 00:00:00 2001 From: Runs Date: Mon, 7 Sep 2026 15:02:11 -0700 Subject: [PATCH 2/3] docs: avoid repeating API in the GIF reference label --- tools/image/gif-generator.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/image/gif-generator.mdx b/tools/image/gif-generator.mdx index 9bdd26b..78f89b8 100644 --- a/tools/image/gif-generator.mdx +++ b/tools/image/gif-generator.mdx @@ -21,7 +21,7 @@ To animate an existing image, use the [Image-to-Video API guide](/tools/video/im Date: Tue, 8 Sep 2026 02:44:26 -0700 Subject: [PATCH 3/3] docs: repair Python reference sample syntax --- api-reference/openapi.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index b074b41..853397e 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -836,7 +836,7 @@ "x-codeSamples": [ { "lang": "python", - "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.face_detection.generate(\n assets={\"target_file_path\": \"/path/to/1234.png\"}, confidence_score=0.5\n wait_for_completion=True,\n download_outputs=True,\n download_directory=\".\"\n)" + "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.face_detection.generate(\n assets={\"target_file_path\": \"/path/to/1234.png\"}, confidence_score=0.5,\n wait_for_completion=True,\n download_outputs=True,\n download_directory=\".\"\n)" }, { "lang": "javascript", @@ -6226,7 +6226,7 @@ "x-codeSamples": [ { "lang": "python", - "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.ai_headshot_generator.generate(\n assets={\"image_file_path\": \"/path/to/1234.png\"}, name=\"Ai Headshot image\"\n wait_for_completion=True,\n download_outputs=True,\n download_directory=\".\"\n)" + "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.ai_headshot_generator.generate(\n assets={\"image_file_path\": \"/path/to/1234.png\"}, name=\"Ai Headshot image\",\n wait_for_completion=True,\n download_outputs=True,\n download_directory=\".\"\n)" }, { "lang": "javascript", @@ -8378,7 +8378,7 @@ "x-codeSamples": [ { "lang": "python", - "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.photo_colorizer.generate(\n assets={\"image_file_path\": \"/path/to/1234.png\"}, name=\"Photo Colorizer image\"\n wait_for_completion=True,\n download_outputs=True,\n download_directory=\".\"\n)" + "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.photo_colorizer.generate(\n assets={\"image_file_path\": \"/path/to/1234.png\"}, name=\"Photo Colorizer image\",\n wait_for_completion=True,\n download_outputs=True,\n download_directory=\".\"\n)" }, { "lang": "javascript",