Magic Hour API

https://docs.magichour.ai
Admin
Magic Hour API is a REST API for AI-powered video, image, and audio generation featuring tools for...
Tokens:210,508
Snippets:1,410
Trust Score:9.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install ngrok

Source: https://docs.magichour.ai/integration/webhook/overview

Use these commands to install ngrok on your local machine.

```bash
# macOS
brew install ngrok

# Windows/Linux - download from https://ngrok.com/download
```

--------------------------------

### Image to Video Tool Section Usage Example

Source: https://docs.magichour.ai/tools/video/image-to-video

This example demonstrates how to use the ToolSection component to display the Image to Video tool, including its title, product slug, API slug, type, and example video outputs.

```javascript
<ToolSection
  title="Image to Video"
  productSlug="image-to-video"
  apiSlug="image-to-video"
  type="video"
  outputs={[
  {
    src: "https://d28dkohlqf5vwj.cloudfront.net/products/image-to-video/examples/cinematic-2.mp4",
  },
  {
    src: "https://d28dkohlqf5vwj.cloudfront.net/products/image-to-video/examples/halo.mp4",
  },
]}
/>

```

--------------------------------

### Start Webhook Server

Source: https://docs.magichour.ai/integration/webhook/overview

Commands to launch your local server for receiving webhooks.

```bash
python webhook_server.py
# or
uvicorn main:app --host 0.0.0.0 --port 8000
```

```bash
node webhook_server.js
```

--------------------------------

### Instantiate Face Swap Photo Tool Section

Source: https://docs.magichour.ai/tools/image/face-swap-photo

Example of how to use the ToolSection component for the Face Swap Photo feature. This setup specifies the type as 'image' and provides example image sources.

```javascript
<ToolSection
  title="Face Swap Photo"
  productSlug="face-swap?mode=photo"
  apiSlug="face-swap-photo"
  type="image"
  outputs={[
  {
    src: "/get-started/images/faceswapphotoexample1.jpg",
  },
  {
    src: "/get-started/images/mr-bean-swap.jpeg",
  },
]} 
/>
```

--------------------------------

### Install Notebook Dependencies

Source: https://docs.magichour.ai/integration/webhook/overview

Install required packages for running webhook servers in Colab or Jupyter environments.

```python
!pip install fastapi uvicorn nest-asyncio pyngrok
```

--------------------------------

### Install Python Dependencies

Source: https://docs.magichour.ai/integration/first-integration

Install the Magic Hour Python SDK, python-dotenv for managing environment variables, and the requests library.

```bash
pip install magic-hour python-dotenv requests
```

--------------------------------

### Start Webhook Server

Source: https://docs.magichour.ai/integration/webhook/create-handler

Initializes the server listener on the specified port.

```javascript
const port = process.env.PORT || 8000;
  app.listen(port, () => {
    logger.info(`Webhook server running on port ${port}`);
  });
```

--------------------------------

### Install Magic Hour SDK

Source: https://docs.magichour.ai/get-started/quick-start

Install the official Magic Hour SDK for your chosen programming language.

```sh
pip install magic_hour
```

```sh
npm install magic-hour
```

```sh
go get -u github.com/magichourhq/magic-hour-go
```

```sh
cargo add magic_hour
```

--------------------------------

### Example Animation Usage

Source: https://docs.magichour.ai/tools/video/animation

Demonstrates how to use the ToolSection component to display animation examples. It configures the component with a title, product slug, API slug, type set to 'video', and an array of video output sources.

```javascript
<ToolSection
  title="Animation"
  productSlug="animation"
  apiSlug="animation"
  type="video"
  outputs={[
  {
    src: "https://videos.magichour.ai/clttnhtz5000bqp36hd2xrent/video.mp4",
  },
  {
    src: "https://videos.magichour.ai/cltweykuq003lrck44hd2e5ty/video.mp4",
  },
]} 
/>

```

--------------------------------

### AI Image Editor Usage Example

Source: https://docs.magichour.ai/tools/image/image-editor

This example demonstrates how to use the ToolSection component to display the AI Image Editor with sample outputs. Ensure the 'outputs' array contains valid image sources.

```javascript
<ToolSection
  title="AI Image Editor"
  productSlug="ai-image-editor"
  apiSlug="ai-image-editor"
  type="image"
  outputs={[
  {
    src: "/get-started/images/aiimageeditorexample1.jpg",
  },
  {
    src: "/get-started/images/aiimageeditorexample2.png",
  },
]} 
/>
```

--------------------------------

### Test Webhook Handler Locally

