---
canonical_url: "https://docs.composio.dev/toolkits/magic_hour"
markdown_url: "https://docs.composio.dev/toolkits/magic_hour.md"
product: "platform"
version: null
last_updated: null
---

# Magic Hour

Magic Hour is an AI media creation platform for generating and editing images, videos, and audio through a unified API.

- **Category:** ai content generation
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 38
- **Triggers:** 0
- **Slug:** `MAGIC_HOUR`
- **Version:** 00000000_00

## Tools

### Create AI Clothes Change

**Slug:** `MAGIC_HOUR_CREATE_AI_CLOTHES_CHANGE`

Start a credit-consuming asynchronous clothes-change image job from person and garment images. Each image costs 25 credits. The operation is documented for Free accounts but requires sufficient credits. It returns an image project ID immediately, not a completed image; poll MAGIC_HOUR_GET_IMAGE_PROJECT until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the clothes-change image project. |
| `assets` | object | Yes | Person and garment images, plus the optional clothing region to replace. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI Face Edit

**Slug:** `MAGIC_HOUR_CREATE_AI_FACE_EDIT`

Start a credit-consuming asynchronous edit of facial features in an image. This Free-tier operation returns an image project ID and credit charge immediately, not a completed image. Pass the ID to MAGIC_HOUR_GET_IMAGE_PROJECT and poll until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the face-edit image project. |
| `style` | object | Yes | Face enhancement, gaze, expression, mouth-position, and pose controls. |
| `assets` | object | Yes | Source image containing the face to edit. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI GIF

**Slug:** `MAGIC_HOUR_CREATE_AI_GIF`

Start a credit-consuming asynchronous prompt-based animation in GIF, MP4, or WebM format. This operation costs 50 credits and returns an image project ID immediately, not completed media. Pass the ID to MAGIC_HOUR_GET_IMAGE_PROJECT and poll until status is complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the AI GIF project. |
| `style` | object | Yes | Prompt controls for the generated animation. |
| `output_format` | string ("gif" | "mp4" | "webm") | No | Output file format for the generated animation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI Headshot

**Slug:** `MAGIC_HOUR_CREATE_AI_HEADSHOT`

Start a credit-consuming asynchronous headshot generation from an image containing one detectable face. Each headshot costs 50 credits. This returns an image project ID immediately, not a completed image; poll MAGIC_HOUR_GET_IMAGE_PROJECT until status is complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the AI headshot image project. |
| `style` | object | No | Optional prompt controls for the generated headshot style. |
| `assets` | object | Yes | Source image asset used to generate the headshot. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI Image

**Slug:** `MAGIC_HOUR_CREATE_AI_IMAGE`

Start a credit-consuming asynchronous text-to-image job. The request returns a project ID and immediate credit charge, not completed images. Model, image-count, resolution, cost, and tier availability vary by option; only flux-2-klein, flux-schnell, and z-image-turbo are documented for Free. Pass the returned ID to MAGIC_HOUR_GET_IMAGE_PROJECT and poll until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the image generation project. |
| `model` | string ("default" | "nano-banana-2" | "gpt-image-2" | "z-image-turbo" | "flux-2-klein" | "nano-banana-2-lite" | "seedream-v4" | "seedream-v5-pro" | "nano-banana" | "nano-banana-pro" | "flux-schnell" | "seedream") | No | Generation model. Omit or use default for Magic Hour's current recommendation. Free-tier models are flux-2-klein, flux-schnell, and z-image-turbo, starting at 5 credits per image. gpt-image-2, nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, seedream-v4, and seedream-v5-pro require Creator or higher and start at 40-150 credits per image. seedream is deprecated; use seedream-v4. |
| `style` | object | Yes | Prompt and art-style controls for image generation. |
| `resolution` | string ("auto" | "640px" | "1k" | "2k" | "4k") | No | Maximum output resolution on the longest edge. auto is deprecated and maps to a tier-dependent supported resolution. flux-2-klein, flux-schnell, and z-image-turbo support 640px, 1k, and 2k; gpt-image-2, nano-banana-2, and seedream-v4 also support 4k; nano-banana and nano-banana-2-lite support 640px and 1k; nano-banana-pro supports 1k, 2k, and 4k; seedream-v5-pro supports 640px, 1k, and 2k. Availability also depends on account tier. |
| `image_count` | integer | Yes | Number of images to generate, from 1 to 16. flux-2-klein supports only 1; flux-schnell, gpt-image-2, nano-banana, nano-banana-2-lite, seedream-v4, seedream-v5-pro, and z-image-turbo support 1-4; nano-banana-2 and nano-banana-pro support 1, 4, 9, or 16. |
| `aspect_ratio` | string ("1:1" | "16:9" | "9:16") | No | Output aspect ratio. When omitted, Magic Hour defaults to 1:1. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI Image Edit

