Adding API to Your App
Learn how to fully integrate APIs into your own application.
Following the Quick Start Guide, you now can call any APIs to create an image or video.
Quick start recap
- 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.
- Install the SDK in your project
- 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:
Status | Description |
---|---|
draft | Not currently used |
queued | The job is queued and waiting for a server |
rendering | Rendering is in progress |
complete | Rendering completed |
error | An error occurred during rendering |
canceled | Video render is canceled |
Error details
When status
is error
, you can get details on why the failure happened. For example,
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:
- configure a webhook in Developer Hub, and pick the events you want to be notified.
- create an API in your application to listen to events with logic for each event you’re listening too.
- 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.
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.
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.
Then, use any http package to download the file. Below are some sample code:
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:
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
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.
If you are not using SDKs, simply replace the URL to use the mock server.
Canceling render in the web app
You have the option to cancel a video render with a full frames refund.
Visit Video Details Page
You can access the video details page using the URL
Click Cancel Render
Confirm cancel
Cancel successful
Was this page helpful?