Source: https://docs.magichour.ai/integration/webhook/create-handler

Commands to start the server and simulate incoming webhook events.

```bash
# Start your server
uvicorn main:app --reload --port 8000

# In another terminal, send test event
curl -X POST http://localhost:8000/webhook \
  -H "Content-Type: application/json" \
  -d '{
      "type": "video.completed",
      "payload": {
        "id": "test-job-123",
        "status": "complete",
        "downloads": [
          {
            "url": "https://example.com/video.mp4",
            "expires_at": "2024-12-01T12:00:00Z"
          }
        ]
      }
    }'
```

```bash
# Start your server
node server.js

# In another terminal, send test event
curl -X POST http://localhost:8000/webhook \
  -H "Content-Type: application/json" \
  -d '{
      "type": "image.completed",
      "payload": {
        "id": "test-job-456",
        "status": "complete",
        "downloads": [
          {
            "url": "https://example.com/image.png",
            "expires_at": "2024-12-01T12:00:00Z"
          }
        ]
      }
    }'
```

--------------------------------

### Configure Load Balancing

Source: https://docs.magichour.ai/integration/webhook/create-handler

Example configuration for scaling the webhook handler using Docker Compose.

```yaml
# docker-compose.yml
services:
  webhook-handler:
    image: your-webhook-app
    replicas: 3
    ports:
      - "8000-8002:8000"
```

--------------------------------

### Implement Text to Video Tool Section

Source: https://docs.magichour.ai/tools/video/text-to-video

Example usage of the ToolSection component for a video generation product.

```jsx
<ToolSection
  title="Text to Video"
  productSlug="text-to-video"
  apiSlug="text-to-video"
  type="video"
  outputs={[
  {
    src: "https://d28dkohlqf5vwj.cloudfront.net/products/text-to-video/examples/underwater-world.mp4",
  },
  {
    src: "https://d28dkohlqf5vwj.cloudfront.net/products/text-to-video/examples/slow-motion-leopard-leap.mp4",
  },
]}
/>
```

--------------------------------

### Set Up Node.js Project Structure

Source: https://docs.magichour.ai/integration/first-integration

Initializes a new Node.js project, creates necessary directories for outputs and assets, and sets up the main script and environment file.

```bash
# Create project directory
mkdir magic-hour-tutorial
cd magic-hour-tutorial

# Initialize npm project
npm init -y

# Create necessary directories
mkdir outputs
mkdir assets

# Create main script file
touch index.js

# Create environment file for your API key
touch .env
```

--------------------------------

### Prototyping with `generate()`

Source: https://docs.magichour.ai/integration/overview

Start with the `generate()` function for prototyping. This example demonstrates a basic call to generate a square image.

```python
result = client.v1.ai_image_generator.generate(
    image_count=1,
    orientation="square",
    style={"prompt": "Test image", "tool": "ai-anime-generator"}
)
```

--------------------------------

### Run Go Project

Source: https://docs.magichour.ai/get-started/quick-start

Navigate to your project directory and run the main Go program.

```bash
# Make sure you're in your project directory
cd magic-hour-quickstart

# Run the program
go run main.go
```

--------------------------------

### Initialize Project Directory

Source: https://docs.magichour.ai/get-started/quick-start

Commands to create a project directory and initialize the environment for various programming languages.

```bash
# Create and navigate to project directory
mkdir magic-hour-quickstart
cd magic-hour-quickstart

# Create outputs directory (prevents FileNotFoundError)
mkdir outputs

# Create your Python file
touch main.py
```

```bash
# Create and navigate to project directory
mkdir magic-hour-quickstart
cd magic-hour-quickstart

# Initialize npm project
npm init -y

# Create outputs directory (prevents FileNotFoundError)
mkdir outputs

# Create your JavaScript file
touch main.js
```

```bash
# Create and navigate to project directory
mkdir magic-hour-quickstart
cd magic-hour-quickstart

# Initialize Go module
go mod init magic-hour-quickstart

# Create your Go file
touch main.go
```

```bash
# Create new Rust project
cargo new magic-hour-quickstart
cd magic-hour-quickstart
```

--------------------------------

### Get Face Detection by ID (cURL)

Source: https://docs.magichour.ai/api-reference/files/get-face-detection-details

A command-line example using cURL to request face detection data. Remember to replace `<token>` with your actual API token.

```curl
curl --request GET \
     --url https://api.magichour.ai/v1/face-detection/id \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>'
```

--------------------------------

### Get Face Detection by ID (Rust)

Source: https://docs.magichour.ai/api-reference/files/get-face-detection-details

