Following the Quick Start Guide, you now can call any APIs to create an image or video.

​
Quick start recap

  1. Visit Developer Hub to create an API key.
Do not expose your API key in client-side code. Keep it secure on your server to prevent unauthorized usage and potential abuse.
  1. Install the SDK in your project
pip install magic_hour
  1. Using the methods built into the SDK to create a video or image.

​
Input files

The easiest way to get started is passing a URL as the input. When calling our APIs, you can simply pass the URL as the video_file_path, image_file_path, or audio_file_path. 
{
  "assets": {
    "video_file_file": "https://cdn.yourwebsite.com/video.mp4"
  }
}

Input Files

Get more details about managing input files, uploading files to Magic Hour storage, and more.

​
Render status

Videos and images can be one of the following statuses:
StatusDescription
draftNot currently used
queuedThe job is queued and waiting for a server
renderingRendering is in progress
completeRendering completed
errorAn error occurred during rendering
canceledVideo render is canceled

​
Error details

When status is error, you can get details on why the failure happened. For example, 
{
    ...
    "error": {
        "code": "no_source_face",
        "message": "Please use an image with a detectable face"
    }
}
Occasionally, you may see "code": "unknown_error". Please reach to our team support@magichour.ai so we can investigate.

​
Checking rendering status

The render time depends on a variety of factors. For images, you should have your result within one minute. For videos, render time is generally longer, depending on the length of the output video, but most of the time, you should have your result within a few minutes. There are two ways to check whether generation completed:
  • Webhook notification
  • Polling the details API

​
Webhook notification

This is the recommended way to receive status change events for modes with longer rendering times (e.g. video modes); however, it does require extra effort to setup. At a high level, to implement webhook notification:
  1. configure a webhook in Developer Hub, and pick the events you want to be notified.
  2. create an API in your application to listen to events with logic for each event you’re listening too.
  3. add additional logic in your application when status changes.
Polling is a valid solution if you mainly render images or very short videos.
For videos with long render time, setting up an API to listen for event will be more efficient than constantly calling the video details API.

Webhook Overview

Learn how to implement webhook with Magic Hour

​
Polling the details API

To check the status of the render, you can call the following APIs Then check the status field in set intervals. 
create_res = client.v1.image_to_video.create(...)
project_id = create_res.id
while True:
    res = client.v1.video_projects.get(id=project_id)
    if res.status == 'complete':
        print("render complete")
        break
    elif res.status == "error":
        print("render failed")
        break
    else:
        print("render in progress")
        time.sleep(3)

​
Downloading result

Once status is complete, the response for the image/video details will populate the downloads key. Note this is an array since some modes may have more than one output. 
- "downloads": [],
+ "downloads": [
+     {
+         "url": "https://video.magichour.ai/id/output.mp4?auth-token=1234",
+         "expires_at": "2024-10-19T05:16:19.027Z"
+     }
+ ],
Then, use any http package to download the file. Below are some sample code: 
import requests

with open("output.mp4", "wb") as file:
  response = requests.get("https://video.magichour.ai/id/output.mp4?auth-token=1234")
  file.write(response.content)

​
Deleting generated files

Currently, the generated content are kept in our storage without expiration. If you want to remove the generated files, you can call the following endpoints:
This action is not reversible, please be sure before deleting.
client.v1.video_projects.delete(
  id="cuid",
)

​
Reducing credit usage during integration

While building out the integration, you’d want to avoid actually rendering the video/image since you will be charged on any completed render. There are a few ways to reduce your usage.

​
Using mock API server

The mock server only responds with sample data and does not actually create any records.
To use the mock server, simply pass the environment parameter when initializing the client. 
from magic_hour import Client
from magic_hour.environment import Environment

client = Client(
    token="API_TOKEN", environment=Environment.MOCK_SERVER,
)
If you are not using SDKs, simply replace the URL to use the mock server.
- https://api.magichour.ai/v1/image-to-video
+ https://api.sideko.dev/v1/mock/magichour/magic-hour/latest/v1/image-to-video

​
Canceling render in the web app

You have the option to cancel a video render with a full credit refund.
Image rendering cannot be cancelled
1

Visit Video Details Page

You can access the video details page using the URL
https://magichour.ai/dashboard/videos/:id
2

Click Cancel Render

Cancel Render Button
3

Confirm cancel

Confirm Cancel Button
4

Cancel successful

Confirm Cancel Button
Cancelling is not currently supported via API