Choose your path
Build with an SDK
Create an API key, then follow the runnable example below.
Connect an AI agent
Use Magic Hour from Claude, ChatGPT, Claude Code, or Codex through MCP.
Run in Google Colab
Try the APIs in your browser without setting up a local project.
- Create an API key - Get credentials to authenticate with our API
- Set up your development environment - Install SDK and create project files
- Generate your first output - Make an API call and download the result
Credit Cost: Pick the example that matches your goal. The image tab costs about 5 credits; the
face swap video tab costs about 200 credits for the sample clip. New accounts may receive starter
credits and account-specific rewards; check your balance in the web app.
1. Create your API key
Why: API keys authenticate your requests and track your usage.- Open the API Keys section of the Developer Hub and sign in.
- Click Create key, give it a name (e.g., “My First Project”), and create it.
- Copy the API key immediately — you won’t be able to see it again.
Need the full walkthrough?
See screenshots and key-management guidance in the Authentication guide.
2. Set up your development environment
Why: SDKs handle authentication, polling, and file downloads automatically, reducing boilerplate code.Create your project directory
Install the SDK
pkg-config before building.
On Ubuntu/Debian, run sudo apt-get install pkg-config libssl-dev. See the
OpenSSL setup guide for other Linux distributions.
3. Generate your first output
What we’re doing: Submit a generation job, wait for Magic Hour to render it, then download the result. Choose the example that matches what you want to build:
Prefer to submit your first image request in a browser? Use the
AI Image Generator interactive tester. Whether
you use the tester or the code below, reaching a first result takes three steps:
- Request accepted: Creating an image returns a project ID and
credits_charged. This is not a completed image yet. - Queued or rendering: Check the image project’s status
until it is
complete,error, orcanceled. The Python and Node.jsgenerate()examples handle polling for you; the other examples show how to pause between status checks. - Result ready: On
complete, use the returned download URL (or the SDK’s downloaded file) and check the charged credits.errorandcanceledare terminal states, not download-ready results.
Copy the code and run it
For cURL, use Bash withcurl and jq installed, and set MAGIC_HOUR_API_KEY. The examples check these prerequisites before creating a generation.
SDK compatibility: Install or upgrade the current Python or Node.js SDK before running these
examples. Older SDKs may provide
generate() but not support the model, aspect ratio, and
resolution fields used below. Go and Rust use the manual create/poll/download pattern shown below.- Choose an example tab, then copy the code from your preferred language tab below.
- Generate image (~5 credits)
- Face swap video (~200 credits)
Create an image from a text prompt. This is the cheapest way to verify your setup end to end.See the image generation guide for prompt examples and the
Image Generator API reference for every request field.Why these parameters:Expected output for Python and Node.js:Expected output for Go, Rust, and cURL:
image_count: 1- Generate one image (costs 5 credits)model: "z-image-turbo"- Use a specific model available on Free and paid plansaspect_ratio: "16:9"- Widescreen (landscape) output; also supports1:1and9:16resolution: "640px"- Use the resolution available on every plan instead of deprecatedautowait_for_completion: true- SDK polls until donedownload_outputs: true- Automatically download to local diskdownload_directory: "."- Save to the current directory
- Paste it into your file (
main.py,main.js,main.go, etc.) - Run the code:
Generate from your terminal
Installmh using the CLI installation instructions
for macOS, Linux, or Windows. Then sign in through your browser and check your account and credits:
PROJECT_ID with your existing image project ID. These commands do not create another
generation. An errored or canceled project cannot be resumed this way. If creation times out
before returning an ID, check your dashboard before retrying.
Troubleshooting
Common Issues
FileNotFoundError when using a customdownload_directory
The SDK saves outputs into download_directory but does not create the folder for you. The default (".") always works. If you point it at a folder that doesn’t exist yet (e.g. "outputs"), create it first:
HTTP Error Codes
If you encounter HTTP errors, here’s what they mean:
For a
402, use the response’s structured code, not its human-readable message:
insufficient_credits: add credits or choose a request that fits your balance.subscription_required: start a subscription.plan_upgrade_required: upgrade your plan or choose settings available on your current plan.
🎉 Congratulations! You have successfully created your first Magic Hour project.
Next Steps
- Explore the API Reference: Learn how to generate and edit videos and images programmatically. API Reference →
- Explore Face Swap Video: See parameter details, pricing, and production patterns in the Face Swap Video guide.
- Try All APIs in Google Colab: Run our complete cookbook with ready-to-run sample code. Just add your API key and start experimenting.
- Use the Web App: Try more tools and experiment interactively at magichour.ai.
- Handle Results at Scale: Set up webhooks to process results async and avoid polling.
- Join the Community: Get help, share projects, and see what others are building in Discord.
- Stay Updated: Check out the Changelog for new products and API updates.