**Slug:** `MAGIC_HOUR_CREATE_AI_IMAGE_EDIT`

Start a credit-consuming asynchronous prompt-based edit of one or more images. Model, resolution, input-image limits, cost, and tier availability vary by option. Credits are charged when the request is made. Pass the returned project ID to MAGIC_HOUR_GET_IMAGE_PROJECT and poll until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name for identifying the image edit project. |
| `model` | string ("default" | "nano-banana-2" | "gpt-image-2" | "flux-2-klein" | "nano-banana-2-lite" | "qwen-edit" | "seedream-v4" | "seedream-v4.5" | "seedream-v5-pro" | "nano-banana" | "nano-banana-pro") | No | Image-editing model. default uses Magic Hour's current recommendation. Free-tier models are flux-2-klein and qwen-edit; other listed models require a paid tier. Costs range from 5 credits per image for flux-2-klein to 150 credits per image for nano-banana-pro, and each model has its own resolution and input-image limits. |
| `style` | object | Yes | Prompt controls for the image edit. |
| `assets` | object | Yes | Input images for the edit. |
| `resolution` | string ("auto" | "640px" | "1k" | "2k" | "4k") | No | Maximum output resolution. flux-2-klein, qwen-edit, and seedream-v5-pro support 640px/1k/2k; nano-banana and nano-banana-2-lite support 640px/1k; nano-banana-pro supports 1k/2k/4k; gpt-image-2, nano-banana-2, seedream-v4, and seedream-v4.5 support 640px/1k/2k/4k. auto is deprecated but retained for a tier-dependent provider default. |
| `image_count` | integer ("1" | "4" | "9" | "16") | No | Number of edited images to generate. Allowed values are 1, 4, 9, and 16; the maximum supported value and credit cost depend on the model. |
| `aspect_ratio` | string ("auto" | "16:9" | "9:16" | "4:3" | "3:2" | "1:1" | "4:5" | "2:3") | No | Output image aspect ratio. Magic Hour defaults to auto when omitted; supported values are auto, 16:9, 9:16, 4:3, 3:2, 1:1, 4:5, and 2:3. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI Meme

**Slug:** `MAGIC_HOUR_CREATE_AI_MEME`

Start a credit-consuming asynchronous meme generation from a topic and a documented Magic Hour template. Each meme costs 10 credits. This returns an image project ID immediately, not a completed image; pass the ID to MAGIC_HOUR_GET_IMAGE_PROJECT and poll until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional name used to identify the meme image project. |
| `style` | object | Yes | Meme topic, documented template, and optional web-search setting. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI QR Code

**Slug:** `MAGIC_HOUR_CREATE_AI_QR_CODE`

Start an asynchronous artistic QR-code generation for supplied content. Magic Hour documents each AI QR code as costing 0 credits. The operation returns an image project ID and credits charged immediately, not a completed image; poll MAGIC_HOUR_GET_IMAGE_PROJECT until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the AI QR-code image project. |
| `style` | object | Yes | Template or custom art style applied to the QR code. |
| `content` | string | Yes | Content encoded by the QR code. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI Video Edit

**Slug:** `MAGIC_HOUR_CREATE_AI_VIDEO_EDIT`