Retrieve face detection information in Rust. This example shows how to initialize the client with bearer authentication and make the API call.

```rust
let client = magic_hour::Client::default()
    .with_bearer_auth(&std::env::var("API_TOKEN").unwrap());
let res = client
    .v1()
    .face_detection()
    .get(magic_hour::resources::v1::face_detection::GetRequest {
        id: "uuid-example".to_string(),
    })
    .await;
```

--------------------------------

### Get Face Detection by ID (Java)

Source: https://docs.magichour.ai/api-reference/files/get-face-detection-details

Example of fetching face detection data using Java with the Unirest library. Ensure your API token is correctly formatted in the authorization header.

```java
HttpResponse<String> response = 
    Unirest.get("https://api.magichour.ai/v1/face-detection/id")
      .header("accept", "application/json")
      .header("authorization", "Bearer <token>")
      .asString();
```

--------------------------------

### Set Up Python Project Structure

Source: https://docs.magichour.ai/integration/first-integration

Create the necessary directories and files for your Magic Hour integration project. This includes the main script, environment file, and output/asset directories.

```bash
mkdir magic-hour-tutorial
cd magic-hour-tutorial

mkdir outputs
mkdir assets

touch main.py

touch .env
```

--------------------------------

### Swap Faces in Video with Python SDK

Source: https://docs.magichour.ai/get-started/quick-start

Use the Python SDK to swap faces in a video. This example specifies the source assets, start and end times for the swap, and enables waiting for completion and downloading outputs.

```python
from magic_hour import Client
import time
import os
import urllib.request

# Use environment variable for security
client = Client(token=os.getenv("MAGIC_HOUR_API_KEY"))

result = client.v1.face_swap.generate(
    name="Swap Tom Cruise into Iron Man scene",
    assets={
        "image_file_path": "https://videos.magichour.ai/api-assets/sample/tom-cruise.png",
        "video_file_path": "https://videos.magichour.ai/api-assets/sample/iron-man.mp4",
        "video_source": "file",
    },
    start_seconds=2.3,
    end_seconds=8.5,
    wait_for_completion=True, # wait for the render to complete
    download_outputs=True # download the outputs to local disk
)
```

--------------------------------

### Upload File using Go SDK

Source: https://docs.magichour.ai/integration/input-files

This Go example demonstrates requesting upload URLs for assets, uploading the file via a PUT request, and then using the returned file path. Ensure the Go SDK is up-to-date.

```go
package main

import (
	"fmt"
	"net/http"
	"os"

	sdk "github.com/magichourhq/magic-hour-go/client"
	"github.com/magichourhq/magic-hour-go/resources/v1/files/upload_urls"
	"github.com/magichourhq/magic-hour-go/types"
)

func main() {
	client := sdk.NewClient(sdk.WithBearerAuth(os.Getenv("API_KEY"))) // change to your API key

	response, err := client.V1.Files.UploadUrls.Create(upload_urls.CreateRequest{
		Items: []types.PostV1FilesUploadUrlsBodyItemsItem{
			types.PostV1FilesUploadUrlsBodyItemsItem{ Extension: "mp4", Type: types.PostV1FilesUploadUrlsBodyItemsItemTypeEnumVideo },
			// if you have multiple files to upload, you can request multiple upload urls
			// the order of the response will be in the same order as the request
			// types.PostV1FilesUploadUrlsBodyItemsItem{ Extension: "mp3", Type: types.PostV1FilesUploadUrlsBodyItemsItemTypeEnumAudio },
			// types.PostV1FilesUploadUrlsBodyItemsItem{ Extension: "png", Type: types.PostV1FilesUploadUrlsBodyItemsItemTypeEnumImage },
		},
	})

	if err != nil {
		fmt.Println(err)
		return
	}

	local_path := "/path/to/file/video.mp4" // change to your local file path
	file, err := os.Open(local_path)
	if err != nil {
		fmt.Println(err)
	}
	defer file.Close()

	req, err := http.NewRequest("PUT", response.Items[0].UploadUrl, file)
	if err != nil {
		fmt.Println(err)
	}

	fileClient := &http.Client{}
	_, err = fileClient.Do(req)
	if err != nil {
		fmt.Println(err)
	}

	file_path := response.Items[0].FilePath

	fmt.Printf("file uploaded successfully to %s\n", file_path)

	// now you can use `file_path` in your API calls for
	// `video_file_path`, `image_file_path`, or `audio_file_path`
}

```

--------------------------------

### Python Webhook Handler (FastAPI)

Source: https://docs.magichour.ai/integration/webhook/overview

