Skip to main content
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 and per-model credit costs before running a generation. You can use the account endpoint to check your balance.

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.
Prefer your terminal? Use the CLI to generate and download an image without writing SDK code. For the SDK path, you’ll:
  1. Create an API key - Get credentials to authenticate with our API
  2. Set up your development environment - Install SDK and create project files
  3. 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.
  1. Open the API Keys section of the Developer Hub and sign in.
  2. Click Create key, give it a name (e.g., “My First Project”), and create it.
  3. 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.
Store your API key as an environment variable:
Never commit API keys to version control. Always use environment variables or secure credential management. A new key’s full secret is shown only when it is created; if you lose it, create another key instead of trying to recover it from the Developer Hub.

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

Rust on Linux: Install OpenSSL development headers and 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.
Want to test your integration without spending credits? The SDKs include a mock server that returns sample responses instantly.

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:
  1. Request accepted: Creating an image returns a project ID and credits_charged. This is not a completed image yet.
  2. Queued or rendering: Check the image project’s status until it is complete, error, or canceled. The Python and Node.js generate() examples handle polling for you; the other examples show how to pause between status checks.
  3. Result ready: On complete, use the returned download URL (or the SDK’s downloaded file) and check the charged credits. error and canceled are terminal states, not download-ready results.

Copy the code and run it

For cURL, use Bash with curl 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.
  1. Choose an example tab, then copy the code from your preferred language tab below.
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:
  • image_count: 1 - Generate one image (costs 5 credits)
  • model: "z-image-turbo" - Use a specific model available on Free and paid plans
  • aspect_ratio: "16:9" - Widescreen (landscape) output; also supports 1:1 and 9:16
  • resolution: "640px" - Use the resolution available on every plan instead of deprecated auto
  • wait_for_completion: true - SDK polls until done
  • download_outputs: true - Automatically download to local disk
  • download_directory: "." - Save to the current directory
Expected output for Python and Node.js:
Expected output for Go, Rust, and cURL:
  1. Paste it into your file (main.py, main.js, main.go, etc.)
  2. Run the code:

Generate from your terminal

Install mh using the CLI installation instructions for macOS, Linux, or Windows. Then sign in through your browser and check your account and credits:
Each generation creates a new project and uses credits. The command below requests one z-image-turbo image at 640px, currently 5 credits. Check your balance before running it. Stopping the command does not cancel a submitted project.
The CLI waits for completion, downloads the image into your current directory, and prints its path and project ID. No SDK project or manual polling loop is needed. If waiting or downloading is interrupted, keep the project ID printed by the CLI. Recover the same project instead of running the generation command again:
Replace 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 custom download_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:
Error: MAGIC_HOUR_API_KEY environment variable not set Solution: Set your API key as an environment variable. See Environment Variables in the Authentication guide for platform-specific setup steps.

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.
Credit packs do not unlock paid-plan models or settings. Retry only after resolving the indicated requirement. For persistent errors: Contact support@magichour.ai with your project ID.
🎉 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.
Prefer fast iteration inside your editor? Install this documentation as an MCP server to get contextual help while integrating the Magic Hour API. Learn more.