Start a credit-consuming asynchronous prompt-based edit of an input video. Free accounts default to the ltx-2.3 model and 480p; other model and resolution options depend on the connected account's plan. The returned credit charge is initially an estimate. Pass the returned project ID to MAGIC_HOUR_GET_VIDEO_PROJECT and poll until status is complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name for identifying the video edit project. |
| `model` | string ("gemini-omni-1.1" | "gemini-omni" | "ltx-2.3") | No | Editing model. Magic Hour documents ltx-2.3 as the Free-tier default and gemini-omni-1.1 as the paid-tier default. gemini-omni is deprecated; use gemini-omni-1.1 instead. Model availability depends on the connected account's plan. |
| `style` | object | Yes | Prompt controls for the video edit. |
| `assets` | object | Yes | Input video asset for the edit. |
| `resolution` | string ("480p" | "720p" | "1080p") | No | Output resolution. Magic Hour documents 480p as the Free-tier default and 720p as the paid-tier default. Gemini Omni 1.1 and deprecated Gemini Omni support 720p and 1080p; LTX-2.3 supports 480p, 720p, and 1080p. Availability depends on the connected account's plan. |
| `end_seconds` | number | Yes | End time of the input clip in seconds; must be greater than start_seconds. Gemini Omni 1.1 supports 3-10 seconds, while LTX-2.3 supports 0.5-45 seconds. |
| `start_seconds` | number | No | Start time of the input clip in seconds; must be at least 0. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI Voice

**Slug:** `MAGIC_HOUR_CREATE_AI_VOICE`

Start credit-consuming asynchronous speech generation from text using a documented preset voice. Each character costs 0.1 credits, rounded up to a whole credit. This returns an audio project ID and immediate credit charge, not completed audio; pass the ID to MAGIC_HOUR_GET_AUDIO_PROJECT and poll until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the generated audio project. |
| `style` | object | Yes | Text content and documented preset voice used to generate speech. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create AI Voice Clone

**Slug:** `MAGIC_HOUR_CREATE_AI_VOICE_CLONE`

Start credit-consuming asynchronous speech generation by cloning an input voice recording. Each prompt character costs 0.1 credits, rounded up to a whole credit, and sufficient credits are required. This returns an audio project ID and immediate credit charge, not completed audio; pass the ID to MAGIC_HOUR_GET_AUDIO_PROJECT and poll until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the generated audio project. |
| `style` | object | Yes | Text content to generate using the cloned voice. |
| `assets` | object | Yes | Audio recording used as the source voice for cloning. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Animation Video

**Slug:** `MAGIC_HOUR_CREATE_ANIMATION_VIDEO`

