Overview
Most Magic Hour APIs use a file-based workflow: you provide input files (images, videos, audio), the API processes them, and returns generated output files. Some APIs like AI Image Generator or Text-to-Video work with text prompts instead. This guide covers both sides of file handling: getting your files to Magic Hour and retrieving the results.Input Files
How to Provide Input Files
You have three options for providing input files to the API:| Method | Best For | Pros | Cons |
|---|---|---|---|
| Public URLs | Files already hosted | Simple, no upload needed | Requires public hosting |
| Magic Hour Library URLs | Reusing generated content | No upload, direct reference | Must be from your Magic Hour account |
| Upload to Magic Hour | Local files, secure files | No hosting required, secure | Extra upload step |
Option 1: Using Public URLs
The simplest method if your files are already hosted somewhere publicly accessible:URL Requirements
- Must be publicly accessible (or use authenticated URLs that Magic Hour can access)
- Must include the file extension in the URL
- Should use HTTPS for security
- Files must be in supported formats
Option 2: Using Magic Hour Library URLs
You can reference files from your Magic Hour library directly using library URLs. This is useful when you want to reuse previously generated content or files you’ve uploaded to Magic Hour.Library URL Format
Magic Hour library URLs follow this pattern:- Videos:
https://magichour.ai/my-library?videoId={video_id} - Images:
https://magichour.ai/my-library?imageId={image_id} - Audio:
https://magichour.ai/my-library?audioId={audio_id}
Using Library URLs in API Calls
Library Access: You can only use library URLs for files in your own Magic Hour account. The file IDs are available from your my-library dashboard or from API responses.
- ✅ Reuse previously generated content
- ✅ No need to re-upload files
- ✅ Direct reference to your Magic Hour files
- ✅ Works with any file type (video, image, audio)
Option 3: Uploading to Magic Hour Storage
For local files or files that aren’t publicly hosted, upload them to Magic Hour’s storage:Upload Process
The upload workflow has three steps:- Request upload URLs - Tell Magic Hour what file types you’re uploading (specify extension and type)
- Upload files - PUT your files to the provided temporary URLs
- Use file paths - Reference the returned
file_pathin your API calls
SDK Upload (Simplified)
Python and Node.js SDKs provide a helper function:SDK Version Required: Python SDK v0.36.0+ or Node SDK v0.37.0+
Go and Rust SDKs: Manual upload process (shown below)
Go and Rust SDKs: Manual upload process (shown below)
Manual Upload Process
For Go, Rust, or custom implementations:Upload Response Format
upload_url: Temporary URL for uploading (PUT request)file_path: Reference to use in API calls (starts withmh://)type: File type (video, image, audio)extension: File extension
Uploading Multiple Files
Request multiple upload URLs in a single call:Output Files
Download URLs
When a job completes successfully, the response includes download URLs:Download URL Expiration
To get fresh download URLs for an existing project:Streaming Downloads
For production applications, use streaming downloads to handle large files efficiently:Handling Multiple Output Files
Some APIs generate multiple files (e.g., multiple images):Automatic Downloads with generate()
The SDK’s generate() function can download files automatically:
File Specifications
Supported File Formats
Video
mp4, m4v, mov, webm
Image
png, jpg, jpeg, webp, avif, jp2, tiff, bmp
Audio
mp3, mpeg, wav, aac, aiff, flac
gif extension is only supported by face swap API’s video_file_path field.File Size Limits
Different subscription tiers have different upload limits:| Tier | Maximum Upload Size |
|---|---|
| Free | 200 MB |
| Creator | 1 GB |
| Pro | 2 GB |
| Business | 3 GB |
Upgrade for Larger Files: If you need to process files larger than your current limit, upgrade your subscription tier.
Retention & Storage Policies
Uploaded Files (Inputs)
7-Day Retention: Files uploaded to Magic Hour storage are automatically deleted after 7 days.file_path for multiple API calls to avoid duplicate uploads.
Generated Files (Outputs)
Permanent Storage: Generated files are stored indefinitely in Magic Hour cloud storage. Download URL Expiration: Download URLs expire after 24 hours for security, but you can request fresh URLs anytime. Web Dashboard: All generated content appears in your magichour.ai/my-library dashboard.Getting Fresh Download URLs
If your download URL expired, request a new one:Best Practices
For Uploads
✅ Do:- Validate file formats before uploading
- Use the SDK upload helpers when available
- Reuse uploaded files within the 7-day window
- Compress large files to save upload time
- Upload the same file repeatedly (reuse the
file_path) - Exceed your tier’s file size limits
- Rely on uploaded files after 7 days
For Downloads
✅ Do:- Download files immediately after job completion
- Implement retry logic with exponential backoff
- Stream large files to avoid memory issues
- Store files in your own storage for permanent access
- Verify file integrity after download
- Rely on download URLs after 24 hours
- Download the same file multiple times unnecessarily
- Ignore download errors without retry logic
Troubleshooting
Upload Issues
“Invalid file format” error:- Check that your file extension is in the supported list
- Verify the file isn’t corrupted
- Ensure the file type matches the extension
- Check your subscription tier’s upload limit
- Compress the file or upgrade your subscription
- Split large videos into smaller segments
- Check your internet connection
- Try uploading during off-peak hours
- Consider using a CDN for faster uploads
Download Issues
“URL expired” error:- Request fresh download URLs using the GET endpoint
- Download files within 24 hours of job completion
- Store files in your own storage for permanent access
- Implement retry logic with exponential backoff
- Verify file integrity (check file size matches)
- Use streaming downloads for large files
- Verify the job ID is correct
- Ensure the job status is “complete”
- Check that the project hasn’t been deleted
Next Steps
First Integration
Build your first integration step-by-step
Development & Testing
Test without using credits
API Reference
Complete upload API documentation
Webhooks
Set up webhooks for production apps
Questions? Join our Discord community or email [email protected]