Adding API to Your App

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.

2. Install the SDK in your project

pip install magic_hour

3. Using the methods built into the SDK to create a video or image.

​

Render status

Videos and images can be one of the following statuses:

​

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.

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.

​

Polling the details API

To check the status of the render, you can call the following APIs

• GET /v1/video-projects/:id
• GET /v1/image-projects/:id

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:

• DELETE /v1/video-projects/:id
• DELETE /v1/image-projects/:id

client.v1.video_projects.delete(
  id="cuid",
)

​

Reducing frame 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

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,
)

- 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 frames refund.