Start one credit-consuming asynchronous animation render with explicit dimensions, frame rate, duration, style, and assets. The request returns immediately with a video project ID and estimated credits charged; pass the ID to MAGIC_HOUR_GET_VIDEO_PROJECT and poll until complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fps` | number | Yes | Desired output frame rate. Together with end_seconds, this determines the estimated frame-based credit cost. |
| `name` | string | No | Optional custom video name for identification. Magic Hour generates an Animation timestamp name when omitted. |
| `style` | object | Yes | Style and motion controls for the animation. |
| `width` | integer | Yes | Output width in pixels, at least 64. The maximum depends on the connected account's subscription. |
| `assets` | object | Yes | Audio and optional first-frame assets. |
| `height` | integer | Yes | Output height in pixels, at least 64. The maximum depends on the connected account's subscription. |
| `end_seconds` | number | Yes | Output video duration in seconds. Together with fps, this determines the estimated frame-based credit cost. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Audio-to-Video

**Slug:** `MAGIC_HOUR_CREATE_AUDIO_TO_VIDEO`

Start a credit-consuming asynchronous video generation job from audio and optional visual style controls. Free accounts can use the documented 480p default; higher resolutions depend on the connected account's plan. Returns a video project ID immediately; poll MAGIC_HOUR_GET_VIDEO_PROJECT until the project is complete, error, or canceled. Requires sufficient credits, and the initial credits_charged value is an estimate until rendering finishes.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the video project. |
| `style` | object | No | Optional controls for the visual style of the output video. |
| `assets` | object | Yes | Audio input and optional initial-frame reference image. |
| `resolution` | string ("480p" | "720p" | "1080p") | No | Output video resolution. The provider defaults to 720p on paid tiers and 480p on free tiers. |
| `end_seconds` | number | Yes | End time of the audio clip in seconds. Must be greater than start_seconds. |
| `start_seconds` | number | No | Start time of the audio clip in seconds. Must be at least 0. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Background Removal

**Slug:** `MAGIC_HOUR_CREATE_BACKGROUND_REMOVAL`

Start a credit-consuming asynchronous image job that removes a background or replaces it with an optional supplied image. Each image costs 5 credits. The operation is documented for Free accounts but requires sufficient credits. It returns an image project ID immediately, not a completed image; poll MAGIC_HOUR_GET_IMAGE_PROJECT until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the background-removal image project. |
| `assets` | object | Yes | Source image and optional replacement background image. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Body Swap

**Slug:** `MAGIC_HOUR_CREATE_BODY_SWAP`

Start a credit-consuming asynchronous body-swap image job that places a person into a scene at the selected resolution. Resolution determines the model and credit cost. This returns an image project ID immediately, not a completed image; pass the ID to MAGIC_HOUR_GET_IMAGE_PROJECT and poll until status is complete or error. Credits are charged when this request is made and refunded if generation fails.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the body-swap image project. |
| `assets` | object | Yes | Person image and scene image used for the body swap. |
| `resolution` | string ("640px" | "1k" | "2k" | "4k") | Yes | Output resolution. The selected resolution determines the model and credits charged; 640px starts at 50 credits. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Character Animation Video

**Slug:** `MAGIC_HOUR_CREATE_CHARACTER_ANIMATION_VIDEO`

Animate a reference character with motion transferred from a source video in a credit-consuming asynchronous job. The documented 480p default is available on Free; 720p depends on the connected account's plan. This returns a project ID and estimated credit charge, not a completed video. Poll MAGIC_HOUR_GET_VIDEO_PROJECT with the returned ID until status is complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom video name for easy identification. |
| `style` | object | No | Optional controls for selecting the source-video subject. |
| `assets` | object | Yes | Source video and reference character image for the generation job. |
| `resolution` | string ("480p" | "720p") | No | Output video resolution. The provider defaults to 480p, the lowest resolution available on the connected account's plan; 720p may require a higher plan. |
| `end_seconds` | number | Yes | End time of the source clip in seconds. It must be greater than start_seconds. |
| `start_seconds` | number | No | Start time of the source clip in seconds; it must be at least 0. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Character Replacement Video

**Slug:** `MAGIC_HOUR_CREATE_CHARACTER_REPLACEMENT_VIDEO`

Replace a source-video subject with a reference character in a credit-consuming asynchronous video job. The documented 480p default is available on Free; 720p depends on the connected account's plan. This returns a project ID and estimated credit charge, not a completed video. Poll MAGIC_HOUR_GET_VIDEO_PROJECT with the returned ID until status is complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom video name for easy identification. |
| `style` | object | No | Optional controls for selecting the source-video subject. |
| `assets` | object | Yes | Source video and reference character image for the generation job. |
| `resolution` | string ("480p" | "720p") | No | Output video resolution. The provider defaults to 480p, the lowest resolution available on the connected account's plan; 720p may require a higher plan. |
| `end_seconds` | number | Yes | End time of the source clip in seconds. It must be greater than start_seconds. |
| `start_seconds` | number | No | Start time of the source clip in seconds; it must be at least 0. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Face Swap Photo

**Slug:** `MAGIC_HOUR_CREATE_FACE_SWAP_PHOTO`

Start a credit-consuming asynchronous photo face swap using one source face for all detected faces or up to five individual face mappings. Each photo costs 10 credits. The operation returns an image project ID and credit charge immediately, not a completed image; poll MAGIC_HOUR_GET_IMAGE_PROJECT until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the face-swap image project. |
| `assets` | object | Yes | Source face or mappings and the target image for the photo face swap. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Face Swap Video

**Slug:** `MAGIC_HOUR_CREATE_FACE_SWAP_VIDEO`

Start a credit-consuming asynchronous video face-swap job using one image for all detected faces or up to five individual face mappings. The operation is documented for Free accounts but requires sufficient credits. It returns a project ID and estimated charge immediately, not a completed video; poll MAGIC_HOUR_GET_VIDEO_PROJECT until status is complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom video project name for identification. |
| `style` | object | No | Optional face-swap model version settings. |
| `assets` | object | Yes | Nested source video and replacement face configuration. Select both a video source and an all-face or individual-face mapping mode. |
| `end_seconds` | number | Yes | End time of the source video clip in seconds; must exceed start_seconds. |
| `start_seconds` | number | Yes | Start time of the source video clip in seconds. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Head Swap

**Slug:** `MAGIC_HOUR_CREATE_HEAD_SWAP`

Start a credit-consuming asynchronous head-swap image job from body and head images. Each image costs 10 credits. This returns an image project ID immediately, not a completed image; pass the ID to MAGIC_HOUR_GET_IMAGE_PROJECT and poll until status is complete or error. Credits are charged when this request is made and refunded if generation fails.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the head-swap image project. |
| `assets` | object | Yes | Body and head images used for the head swap. |
| `max_resolution` | integer | No | Maximum larger output dimension in pixels. Omit to use the plan maximum, capped at 2048 pixels; higher values are clamped to the connected account's plan maximum. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Image-to-Video

**Slug:** `MAGIC_HOUR_CREATE_IMAGE_TO_VIDEO`

Start a credit-consuming asynchronous video generation job from a still image and optional final frame, prompt, audio, model, and resolution controls. Free accounts default to ltx-2.5 at 480p; other model and resolution options depend on the connected account's plan. Returns a project ID and estimated credit charge immediately; poll MAGIC_HOUR_GET_VIDEO_PROJECT until status is complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom video name for easy identification. |
| `audio` | boolean | No | Whether to include generated audio. Magic Hour defaults to false when omitted. Model support and additional credit cost vary; gemini-omni-1.1, kling-2.6, and wan-2.2 do not support audio. |
| `model` | string ("default" | "ltx-2" | "ltx-2.3" | "ltx-2.5" | "minimax-h3" | "wan-2.2" | "seedance-1.5" | "seedance-2.0" | "seedance-2.0-mini" | "seedance-2.5" | "kling-2.5" | "kling-2.6" | "kling-3.0" | "gemini-omni-1.1" | "veo3.1" | "veo3.1-lite" | "sora-2" | "kling-1.6" | "seedance" | "kling-2.5-audio" | "veo3.1-audio") | No | AI generation model. default selects Magic Hour's recommended model for the account tier (ltx-2.5 on Free and kling-3.0 on paid tiers). Values ltx-2, kling-2.5, kling-1.6, seedance, kling-2.5-audio, and veo3.1-audio are retained documented values; audio-suffixed models behave like enabling audio. |
| `style` | object | No | Optional prompt controls for the generated video. |
| `assets` | object | Yes | Starting image and optional final-frame image for image-to-video generation. |
| `resolution` | string ("360p" | "480p" | "720p" | "1080p" | "4k") | No | Output resolution. Magic Hour defaults to 720p on paid tiers and 480p on Free. gemini-omni-1.1 supports 360p/720p/1080p/4k; kling-2.6 supports 720p/1080p; kling-3.0 supports 720p/1080p/4k; ltx-2.3, ltx-2.5, minimax-h3, seedance-1.5, and wan-2.2 support 480p/720p/1080p; seedance-2.0 variants and seedance-2.5 support 480p/720p; sora-2 supports 720p; veo3.1 variants support 720p/1080p. |
| `end_seconds` | number | Yes | Output duration in seconds. gemini-omni-1.1: integers 3-10; kling-2.6: 5 or 10; kling-3.0: integers 3-15; ltx-2.3 and minimax-h3: integers 1-10 plus 15, 20, 25, or 30; ltx-2.5: integers 1-10 then multiples of 5 through 60; seedance-1.5: integers 4-12; seedance-2.0 and seedance-2.0-mini: integers 4-15; seedance-2.5: integers 4-30; sora-2: 4, 8, 12, 24, 36, 48, or 60; veo3.1 variants: 4, 6, 8, 16, 24, 32, 40, 48, or 56; wan-2.2: integers 3-10 or 15. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Image Upscale

**Slug:** `MAGIC_HOUR_CREATE_IMAGE_UPSCALE`

Start a credit-consuming asynchronous 2x or 4x image upscale. A 4x upscale requires a Creator, Pro, or Business tier, while mode affects the credit charge. This returns an image project ID immediately, not a completed image; poll MAGIC_HOUR_GET_IMAGE_PROJECT until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name for identifying the image upscale project. |
| `style` | object | No | Optional mode and prompt settings controlling the upscale. |
| `assets` | object | Yes | Source image asset to upscale. |
| `scale_factor` | integer ("2" | "4") | Yes | Image scale multiplier: 2 or 4. A 4x upscale requires a Creator, Pro, or Business tier. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Lip Sync Video

**Slug:** `MAGIC_HOUR_CREATE_LIP_SYNC_VIDEO`

Start a credit-consuming asynchronous lip-sync video job from audio and a file or YouTube video. This returns a project ID immediately, not the completed video; poll MAGIC_HOUR_GET_VIDEO_PROJECT until complete, error, or canceled. The returned credit charge is an estimate, may be adjusted after rendering based on actual output FPS, and is refunded if generation fails.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the lip-sync video project. |
| `style` | object | No | Optional generation mode controlling quality, tier availability, and cost. |
| `assets` | object | Yes | Audio input and file or YouTube video input for lip synchronization. |
| `end_seconds` | number | Yes | End time of the input video clip in seconds; must exceed start_seconds. |
| `max_fps_limit` | number | No | Maximum output frames per second. If the input FPS is lower, Magic Hour retains it; reducing this limit can avoid unnecessary frame usage. |
| `start_seconds` | number | Yes | Start time of the input video clip in seconds. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Photo Colorization

**Slug:** `MAGIC_HOUR_CREATE_PHOTO_COLORIZATION`

Start a credit-consuming asynchronous colorization of a photo. Each image costs 10 credits. This returns an image project ID immediately, not a completed image; poll MAGIC_HOUR_GET_IMAGE_PROJECT until status is complete or error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the photo colorization image project. |
| `assets` | object | Yes | Source image asset to colorize. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Subtitled Video

**Slug:** `MAGIC_HOUR_CREATE_SUBTITLED_VIDEO`

Start a credit-consuming asynchronous job that transcribes speech and burns styled subtitles into an MP4 video. This returns a project ID immediately, not the completed video; poll MAGIC_HOUR_GET_VIDEO_PROJECT until complete, error, or canceled. The initial credit charge is an estimate, can be adjusted after rendering, and is refunded if generation fails.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional project name for identification. When omitted, Magic Hour generates an Auto Subtitle name with the creation date and time. |
| `style` | object | Yes | Subtitle styling. Provide a preset template, custom_config, or both; custom fields override the selected template. |
| `assets` | object | Yes | Source video asset whose speech will be transcribed into subtitles. |
| `end_seconds` | number | Yes | End time of the source video clip in seconds; must exceed start_seconds. |
| `start_seconds` | number | Yes | Inclusive start time of the source video clip in seconds. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Talking Photo

**Slug:** `MAGIC_HOUR_CREATE_TALKING_PHOTO`

Start a credit-consuming asynchronous talking-photo video from an image and audio. This operation is documented for Free accounts, but requires enough credits and available models and resolutions depend on the connected account's tier. It returns immediately with a video project ID; pass that ID to MAGIC_HOUR_GET_VIDEO_PROJECT and poll until complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the talking-photo project. |
| `style` | object | No | Optional attributes controlling the motion style of the output video. |
| `assets` | object | Yes | Image and audio assets used to create the talking photo. |
| `end_seconds` | number | Yes | End time of the input audio in seconds. Maximum clip length is 300 seconds for realistic mode and 45 seconds for prompted mode. |
| `start_seconds` | number | Yes | Start time of the input audio in seconds. Maximum clip length is 300 seconds for realistic mode and 45 seconds for prompted mode. |
| `max_resolution` | integer | No | Maximum larger dimension, in pixels, for the output video. Magic Hour caps this value at the connected account plan's maximum resolution. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Text-to-Video

**Slug:** `MAGIC_HOUR_CREATE_TEXT_TO_VIDEO`

Start a credit-consuming asynchronous video generation job from a text prompt and model/output options. Free accounts default to ltx-2.5 at 480p; model, duration, aspect ratio, resolution, and audio availability vary by plan. This returns a project ID and estimated credit charge, not a completed video; poll MAGIC_HOUR_GET_VIDEO_PROJECT until status is complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the text-to-video project. |
| `audio` | boolean | No | Whether to generate audio; omitted means false. gemini-omni-1.1, kling-2.6, and wan-2.2 do not support audio. Audio-suffixed legacy models imply true; support and additional cost vary for other models. |
| `model` | string ("default" | "ltx-2" | "ltx-2.3" | "ltx-2.5" | "minimax-h3" | "wan-2.2" | "seedance-1.5" | "seedance-2.0" | "seedance-2.0-mini" | "seedance-2.5" | "kling-2.5" | "kling-2.6" | "kling-3.0" | "gemini-omni-1.1" | "veo3.1" | "veo3.1-lite" | "sora-2" | "kling-1.6" | "seedance" | "kling-2.5-audio" | "veo3.1-audio") | No | Generation model. default selects Magic Hour's recommended model for the account tier (ltx-2.5 on Free and kling-3.0 on paid tiers). Values ltx-2, kling-2.5, kling-1.6, seedance, kling-2.5-audio, and veo3.1-audio remain accepted for compatibility; audio-suffixed models imply audio=true. |
| `style` | object | Yes | Prompt controls for the generated video. |
| `resolution` | string ("360p" | "480p" | "720p" | "1080p" | "4k") | No | Output resolution. gemini-omni-1.1 supports 360p/720p/1080p/4k; kling-2.6 supports 720p/1080p; kling-3.0 supports 720p/1080p/4k; ltx-2.3, ltx-2.5, minimax-h3, seedance-1.5, and wan-2.2 support 480p/720p/1080p; seedance-2.0 variants and seedance-2.5 support 480p/720p; sora-2 supports 720p; veo3.1 variants support 720p/1080p. |
| `end_seconds` | number | Yes | Output duration in seconds. gemini-omni-1.1: integers 3-10; kling-2.6: 5 or 10; kling-3.0: integers 3-15; ltx-2.3 and minimax-h3: integers 1-10 plus 15, 20, 25, or 30; ltx-2.5: integers 1-10 then multiples of 5 through 60; seedance-1.5: integers 4-12; seedance-2.0 variants: integers 4-15; seedance-2.5: integers 4-30; sora-2: 4, 8, 12, 24, 36, 48, or 60; veo3.1 variants: 4, 6, 8, 16, 24, 32, 40, 48, or 56; wan-2.2: integers 3-10 or 15. |
| `aspect_ratio` | string ("16:9" | "9:16" | "1:1") | No | Output aspect ratio. gemini-omni-1.1, sora-2, veo3.1, and veo3.1-lite support 16:9 or 9:16; other current models also support 1:1. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Video-to-Video

**Slug:** `MAGIC_HOUR_CREATE_VIDEO_TO_VIDEO`

Start a credit-consuming asynchronous stylized transformation of an input video. Free accounts can use the documented lower-resolution configuration; higher output quality depends on the connected account's plan. Returns a project ID and estimated credit charge immediately, not a completed video. Poll MAGIC_HOUR_GET_VIDEO_PROJECT with the returned ID until status is complete, error, or canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Custom name used to identify the video-to-video project. |
| `style` | object | Yes | Art style, style-engine version, prompt behavior, and model controls. |
| `assets` | object | Yes | Input video source and location. |
| `end_seconds` | number | Yes | End time of the input clip in seconds; must exceed start_seconds. |
| `start_seconds` | number | Yes | Start time of the input clip in seconds; must be at least 0. |
| `fps_resolution` | string ("FULL" | "HALF") | No | Output frame-rate mode. FULL preserves the input FPS; HALF generates at half the input FPS and generally consumes fewer credits. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Audio Project

**Slug:** `MAGIC_HOUR_DELETE_AUDIO_PROJECT`

Permanently delete one rendered Magic Hour audio project by ID. This destructive operation is irreversible and is not a way to cancel a queued or rendering audio project. Success requires exactly HTTP 204 with an empty body.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Audio project ID to permanently delete. This irreversible operation does not cancel a queued or rendering audio project. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Image Project

**Slug:** `MAGIC_HOUR_DELETE_IMAGE_PROJECT`

Permanently delete one Magic Hour image project and its rendered images by ID. This destructive operation is irreversible and is not a way to cancel a render. Success requires exactly HTTP 204 with an empty body.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Image project ID to permanently delete. This operation irreversibly deletes the rendered images and cannot be used to cancel a render. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Video Project

**Slug:** `MAGIC_HOUR_DELETE_VIDEO_PROJECT`

Permanently delete one rendered Magic Hour video project by ID. This destructive operation is irreversible and is not a way to cancel a queued or rendering video. Success requires exactly HTTP 204 with an empty body.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Video project ID to permanently delete. This irreversible operation does not cancel a queued or rendering video. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Detect Faces

**Slug:** `MAGIC_HOUR_DETECT_FACES`

Start asynchronous face detection for an image or video and return a task ID. Pass the returned ID to MAGIC_HOUR_GET_FACE_DETECTION and poll until status is complete or error. Face detection is currently documented as free, though pricing may change.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assets` | object | Yes | Target image or video asset to inspect for faces. |
| `confidence_score` | number | No | Confidence threshold for filtering detected faces, from 0 to 1 in increments of 0.05. Higher values reduce false positives; lower values include more possible faces. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Asset Upload URLs