Implement a webhook handler using FastAPI to receive and process events. This example logs received events and handles different event types like video and image processing statuses. Ensure FastAPI and Uvicorn are installed.

```python
from fastapi import FastAPI, Request
import json

app = FastAPI()

@app.post("/webhook")
async def webhook_handler(request: Request):
    # Get the event data
    event = await request.json()

    # Log the event for testing
    print(f"Received event: {event['type']}")
    print(f"Payload: {json.dumps(event['payload'], indent=2)}")

    # Handle different event types
    match event['type']:
        case 'video.started':
            print('🎬 Video processing started')
        case 'video.completed':
            print('✅ Video processing completed')
            # Download URL available in event['payload']['downloads']
        case 'video.errored':
            print('❌ Video processing failed')
        case 'image.completed':
            print('🖼️ Image processing completed')
        case 'image.errored':
            print('❌ Image processing failed')

    # Always return success
    return {"success": True}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

```

--------------------------------

### Retrieve a video project

Source: https://docs.magichour.ai/api-reference/video-projects/get-video-details

Use these examples to fetch a specific video project by its ID. Ensure the API_TOKEN environment variable is set before execution.

```python
from magic_hour import Client
from os import getenv

client = Client(token=getenv("API_TOKEN"))
res = client.v1.video_projects.get(id="cuid-example")
```

```javascript
import { Client } from "magic-hour";


const client = new Client({ token: process.env["API_TOKEN"]!! });

const res = await client.v1.videoProjects.get({ id: "cuid-example"
});
```

```go
package main

import (
	os "os"

	sdk "github.com/magichourhq/magic-hour-go/client"
	video_projects "github.com/magichourhq/magic-hour-go/resources/v1/video_projects"
)

func main() {
	client := sdk.NewClient(
		sdk.WithBearerAuth(os.Getenv("API_TOKEN")),
	)
	res, err := client.V1.VideoProjects.Get(video_projects.GetRequest{
		Id: "cuid-example",
	})
}
```

```rust
let client = magic_hour::Client::default()
    .with_bearer_auth(&std::env::var("API_TOKEN").unwrap());
let res = client
    .v1()
    .video_projects()
    .get(magic_hour::resources::v1::video_projects::GetRequest {
        id: "cuid-example".to_string(),
    })
    .await;
```

```curl
curl --request GET \
     --url https://api.magichour.ai/v1/video-projects/id \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>'
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.magichour.ai/v1/video-projects/id",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "accept: application/json",
    "authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```java
HttpResponse<String> response =
Unirest.get("https://api.magichour.ai/v1/video-projects/id")
  .header("accept", "application/json")
  .header("authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### Generate Image with AI Clothes Changer (Python)

Source: https://docs.magichour.ai/api-reference/image-projects/ai-clothes-changer

Use this Python snippet to generate an image using the AI Clothes Changer. Ensure you have the 'magic-hour' library installed and your API token set as an environment variable. This example waits for completion and downloads the output.

```python
from magic_hour import Client
from os import getenv

client = Client(token=getenv("API_TOKEN"))
res = client.v1.ai_clothes_changer.generate(
    assets={
        "garment_file_path": "/path/to/outfit.png",
        "garment_type": "upper_body",
        "person_file_path": "/path/to/model.png",
    },
    name="Clothes Changer image",
    wait_for_completion=True,
    download_outputs=True,
    download_directory=".",
)
```

--------------------------------

### Configure Mock Server

Source: https://docs.magichour.ai/integration/adding-api-to-your-app

Initialize the client with the mock server environment to perform testing without consuming credits.

```python
from magic_hour import Client
from magic_hour.environment import Environment

# Use mock server for development
client = Client(
    token="API_TOKEN",
    environment=Environment.MOCK_SERVER
)

# All API calls will return mock data
result = client.v1.face_swap.create(...)  # No credits charged
```

```typescript
import Client, { Environment } from "magic-hour";

// Use mock server for development
const client = new Client({
  token: "API_TOKEN",
  environment: Environment.MockServer,
});

// All API calls will return mock data
const result = await client.v1.faceSwap.create({...}); // No credits charged
```

--------------------------------

### Run Production Environment

Source: https://docs.magichour.ai/integration/development-and-testing

Use this command for production deployment, ensuring the application connects to the production API using the provided production API key.

```bash
ENV=production python main.py  # Uses production API key
```

--------------------------------

### Generate AI Meme with Go

Source: https://docs.magichour.ai/api-reference/image-projects/ai-meme-generator

The Go client example demonstrates meme generation. It uses environment variables for authentication and allows configuration of search, template, and topic. Ensure the necessary SDK components are imported.

```go
package main

import (
	os "os"
	sdk "github.com/magichourhq/magic-hour-go/client"
	nullable "github.com/magichourhq/magic-hour-go/nullable"
	ai_meme_generator "github.com/magichourhq/magic-hour-go/resources/v1/ai_meme_generator"
	types "github.com/magichourhq/magic-hour-go/types"
)

func main() {
	client := sdk.NewClient(
		sdk.WithBearerAuth(os.Getenv("API_TOKEN")),
	)
	res, err := client.V1.AiMemeGenerator.Create(ai_meme_generator.CreateRequest{
		Name: nullable.NewValue("My Funny Meme"),
		Style: types.V1AiMemeGeneratorCreateBodyStyle{
			SearchWeb: nullable.NewValue(false),
			Template:  types.V1AiMemeGeneratorCreateBodyStyleTemplateEnumDrakeHotlineBling,
			Topic:     "When the code finally works",
		},
	})
}
```

--------------------------------

### Install Node.js Dependencies

Source: https://docs.magichour.ai/integration/first-integration

Installs the Magic Hour Node SDK and the dotenv package for managing environment variables.

```bash
npm install magic-hour dotenv
```

--------------------------------

### Create a Face Swap Job with Python SDK

Source: https://docs.magichour.ai/integration/adding-api-to-your-app

Demonstrates initializing the client and submitting a face swap request using the Python SDK.

```python
from magic_hour import Client
import os

client = Client(token=os.getenv("MAGIC_HOUR_API_KEY"))

# 1. Create job
print("Creating face swap job...")
create_res = client.v1.face_swap.create(
    name="My face swap",
    assets={
        "image_file_path": "https://upload.wikimedia.org/wikipedia/commons/e/ec/Chris_Cassidy_-_Official_NASA_Astronaut_Portrait_in_EMU_%28cropped%29.jpg",
        "video_file_path": "https://svs.gsfc.nasa.gov/vis/a010000/a014300/a014327/john_bolten_no_graphics.mp4",
        "video_source": "file"
    },
    start_seconds=0.0,
    end_seconds=10.0,
)
print(f"Job created with ID: {create_res.id}, status: {create_res.status}")
```

--------------------------------

### Retrieve Audio Project Details

Source: https://docs.magichour.ai/api-reference/audio-projects/get-audio-details

Examples for fetching a specific audio project by ID across multiple programming languages.

```python
from magic_hour import Client
from os import getenv

client = Client(token=getenv("API_TOKEN"))
res = client.v1.audio_projects.get(id="cuid-example")
```

```javascript
import { Client } from "magic-hour";


const client = new Client({ token: process.env["API_TOKEN"]!! });

const res = await client.v1.audioProjects.get({ id: "cuid-example"
});
```

```go
package main

import (
	os "os"

	sdk "github.com/magichourhq/magic-hour-go/client"
	audio_projects "github.com/magichourhq/magic-hour-go/resources/v1/audio_projects"
)

func main() {
	client := sdk.NewClient(
		sdk.WithBearerAuth(os.Getenv("API_TOKEN")),
	)
	res, err := client.V1.AudioProjects.Get(audio_projects.GetRequest{
		Id: "cuid-example",
	})
}
```

```rust
let client = magic_hour::Client::default()
    .with_bearer_auth(&std::env::var("API_TOKEN").unwrap());
let res = client
    .v1()
    .audio_projects()
    .get(magic_hour::resources::v1::audio_projects::GetRequest {
        id: "cuid-example".to_string(),
    })
    .await;
```

```curl
curl --request GET \
     --url https://api.magichour.ai/v1/audio-projects/id \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>'
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
```

--------------------------------

### Example Signed Payload

Source: https://docs.magichour.ai/webhook-reference/audio-events/audio-errored

This example demonstrates the format of a signed payload used for webhook verification. It concatenates the timestamp, a dot, and the stringified JSON payload.

```txt
1729314984.{"type":"video.started","object":{"id":"cm2fphlo3000dmfhu8m0dh63z","name":"Video","status":"rendering","type":"TEXT_TO_VIDEO","created_at":"2024-10-19T05:16:19.027Z","width":720,"height":1280,"total_frame_cost":300,"start_seconds":0,"end_seconds":5,"fps":30,"download":null}}
```

--------------------------------

### Example Webhook Event Payload

Source: https://docs.magichour.ai/integration/webhook/create-webhook

This is an example of a completed image generation webhook event payload. It includes the job ID and download URLs for the generated images.

```json
{
  "type": "image.completed",
  "payload": {
    "id": "clx7uu86w0a5qp55yxz315r6r",
    "status": "complete",
    "downloads": [
      {
        "url": "https://images.magichour.ai/id/output.png",
        "expires_at": "2024-10-19T05:16:19.027Z"
      }
    ]
  }
}
```

--------------------------------

### Run Development Environment

Source: https://docs.magichour.ai/integration/development-and-testing

Use this command to run the application in development mode, utilizing a mock server for local testing and integration logic building.

```bash
ENV=development python main.py  # Uses mock server
```

--------------------------------

### API Error Response Structure

Source: https://docs.magichour.ai/changelog/2024

Use this JSON structure to interpret errors returned by the GET /v1/image-projects/:id and GET /v1/video-projects/:id APIs. Contact support if you encounter 'unknown_error'.

```json
{
  "error": {
    "code": "<error code>",
    "message": "<explanation of error>"
  }
}
```

--------------------------------

### Run Node.js Project

Source: https://docs.magichour.ai/get-started/quick-start

Navigate to your project directory and execute the main Node.js script.

```bash
# Make sure you're in your project directory
cd magic-hour-quickstart

# Run the script
node main.js
```

--------------------------------

### Audio Completed Webhook Event Example

Source: https://docs.magichour.ai/webhook-reference/audio-events/audio-completed

This example shows the expected structure of an `audio.completed` event payload that your webhook endpoint will receive. It includes event type, audio ID, name, and status.

```yaml
post /audio.completed
openapi: 3.1.0
info:
  title: Magic Hour Webhook
  version: beta
  description: >-
    ## Introduction 


    Configuring a webhook allow Magic Hour to notify you whenever an event
    occurs in your account. To get started, create a webhook
    [here](https://magichour.ai/developer).


    API documentation can be found
    [here](https://docs.magichour.ai/webhook-reference).


    If you have any questions, please reach out to us via
    [discord](https://discord.gg/JX5rgsZaJp).


    ## Securing your endpoint


    Events includes two headers to help verify the authenticity of the payload. 

    - `magic-hour-event-signature` - A signatured created with the webhook
    secret key and a signed_payload, using HMAC with SHA-256

    - `magic-hour-event-timestamp` - Time in seconds since the epoch. Use this
    value to check whether the request is within a reasonable window of the
    current time. Usually less than 5 minutes.


    Using the header to verify the request ensures that the request is
    authentic. However, the header verification is optional. 


    To compute the signature to verify:

    1. create a `signed_payload` by concatenating:
          - the timestamp as a string
          - the character `.`
          - the payload JSON (stringified)

    For example,

    ```txt

    1729314984.{"type":"video.started","object":{"id":"cm2fphlo3000dmfhu8m0dh63z","name":"Video","status":"rendering","type":"TEXT_TO_VIDEO","created_at":"2024-10-19T05:16:19.027Z","width":720,"height":1280,"total_frame_cost":300,"start_seconds":0,"end_seconds":5,"fps":30,"download":null}}

    ```


    2. Compute an HMAC with the SHA256 Hash function. Using the webhook secret
    as the key, and use the `signed_payload` as the message.

    3. Compare the computed hash value against the header and verify that the
    timestamp is within a reasonable window.


    ## Retry behavior


    If event delivery failed, meaning the response from your endpoint does not
    have a status code of `2XX`, we will retry delivery up to 24 hours with
    exponential backoff. After 24 hours, the event will be marked as failed and
    will not be retried.


    In the case where the webhook is disabled, pending events for the webhook
    will be skipped. Please note that these events will also be marked as failed
    after 24 hours.
  termsOfService: https://magichour.ai/terms-of-service
servers:
  - url: https://your-webhook.com
security: []
tags:
  - name: Image Events
    description: Events related to image
  - name: Video Events
    description: Events related to video
  - name: Audio Events
    description: Events related to audio
paths:
  /audio.completed:
    post:
      tags:
        - Audio Events
      summary: Audio Completed
      description: >-
        The request example illustrates what your webhook endpoint should
        expect.
      operationId: audio.completed
      parameters:
        - name: magic-hour-event-signature
          in: header
          required: true
          schema:
            type: string
            description: >-
              A signatured created with the webhook secret key and a
              signed_payload, using HMAC with SHA-256
            example: 3e771b50c...
        - name: magic-hour-event-timestamp
          in: header
          required: true
          schema:
            type: string
            description: >-
              Time in seconds since the epoch. Use this value to check whether
              the request is within a reasonable window of the current time.
              Usually less than 5 minutes.
            example: '1730742038'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - audio.completed
                payload:
                  type: object
                  properties:
                    id:
                      type: string
                      example: cuid-example
                      description: >-
                        Unique ID of the audio. Use it with the [Get audio
                        Project
                        API](https://docs.magichour.ai/api-reference/audio-projects/get-audio-details)
                        to fetch status and downloads.
                    name:
                      type: string
                      nullable: true
                      description: The name of the audio.
                      example: Example Name
                    status:
                      type: string
                      enum:
                        - draft
                        - queued
                        - rendering
                        - complete
                        - error
                        - canceled
                      description: The status of the audio.

```

--------------------------------

### Generate AI Images via SDK

Source: https://docs.magichour.ai/api-reference/image-projects/ai-image-generator

Use these examples to initialize the client and trigger an AI image generation task. Ensure the API_TOKEN environment variable is set before execution.

```python
from magic_hour import Client
from os import getenv

client = Client(token=getenv("API_TOKEN"))
res = client.v1.ai_image_generator.generate(
    image_count=1,
    style={
        "prompt": "Cool image",
        "tool": "ai-anime-generator",
    },
    aspect_ratio="1:1",
    model="default",
    name="My Ai Image image",
    resolution="auto",
    wait_for_completion=True,
    download_outputs=True,
    download_directory="."
)
```

```javascript
import { Client } from "magic-hour";

const client = new Client({ token: process.env["API_TOKEN"]!! });
const res = await client.v1.aiImageGenerator.generate(
  {
    aspectRatio: "1:1",
    imageCount: 1,
    model: "default",
    name: "My Ai Image image",
    resolution: "auto",
    style: { prompt: "Cool image", tool: "ai-anime-generator" },
  },
  {
    waitForCompletion: true,
    downloadOutputs: true,
    downloadDirectory: ".",
  },
);
```

```go
package main

import (
	os "os"

	sdk "github.com/magichourhq/magic-hour-go/client"
	nullable "github.com/magichourhq/magic-hour-go/nullable"
	ai_image_generator "github.com/magichourhq/magic-hour-go/resources/v1/ai_image_generator"
	types "github.com/magichourhq/magic-hour-go/types"
)

func main() {
	client := sdk.NewClient(
		sdk.WithBearerAuth(os.Getenv("API_TOKEN")),
	)
	res, err := client.V1.AiImageGenerator.Create(ai_image_generator.CreateRequest{
		AspectRatio: nullable.NewValue(types.V1AiImageGeneratorCreateBodyAspectRatioEnum11),
		ImageCount:  1,
		Model:       nullable.NewValue(types.V1AiImageGeneratorCreateBodyModelEnumDefault),
		Name:        nullable.NewValue("My Ai Image image"),
		Resolution:  nullable.NewValue(types.V1AiImageGeneratorCreateBodyResolutionEnumAuto),
		Style: types.V1AiImageGeneratorCreateBodyStyle{
			Prompt: "Cool image",
			Tool:   nullable.NewValue(types.V1AiImageGeneratorCreateBodyStyleToolEnumAiAnimeGenerator),
		},
	})
}
```

```rust
let client = magic_hour::Client::default()
    .with_bearer_auth(&std::env::var("API_TOKEN").unwrap());
let res = client
    .v1()
    .ai_image_generator()
    .create(magic_hour::resources::v1::ai_image_generator::CreateRequest {
        aspect_ratio: Some(
            magic_hour::models::V1AiImageGeneratorCreateBodyAspectRatioEnum::Enum11,
        ),
        image_count: 1,
        model: Some(
            magic_hour::models::V1AiImageGeneratorCreateBodyModelEnum::Default,
        ),
        name: Some("My Ai Image image".to_string()),
        resolution: Some(
```

--------------------------------

### Example Usage of ToolSection for Photo Colorizer

Source: https://docs.magichour.ai/tools/image/photo-colorizer

Demonstrates how to use the ToolSection component to display information and examples for the Photo Colorizer tool. Ensure the 'outputs' prop is an array of objects with 'src' properties.

```javascript
<ToolSection
  title="Photo Colorizer"
  productSlug="photo-colorizer"
  apiSlug="photo-colorizer"
  type="image"
  outputs={[
  {
    src: "/get-started/images/photocolorizerexample1.gif",
  },
  {
    src: "/get-started/images/photcolorizerexample2.jpg",
  },
]} 
/>
```

--------------------------------

### Initialize Mock Server Client

Source: https://docs.magichour.ai/integration/development-and-testing

Configure the Magic Hour client to use the mock server, which returns sample data without consuming credits or processing jobs.

```python
from magic_hour import Client
from magic_hour.environment import Environment

# Use mock server for development
client = Client(
    token="YOUR_API_KEY",  # Can use any value for mock mode
    environment=Environment.MOCK_SERVER
)

# All API calls return mock data instantly
result = client.v1.ai_image_generator.create(
    image_count=1,
    orientation="landscape",
    style={"prompt": "Test image", "tool": "ai-anime-generator"}
)

print(f"Job ID: {result.id}")  # Returns mock ID
# No credits charged, no actual processing
```

```typescript
import Client, { Environment } from "magic-hour";

// Use mock server for development
const client = new Client({
  token: "YOUR_API_KEY", // Can use any value for mock mode
  environment: Environment.MockServer,
});

// All API calls return mock data instantly
const result = await client.v1.aiImageGenerator.create({
  imageCount: 1,
  orientation: "landscape",
  style: { prompt: "Test image", tool: "ai-anime-generator" },
});

console.log(`Job ID: ${result.id}`); // Returns mock ID
// No credits charged, no actual processing
```

--------------------------------

### Run Python Project

Source: https://docs.magichour.ai/get-started/quick-start

Navigate to your project directory and execute the main Python script.

```bash
# Make sure you're in your project directory
cd magic-hour-quickstart

# Run the script
python main.py
```

--------------------------------

### AI Voice Generator Example Usage

Source: https://docs.magichour.ai/tools/audio/voice-generator

Example of how to use the ToolSection component to display audio outputs for the AI Voice Generator. Ensure the 'outputs' prop is an array of objects with 'src' properties pointing to the audio files.

```javascript
<ToolSection
  title="AI Voice Generator"
  productSlug="ai-voice-generator"
  apiSlug="ai-voice-generator"
  type="audio"
  outputs={[
  {
    src: "/get-started/images/voicegeneratorexample1.mp3",
  },
  {
    src: "/get-started/images/voicegeneratorexample2.mp3",
  },
]} 
/>
```

--------------------------------

### Create Face Swap Video (Rust SDK)

Source: https://docs.magichour.ai/get-started/quick-start

This Rust example shows how to initiate a face swap video creation. It requires the `MAGIC_HOUR_API_KEY` environment variable to be set and uses `tokio` for asynchronous operations.

```rust
use magic_hour;
use reqwest;
use std::io::Read;

#[tokio::main]
async fn main() {
    // Use environment variable for security
    let api_key = std::env::var("MAGIC_HOUR_API_KEY")
        .expect("MAGIC_HOUR_API_KEY environment variable not set");
    let mut client = magic_hour::Client::default().with_bearer_auth(&api_key);

    let create_res = client
        .v1()
        .face_swap()
        .create(magic_hour::resources::v1::face_swap::CreateRequest {
            name: Some("Swap Tom Cruise into Iron Man scene".to_string()),
            assets: magic_hour::models::PostV1FaceSwapBodyAssets {
                image_file_path: "https://videos.magichour.ai/api-assets/sample/tom-cruise.png"
                    .to_string(),
                video_file_path: Some(

```

--------------------------------

### Video Started Event Payload

Source: https://docs.magichour.ai/integration/webhook/event-types

This payload is sent when video processing begins. It includes details like the job ID, status, creation time, and dimensions. Use this to update UI or log job start times.

```json
{
  "type": "video.started",
  "payload": {
    "id": "clx7uu86w0a5qp55yxz315r6r",
    "status": "rendering",
    "type": "ANIMATION",
    "created_at": "2024-10-19T05:10:19.027Z",
    "width": 512,
    "height": 960,
    "total_frame_cost": 450,
    "credits_charged": 450,
    "downloads": [],
    "error": null
  }
}
```

--------------------------------

### Face Swap Video Tool Section Example

Source: https://docs.magichour.ai/tools/video/face-swap-video

Example usage of the ToolSection component for the Face Swap Video feature. Pass the title, product slug, API slug, type as 'video', and an array of video output sources.

```javascript
<ToolSection
  title="Face Swap Video"
  productSlug="face-swap?mode=video"
  apiSlug="face-swap-video"
  type="video"
  outputs={[
  {
    src: "https://videos.magichour.ai/clttqdcuq000fqp36h8i8bapl/video.mp4",
  },
  {
    src: "https://videos.magichour.ai/cltw1ygmc0027rck4x1lrmrqs/video.mp4",
  },
]} 
/>
```
Tokens:
Raw