**Slug:** `MAGIC_HOUR_GENERATE_ASSET_UPLOAD_URLS`

Generate ordered, expiring signed upload URLs and Magic Hour file paths for image, video, or audio assets. This allocates upload URLs but does not upload file bytes. Treat each signed URL query string as sensitive: do not log or persist it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `items` | array | Yes | Assets to prepare in request order. Each item requires a documented asset type and compatible extension; response items use the same order. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account

**Slug:** `MAGIC_HOUR_GET_ACCOUNT`

Return the connected Magic Hour account's tier, available credits, identity, and subscription details; use this before generation to check entitlement and balance.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Audio Project

**Slug:** `MAGIC_HOUR_GET_AUDIO_PROJECT`

Get an audio project's asynchronous status, error, credit charge, and temporary downloads. Poll until complete, error, or canceled. Download URLs expire at their expires_at timestamps; call this tool again afterward to obtain refreshed URLs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Audio project ID returned by a Magic Hour audio creation tool. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Face Detection

**Slug:** `MAGIC_HOUR_GET_FACE_DETECTION`

Get face-detection status and detected face paths by task ID. Poll only IDs returned by MAGIC_HOUR_DETECT_FACES and stop on complete or error: live probing showed that arbitrary and malformed IDs can return 200 queued indefinitely, so a successful response does not prove the task exists.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Face-detection task ID returned by MAGIC_HOUR_DETECT_FACES. Do not use an arbitrary ID: unknown and malformed IDs can return 200 queued indefinitely. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Image Project

**Slug:** `MAGIC_HOUR_GET_IMAGE_PROJECT`

Get an image project's asynchronous status, error, credit charge, and temporary downloads. Poll until complete, error, or canceled. Download URLs expire at their expires_at timestamps; call this tool again afterward to obtain refreshed URLs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Image project ID returned by a Magic Hour image creation tool. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Video Project

**Slug:** `MAGIC_HOUR_GET_VIDEO_PROJECT`

Get a video project's asynchronous status, error, credit charge, and temporary downloads. Poll until complete, error, or canceled. Download URLs expire after 24 hours; call this tool again to refresh expired URLs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Video project ID returned by a Magic Hour video creation tool. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |