Magic Hour

Official44 toolsLive

by magichourhq · Python

Create and edit images, videos, and audio through Magic Hour's hosted Streamable HTTP MCP server.

Magic Hour MCP Server (io.github.magichourhq/magic-hour)

This MCP server provides an OpenAPI-backed interface to Magic Hour to create and edit images, videos, and audio through a hosted Streamable HTTP MCP server. On startup, it reads docs/openapi.json and generates MCP tools using FastMCP.from_openapi(), with additional Magic Hour MCP policies for agent workflows.

🛠️ Key Features

Hosted Streamable HTTP MCP server for Magic Hour media generation
OpenAPI-backed tool creation from docs/openapi.json
Tool coverage derived from OpenAPI endpoints
Policies for async polling, uploads, and project downloads
Documentation files including user.md and integration-handoff.md

🚀 Use Cases

Generate and edit images via Magic Hour
Generate and edit videos via Magic Hour
Generate and edit audio via Magic Hour

⚡ Developer Benefits

Developers can rely on an OpenAPI spec for endpoint coverage
Async polling guidance, upload handling, and project download workflow support
FastMCP.from_openapi() auto-builds tools from docs/openapi.json
Available integration guidance in integration-handoff.md

⚠️ Limitations

Coverage depends on docs/openapi.json and the referenced OpenAPI specification
Described documentation focuses on hosted endpoint usage and integration mounting checklist

Topics

claude-pluginmcpmcp-serveropenai-pluginai-audioai-imageai-videogenerative-aimodel-context-protocol

Captured live from the server via tools/list.

ping

Check that the Magic Hour MCP server is reachable.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

wait_for_video_project

Poll a video project until it completes, errors, is canceled, or times out. Returns sanitized download fields. Use `exact_download_urls[n]` or `downloads[n].url` exactly as returned; do not shorten it, remove query parameters, or append expiration metadata.

Parameters5

id	string	required
poll_interval_seconds	number	optional
timeout_seconds	number	optional
include_inline_downloads	boolean	optional
max_inline_downloads	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "poll_interval_seconds": {
      "default": 2,
      "type": "number"
    },
    "timeout_seconds": {
      "default": 300,
      "type": "number"
    },
    "include_inline_downloads": {
      "default": false,
      "type": "boolean"
    },
    "max_inline_downloads": {
      "default": 0,
      "type": "integer"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

wait_for_image_project

Poll an image project until it completes, errors, is canceled, or times out. Returns the final project JSON and, when complete, attempts to inline image downloads for Inspector or compatible clients. Returns sanitized download fields. Use `exact_download_urls[n]` or `downloads[n].url` exactly as returned; do not shorten it, remove query parameters, or append expiration metadata.

Parameters6

id	string	required
poll_interval_seconds	number	optional
timeout_seconds	number	optional
include_inline_downloads	boolean	optional
max_inline_downloads	integer	optional
max_bytes_per_download	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "poll_interval_seconds": {
      "default": 2,
      "type": "number"
    },
    "timeout_seconds": {
      "default": 180,
      "type": "number"
    },
    "include_inline_downloads": {
      "default": true,
      "type": "boolean"
    },
    "max_inline_downloads": {
      "default": 4,
      "type": "integer"
    },
    "max_bytes_per_download": {
      "default": 15728640,
      "type": "integer"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

wait_for_audio_project

Poll an audio project until it completes, errors, is canceled, or times out. Returns the final project JSON and, when complete, attempts to inline audio downloads for Inspector or compatible clients. Returns sanitized download fields. Use `exact_download_urls[n]` or `downloads[n].url` exactly as returned; do not shorten it, remove query parameters, or append expiration metadata.

Parameters6

id	string	required
poll_interval_seconds	number	optional
timeout_seconds	number	optional
include_inline_downloads	boolean	optional
max_inline_downloads	integer	optional
max_bytes_per_download	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "poll_interval_seconds": {
      "default": 2,
      "type": "number"
    },
    "timeout_seconds": {
      "default": 180,
      "type": "number"
    },
    "include_inline_downloads": {
      "default": true,
      "type": "boolean"
    },
    "max_inline_downloads": {
      "default": 4,
      "type": "integer"
    },
    "max_bytes_per_download": {
      "default": 15728640,
      "type": "integer"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

upload_file_to_presigned_url

Upload a local file from the MCP server's filesystem to a presigned `upload_url` returned by the upload-URL endpoint. Use this for local CLI testing when the server can read the file path; remote web-chat users still need a browser or backend upload bridge.

Parameters3

upload_url	string	required
local_file_path	string	required
content_type	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "upload_url": {
      "type": "string"
    },
    "local_file_path": {
      "type": "string"
    },
    "content_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "upload_url",
    "local_file_path"
  ],
  "additionalProperties": false
}

fetch_image_download

Fetch a image `downloads[n].url` from a completed image project and return it as inline MCP image content for compatible clients. Pass the exact full signed URL from `downloads[n].url` without trimming query parameters; `expires_at` is separate metadata, not part of the URL.

Parameters2

download_url	string	required
max_bytes	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "download_url": {
      "type": "string"
    },
    "max_bytes": {
      "default": 15728640,
      "type": "integer"
    }
  },
  "required": [
    "download_url"
  ],
  "additionalProperties": false
}

fetch_audio_download

Fetch a audio `downloads[n].url` from a completed audio project and return it as inline MCP audio content for compatible clients. Pass the exact full signed URL from `downloads[n].url` without trimming query parameters; `expires_at` is separate metadata, not part of the URL.

Parameters2

download_url	string	required
max_bytes	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "download_url": {
      "type": "string"
    },
    "max_bytes": {
      "default": 15728640,
      "type": "integer"
    }
  },
  "required": [
    "download_url"
  ],
  "additionalProperties": false
}

fetch_video_download

Fetch a video `downloads[n].url` from a completed video project and return it as an embedded MCP binary resource for compatible clients. Pass the exact full signed URL from `downloads[n].url` without trimming query parameters; `expires_at` is separate metadata, not part of the URL.

Parameters2

download_url	string	required
max_bytes	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "download_url": {
      "type": "string"
    },
    "max_bytes": {
      "default": 15728640,
      "type": "integer"
    }
  },
  "required": [
    "download_url"
  ],
  "additionalProperties": false
}

video_assets_generate_presigned_url

Generates a list of pre-signed upload URLs for the assets required. This API is only necessary if you want to upload to Magic Hour's storage. Refer to the [Input Files Guide](https://docs.magichour.ai/integration/inputs-and-outputs) for more details. The response array will match the order of items in the request body. **Valid file extensions per asset type**: - video: mp4, m4v, mov, webm - audio: mp3, wav, aac, flac, webm, weba, m4a, opus, ogg, oga, aiff, amr - image: png, jpg, jpeg, jfif, heic, heif, webp, avif, jp2, tiff, tif, bmp - gif: gif, webp, webm > Note: `gif` is only supported for face swap API `video_file_path` field. Once you receive an upload URL, send a `PUT` request to upload the file directly. Example: ``` curl -X PUT --data '@/path/to/file/video.mp4' \ https://videos.magichour.ai/api-assets/id/video.mp4?<auth params from the API response> ``` MCP guidance: - This only creates presigned upload URLs. For local files, upload the raw bytes to each returned `upload_url` outside the generation call, then pass the matching `file_path` into the create tool. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters1

items

array

required

The list of assets to upload. The response array will match the order of items in the request body.

Raw schema

{
  "type": "object",
  "properties": {
    "items": {
      "minItems": 1,
      "type": "array",
      "items": {
        "required": [
          "type",
          "extension"
        ],
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "video",
              "audio",
              "image"
            ],
            "type": "string",
            "description": "The type of asset to upload. Possible types are video, audio, image",
            "example": "video"
          },
          "extension": {
            "pattern": "^[a-z0-9]+$",
            "type": "string",
            "description": "The extension of the file to upload. Do not include the dot (.) before the extension. Possible extensions are mp4,m4v,mov,webm,mp3,wav,aac,flac,webm,weba,m4a,opus,ogg,oga,aiff,amr,png,jpg,jpeg,jfif,heic,heif,webp,avif,jp2,tiff,tif,bmp,gif,webp,webm",
            "example": "mp4"
          }
        }
      },
      "description": "The list of assets to upload. The response array will match the order of items in the request body.",
      "example": [
        {
          "type": "video",
          "extension": "mp4"
        },
        {
          "type": "audio",
          "extension": "mp3"
        }
      ]
    }
  },
  "required": [
    "items"
  ]
}

face_detection_retrieve_details

Get the details of a face detection task. Use this API to get the list of faces detected in the image or video to use in the [face swap photo](https://docs.magichour.ai/api-reference/image-projects/face-swap-photo) or [face swap video](https://docs.magichour.ai/api-reference/video-projects/face-swap-video) API calls for multi-face swaps.

Parameters1

string

required

The id of the task. This value is returned by the [face detection API](https://docs.magichour.ai/api-reference/files/face-detection#response-id).

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "uuid-example",
      "description": "The id of the task. This value is returned by the [face detection API](https://docs.magichour.ai/api-reference/files/face-detection#response-id)."
    }
  },
  "required": [
    "id"
  ]
}

face_detection_detect_faces

Detect faces in an image or video. Use this API to get the list of faces detected in the image or video to use in the [face swap photo](https://docs.magichour.ai/api-reference/image-projects/face-swap-photo) or [face swap video](https://docs.magichour.ai/api-reference/video-projects/face-swap-video) API calls for multi-face swaps. Note: Face detection is free to use for the near future. Pricing may change in the future. MCP guidance: - This starts an async face-detection task and returns an `id`. Use the face-detection details endpoint with that id to retrieve detected faces before doing individual face swaps. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters2

confidence_score	number	optional	Confidence threshold for filtering detected faces. * Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives. * Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections.
assets	object	required	Provide the assets for face detection

Raw schema

{
  "type": "object",
  "properties": {
    "confidence_score": {
      "multipleOf": 0.05,
      "maximum": 1,
      "minimum": 0,
      "type": "number",
      "description": "Confidence threshold for filtering detected faces. \n* Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives. \n* Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections.",
      "default": 0.5,
      "example": 0.5
    },
    "assets": {
      "required": [
        "target_file_path"
      ],
      "type": "object",
      "properties": {
        "target_file_path": {
          "type": "string",
          "description": "This is the image or video where the face will be detected. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the assets for face detection"
    }
  },
  "required": [
    "assets"
  ]
}

video_projects_retrieve_details

Check the progress of a video project. The `downloads` field is populated after a successful render. **Statuses** - `queued` — waiting to start - `rendering` — in progress - `complete` — ready; see `downloads` - `error` — a failure occurred (see `error`) - `canceled` — user canceled - `draft` — not used MCP guidance: - Use this after a create tool to poll job status. When status is `complete`, surface the `downloads` URLs to the user; if status is `error`, surface the error message. - Each `downloads[n].url` is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append `expires_at` onto the URL string.

Parameters1

string

required

Unique ID of the video project. This value is returned by all of the POST APIs that create a video.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "cuid-example",
      "description": "Unique ID of the video project. This value is returned by all of the POST APIs that create a video."
    }
  },
  "required": [
    "id"
  ]
}

video_projects_delete

Permanently delete the rendered video. This action is not reversible, please be sure before deleting.

Parameters1

string

required

Unique ID of the video project. This value is returned by all of the POST APIs that create a video.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "cuid-example",
      "description": "Unique ID of the video project. This value is returned by all of the POST APIs that create a video."
    }
  },
  "required": [
    "id"
  ]
}

ai_talking_photo_create_talking_photo

Create a talking photo from an image and audio or text input. MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters6

name	string	optional	Give your image a custom name for easy identification.
start_seconds	number	required	The start time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 180s, prompted 45s.
end_seconds	number	required	The end time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 180s, prompted 45s.
assets	object	required	Provide the assets for creating a talking photo
style	object	optional	Attributes used to dictate the style of the output
max_resolution	integer	optional	Constrains the larger dimension (height or width) of the output video. Allows you to set a lower resolution than your plan's maximum if desired. The value is capped by your plan's max resolution.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Talking Photo - dateTime",
      "example": "My Talking Photo image"
    },
    "start_seconds": {
      "minimum": 0,
      "type": "number",
      "description": "The start time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 180s, prompted 45s.",
      "format": "float",
      "example": 0
    },
    "end_seconds": {
      "minimum": 0.1,
      "type": "number",
      "description": "The end time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 180s, prompted 45s.",
      "format": "float",
      "example": 15
    },
    "assets": {
      "required": [
        "image_file_path",
        "audio_file_path"
      ],
      "type": "object",
      "properties": {
        "image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The source image to animate. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        },
        "audio_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The audio file to sync with the image. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp3"
        }
      },
      "description": "Provide the assets for creating a talking photo"
    },
    "style": {
      "type": "object",
      "properties": {
        "generation_mode": {
          "enum": [
            "realistic",
            "prompted",
            "pro",
            "standard",
            "stable",
            "expressive"
          ],
          "type": "string",
          "description": "Controls overall motion style.\n* `realistic` - Maintains likeness well, high quality, and reliable.\n* `prompted` - Slightly lower likeness; allows option to prompt scene.\n\n**Deprecated values (maintained for backward compatibility):**\n* `pro` - Deprecated: use `realistic`\n* `standard` - Deprecated: use `prompted`\n* `stable` - Deprecated: use `realistic`\n* `expressive` - Deprecated: use `prompted`",
          "default": "realistic",
          "example": "realistic"
        },
        "prompt": {
          "type": "string",
          "description": "A text prompt to guide the generation. Only applicable when generation_mode is `prompted`.\nThis field is ignored for other modes."
        }
      },
      "description": "Attributes used to dictate the style of the output"
    },
    "max_resolution": {
      "type": "integer",
      "description": "Constrains the larger dimension (height or width) of the output video. Allows you to set a lower resolution than your plan's maximum if desired. The value is capped by your plan's max resolution.",
      "example": 1024
    }
  },
  "required": [
    "start_seconds",
    "end_seconds",
    "assets"
  ]
}

ai_video_editor_create_video

**What this API does** Create the same Video Editor you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding video editor into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a video editor job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: see the request schema for endpoint-specific assets - Resolution: free users default to 480p; higher plans unlock HD and larger sizes - Extra fields: see the request schema for endpoint-specific options **Cost** Credits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done. For detailed examples, see the [product page](https://magichour.ai/products/ai-video-editor). MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters7

name	string	optional	Give your video a custom name for easy identification.
start_seconds	number	optional	Start time of your clip (seconds). Must be ≥ 0.
end_seconds	number	required	End time of your clip in seconds. Must be greater than `start_seconds`. Minimum duration depends on model: `gemini-omni`: 3s, `ltx-2.3`: 0.5s. Maximum duration depends on model: `gemini-omni`: 10s, `ltx-2.3`: 45s.
model	string	optional	Editing model. Defaults to `ltx-2.3` for free tier and `gemini-omni` for paid. Use `ltx-2.3` for LTX video edit.
resolution	string	optional	Output resolution. Defaults to `480p` for free tier and `720p` for paid. Google Omni supports 720p only; LTX-2.3 supports 480p, 720p, and 1080p.
style	object	required
assets	object	required	Provide the assets for video editing.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Video Editor - dateTime",
      "example": "My Video Editor video"
    },
    "start_seconds": {
      "minimum": 0,
      "type": "number",
      "description": "Start time of your clip (seconds). Must be ≥ 0.",
      "format": "float",
      "default": 0,
      "example": 0
    },
    "end_seconds": {
      "minimum": 0.1,
      "type": "number",
      "description": "End time of your clip in seconds. Must be greater than `start_seconds`. Minimum duration depends on model: `gemini-omni`: 3s, `ltx-2.3`: 0.5s. Maximum duration depends on model: `gemini-omni`: 10s, `ltx-2.3`: 45s.",
      "format": "float",
      "example": 5
    },
    "model": {
      "enum": [
        "gemini-omni",
        "ltx-2.3"
      ],
      "type": "string",
      "description": "Editing model. Defaults to `ltx-2.3` for free tier and `gemini-omni` for paid. Use `ltx-2.3` for LTX video edit.",
      "example": "gemini-omni"
    },
    "resolution": {
      "enum": [
        "480p",
        "720p",
        "1080p"
      ],
      "type": "string",
      "description": "Output resolution. Defaults to `480p` for free tier and `720p` for paid. Google Omni supports 720p only; LTX-2.3 supports 480p, 720p, and 1080p.",
      "example": "720p"
    },
    "style": {
      "required": [
        "prompt"
      ],
      "type": "object",
      "properties": {
        "prompt": {
          "minLength": 1,
          "type": "string",
          "description": "The prompt used to edit the video.",
          "example": "Change the car color to blue"
        }
      }
    },
    "assets": {
      "required": [
        "video_file_path"
      ],
      "type": "object",
      "properties": {
        "video_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The video to edit. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp4"
        }
      },
      "description": "Provide the assets for video editing."
    }
  },
  "required": [
    "end_seconds",
    "style",
    "assets"
  ]
}

animation_create_video

Create a Animation video. The estimated frame cost is calculated based on the `fps` and `end_seconds` input. MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters7

name	string	optional	Give your video a custom name for easy identification.
fps	number	required	The desire output video frame rate
end_seconds	number	required	This value determines the duration of the output video.
height	integer	required	The height of the final output video. The maximum height depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details
width	integer	required	The width of the final output video. The maximum width depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details
style	object	required	Defines the style of the output video
assets	object	required	Provide the assets for animation.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Animation - dateTime",
      "example": "My Animation video"
    },
    "fps": {
      "minimum": 1,
      "type": "number",
      "description": "The desire output video frame rate",
      "example": 12
    },
    "end_seconds": {
      "minimum": 0.1,
      "type": "number",
      "description": "This value determines the duration of the output video.",
      "format": "float",
      "example": 15
    },
    "height": {
      "minimum": 64,
      "type": "integer",
      "description": "The height of the final output video. The maximum height depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details",
      "example": 960
    },
    "width": {
      "minimum": 64,
      "type": "integer",
      "description": "The width of the final output video. The maximum width depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details",
      "example": 512
    },
    "style": {
      "required": [
        "art_style",
        "camera_effect",
        "prompt_type",
        "transition_speed"
      ],
      "type": "object",
      "properties": {
        "art_style": {
          "enum": [
            "Custom",
            "Painterly Illustration",
            "Vibrant Matte Illustration",
            "Traditional Watercolor",
            "Cyberpunk",
            "Ink and Watercolor Portrait",
            "Intricate Abstract Lines Portrait",
            "3D Render",
            "Old School Comic",
            "Bold Colored Illustration",
            "Synthwave",
            "Minimal Cold Futurism",
            "Futuristic Anime",
            "Cinematic Miyazaki",
            "Studio Ghibli Film Still",
            "Soft Delicate Matte Portrait",
            "Cinematic Landscape",
            "Landscape Painting",
            "Photograph",
            "Jackson Pollock",
            "Cubist",
            "Abstract Minimalist",
            "Impressionism",
            "Van Gogh",
            "Woodcut",
            "Oil Painting",
            "Vintage Japanese Anime",
            "Pixar",
            "Cosmic",
            "Pixel Art",
            "Fantasy",
            "Arcane",
            "Sin City",
            "Double Exposure",
            "Painted Cityscape",
            "90s Streets",
            "Overgrown",
            "Postapocalyptic",
            "Spooky",
            "Miniatures",
            "Low Poly",
            "Art Deco",
            "Inkpunk",
            "Dark Graphic Illustration",
            "Dark Watercolor",
            "Faded Illustration",
            "Directed by AI"
          ],
          "type": "string",
          "description": "The art style used to create the output video",
          "example": "Painterly Illustration"
        },
        "art_style_custom": {
          "type": "string",
          "description": "Describe custom art style. This field is required if `art_style` is `Custom`"
        },
        "camera_effect": {
          "enum": [
            "Simple Zoom Out",
            "Simple Zoom In",
            "Bounce Out",
            "Spin Bounce",
            "Rolling Bounces",
            "Rise and Climb",
            "Dramatic Zoom In",
            "Dramatic Zoom Out",
            "Sway Out",
            "Boost Zoom In",
            "Boost Zoom Out",
            "Heartbeat",
            "Bounce in Place",
            "Earthquake Bounce",
            "Slice Bounce",
            "Bounce In And Out",
            "Jump",
            "Road Trip",
            "Traverse",
            "Rubber Band",
            "Rodeo",
            "Accelerate",
            "Speed of Light",
            "Drift Spin",
            "Vertigo",
            "Cog in the Machine",
            "Quadrant",
            "Tron",
            "Pusher",
            "Roll In",
            "Hesitate In",
            "Zoom In - Audio Sync",
            "Pulse - Audio Sync",
            "Aggressive Zoom In - Audio Sync",
            "Roll In - Audio Sync",
            "Zoom Out - Audio Sync",
            "Aggressive Zoom Out - Audio Sync",
            "Sway Out - Audio Sync",
            "Bounce and Spin - Audio Sync",
            "Zoom In and Spin - Audio Sync",
            "Vertigo - Audio Sync",
            "Bounce Out - Audio Sync",
            "Earthquake Bounce - Audio Sync",
            "Pusher - Audio Sync",
            "Evolve - Audio Sync",
            "Devolve - Audio Sync",
            "Slideshow",
            "Pan Left",
            "Pan Right",
            "Tilt Up",
            "Tilt Down",
            "Directed by AI"
          ],
          "type": "string",
          "description": "The camera effect used to create the output video",
          "example": "Simple Zoom In"
        },
        "prompt_type": {
          "enum": [
            "custom",
            "use_lyrics",
            "ai_choose"
          ],
          "type": "string",
          "description": "\n* `custom` - Use your own prompt for the video.\n* `use_lyrics` - Use the lyrics of the audio to create the prompt. If this option is selected, then `assets.audio_source` must be `file` or `youtube`.\n* `ai_choose` - Let AI write the prompt. If this option is selected, then `assets.audio_source` must be `file` or `youtube`.",
          "example": "custom"
        },
        "prompt": {
          "type": "string",
          "description": "The prompt used for the video. Prompt is required if `prompt_type` is `custom`. Otherwise this value is ignored",
          "example": "Cyberpunk city"
        },
        "transition_speed": {
          "maximum": 10,
          "minimum": 1,
          "type": "integer",
          "description": "Change determines how quickly the video's content changes across frames. \n* Higher = more rapid transitions.\n* Lower = more stable visual experience.",
          "example": 5
        }
      },
      "description": "Defines the style of the output video"
    },
    "assets": {
      "required": [
        "audio_source"
      ],
      "type": "object",
      "properties": {
        "audio_source": {
          "enum": [
            "none",
            "file",
            "youtube"
          ],
          "type": "string",
          "description": "Optionally add an audio source if you'd like to incorporate audio into your video",
          "example": "file"
        },
        "audio_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The path of the input audio. This field is required if `audio_source` is `file`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp3"
        },
        "youtube_url": {
          "minLength": 1,
          "type": "string",
          "description": "Using a youtube video as the input source. This field is required if `audio_source` is `youtube`",
          "format": "uri"
        },
        "image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "An initial image to use a the first frame of the video. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the assets for animation."
    }
  },
  "required": [
    "fps",
    "end_seconds",
    "height",
    "width",
    "style",
    "assets"
  ]
}

audio_to_video_create_video

**What this API does** Create the same Audio To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding audio to video into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a audio to video job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: see the request schema for endpoint-specific assets - Resolution: free users default to 480p; higher plans unlock HD and larger sizes - Extra fields: see the request schema for endpoint-specific options **Cost** Credits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done. For detailed examples, see the [product page](https://magichour.ai/products/audio-to-video). MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters6

name	string	optional	Give your video a custom name for easy identification.
start_seconds	number	optional	Start time of your clip (seconds). Must be ≥ 0.
end_seconds	number	required	End time of your clip (seconds). Must be greater than start_seconds.
resolution	string	optional	Output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers.
assets	object	required	Provide the audio file and an optional reference image.
style	object	optional	Attributes used to dictate the style of the output

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Audio To Video - dateTime",
      "example": "My Audio To Video video"
    },
    "start_seconds": {
      "minimum": 0,
      "type": "number",
      "description": "Start time of your clip (seconds). Must be ≥ 0.",
      "format": "float",
      "default": 0,
      "example": 0
    },
    "end_seconds": {
      "minimum": 0.1,
      "type": "number",
      "description": "End time of your clip (seconds). Must be greater than start_seconds.",
      "format": "float",
      "example": 15
    },
    "resolution": {
      "enum": [
        "480p",
        "720p",
        "1080p"
      ],
      "type": "string",
      "description": "Output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers.",
      "example": "720p"
    },
    "assets": {
      "required": [
        "audio_file_path"
      ],
      "type": "object",
      "properties": {
        "audio_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The path of the audio file. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp3"
        },
        "image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "Reference image for the initial frame of the video. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the audio file and an optional reference image."
    },
    "style": {
      "type": "object",
      "properties": {
        "prompt": {
          "type": "string",
          "description": "Prompt to guide the visual style of the video.",
          "example": "Car driving through a city"
        }
      },
      "description": "Attributes used to dictate the style of the output"
    }
  },
  "required": [
    "end_seconds",
    "assets"
  ]
}

auto_subtitle_generator_create_video

Automatically generate subtitles for your video in multiple languages. MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters5

name	string	optional	Give your video a custom name for easy identification.
start_seconds	number	required	Start time of your clip (seconds). Must be ≥ 0.
end_seconds	number	required	End time of your clip (seconds). Must be greater than start_seconds.
assets	object	required	Provide the assets for auto subtitle generator
style	object	required	Style of the subtitle. At least one of `.style.template` or `.style.custom_config` must be provided. * If only `.style.template` is provided, default values for the template will be used. * If both are provided, the fields in `.style.custom_config` will be used to overwrite the fields in `.style.template`. * If only `.style.custom_config` is provided, then all fields in `.style.custom_config` will be used. To use custom config only, the following `custom_config` params are required: * `.style.custom_config.font` * `.style.custom_config.text_color` * `.style.custom_config.vertical_position` * `.style.custom_config.horizontal_position`

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Auto Subtitle - dateTime",
      "example": "My Auto Subtitle video"
    },
    "start_seconds": {
      "minimum": 0,
      "type": "number",
      "description": "Start time of your clip (seconds). Must be ≥ 0.",
      "format": "float",
      "example": 0
    },
    "end_seconds": {
      "minimum": 0.1,
      "type": "number",
      "description": "End time of your clip (seconds). Must be greater than start_seconds.",
      "format": "float",
      "example": 15
    },
    "assets": {
      "required": [
        "video_file_path"
      ],
      "type": "object",
      "properties": {
        "video_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "This is the video used to add subtitles. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp4"
        }
      },
      "description": "Provide the assets for auto subtitle generator"
    },
    "style": {
      "type": "object",
      "properties": {
        "template": {
          "enum": [
            "karaoke",
            "cinematic",
            "minimalist",
            "highlight"
          ],
          "type": "string",
          "description": "Preset subtitle templates. Please visit https://magichour.ai/create/auto-subtitle-generator to see the style of the existing templates."
        },
        "custom_config": {
          "type": "object",
          "properties": {
            "font": {
              "type": "string",
              "description": "Font name from Google Fonts. Not all fonts support all languages or character sets. \nWe recommend verifying language support and appearance directly on https://fonts.google.com before use.",
              "example": "Noto Sans"
            },
            "font_size": {
              "type": "number",
              "description": "Font size in pixels. If not provided, the font size is automatically calculated based on the video resolution.",
              "example": 24
            },
            "font_style": {
              "type": "string",
              "description": "Font style (e.g., normal, italic, bold)",
              "example": "normal"
            },
            "text_color": {
              "type": "string",
              "description": "Primary text color in hex format",
              "example": "#FFFFFF"
            },
            "highlighted_text_color": {
              "type": "string",
              "description": "Color used to highlight the current spoken text",
              "example": "#FFD700"
            },
            "stroke_color": {
              "type": "string",
              "description": "Stroke (outline) color of the text",
              "example": "#000000"
            },
            "stroke_width": {
              "type": "number",
              "description": "Width of the text stroke in pixels. If `stroke_color` is provided, but `stroke_width` is not, the `stroke_width` will be calculated automatically based on the font size.",
              "example": 1
            },
            "vertical_position": {
              "type": "string",
              "description": "Vertical alignment of the text (e.g., top, center, bottom)",
              "example": "bottom"
            },
            "horizontal_position": {
              "type": "string",
              "description": "Horizontal alignment of the text (e.g., left, center, right)",
              "example": "center"
            }
          },
          "description": "Custom subtitle configuration."
        }
      },
      "description": "Style of the subtitle. At least one of `.style.template` or `.style.custom_config` must be provided. \n* If only `.style.template` is provided, default values for the template will be used.\n* If both are provided, the fields in `.style.custom_config` will be used to overwrite the fields in `.style.template`.\n* If only `.style.custom_config` is provided, then all fields in `.style.custom_config` will be used.\n\nTo use custom config only, the following `custom_config` params are required:\n* `.style.custom_config.font`\n* `.style.custom_config.text_color`\n* `.style.custom_config.vertical_position`\n* `.style.custom_config.horizontal_position`\n"
    }
  },
  "required": [
    "start_seconds",
    "end_seconds",
    "assets",
    "style"
  ]
}

character_replace_create_video

**What this API does** Create the same Character Replace you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding character replace into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a character replace job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: see the request schema for endpoint-specific assets - Resolution: free users default to 480p; higher plans unlock HD and larger sizes - Extra fields: see the request schema for endpoint-specific options **Cost** Credits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done. For detailed examples, see the [product page](https://magichour.ai/products/character-replace). MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters6

name	string	optional	Give your video a custom name for easy identification.
start_seconds	number	optional	Start time of your clip (seconds). Must be ≥ 0.
end_seconds	number	required	End time of your clip (seconds). Must be greater than start_seconds.
resolution	string	optional	Output video resolution. Defaults to 480p, the lowest resolution available on your plan.
assets	object	required	Source video and reference character image for the job.
style	object	optional	Optional style controls for replace vs animate mode and subject selection.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Character Replace - dateTime",
      "example": "My Character Replace video"
    },
    "start_seconds": {
      "minimum": 0,
      "type": "number",
      "description": "Start time of your clip (seconds). Must be ≥ 0.",
      "format": "float",
      "default": 0,
      "example": 0
    },
    "end_seconds": {
      "minimum": 0.1,
      "type": "number",
      "description": "End time of your clip (seconds). Must be greater than start_seconds.",
      "format": "float",
      "example": 15
    },
    "resolution": {
      "enum": [
        "480p",
        "720p"
      ],
      "type": "string",
      "description": "Output video resolution. Defaults to 480p, the lowest resolution available on your plan.",
      "example": "720p"
    },
    "assets": {
      "required": [
        "video_file_path",
        "image_file_path"
      ],
      "type": "object",
      "properties": {
        "video_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "Source video containing the subject to replace or animate. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp4"
        },
        "image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "Reference character image used as the replacement or animation target. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/5678.png"
        }
      },
      "description": "Source video and reference character image for the job."
    },
    "style": {
      "type": "object",
      "properties": {
        "mode": {
          "enum": [
            "replace",
            "animate"
          ],
          "type": "string",
          "description": "Processing mode. `replace` swaps the detected subject with your reference character. `animate` transfers motion from the video onto your character image.",
          "example": "replace"
        },
        "selection_mode": {
          "enum": [
            "auto",
            "point"
          ],
          "type": "string",
          "description": "How to locate the subject in the source video. `auto` detects a person automatically. `point` uses your `points` to mark the subject. Defaults to `auto`.",
          "example": "auto"
        },
        "points": {
          "type": "array",
          "items": {
            "required": [
              "position_x",
              "position_y",
              "time_seconds"
            ],
            "type": "object",
            "properties": {
              "position_x": {
                "minimum": 0,
                "type": "integer",
                "description": "Horizontal pixel coordinate in the source video frame at `time_seconds`, measured from the left edge.",
                "example": 320
              },
              "position_y": {
                "minimum": 0,
                "type": "integer",
                "description": "Vertical pixel coordinate in the source video frame at `time_seconds`, measured from the top edge.",
                "example": 180
              },
              "time_seconds": {
                "minimum": 0,
                "type": "number",
                "description": "Timestamp on the source video timeline in seconds. Uses the same clock as `start_seconds` and `end_seconds`.",
                "format": "float",
                "example": 2.5
              }
            }
          },
          "description": "On-frame markers for manual subject selection. Required when `selection_mode` is `point`. Ignored when `selection_mode` is `auto` or omitted."
        }
      },
      "description": "Optional style controls for replace vs animate mode and subject selection.",
      "example": {
        "mode": "replace",
        "selection_mode": "auto"
      }
    }
  },
  "required": [
    "end_seconds",
    "assets"
  ]
}

face_swap_create_video

**What this API does** Create the same Face Swap you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding face swap into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a face swap job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: see the request schema for endpoint-specific assets - Resolution: free users default to 480p; higher plans unlock HD and larger sizes - Extra fields: see the request schema for endpoint-specific options **Cost** Credits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done. For detailed examples, see the [product page](https://magichour.ai/products/face-swap). MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters5

name	string	optional	Give your video a custom name for easy identification.
start_seconds	number	required	Start time of your clip (seconds). Must be ≥ 0.
end_seconds	number	required	End time of your clip (seconds). Must be greater than start_seconds.
style	object	optional	Style of the face swap video.
assets	object	required	Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Face Swap - dateTime",
      "example": "My Face Swap video"
    },
    "start_seconds": {
      "minimum": 0,
      "type": "number",
      "description": "Start time of your clip (seconds). Must be ≥ 0.",
      "format": "float",
      "example": 0
    },
    "end_seconds": {
      "minimum": 0.1,
      "type": "number",
      "description": "End time of your clip (seconds). Must be greater than start_seconds.",
      "format": "float",
      "example": 15
    },
    "style": {
      "type": "object",
      "properties": {
        "version": {
          "enum": [
            "v1",
            "v2",
            "default"
          ],
          "type": "string",
          "description": "* `v1` - May preserve skin detail and texture better, but weaker identity preservation.\n* `v2` - Faster, sharper, better handling of hair and glasses. stronger identity preservation.\n* `default` - Use the version we recommend, which will change over time. This is recommended unless you need a specific earlier version. This is the default behavior.",
          "example": "default"
        }
      },
      "description": "Style of the face swap video.",
      "example": {
        "version": "default"
      }
    },
    "assets": {
      "required": [
        "video_source"
      ],
      "type": "object",
      "properties": {
        "face_swap_mode": {
          "enum": [
            "all-faces",
            "individual-faces"
          ],
          "type": "string",
          "description": "Choose how to swap faces:\n**all-faces** (recommended) — swap all detected faces using one source image (`source_file_path` required)\n+- **individual-faces** — specify exact mappings using `face_mappings`",
          "default": "all-faces",
          "example": "all-faces"
        },
        "image_file_path": {
          "type": "string",
          "description": "The path of the input image with the face to be swapped.  The value is required if `face_swap_mode` is `all-faces`.\n\nThis value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "image/id/1234.png"
        },
        "face_mappings": {
          "maxItems": 5,
          "type": "array",
          "items": {
            "required": [
              "original_face",
              "new_face"
            ],
            "type": "object",
            "properties": {
              "original_face": {
                "type": "string",
                "description": "The face detected from the image in `target_file_path`. The file name is in the format of `<face_frame>-<face_index>.png`. This value is corresponds to the response in the [face detection API](https://docs.magichour.ai/api-reference/files/get-face-detection-details).\n\n* The face_frame is the frame number of the face in the target image. For images, the frame number is always 0.\n* The face_index is the index of the face in the target image, starting from 0 going left to right.",
                "example": "api-assets/id/0-0.png"
              },
              "new_face": {
                "type": "string",
                "description": "The face image that will be used to replace the face in the `original_face`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
                "example": "api-assets/id/1234.png"
              }
            }
          },
          "description": "This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`.",
          "example": [
            {
              "original_face": "api-assets/id/0-0.png",
              "new_face": "api-assets/id/1234.png"
            }
          ]
        },
        "video_source": {
          "enum": [
            "file",
            "youtube"
          ],
          "type": "string",
          "description": "Choose your video source.",
          "example": "file"
        },
        "video_file_path": {
          "type": "string",
          "description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp4"
        },
        "youtube_url": {
          "type": "string",
          "description": "YouTube URL (required if `video_source` is `youtube`).",
          "format": "uri"
        }
      },
      "description": "Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used"
    }
  },
  "required": [
    "start_seconds",
    "end_seconds",
    "assets"
  ]
}

image_to_video_create_video

**What this API does** Create the same Image To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding image to video into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a image to video job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: see the request schema for endpoint-specific assets - Resolution: free users default to 480p; higher plans unlock HD and larger sizes - Extra fields: see the request schema for endpoint-specific options **Cost** Credits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done. For detailed examples, see the [product page](https://magichour.ai/products/image-to-video). MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters7

name	string	optional	Give your video a custom name for easy identification.
end_seconds	number	required	The total duration of the output video in seconds. Supported durations depend on the chosen model: * `kling-2.6`: 5, 10 * `kling-3.0`: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 * `ltx-2.3`: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30 * `minimax-h3`: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30 * `seedance-1.5`: 4, 5, 6, 7, 8, 9, 10, 11, 12 * `seedance-2.0`: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 * `seedance-2.0-mini`: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 * `seedance-2.5`: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 * `sora-2`: 4, 8, 12, 24, 36, 48, 60 * `veo3.1`: 4, 6, 8, 16, 24, 32, 40, 48, 56 * `veo3.1-lite`: 4, 6, 8, 16, 24, 32, 40, 48, 56 * `wan-2.2`: 3, 4, 5, 6, 7, 8, 9, 10, 15
model	string	optional	The AI model to use for video generation. * `default`: uses our currently recommended model for general use. For paid tiers, defaults to `kling-3.0`. For free tiers, it defaults to `ltx-2.3`. * `kling-2.6`: Great for action, motion blur, and camera moves. * `kling-3.0`: Best overall quality for cinematic storytelling. * `ltx-2.3`: Fastest output. Best for rapid iteration. * `minimax-h3`: Reference-driven video with native audio. * `seedance-1.5`: Smooth, consistent motion with precision. * `seedance-2.0`: Top quality with reference-to-video control. * `seedance-2.0-mini`: Fast, consistent video with strong motion quality * `seedance-2.5`: Highest quality with superior realism, detail, and motion * `sora-2`: Open AI's model. Great for creativity and viral clips. * `veo3.1`: Google's model. Highest realism and detail. * `veo3.1-lite`: Veo quality at a more accessible cost. * `wan-2.2`: Strong physics, camera moves, and motion. If you specify the deprecated model value that includes the `-audio` suffix, this will be the same as included `audio` as `true`.
resolution	string	optional	Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers. * `kling-2.6`: Supports 720p, 1080p. * `kling-3.0`: Supports 720p, 1080p, 4k. * `ltx-2.3`: Supports 480p, 720p, 1080p. * `minimax-h3`: Supports 480p, 720p, 1080p. * `seedance-1.5`: Supports 480p, 720p, 1080p. * `seedance-2.0`: Supports 480p, 720p. * `seedance-2.0-mini`: Supports 480p, 720p. * `seedance-2.5`: Supports 480p, 720p. * `sora-2`: Supports 720p. * `veo3.1`: Supports 720p, 1080p. * `veo3.1-lite`: Supports 720p, 1080p. * `wan-2.2`: Supports 480p, 720p, 1080p.
audio	boolean	optional	Whether to include audio in the video. Defaults to `false` if not specified. Audio support varies by model: * `kling-2.6`: Not supported * `kling-3.0`: Toggle-able: audio adds extra credits when enabled * `ltx-2.3`: Toggle-able: no additional credits for audio * `minimax-h3`: Toggle-able: no additional credits for audio * `seedance-1.5`: Toggle-able: audio adds extra credits when enabled * `seedance-2.0`: Toggle-able: no additional credits for audio * `seedance-2.0-mini`: Toggle-able: no additional credits for audio * `seedance-2.5`: Toggle-able: no additional credits for audio * `sora-2`: Toggle-able: no additional credits for audio * `veo3.1`: Toggle-able: audio adds extra credits when enabled * `veo3.1-lite`: Toggle-able: audio adds extra credits when enabled * `wan-2.2`: Not supported
style	object	optional	Attributed used to dictate the style of the output
assets	object	required	Provide the assets for image-to-video. Sora 2 only supports images with an aspect ratio of `9:16` or `16:9`.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Image To Video - dateTime",
      "example": "My Image To Video video"
    },
    "end_seconds": {
      "maximum": 60,
      "minimum": 1,
      "type": "number",
      "description": "The total duration of the output video in seconds. Supported durations depend on the chosen model:\n\n* **`kling-2.6`**: 5, 10\n* **`kling-3.0`**: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15\n* **`ltx-2.3`**: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30\n* **`minimax-h3`**: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30\n* **`seedance-1.5`**: 4, 5, 6, 7, 8, 9, 10, 11, 12\n* **`seedance-2.0`**: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15\n* **`seedance-2.0-mini`**: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15\n* **`seedance-2.5`**: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30\n* **`sora-2`**: 4, 8, 12, 24, 36, 48, 60\n* **`veo3.1`**: 4, 6, 8, 16, 24, 32, 40, 48, 56\n* **`veo3.1-lite`**: 4, 6, 8, 16, 24, 32, 40, 48, 56\n* **`wan-2.2`**: 3, 4, 5, 6, 7, 8, 9, 10, 15\n",
      "format": "float",
      "example": 5
    },
    "model": {
      "enum": [
        "default",
        "ltx-2",
        "ltx-2.3",
        "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",
        "veo3.1",
        "veo3.1-lite",
        "sora-2",
        "kling-1.6",
        "seedance",
        "kling-2.5-audio",
        "veo3.1-audio"
      ],
      "type": "string",
      "description": "The AI model to use for video generation.\n\n* `default`: uses our currently recommended model for general use. For paid tiers, defaults to `kling-3.0`. For free tiers, it defaults to `ltx-2.3`.\n* `kling-2.6`: Great for action, motion blur, and camera moves.\n* `kling-3.0`: Best overall quality for cinematic storytelling.\n* `ltx-2.3`: Fastest output. Best for rapid iteration.\n* `minimax-h3`: Reference-driven video with native audio.\n* `seedance-1.5`: Smooth, consistent motion with precision.\n* `seedance-2.0`: Top quality with reference-to-video control.\n* `seedance-2.0-mini`: Fast, consistent video with strong motion quality\n* `seedance-2.5`: Highest quality with superior realism, detail, and motion\n* `sora-2`: Open AI's model. Great for creativity and viral clips.\n* `veo3.1`: Google's model. Highest realism and detail.\n* `veo3.1-lite`: Veo quality at a more accessible cost.\n* `wan-2.2`: Strong physics, camera moves, and motion.\n\nIf you specify the deprecated model value that includes the `-audio` suffix, this will be the same as included `audio` as `true`.",
      "default": "default",
      "example": "kling-3.0"
    },
    "resolution": {
      "enum": [
        "480p",
        "720p",
        "1080p",
        "4k"
      ],
      "type": "string",
      "description": "Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers.\n\n* **`kling-2.6`**: Supports 720p, 1080p.\n* **`kling-3.0`**: Supports 720p, 1080p, 4k.\n* **`ltx-2.3`**: Supports 480p, 720p, 1080p.\n* **`minimax-h3`**: Supports 480p, 720p, 1080p.\n* **`seedance-1.5`**: Supports 480p, 720p, 1080p.\n* **`seedance-2.0`**: Supports 480p, 720p.\n* **`seedance-2.0-mini`**: Supports 480p, 720p.\n* **`seedance-2.5`**: Supports 480p, 720p.\n* **`sora-2`**: Supports 720p.\n* **`veo3.1`**: Supports 720p, 1080p.\n* **`veo3.1-lite`**: Supports 720p, 1080p.\n* **`wan-2.2`**: Supports 480p, 720p, 1080p.\n",
      "example": "720p"
    },
    "audio": {
      "type": "boolean",
      "description": "Whether to include audio in the video. Defaults to `false` if not specified.\n\nAudio support varies by model:\n* **`kling-2.6`**: Not supported\n* **`kling-3.0`**: Toggle-able: audio adds extra credits when enabled\n* **`ltx-2.3`**: Toggle-able: no additional credits for audio\n* **`minimax-h3`**: Toggle-able: no additional credits for audio\n* **`seedance-1.5`**: Toggle-able: audio adds extra credits when enabled\n* **`seedance-2.0`**: Toggle-able: no additional credits for audio\n* **`seedance-2.0-mini`**: Toggle-able: no additional credits for audio\n* **`seedance-2.5`**: Toggle-able: no additional credits for audio\n* **`sora-2`**: Toggle-able: no additional credits for audio\n* **`veo3.1`**: Toggle-able: audio adds extra credits when enabled\n* **`veo3.1-lite`**: Toggle-able: audio adds extra credits when enabled\n* **`wan-2.2`**: Not supported\n",
      "example": true
    },
    "style": {
      "type": "object",
      "properties": {
        "prompt": {
          "type": "string",
          "description": "The prompt used for the video.",
          "example": "a dog running"
        }
      },
      "description": "Attributed used to dictate the style of the output"
    },
    "assets": {
      "required": [
        "image_file_path"
      ],
      "type": "object",
      "properties": {
        "image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The path of the image file. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        },
        "end_image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The image to use as the last frame of the video.\n\n* **`kling-2.6`**: Supports 1080p.\n* **`kling-3.0`**: Supports 720p, 1080p, 4k.\n* **`ltx-2.3`**: Supports 480p, 720p, 1080p.\n* **`minimax-h3`**: Not supported\n* **`seedance-1.5`**: Supports 480p, 720p, 1080p.\n* **`seedance-2.0`**: Supports 480p, 720p.\n* **`seedance-2.0-mini`**: Supports 480p, 720p.\n* **`seedance-2.5`**: Supports 480p, 720p.\n* **`sora-2`**: Not supported\n* **`veo3.1`**: Supports 720p, 1080p. Requires a duration of 8 seconds or less.\n* **`veo3.1-lite`**: Supports 720p, 1080p. Requires a duration of 8 seconds or less.\n* **`wan-2.2`**: Not supported\n",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the assets for image-to-video. Sora 2 only supports images with an aspect ratio of `9:16` or `16:9`."
    }
  },
  "required": [
    "end_seconds",
    "assets"
  ]
}

lip_sync_create_video

**What this API does** Create the same Lip Sync you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding lip sync into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a lip sync job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: see the request schema for endpoint-specific assets - Resolution: free users default to 480p; higher plans unlock HD and larger sizes - Extra fields: see the request schema for endpoint-specific options **Cost** Credits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done. For detailed examples, see the [product page](https://magichour.ai/products/lip-sync). MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters6

name	string	optional	Give your video a custom name for easy identification.
start_seconds	number	required	Start time of your clip (seconds). Must be ≥ 0.
end_seconds	number	required	End time of your clip (seconds). Must be greater than start_seconds.
max_fps_limit	number	optional	Defines the maximum FPS (frames per second) for the output video. If the input video's FPS is lower than this limit, the output video will retain the input FPS. This is useful for reducing unnecessary frame usage in scenarios where high FPS is not required.
assets	object	required	Provide the assets for lip-sync. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used
style	object	optional	Attributes used to dictate the style of the output

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Lip Sync - dateTime",
      "example": "My Lip Sync video"
    },
    "start_seconds": {
      "minimum": 0,
      "type": "number",
      "description": "Start time of your clip (seconds). Must be ≥ 0.",
      "format": "float",
      "example": 0
    },
    "end_seconds": {
      "minimum": 0.1,
      "type": "number",
      "description": "End time of your clip (seconds). Must be greater than start_seconds.",
      "format": "float",
      "example": 15
    },
    "max_fps_limit": {
      "minimum": 1,
      "type": "number",
      "description": "Defines the maximum FPS (frames per second) for the output video. If the input video's FPS is lower than this limit, the output video will retain the input FPS. This is useful for reducing unnecessary frame usage in scenarios where high FPS is not required.",
      "example": 12
    },
    "assets": {
      "required": [
        "audio_file_path",
        "video_source"
      ],
      "type": "object",
      "properties": {
        "audio_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The path of the audio file. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp3"
        },
        "video_source": {
          "enum": [
            "file",
            "youtube"
          ],
          "type": "string",
          "description": "Choose your video source.",
          "example": "file"
        },
        "video_file_path": {
          "type": "string",
          "description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp4"
        },
        "youtube_url": {
          "type": "string",
          "description": "YouTube URL (required if `video_source` is `youtube`).",
          "format": "uri"
        }
      },
      "description": "Provide the assets for lip-sync. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used"
    },
    "style": {
      "type": "object",
      "properties": {
        "generation_mode": {
          "enum": [
            "lite",
            "standard",
            "pro"
          ],
          "type": "string",
          "description": "A specific version of our lip sync system, optimized for different needs.\n* `lite` -  Fast and affordable lip sync - best for simple videos. Costs 1 credit per frame of video.\n* `standard` -  Natural, accurate lip sync - best for most creators. Costs 1 credit per frame of video.\n* `pro` -  Premium fidelity with enhanced detail - best for professionals. Costs 2 credits per frame of video.\n\nNote: `standard` and `pro` are only available for users on Creator, Pro, and Business tiers.\n              ",
          "default": "lite",
          "example": "lite"
        }
      },
      "description": "Attributes used to dictate the style of the output"
    }
  },
  "required": [
    "start_seconds",
    "end_seconds",
    "assets"
  ]
}

text_to_video_create_video

**What this API does** Create the same Text To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding text to video into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a text to video job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: see the request schema for endpoint-specific assets - Resolution: free users default to 480p; higher plans unlock HD and larger sizes - Extra fields: see the request schema for endpoint-specific options **Cost** Credits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done. For detailed examples, see the [product page](https://magichour.ai/products/text-to-video). MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.

Parameters7

name	string	optional	Give your video a custom name for easy identification.
end_seconds	number	required	The total duration of the output video in seconds. Supported durations depend on the chosen model: * `kling-2.6`: 5, 10 * `kling-3.0`: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 * `ltx-2.3`: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30 * `minimax-h3`: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30 * `seedance-1.5`: 4, 5, 6, 7, 8, 9, 10, 11, 12 * `seedance-2.0`: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 * `seedance-2.0-mini`: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 * `seedance-2.5`: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 * `sora-2`: 4, 8, 12, 24, 36, 48, 60 * `veo3.1`: 4, 6, 8, 16, 24, 32, 40, 48, 56 * `veo3.1-lite`: 4, 6, 8, 16, 24, 32, 40, 48, 56 * `wan-2.2`: 3, 4, 5, 6, 7, 8, 9, 10, 15
aspect_ratio	string	optional	Determines the aspect ratio of the output video. * `kling-2.6`: Supports 9:16, 16:9, 1:1. * `kling-3.0`: Supports 9:16, 16:9, 1:1. * `ltx-2.3`: Supports 9:16, 16:9, 1:1. * `minimax-h3`: Supports 16:9, 9:16, 1:1. * `seedance-1.5`: Supports 9:16, 16:9, 1:1. * `seedance-2.0`: Supports 9:16, 16:9, 1:1. * `seedance-2.0-mini`: Supports 9:16, 16:9, 1:1. * `seedance-2.5`: Supports 9:16, 16:9, 1:1. * `sora-2`: Supports 9:16, 16:9. * `veo3.1`: Supports 9:16, 16:9. * `veo3.1-lite`: Supports 9:16, 16:9. * `wan-2.2`: Supports 9:16, 16:9, 1:1.
resolution	string	optional	Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers. * `kling-2.6`: Supports 720p, 1080p. * `kling-3.0`: Supports 720p, 1080p, 4k. * `ltx-2.3`: Supports 480p, 720p, 1080p. * `minimax-h3`: Supports 480p, 720p, 1080p. * `seedance-1.5`: Supports 480p, 720p, 1080p. * `seedance-2.0`: Supports 480p, 720p. * `seedance-2.0-mini`: Supports 480p, 720p. * `seedance-2.5`: Supports 480p, 720p. * `sora-2`: Supports 720p. * `veo3.1`: Supports 720p, 1080p. * `veo3.1-lite`: Supports 720p, 1080p. * `wan-2.2`: Supports 480p, 720p, 1080p.
model	string	optional	The AI model to use for video generation. * `default`: uses our currently recommended model for general use. For paid tiers, defaults to `kling-3.0`. For free tiers, it defaults to `ltx-2.3`. * `kling-2.6`: Great for action, motion blur, and camera moves. * `kling-3.0`: Best overall quality for cinematic storytelling. * `ltx-2.3`: Fastest output. Best for rapid iteration. * `minimax-h3`: Reference-driven video with native audio. * `seedance-1.5`: Smooth, consistent motion with precision. * `seedance-2.0`: Top quality with reference-to-video control. * `seedance-2.0-mini`: Fast, consistent video with strong motion quality * `seedance-2.5`: Highest quality with superior realism, detail, and motion * `sora-2`: Open AI's model. Great for creativity and viral clips. * `veo3.1`: Google's model. Highest realism and detail. * `veo3.1-lite`: Veo quality at a more accessible cost. * `wan-2.2`: Strong physics, camera moves, and motion. If you specify the deprecated model value that includes the `-audio` suffix, this will be the same as included `audio` as `true`.
audio	boolean	optional	Whether to include audio in the video. Defaults to `false` if not specified. Audio support varies by model: * `kling-2.6`: Not supported * `kling-3.0`: Toggle-able: audio adds extra credits when enabled * `ltx-2.3`: Toggle-able: no additional credits for audio * `minimax-h3`: Toggle-able: no additional credits for audio * `seedance-1.5`: Toggle-able: audio adds extra credits when enabled * `seedance-2.0`: Toggle-able: no additional credits for audio * `seedance-2.0-mini`: Toggle-able: no additional credits for audio * `seedance-2.5`: Toggle-able: no additional credits for audio * `sora-2`: Toggle-able: no additional credits for audio * `veo3.1`: Toggle-able: audio adds extra credits when enabled * `veo3.1-lite`: Toggle-able: audio adds extra credits when enabled * `wan-2.2`: Not supported
style	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Text To Video - dateTime",
      "example": "My Text To Video video"
    },
    "end_seconds": {
      "maximum": 60,
      "minimum": 1,
      "type": "number",
      "description": "The total duration of the output video in seconds. Supported durations depend on the chosen model:\n\n* **`kling-2.6`**: 5, 10\n* **`kling-3.0`**: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15\n* **`ltx-2.3`**: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30\n* **`minimax-h3`**: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30\n* **`seedance-1.5`**: 4, 5, 6, 7, 8, 9, 10, 11, 12\n* **`seedance-2.0`**: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15\n* **`seedance-2.0-mini`**: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15\n* **`seedance-2.5`**: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30\n* **`sora-2`**: 4, 8, 12, 24, 36, 48, 60\n* **`veo3.1`**: 4, 6, 8, 16, 24, 32, 40, 48, 56\n* **`veo3.1-lite`**: 4, 6, 8, 16, 24, 32, 40, 48, 56\n* **`wan-2.2`**: 3, 4, 5, 6, 7, 8, 9, 10, 15\n",
      "format": "float",
      "example": 5
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "9:16",
        "1:1"
      ],
      "type": "string",
      "description": "Determines the aspect ratio of the output video.\n\n* **`kling-2.6`**: Supports 9:16, 16:9, 1:1.\n* **`kling-3.0`**: Supports 9:16, 16:9, 1:1.\n* **`ltx-2.3`**: Supports 9:16, 16:9, 1:1.\n* **`minimax-h3`**: Supports 16:9, 9:16, 1:1.\n* **`seedance-1.5`**: Supports 9:16, 16:9, 1:1.\n* **`seedance-2.0`**: Supports 9:16, 16:9, 1:1.\n* **`seedance-2.0-mini`**: Supports 9:16, 16:9, 1:1.\n* **`seedance-2.5`**: Supports 9:16, 16:9, 1:1.\n* **`sora-2`**: Supports 9:16, 16:9.\n* **`veo3.1`**: Supports 9:16, 16:9.\n* **`veo3.1-lite`**: Supports 9:16, 16:9.\n* **`wan-2.2`**: Supports 9:16, 16:9, 1:1.\n",
      "example": "16:9"
    },
    "resolution": {
      "enum": [
        "480p",
        "720p",
        "1080p",
        "4k"
      ],
      "type": "string",
      "description": "Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers.\n\n* **`kling-2.6`**: Supports 720p, 1080p.\n* **`kling-3.0`**: Supports 720p, 1080p, 4k.\n* **`ltx-2.3`**: Supports 480p, 720p, 1080p.\n* **`minimax-h3`**: Supports 480p, 720p, 1080p.\n* **`seedance-1.5`**: Supports 480p, 720p, 1080p.\n* **`seedance-2.0`**: Supports 480p, 720p.\n* **`seedance-2.0-mini`**: Supports 480p, 720p.\n* **`seedance-2.5`**: Supports 480p, 720p.\n* **`sora-2`**: Supports 720p.\n* **`veo3.1`**: Supports 720p, 1080p.\n* **`veo3.1-lite`**: Supports 720p, 1080p.\n* **`wan-2.2`**: Supports 480p, 720p, 1080p.\n",
      "example": "720p"
    },
    "model": {
      "enum": [
        "default",
        "ltx-2",
        "ltx-2.3",
        "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",
        "veo3.1",
        "veo3.1-lite",
        "sora-2",
        "kling-1.6",
        "seedance",
        "kling-2.5-audio",
        "veo3.1-audio"
      ],
      "type": "string",
      "description": "The AI model to use for video generation.\n\n* `default`: uses our currently recommended model for general use. For paid tiers, defaults to `kling-3.0`. For free tiers, it defaults to `ltx-2.3`.\n* `kling-2.6`: Great for action, motion blur, and camera moves.\n* `kling-3.0`: Best overall quality for cinematic storytelling.\n* `ltx-2.3`: Fastest output. Best for rapid iteration.\n* `minimax-h3`: Reference-driven video with native audio.\n* `seedance-1.5`: Smooth, consistent motion with precision.\n* `seedance-2.0`: Top quality with reference-to-video control.\n* `seedance-2.0-mini`: Fast, consistent video with strong motion quality\n* `seedance-2.5`: Highest quality with superior realism, detail, and motion\n* `sora-2`: Open AI's model. Great for creativity and viral clips.\n* `veo3.1`: Google's model. Highest realism and detail.\n* `veo3.1-lite`: Veo quality at a more accessible cost.\n* `wan-2.2`: Strong physics, camera moves, and motion.\n\nIf you specify the deprecated model value that includes the `-audio` suffix, this will be the same as included `audio` as `true`.",
      "default": "default",
      "example": "kling-3.0"
    },
    "audio": {
      "type": "boolean",
      "description": "Whether to include audio in the video. Defaults to `false` if not specified.\n\nAudio support varies by model:\n* **`kling-2.6`**: Not supported\n* **`kling-3.0`**: Toggle-able: audio adds extra credits when enabled\n* **`ltx-2.3`**: Toggle-able: no additional credits for audio\n* **`minimax-h3`**: Toggle-able: no additional credits for audio\n* **`seedance-1.5`**: Toggle-able: audio adds extra credits when enabled\n* **`seedance-2.0`**: Toggle-able: no additional credits for audio\n* **`seedance-2.0-mini`**: Toggle-able: no additional credits for audio\n* **`seedance-2.5`**: Toggle-able: no additional credits for audio\n* **`sora-2`**: Toggle-able: no additional credits for audio\n* **`veo3.1`**: Toggle-able: audio adds extra credits when enabled\n* **`veo3.1-lite`**: Toggle-able: audio adds extra credits when enabled\n* **`wan-2.2`**: Not supported\n",
      "example": true
    },
    "style": {
      "required": [
        "prompt"
      ],
      "type": "object",
      "properties": {
        "prompt": {
          "maxLength": 2000,
          "minLength": 1,
          "type": "string",
          "description": "The prompt used for the video.",
          "example": "a dog running"
        }
      }
    }
  },
  "required": [
    "end_seconds",
    "style"
  ]
}

video_to_video_create_video

**What this API does** Create the same Video To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding video to video into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a video to video job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: see the request schema for endpoint-specific assets - Resolution: free users default to 480p; higher plans unlock HD and larger sizes - Extra fields: see the request schema for endpoint-specific options **Cost** Credits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done. For detailed examples, see the [product page](https://magichour.ai/products/video-to-video). MCP guidance: - This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters6

name	string	optional	Give your video a custom name for easy identification.
start_seconds	number	required	Start time of your clip (seconds). Must be ≥ 0.
end_seconds	number	required	End time of your clip (seconds). Must be greater than start_seconds.
fps_resolution	string	optional	Determines whether the resulting video will have the same frame per second as the original video, or half. * `FULL` - the result video will have the same FPS as the input video * `HALF` - the result video will have half the FPS as the input video
style	object	required
assets	object	required	Provide the assets for video-to-video. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your video a custom name for easy identification.",
      "default": "Video To Video - dateTime",
      "example": "My Video To Video video"
    },
    "start_seconds": {
      "minimum": 0,
      "type": "number",
      "description": "Start time of your clip (seconds). Must be ≥ 0.",
      "format": "float",
      "example": 0
    },
    "end_seconds": {
      "minimum": 0.1,
      "type": "number",
      "description": "End time of your clip (seconds). Must be greater than start_seconds.",
      "format": "float",
      "example": 15
    },
    "fps_resolution": {
      "enum": [
        "FULL",
        "HALF"
      ],
      "type": "string",
      "description": "Determines whether the resulting video will have the same frame per second as the original video, or half.\n* `FULL` - the result video will have the same FPS as the input video\n* `HALF` - the result video will have half the FPS as the input video",
      "default": "HALF",
      "example": "HALF"
    },
    "style": {
      "required": [
        "art_style"
      ],
      "type": "object",
      "properties": {
        "art_style": {
          "enum": [
            "Minecraft",
            "Watercolor",
            "Pixel",
            "Retro Sci-Fi",
            "Lego",
            "Origami",
            "Ghost",
            "Sub-Zero",
            "Studio Ghibli",
            "Comic",
            "Impressionism",
            "Master Chief",
            "Solid Snake",
            "Street Fighter",
            "Hologram",
            "GTA",
            "Clay",
            "Mystique",
            "Dragonball Z",
            "Mario",
            "Samurai",
            "Spartan",
            "Boba Fett",
            "3D Render",
            "Airbender",
            "Android",
            "Anime Warrior",
            "Armored Knight",
            "Assassin's Creed",
            "Avatar",
            "Black Spiderman",
            "Bold Anime",
            "Celestial Skin",
            "Chinese Swordsmen",
            "Cyberpunk",
            "Cypher",
            "Dark Fantasy",
            "Future Bot",
            "Futuristic Fantasy",
            "Ghibli Anime",
            "Gundam",
            "Illustration",
            "Ink",
            "Ink Poster",
            "Jinx",
            "Knight",
            "Link",
            "Marble",
            "Mech",
            "Naruto",
            "Neon Dream",
            "No Art Style",
            "Oil Painting",
            "On Fire",
            "Painterly Anime",
            "Pixar",
            "Power Armor",
            "Power Ranger",
            "Radiant Anime",
            "Realistic Anime",
            "Realistic Pixar",
            "Retro Anime",
            "Samurai Bot",
            "Sharp Anime",
            "Soft Anime",
            "Starfield",
            "The Void",
            "Tomb Raider",
            "Underwater",
            "Van Gogh",
            "Viking",
            "Western Anime",
            "Wu Kong",
            "Wuxia Anime",
            "Zelda"
          ],
          "type": "string"
        },
        "version": {
          "enum": [
            "v1",
            "v2",
            "default"
          ],
          "type": "string",
          "description": "* `v1` - more detail, closer prompt adherence, and frame-by-frame previews.\n* `v2` - faster, more consistent, and less noisy.\n* `default` - use the default version for the selected art style.",
          "default": "default",
          "example": "default"
        },
        "prompt_type": {
          "enum": [
            "default",
            "custom",
            "append_default"
          ],
          "type": "string",
          "description": "* `default` - Use the default recommended prompt for the art style.\n* `custom` - Only use the prompt passed in the API. Note: for v1, lora prompt will still be auto added to apply the art style properly.\n* `append_default` - Add the default recommended prompt to the end of the prompt passed in the API.",
          "default": "default",
          "example": "default"
        },
        "prompt": {
          "type": [
            "string",
            "null"
          ],
          "description": "The prompt used for the video. Prompt is required if `prompt_type` is `custom` or `append_default`. If `prompt_type` is `default`, then the `prompt` value passed will be ignored."
        },
        "model": {
          "enum": [
            "Dreamshaper",
            "Absolute Reality",
            "Flat 2D Anime",
            "Soft Anime",
            "Kaywaii",
            "Western Anime",
            "3D Anime",
            "default"
          ],
          "type": "string",
          "description": "* `Dreamshaper` - a good all-around model that works for both animations as well as realism.\n* `Absolute Reality` - better at realism, but you'll often get similar results with Dreamshaper as well.\n* `Flat 2D Anime` - best for a flat illustration style that's common in most anime.\n* `default` - use the default recommended model for the selected art style.",
          "default": "default",
          "example": "default"
        }
      }
    },
    "assets": {
      "required": [
        "video_source"
      ],
      "type": "object",
      "properties": {
        "video_source": {
          "enum": [
            "file",
            "youtube"
          ],
          "type": "string",
          "description": "Choose your video source.",
          "example": "file"
        },
        "video_file_path": {
          "type": "string",
          "description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp4"
        },
        "youtube_url": {
          "type": "string",
          "description": "YouTube URL (required if `video_source` is `youtube`).",
          "format": "uri"
        }
      },
      "description": "Provide the assets for video-to-video. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used"
    }
  },
  "required": [
    "start_seconds",
    "end_seconds",
    "style",
    "assets"
  ]
}

image_projects_retrieve_details

Check the progress of a image project. The `downloads` field is populated after a successful render. **Statuses** - `queued` — waiting to start - `rendering` — in progress - `complete` — ready; see `downloads` - `error` — a failure occurred (see `error`) - `canceled` — user canceled - `draft` — not used MCP guidance: - Use this after a create tool to poll job status. When status is `complete`, surface the `downloads` URLs to the user; if status is `error`, surface the error message. - Each `downloads[n].url` is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append `expires_at` onto the URL string.

Parameters1

string

required

Unique ID of the image project. This value is returned by all of the POST APIs that create an image.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "cuid-example",
      "description": "Unique ID of the image project. This value is returned by all of the POST APIs that create an image."
    }
  },
  "required": [
    "id"
  ]
}

image_projects_delete

Permanently delete the rendered image(s). This action is not reversible, please be sure before deleting.

Parameters1

string

required

Unique ID of the image project. This value is returned by all of the POST APIs that create an image.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "cuid-example",
      "description": "Unique ID of the image project. This value is returned by all of the POST APIs that create an image."
    }
  },
  "required": [
    "id"
  ]
}

ai_clothes_changer_create_image

Change outfits in photos in seconds with just a photo reference. Each photo costs 25 credits. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters2

name	string	optional	Give your image a custom name for easy identification.
assets	object	required	Provide the assets for clothes changer

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Clothes Changer - dateTime",
      "example": "My Clothes Changer image"
    },
    "assets": {
      "required": [
        "person_file_path",
        "garment_file_path"
      ],
      "type": "object",
      "properties": {
        "person_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The image with the person. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/model.png"
        },
        "garment_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The image of the outfit. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/outfit.png"
        },
        "garment_type": {
          "enum": [
            "entire_outfit",
            "upper_body",
            "lower_body",
            "dresses"
          ],
          "type": "string",
          "description": "Type of garment to swap. If not provided, swaps the entire outfit. \n* `upper_body` - for shirts/jackets \n* `lower_body` - for pants/skirts \n* `dresses` - for entire outfit (deprecated, use `entire_outfit` instead) \n* `entire_outfit` - for entire outfit",
          "example": "entire_outfit"
        }
      },
      "description": "Provide the assets for clothes changer"
    }
  },
  "required": [
    "assets"
  ]
}

ai_face_editor_edit_image

Edit facial features of an image using AI. Each edit costs 1 frame. The height/width of the output image depends on your subscription. Please refer to our [pricing](https://magichour.ai/pricing) page for more details MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters3

name	string	optional	Give your image a custom name for easy identification.
assets	object	required	Provide the assets for face editor
style	object	required	Face editing parameters

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Face Editor - dateTime",
      "example": "My Face Editor image"
    },
    "assets": {
      "required": [
        "image_file_path"
      ],
      "type": "object",
      "properties": {
        "image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "This is the image whose face will be edited. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the assets for face editor"
    },
    "style": {
      "type": "object",
      "properties": {
        "enhance_face": {
          "type": "boolean",
          "description": "Enhance face features",
          "default": false,
          "example": false
        },
        "eyebrow_direction": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Eyebrow direction (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "eye_gaze_horizontal": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Horizontal eye gaze (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "eye_gaze_vertical": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Vertical eye gaze (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "eye_open_ratio": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Eye open ratio (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "lip_open_ratio": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Lip open ratio (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "head_roll": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Head roll (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "mouth_grim": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Mouth grim (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "mouth_pout": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Mouth pout (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "mouth_purse": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Mouth purse (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "mouth_smile": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Mouth smile (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "mouth_position_horizontal": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Horizontal mouth position (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "mouth_position_vertical": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Vertical mouth position (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "head_pitch": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Head pitch (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        },
        "head_yaw": {
          "multipleOf": 5,
          "maximum": 100,
          "minimum": -100,
          "type": "number",
          "description": "Head yaw (-100 to 100), in increments of 5",
          "default": 0,
          "example": 0
        }
      },
      "description": "Face editing parameters"
    }
  },
  "required": [
    "assets",
    "style"
  ]
}

ai_gif_generator_create_image

Create an AI GIF. Each GIF costs 50 credits. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.

Parameters3

name	string	optional	Give your gif a custom name for easy identification.
style	object	required
output_format	string	optional	The output file format for the generated animation.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your gif a custom name for easy identification.",
      "default": "Ai Gif - dateTime",
      "example": "My Ai Gif gif"
    },
    "style": {
      "required": [
        "prompt"
      ],
      "type": "object",
      "properties": {
        "prompt": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string",
          "description": "The prompt used for the GIF.",
          "example": "Cute dancing cat, pixel art"
        }
      }
    },
    "output_format": {
      "enum": [
        "gif",
        "mp4",
        "webm"
      ],
      "type": "string",
      "description": "The output file format for the generated animation.",
      "default": "gif",
      "example": "gif"
    }
  },
  "required": [
    "style"
  ]
}

ai_image_editor_create_image

Edit images with AI. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters7

name	string	optional	Give your image a custom name for easy identification.
image_count	number	optional	Number of images to generate. Maximum varies by model. Defaults to 1 if not specified.
model	string	optional	The AI model to use for image editing. Each model has different capabilities and costs. Models: - `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior. - `flux-2-klein` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Max additional input images: 5 - `gpt-image-2` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-2` - from 100 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-2-lite` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-pro` - from 150 credits/image - Supported resolutions: 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `qwen-edit` - from 10 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Max additional input images: 2 - `seedream-v4` - from 40 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `seedream-v4.5` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `seedream-v5-pro` - from 75 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: creator, pro, business - Max additional input images: 9
aspect_ratio	string	optional	The aspect ratio of the output image(s). If not specified, defaults to `auto`.
resolution	string	optional	Maximum resolution (longest edge) for the output image. Options: - `640px` — up to 640px - `1k` — up to 1024px - `2k` — up to 2048px - `4k` — up to 4096px - `auto` — Deprecated. Mapped server-side from your subscription tier to the best matching resolution the model supports Per-model support: - `flux-2-klein` - 640px, 1k, 2k - `gpt-image-2` - 640px, 1k, 2k, 4k - `nano-banana` - 640px, 1k - `nano-banana-2` - 640px, 1k, 2k, 4k - `nano-banana-2-lite` - 640px, 1k - `nano-banana-pro` - 1k, 2k, 4k - `qwen-edit` - 640px, 1k, 2k - `seedream-v4` - 640px, 1k, 2k, 4k - `seedream-v4.5` - 640px, 1k, 2k, 4k - `seedream-v5-pro` - 640px, 1k, 2k Note: Resolution availability depends on the model and your subscription tier.
style	object	required
assets	object	required	Provide the assets for image edit

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Ai Image Editor - dateTime",
      "example": "My Ai Image Editor image"
    },
    "image_count": {
      "enum": [
        1,
        4,
        9,
        16
      ],
      "type": "number",
      "description": "Number of images to generate. Maximum varies by model. Defaults to 1 if not specified.",
      "default": 1,
      "example": 1
    },
    "model": {
      "enum": [
        "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"
      ],
      "type": "string",
      "description": "The AI model to use for image editing. Each model has different capabilities and costs.\n\n**Models:**\n- `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior.\n- `flux-2-klein` - from 5 credits/image\n  - Supported resolutions: 640px, 1k, 2k\n  - Available for tiers: free, creator, pro, business\n  - Max additional input images: 5\n- `gpt-image-2` - from 50 credits/image\n  - Supported resolutions: 640px, 1k, 2k, 4k\n  - Available for tiers: creator, pro, business\n  - Max additional input images: 9\n- `nano-banana` - from 50 credits/image\n  - Supported resolutions: 640px, 1k\n  - Available for tiers: creator, pro, business\n  - Max additional input images: 9\n- `nano-banana-2` - from 100 credits/image\n  - Supported resolutions: 640px, 1k, 2k, 4k\n  - Available for tiers: creator, pro, business\n  - Max additional input images: 9\n- `nano-banana-2-lite` - from 50 credits/image\n  - Supported resolutions: 640px, 1k\n  - Available for tiers: creator, pro, business\n  - Max additional input images: 9\n- `nano-banana-pro` - from 150 credits/image\n  - Supported resolutions: 1k, 2k, 4k\n  - Available for tiers: creator, pro, business\n  - Max additional input images: 9\n- `qwen-edit` - from 10 credits/image\n  - Supported resolutions: 640px, 1k, 2k\n  - Available for tiers: free, creator, pro, business\n  - Max additional input images: 2\n- `seedream-v4` - from 40 credits/image\n  - Supported resolutions: 640px, 1k, 2k, 4k\n  - Available for tiers: creator, pro, business\n  - Max additional input images: 9\n- `seedream-v4.5` - from 50 credits/image\n  - Supported resolutions: 640px, 1k, 2k, 4k\n  - Available for tiers: creator, pro, business\n  - Max additional input images: 9\n- `seedream-v5-pro` - from 75 credits/image\n  - Supported resolutions: 640px, 1k, 2k\n  - Available for tiers: creator, pro, business\n  - Max additional input images: 9\n",
      "example": "default"
    },
    "aspect_ratio": {
      "enum": [
        "auto",
        "16:9",
        "9:16",
        "4:3",
        "3:2",
        "1:1",
        "4:5",
        "2:3"
      ],
      "type": "string",
      "description": "The aspect ratio of the output image(s). If not specified, defaults to `auto`.",
      "example": "1:1"
    },
    "resolution": {
      "enum": [
        "auto",
        "640px",
        "1k",
        "2k",
        "4k"
      ],
      "type": "string",
      "description": "Maximum resolution (longest edge) for the output image.\n\n**Options:**\n- `640px` — up to 640px\n- `1k` — up to 1024px\n- `2k` — up to 2048px\n- `4k` — up to 4096px\n- `auto` — **Deprecated.** Mapped server-side from your subscription tier to the best matching resolution the model supports\n\n**Per-model support:**\n- `flux-2-klein` - 640px, 1k, 2k\n- `gpt-image-2` - 640px, 1k, 2k, 4k\n- `nano-banana` - 640px, 1k\n- `nano-banana-2` - 640px, 1k, 2k, 4k\n- `nano-banana-2-lite` - 640px, 1k\n- `nano-banana-pro` - 1k, 2k, 4k\n- `qwen-edit` - 640px, 1k, 2k\n- `seedream-v4` - 640px, 1k, 2k, 4k\n- `seedream-v4.5` - 640px, 1k, 2k, 4k\n- `seedream-v5-pro` - 640px, 1k, 2k\n\nNote: Resolution availability depends on the model and your subscription tier.",
      "example": "1k"
    },
    "style": {
      "required": [
        "prompt"
      ],
      "type": "object",
      "properties": {
        "prompt": {
          "maxLength": 15000,
          "minLength": 1,
          "type": "string",
          "description": "The prompt used to edit the image.",
          "example": "Give me sunglasses"
        }
      }
    },
    "assets": {
      "type": "object",
      "properties": {
        "image_file_paths": {
          "maxItems": 10,
          "type": "array",
          "items": {
            "minLength": 1,
            "type": "string"
          },
          "description": "The image(s) used in the edit, maximum of 10 images. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": [
            "api-assets/id/1234.png",
            "api-assets/id/1235.png"
          ]
        }
      },
      "description": "Provide the assets for image edit"
    }
  },
  "required": [
    "style",
    "assets"
  ]
}

ai_headshot_generator_create_image

Create an AI headshot. Each headshot costs 50 credits. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters3

name	string	optional	Give your image a custom name for easy identification.
style	object	optional
assets	object	required	Provide the assets for headshot photo

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Ai Headshot - dateTime",
      "example": "My Ai Headshot image"
    },
    "style": {
      "type": "object",
      "properties": {
        "prompt": {
          "type": "string",
          "description": "Prompt used to guide the style of your headshot. We recommend omitting the prompt unless you want to customize your headshot. You can visit [AI headshot generator](https://magichour.ai/create/ai-headshot-generator) to view an example of a good prompt used for our 'Professional' style."
        }
      }
    },
    "assets": {
      "required": [
        "image_file_path"
      ],
      "type": "object",
      "properties": {
        "image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The image used to generate the headshot. This image must contain one detectable face. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the assets for headshot photo"
    }
  },
  "required": [
    "assets"
  ]
}

ai_image_generator_create_image

Create an AI image with advanced model selection and quality controls. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.

Parameters6

name	string	optional	Give your image a custom name for easy identification.
image_count	integer	required	Number of images to generate. Maximum varies by model.
model	string	optional	The AI model to use for image generation. Each model has different capabilities and costs. Models: - `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior. - `flux-2-klein` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Image count allowed: 1 - `flux-schnell` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 2, 3, 4 - `gpt-image-2` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `nano-banana` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `nano-banana-2` - from 100 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 4, 9, 16 - `nano-banana-2-lite` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `nano-banana-pro` - from 150 credits/image - Supported resolutions: 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 4, 9, 16 - `seedream-v4` - from 40 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `seedream-v5-pro` - from 75 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `z-image-turbo` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 2, 3, 4 Deprecated Enum Values: - `seedream` - Use `seedream-v4` instead.
aspect_ratio	string	optional	The aspect ratio of the output image(s). If not specified, defaults to `1:1` (square).
resolution	string	optional	Maximum resolution (longest edge) for the output image. Options: - `640px` — up to 640px - `1k` — up to 1024px - `2k` — up to 2048px - `4k` — up to 4096px - `auto` — Deprecated. Mapped server-side from your subscription tier to the best matching resolution the model supports Per-model support: - `flux-2-klein` - 640px, 1k, 2k - `flux-schnell` - 640px, 1k, 2k - `gpt-image-2` - 640px, 1k, 2k, 4k - `nano-banana` - 640px, 1k - `nano-banana-2` - 640px, 1k, 2k, 4k - `nano-banana-2-lite` - 640px, 1k - `nano-banana-pro` - 1k, 2k, 4k - `seedream-v4` - 640px, 1k, 2k, 4k - `seedream-v5-pro` - 640px, 1k, 2k - `z-image-turbo` - 640px, 1k, 2k Note: Resolution availability depends on the model and your subscription tier.
style	object	required	The art style to use for image generation.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Ai Image - dateTime",
      "example": "My Ai Image image"
    },
    "image_count": {
      "maximum": 16,
      "minimum": 1,
      "type": "integer",
      "description": "Number of images to generate. Maximum varies by model.",
      "example": 1
    },
    "model": {
      "enum": [
        "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"
      ],
      "type": "string",
      "description": "The AI model to use for image generation. Each model has different capabilities and costs.\n\n**Models:**\n- `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior.\n- `flux-2-klein` - from 5 credits/image\n  - Supported resolutions: 640px, 1k, 2k\n  - Available for tiers: free, creator, pro, business\n  - Image count allowed: 1\n- `flux-schnell` - from 5 credits/image\n  - Supported resolutions: 640px, 1k, 2k\n  - Available for tiers: free, creator, pro, business\n  - Image count allowed: 1, 2, 3, 4\n- `gpt-image-2` - from 50 credits/image\n  - Supported resolutions: 640px, 1k, 2k, 4k\n  - Available for tiers: creator, pro, business\n  - Image count allowed: 1, 2, 3, 4\n- `nano-banana` - from 50 credits/image\n  - Supported resolutions: 640px, 1k\n  - Available for tiers: creator, pro, business\n  - Image count allowed: 1, 2, 3, 4\n- `nano-banana-2` - from 100 credits/image\n  - Supported resolutions: 640px, 1k, 2k, 4k\n  - Available for tiers: creator, pro, business\n  - Image count allowed: 1, 4, 9, 16\n- `nano-banana-2-lite` - from 50 credits/image\n  - Supported resolutions: 640px, 1k\n  - Available for tiers: creator, pro, business\n  - Image count allowed: 1, 2, 3, 4\n- `nano-banana-pro` - from 150 credits/image\n  - Supported resolutions: 1k, 2k, 4k\n  - Available for tiers: creator, pro, business\n  - Image count allowed: 1, 4, 9, 16\n- `seedream-v4` - from 40 credits/image\n  - Supported resolutions: 640px, 1k, 2k, 4k\n  - Available for tiers: creator, pro, business\n  - Image count allowed: 1, 2, 3, 4\n- `seedream-v5-pro` - from 75 credits/image\n  - Supported resolutions: 640px, 1k, 2k\n  - Available for tiers: creator, pro, business\n  - Image count allowed: 1, 2, 3, 4\n- `z-image-turbo` - from 5 credits/image\n  - Supported resolutions: 640px, 1k, 2k\n  - Available for tiers: free, creator, pro, business\n  - Image count allowed: 1, 2, 3, 4\n\n**Deprecated Enum Values:**\n- `seedream` - Use `seedream-v4` instead.\n",
      "example": "default"
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "16:9",
        "9:16"
      ],
      "type": "string",
      "description": "The aspect ratio of the output image(s). If not specified, defaults to `1:1` (square).",
      "example": "1:1"
    },
    "resolution": {
      "enum": [
        "auto",
        "640px",
        "1k",
        "2k",
        "4k"
      ],
      "type": "string",
      "description": "Maximum resolution (longest edge) for the output image.\n\n**Options:**\n- `640px` — up to 640px\n- `1k` — up to 1024px\n- `2k` — up to 2048px\n- `4k` — up to 4096px\n- `auto` — **Deprecated.** Mapped server-side from your subscription tier to the best matching resolution the model supports\n\n**Per-model support:**\n- `flux-2-klein` - 640px, 1k, 2k\n- `flux-schnell` - 640px, 1k, 2k\n- `gpt-image-2` - 640px, 1k, 2k, 4k\n- `nano-banana` - 640px, 1k\n- `nano-banana-2` - 640px, 1k, 2k, 4k\n- `nano-banana-2-lite` - 640px, 1k\n- `nano-banana-pro` - 1k, 2k, 4k\n- `seedream-v4` - 640px, 1k, 2k, 4k\n- `seedream-v5-pro` - 640px, 1k, 2k\n- `z-image-turbo` - 640px, 1k, 2k\n\nNote: Resolution availability depends on the model and your subscription tier.",
      "default": "auto",
      "example": "auto"
    },
    "style": {
      "required": [
        "prompt"
      ],
      "type": "object",
      "properties": {
        "prompt": {
          "minLength": 1,
          "type": "string",
          "description": "The prompt used for the image(s).",
          "example": "Cool image"
        },
        "tool": {
          "enum": [
            "ai-anime-generator",
            "ai-art-generator",
            "ai-background-generator",
            "ai-character-generator",
            "ai-face-generator",
            "ai-fashion-generator",
            "ai-icon-generator",
            "ai-illustration-generator",
            "ai-interior-design-generator",
            "ai-landscape-generator",
            "ai-logo-generator",
            "ai-manga-generator",
            "ai-outfit-generator",
            "ai-pattern-generator",
            "ai-photo-generator",
            "ai-sketch-generator",
            "ai-tattoo-generator",
            "album-cover-generator",
            "animated-characters-generator",
            "architecture-generator",
            "book-cover-generator",
            "comic-book-generator",
            "dark-fantasy-ai",
            "disney-ai-generator",
            "dnd-ai-art-generator",
            "emoji-generator",
            "fantasy-map-generator",
            "graffiti-generator",
            "movie-poster-generator",
            "optical-illusion-generator",
            "pokemon-generator",
            "south-park-character-generator",
            "superhero-generator",
            "thumbnail-maker",
            "general"
          ],
          "type": "string",
          "description": "The art style to use for image generation. Defaults to 'general' if not provided.",
          "default": "general",
          "example": "ai-anime-generator"
        }
      },
      "description": "The art style to use for image generation."
    }
  },
  "required": [
    "image_count",
    "style"
  ]
}

ai_image_upscaler_create_image

Upscale your image using AI. Each 2x upscale costs 50 credits for balanced/creative modes, and 25 credits for preserve. 4x upscale costs 200 and 100 credits respectively. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters4

name	string	optional	Give your image a custom name for easy identification.
scale_factor	number	required	How much to scale the image. Must be either 2 or 4. Note: 4x upscale is only available on Creator, Pro, or Business tier.
style	object	optional	Style settings for the upscale. Use `mode` (`"preserve"`, `"balanced"`, or `"creative"`). Defaults to `"balanced"`.
assets	object	required	Provide the assets for upscaling

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Image Upscaler - dateTime",
      "example": "My Image Upscaler image"
    },
    "scale_factor": {
      "type": "number",
      "description": "How much to scale the image. Must be either 2 or 4.\n            \nNote: 4x upscale is only available on Creator, Pro, or Business tier.",
      "example": 2
    },
    "style": {
      "type": "object",
      "properties": {
        "mode": {
          "enum": [
            "pro",
            "preserve",
            "balanced",
            "creative"
          ],
          "type": "string",
          "description": "The upscaling mode. `\"preserve\"` uses the fast pro pipeline (1× credit multiplier). `\"balanced\"` and `\"creative\"` use the creative pipeline (2× credit multiplier). `\"pro\"` is deprecated and maps to `\"preserve\"`. Defaults to `\"balanced\"`.",
          "example": "balanced"
        },
        "prompt": {
          "type": "string",
          "description": "A prompt to guide the final image. Only used when mode is `creative`."
        }
      },
      "description": "Style settings for the upscale. Use `mode` (`\"preserve\"`, `\"balanced\"`, or `\"creative\"`). Defaults to `\"balanced\"`.",
      "default": {}
    },
    "assets": {
      "required": [
        "image_file_path"
      ],
      "type": "object",
      "properties": {
        "image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The image to upscale. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n. The maximum input image size is 4096x4096px.",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the assets for upscaling"
    }
  },
  "required": [
    "scale_factor",
    "assets"
  ]
}

ai_meme_generator_create_image

Create an AI generated meme. Each meme costs 10 credits. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.

Parameters2

name	string	optional	The name of the meme.
style	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the meme.",
      "example": "My Funny Meme"
    },
    "style": {
      "required": [
        "topic",
        "template"
      ],
      "type": "object",
      "properties": {
        "topic": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string",
          "description": "The topic of the meme.",
          "example": "When the code finally works"
        },
        "template": {
          "enum": [
            "Random",
            "Drake Hotline Bling",
            "Galaxy Brain",
            "Two Buttons",
            "Gru's Plan",
            "Tuxedo Winnie The Pooh",
            "Is This a Pigeon",
            "Panik Kalm Panik",
            "Disappointed Guy",
            "Waiting Skeleton",
            "Bike Fall",
            "Change My Mind",
            "Side Eyeing Chloe"
          ],
          "type": "string",
          "description": "To use our templates, pass in one of the enum values.",
          "example": "Drake Hotline Bling"
        },
        "searchWeb": {
          "type": "boolean",
          "description": "Whether to search the web for meme content.",
          "default": false,
          "example": false
        }
      }
    }
  },
  "required": [
    "style"
  ]
}

ai_qr_code_generator_create_image

Create an AI QR code. Each QR code costs 0 credits. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.

Parameters3

name	string	optional	Give your image a custom name for easy identification.
content	string	required	The content of the QR code.
style	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Qr Code - dateTime",
      "example": "My Qr Code image"
    },
    "content": {
      "type": "string",
      "description": "The content of the QR code.",
      "example": "https://magichour.ai"
    },
    "style": {
      "required": [
        "art_style"
      ],
      "type": "object",
      "properties": {
        "art_style": {
          "type": "string",
          "description": "To use our templates, pass in one of Watercolor, Cyberpunk City, Ink Landscape, Interior Painting, Japanese Street, Mech, Minecraft, Picasso Painting, Game Map, Spaceship, Chinese Painting, Winter Village, or pass any custom art style.",
          "example": "Watercolor"
        }
      }
    }
  },
  "required": [
    "content",
    "style"
  ]
}

body_swap_create_image

Swap a person into a scene image using Nano Banana 2 Lite (640px/1k) or Nano Banana 2 (2k/4k). Credits depend on `resolution` (from 50 credits at 640px upward). MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters3

name	string	optional	Give your image a custom name for easy identification.
resolution	string	required	Output resolution. Determines credits charged for the run.
assets	object	required	Person image and scene image for body swap

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Body Swap - dateTime",
      "example": "My Body Swap image"
    },
    "resolution": {
      "enum": [
        "640px",
        "1k",
        "2k",
        "4k"
      ],
      "type": "string",
      "description": "Output resolution. Determines credits charged for the run.",
      "example": "1k"
    },
    "assets": {
      "required": [
        "person_file_path",
        "scene_file_path"
      ],
      "type": "object",
      "properties": {
        "person_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "Image of the person to place into the scene. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        },
        "scene_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "Original scene image (background). This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/5678.png"
        }
      },
      "description": "Person image and scene image for body swap"
    }
  },
  "required": [
    "resolution",
    "assets"
  ]
}

face_swap_photo_create_image

Create a face swap photo. Each photo costs 10 credits. The height/width of the output image depends on your subscription. Please refer to our [pricing](https://magichour.ai/pricing) page for more details MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters2

name	string	optional	Give your image a custom name for easy identification.
assets	object	required	Provide the assets for face swap photo

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Face Swap - dateTime",
      "example": "My Face Swap image"
    },
    "assets": {
      "required": [
        "target_file_path"
      ],
      "type": "object",
      "properties": {
        "face_swap_mode": {
          "enum": [
            "all-faces",
            "individual-faces"
          ],
          "type": "string",
          "description": "Choose how to swap faces:\n**all-faces** (recommended) — swap all detected faces using one source image (`source_file_path` required)\n+- **individual-faces** — specify exact mappings using `face_mappings`",
          "default": "all-faces",
          "example": "all-faces"
        },
        "source_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "This is the image from which the face is extracted. The value is required if `face_swap_mode` is `all-faces`.\n\nThis value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        },
        "face_mappings": {
          "maxItems": 5,
          "type": "array",
          "items": {
            "required": [
              "original_face",
              "new_face"
            ],
            "type": "object",
            "properties": {
              "original_face": {
                "type": "string",
                "description": "The face detected from the image in `target_file_path`. The file name is in the format of `<face_frame>-<face_index>.png`. This value is corresponds to the response in the [face detection API](https://docs.magichour.ai/api-reference/files/get-face-detection-details).\n\n* The face_frame is the frame number of the face in the target image. For images, the frame number is always 0.\n* The face_index is the index of the face in the target image, starting from 0 going left to right.",
                "example": "api-assets/id/0-0.png"
              },
              "new_face": {
                "type": "string",
                "description": "The face image that will be used to replace the face in the `original_face`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
                "example": "api-assets/id/1234.png"
              }
            }
          },
          "description": "This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`.",
          "example": [
            {
              "original_face": "api-assets/id/0-0.png",
              "new_face": "api-assets/id/1234.png"
            }
          ]
        },
        "target_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "This is the image where the face from the source image will be placed. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the assets for face swap photo"
    }
  },
  "required": [
    "assets"
  ]
}

head_swap_create_image

Swap a head onto a body image. Each image costs 10 credits. Output resolution depends on your subscription; you may set `max_resolution` lower than your plan maximum if desired. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters3

name	string	optional	Give your image a custom name for easy identification.
max_resolution	integer	optional	Constrains the larger dimension (height or width) of the output. Omit to use the maximum allowed for your plan (capped at 2048px). Values above your plan maximum are clamped down to your plan's maximum.
assets	object	required	Provide the body and head images for head swap

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Head Swap - dateTime",
      "example": "My Head Swap image"
    },
    "max_resolution": {
      "type": "integer",
      "description": "Constrains the larger dimension (height or width) of the output. Omit to use the maximum allowed for your plan (capped at 2048px). Values above your plan maximum are clamped down to your plan's maximum.",
      "example": 1024
    },
    "assets": {
      "required": [
        "body_file_path",
        "head_file_path"
      ],
      "type": "object",
      "properties": {
        "body_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "Image that receives the swapped head. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        },
        "head_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "Image of the head to place on the body. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/5678.png"
        }
      },
      "description": "Provide the body and head images for head swap"
    }
  },
  "required": [
    "assets"
  ]
}

image_background_remover_create_image

Remove background from image. Each image costs 5 credits. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters2

name	string	optional	Give your image a custom name for easy identification.
assets	object	required	Provide the assets for background removal

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Background Remover - dateTime",
      "example": "My Background Remover image"
    },
    "assets": {
      "required": [
        "image_file_path"
      ],
      "type": "object",
      "properties": {
        "image_file_path": {
          "type": "string",
          "description": "The image to remove the background. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        },
        "background_image_file_path": {
          "type": "string",
          "description": "The image used as the new background for the image_file_path. This image will be resized to match the image in image_file_path. Please make sure the resolution between the images are similar.\n\nThis value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the assets for background removal"
    }
  },
  "required": [
    "assets"
  ]
}

photo_colorizer_create_image

Colorize image. Each image costs 10 credits. MCP guidance: - This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters2

name	string	optional	Give your image a custom name for easy identification.
assets	object	required	Provide the assets for photo colorization

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your image a custom name for easy identification.",
      "default": "Photo Colorizer - dateTime",
      "example": "My Photo Colorizer image"
    },
    "assets": {
      "required": [
        "image_file_path"
      ],
      "type": "object",
      "properties": {
        "image_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The image used to generate the colorized image. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.png"
        }
      },
      "description": "Provide the assets for photo colorization"
    }
  },
  "required": [
    "assets"
  ]
}

audio_projects_retrieve_details

Check the progress of a audio project. The `downloads` field is populated after a successful render. **Statuses** - `queued` — waiting to start - `rendering` — in progress - `complete` — ready; see `downloads` - `error` — a failure occurred (see `error`) - `canceled` — user canceled - `draft` — not used MCP guidance: - Use this after a create tool to poll job status. When status is `complete`, surface the `downloads` URLs to the user; if status is `error`, surface the error message. - Each `downloads[n].url` is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append `expires_at` onto the URL string.

Parameters1

string

required

Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "cuid-example",
      "description": "Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio."
    }
  },
  "required": [
    "id"
  ]
}

audio_projects_delete

Permanently delete the rendered audio file(s). This action is not reversible, please be sure before deleting.

Parameters1

string

required

Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "cuid-example",
      "description": "Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio."
    }
  },
  "required": [
    "id"
  ]
}

ai_voice_generator_create_audio

Generate speech from text. Each character costs 0.1 credits. The cost is rounded up to the nearest whole number. MCP guidance: - This starts an async audio generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_audio_project` helper with the returned id, or poll the matching `GET /v1/audio-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.

Parameters2

name	string	optional	Give your audio a custom name for easy identification.
style	object	required	The content used to generate speech.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your audio a custom name for easy identification.",
      "default": "Voice Generator - dateTime",
      "example": "My Voice Generator audio"
    },
    "style": {
      "required": [
        "prompt",
        "voice_name"
      ],
      "type": "object",
      "properties": {
        "prompt": {
          "minLength": 1,
          "type": "string",
          "description": "Text used to generate speech. The character limit is 1000 characters.",
          "example": "Hello, how are you?"
        },
        "voice_name": {
          "enum": [
            "Elon Musk",
            "Mark Zuckerberg",
            "Joe Rogan",
            "Barack Obama",
            "Morgan Freeman",
            "Kanye West",
            "Donald Trump",
            "Joe Biden",
            "Kim Kardashian",
            "Taylor Swift",
            "James Earl Jones",
            "Samuel L. Jackson",
            "Jeff Goldblum",
            "David Attenborough",
            "Sean Connery",
            "Cillian Murphy",
            "Anne Hathaway",
            "Julia Roberts",
            "Natalie Portman",
            "Steve Carell",
            "Amy Poehler",
            "Stephen Colbert",
            "Jimmy Fallon",
            "David Letterman",
            "Alex Trebek",
            "Katy Perry",
            "Prince",
            "Kevin Bacon",
            "Tom Hiddleston",
            "Adam Driver",
            "Alan Rickman",
            "Alexz Johnson",
            "Ana Gasteyer",
            "Andrew Rannells",
            "Arden Cho",
            "Bear Grylls",
            "Ben McKenzie",
            "Ben Stiller",
            "Ben Whishaw",
            "Billie Joe Armstrong",
            "Bingbing Li",
            "Booboo Stewart",
            "Bradley Steven Perry",
            "Bruno Mars",
            "Caity Lotz",
            "Cameron Boyce",
            "Candice Accola",
            "Carrie Underwood",
            "Casey Affleck",
            "Caterina Scorsone",
            "Cedric the Entertainer",
            "Chace Crawford",
            "Chadwick Boseman",
            "Charlie Day",
            "Chris Hemsworth",
            "Chris Martin",
            "Christopher Mintz-Plasse",
            "Dan Fogler",
            "Dan Stevens",
            "Daniel Dae Kim",
            "Danielle Panabaker",
            "Dave Bautista",
            "David Schwimmer",
            "Denis Leary",
            "Derek Mears",
            "Diego Luna",
            "Donald Glover",
            "Donnie Yen",
            "Doutzen Kroes",
            "Dove Cameron",
            "Dr. Dre",
            "Drake Bell",
            "Elle Fanning",
            "Ernie Hudson",
            "Fergie",
            "Forest Whitaker",
            "Francia Raisa",
            "Freddie Highmore",
            "Gillian Jacobs",
            "Gina Carano",
            "Ginnifer Goodwin",
            "Gordon Ramsay",
            "Guy Pearce",
            "Gwendoline Christie",
            "Hailee Steinfeld",
            "Howie Mandel",
            "Hugh Jackman",
            "Hugh Laurie",
            "J. K. Simmons",
            "Jack Black",
            "Jared Leto",
            "Jennifer Carpenter",
            "Kesha",
            "Kris Jenner",
            "Kristen Bell",
            "Lorde",
            "Matt Smith",
            "Marilyn Monroe",
            "Charlie Chaplin",
            "Albert Einstein",
            "Abraham Lincoln",
            "John F. Kennedy",
            "Lucille Ball",
            "A.R. Rahman",
            "Aamir Khan",
            "Ajay Devgn",
            "Akshay Kumar",
            "Alain Delon",
            "Alan Alda",
            "Alan Cumming",
            "Amitabh Bachchan",
            "Ang Lee",
            "Ansel Elgort",
            "Anthony Anderson",
            "Anthony Mackie",
            "Armie Hammer",
            "Asa Butterfield",
            "B.J. Novak",
            "Barbara Eden",
            "Betty White",
            "Bill Nighy",
            "Bill Pullman",
            "Blake Shelton",
            "Bonnie Wright",
            "Brad Paisley",
            "Brendan Gleeson",
            "Brian Cox",
            "Bruno Ganz",
            "Burt Reynolds",
            "Carrie Fisher",
            "Charles Dance",
            "Chiwetel Ejiofor",
            "Chris Pine",
            "Christina Hendricks",
            "Christina Ricci",
            "Cyndi Lauper",
            "Dakota Fanning",
            "Damian Lewis",
            "Dan Aykroyd",
            "Daniel Craig",
            "David Oyelowo",
            "David Tennant",
            "Diane Keaton",
            "Diane Kruger",
            "Dick Van Dyke",
            "Domhnall Gleeson",
            "Dominic Cooper",
            "Donald Sutherland",
            "Drew Carey",
            "Eartha Kitt",
            "Eddie Izzard",
            "Edward Asner",
            "Eli Roth",
            "Elisabeth Moss",
            "Ellen Burstyn",
            "Emile Hirsch",
            "Ezra Miller",
            "Felicity Jones",
            "Fiona Shaw",
            "Florence Henderson",
            "Freida Pinto",
            "Geena Davis",
            "Gemma Arterton",
            "Geri Halliwell",
            "Glenn Close",
            "Gloria Steinem",
            "Greta Gerwig",
            "Gugu Mbatha-Raw",
            "Hans Zimmer",
            "Harry Connick Jr.",
            "Harvey Keitel",
            "Helena Bonham Carter",
            "Henry Cavill",
            "Hilary Swank",
            "Hugh Bonneville",
            "Idina Menzel",
            "Imelda Staunton",
            "Ingrid Bergman",
            "Irrfan Khan",
            "Isla Fisher",
            "Iwan Rheon",
            "Jack Lemmon",
            "Janet Jackson",
            "Jason Bateman",
            "Jason Segel",
            "Jennifer Coolidge",
            "Johnny Galecki",
            "Jon Favreau",
            "Joseph Gordon-Levitt",
            "Josh Brolin",
            "Josh Gad",
            "Josh Groban",
            "Julia Louis-Dreyfus",
            "Kristen Stewart",
            "Kristen Wiig",
            "Rooney Mara",
            "Caitriona Balfe",
            "J.J. Abrams",
            "Zoe Saldana",
            "SpongeBob SquarePants",
            "Patrick Star",
            "Squidward Tentacles",
            "Homer Simpson",
            "Bart Simpson",
            "Peter Griffin",
            "Stewie Griffin",
            "Eric Cartman",
            "Rick Sanchez",
            "Bugs Bunny",
            "Mickey Mouse",
            "Donald Duck",
            "Shrek",
            "Donkey (Shrek)",
            "Elsa (Frozen)",
            "Woody (Toy Story)",
            "Buzz Lightyear",
            "Scooby-Doo",
            "Shaggy Rogers",
            "Bender (Futurama)",
            "Optimus Prime",
            "Batman (Animated)",
            "The Joker (Animated)",
            "Darth Vader",
            "Yoda",
            "Gollum Smeagol",
            "Gandalf",
            "Winnie the Pooh",
            "Kermit the Frog",
            "Elmo",
            "SpiderMan (Tom Holland ver.)",
            "Mario",
            "Luigi",
            "Sonic the Hedgehog",
            "Naruto Uzumaki",
            "Goku",
            "Vegeta",
            "Light Yagami",
            "Luffy (One Piece)",
            "Edward Elric",
            "Eren Jaeger",
            "Levi Ackerman",
            "Tanjiro Kamado",
            "All Might",
            "GLaDOS",
            "Master Chief",
            "Kratos",
            "Arthur Morgan",
            "Geralt of Rivia",
            "Dwayne 'The Rock' Johnson",
            "LeBron James",
            "Shaquille O'Neal",
            "Conor McGregor",
            "Mike Tyson",
            "Kobe Bryant",
            "Floyd Mayweather",
            "Cristiano Ronaldo",
            "Lionel Messi",
            "Serena Williams",
            "Tom Brady",
            "Stephen Curry",
            "John Cena",
            "Hulk Hogan",
            "Stone Cold Steve Austin",
            "The Undertaker",
            "Nate Diaz",
            "Charles Barkley",
            "Shannon Sharpe",
            "Drake",
            "Rihanna",
            "Eminem",
            "Snoop Dogg",
            "Jay-Z",
            "Ed Sheeran",
            "Billie Eilish",
            "Ariana Grande",
            "Adele",
            "Post Malone",
            "Travis Scott",
            "Nicki Minaj",
            "Cardi B",
            "Doja Cat",
            "Bad Bunny",
            "Justin Bieber",
            "Sabrina Carpenter",
            "Chappell Roan",
            "Dua Lipa",
            "The Weeknd",
            "Miley Cyrus",
            "Lady Gaga",
            "Kendrick Lamar",
            "Ozzy Osbourne",
            "Freddie Mercury",
            "Elvis Presley",
            "Bob Marley",
            "Frank Sinatra",
            "MrBeast",
            "PewDiePie",
            "Kai Cenat",
            "IShowSpeed",
            "Markiplier",
            "Jacksepticeye",
            "KSI",
            "Logan Paul",
            "Jake Paul",
            "Dream (Minecraft)",
            "Corpse Husband",
            "xQc",
            "Pokimane",
            "Valkyrae",
            "Ninja",
            "Joe Scott",
            "Linus (LTT)",
            "Ryan Reynolds",
            "Tom Hanks",
            "Robert Downey Jr.",
            "Will Smith",
            "Denzel Washington",
            "Leonardo DiCaprio",
            "Brad Pitt",
            "Keanu Reeves",
            "Nicolas Cage",
            "Al Pacino",
            "Robert De Niro",
            "Arnold Schwarzenegger",
            "Sylvester Stallone",
            "Vin Diesel",
            "Jason Statham",
            "Tom Cruise",
            "Johnny Depp",
            "Scarlett Johansson",
            "Angelina Jolie",
            "Jennifer Aniston",
            "Emma Watson",
            "Margot Robbie",
            "Sydney Sweeney",
            "Zendaya",
            "Timothee Chalamet",
            "Pedro Pascal",
            "Oscar Isaac",
            "Benedict Cumberbatch",
            "Ian McKellen",
            "Patrick Stewart",
            "Christopher Walken",
            "Matthew McConaughey",
            "Harrison Ford",
            "Mark Wahlberg",
            "Owen Wilson",
            "Seth Rogen",
            "Kevin Hart",
            "Adam Sandler",
            "Jim Carrey",
            "Eddie Murphy",
            "Robin Williams",
            "Will Ferrell",
            "Melissa McCarthy",
            "Awkwafina",
            "Jason Momoa",
            "Idris Elba",
            "Tom Hardy",
            "Michael B. Jordan",
            "Austin Butler",
            "Glen Powell",
            "Paul Giamatti",
            "Bryan Cranston",
            "Bob Odenkirk",
            "Vladimir Putin",
            "Queen Elizabeth II",
            "Winston Churchill",
            "Martin Luther King Jr.",
            "Kamala Harris",
            "Bernie Sanders",
            "Alexandria Ocasio-Cortez",
            "Narendra Modi",
            "Oprah Winfrey",
            "Ellen DeGeneres",
            "Dr. Phil",
            "Steve Harvey",
            "Trevor Noah",
            "John Oliver",
            "James Corden",
            "Ryan Seacrest",
            "Howard Stern",
            "Conan O'Brien",
            "Seth Meyers",
            "Bill Nye",
            "Neil deGrasse Tyson",
            "Guy Fieri",
            "Dave Chappelle",
            "Chris Rock",
            "Jerry Seinfeld",
            "Ali Wong",
            "John Mulaney",
            "Hasan Minhaj",
            "Nikki Glaser",
            "Matt Rife",
            "Gabriel Iglesias",
            "Bo Burnham",
            "Jeff Bezos",
            "Bill Gates",
            "Steve Jobs",
            "Tim Cook",
            "Sam Altman",
            "Jensen Huang",
            "Gilbert Gottfried",
            "James May",
            "Jeremy Clarkson",
            "Richard Hammond",
            "Bob Ross",
            "Anthony Bourdain",
            "David Goggins",
            "Jordan Peterson",
            "Joe Pesci",
            "Danny DeVito",
            "Seth MacFarlane",
            "Patrick Warburton",
            "Keith David",
            "Mark Hamill",
            "Liam Neeson",
            "Antonio Banderas",
            "Sofia Vergara",
            "Penelope Cruz",
            "Gal Gadot",
            "Cate Blanchett",
            "Viola Davis",
            "Meryl Streep",
            "Sandra Bullock",
            "Reese Witherspoon",
            "Salma Hayek",
            "Lupita Nyong'o",
            "Florence Pugh",
            "Jenna Ortega",
            "Ana de Armas",
            "Jacob Elordi",
            "Barry White",
            "Dolly Parton",
            "Willie Nelson",
            "Lil Wayne",
            "50 Cent",
            "Ice Cube",
            "Tupac Shakur",
            "Notorious B.I.G.",
            "Bob Dylan",
            "David Bowie",
            "Michael Jackson",
            "Whitney Houston",
            "Amy Winehouse",
            "SZA",
            "Tyler, The Creator",
            "Thanos",
            "Tony Stark",
            "Captain Jack Sparrow",
            "Walter White",
            "Tommy Shelby",
            "Michael Scott",
            "Dwight Schrute",
            "Bowser",
            "Usain Bolt",
            "Tyson Fury",
            "Dana White",
            "Pat McAfee",
            "Giannis Antetokounmpo",
            "Lex Fridman",
            "Ben Shapiro",
            "Tucker Carlson",
            "Martha Stewart",
            "Gordon Lightfoot",
            "Lizzo",
            "Megan Thee Stallion",
            "Ice Spice",
            "21 Savage",
            "Metro Boomin",
            "Jack Harlow",
            "Peso Pluma",
            "BTS Jungkook",
            "Quentin Tarantino",
            "Werner Herzog",
            "Anderson Cooper",
            "Rachel Maddow",
            "Mahatma Gandhi",
            "Muhammad Ali",
            "Princess Diana",
            "Nelson Mandela",
            "Steve Irwin",
            "Morty Smith",
            "Andrew Huberman",
            "Willem Dafoe",
            "Mike Rowe",
            "Terminator",
            "Deadpool",
            "Plankton",
            "Mr. Krabs",
            "Picard"
          ],
          "type": "string",
          "description": "The voice to use for the speech. Available voices: Elon Musk, Mark Zuckerberg, Joe Rogan, Barack Obama, Morgan Freeman, Kanye West, Donald Trump, Joe Biden, Kim Kardashian, Taylor Swift, James Earl Jones, Samuel L. Jackson, Jeff Goldblum, David Attenborough, Sean Connery, Cillian Murphy, Anne Hathaway, Julia Roberts, Natalie Portman, Steve Carell, Amy Poehler, Stephen Colbert, Jimmy Fallon, David Letterman, Alex Trebek, Katy Perry, Prince, Kevin Bacon, Tom Hiddleston, Adam Driver, Alan Rickman, Alexz Johnson, Ana Gasteyer, Andrew Rannells, Arden Cho, Bear Grylls, Ben McKenzie, Ben Stiller, Ben Whishaw, Billie Joe Armstrong, Bingbing Li, Booboo Stewart, Bradley Steven Perry, Bruno Mars, Caity Lotz, Cameron Boyce, Candice Accola, Carrie Underwood, Casey Affleck, Caterina Scorsone, Cedric the Entertainer, Chace Crawford, Chadwick Boseman, Charlie Day, Chris Hemsworth, Chris Martin, Christopher Mintz-Plasse, Dan Fogler, Dan Stevens, Daniel Dae Kim, Danielle Panabaker, Dave Bautista, David Schwimmer, Denis Leary, Derek Mears, Diego Luna, Donald Glover, Donnie Yen, Doutzen Kroes, Dove Cameron, Dr. Dre, Drake Bell, Elle Fanning, Ernie Hudson, Fergie, Forest Whitaker, Francia Raisa, Freddie Highmore, Gillian Jacobs, Gina Carano, Ginnifer Goodwin, Gordon Ramsay, Guy Pearce, Gwendoline Christie, Hailee Steinfeld, Howie Mandel, Hugh Jackman, Hugh Laurie, J. K. Simmons, Jack Black, Jared Leto, Jennifer Carpenter, Kesha, Kris Jenner, Kristen Bell, Lorde, Matt Smith, Marilyn Monroe, Charlie Chaplin, Albert Einstein, Abraham Lincoln, John F. Kennedy, Lucille Ball, A.R. Rahman, Aamir Khan, Ajay Devgn, Akshay Kumar, Alain Delon, Alan Alda, Alan Cumming, Amitabh Bachchan, Ang Lee, Ansel Elgort, Anthony Anderson, Anthony Mackie, Armie Hammer, Asa Butterfield, B.J. Novak, Barbara Eden, Betty White, Bill Nighy, Bill Pullman, Blake Shelton, Bonnie Wright, Brad Paisley, Brendan Gleeson, Brian Cox, Bruno Ganz, Burt Reynolds, Carrie Fisher, Charles Dance, Chiwetel Ejiofor, Chris Pine, Christina Hendricks, Christina Ricci, Cyndi Lauper, Dakota Fanning, Damian Lewis, Dan Aykroyd, Daniel Craig, David Oyelowo, David Tennant, Diane Keaton, Diane Kruger, Dick Van Dyke, Domhnall Gleeson, Dominic Cooper, Donald Sutherland, Drew Carey, Eartha Kitt, Eddie Izzard, Edward Asner, Eli Roth, Elisabeth Moss, Ellen Burstyn, Emile Hirsch, Ezra Miller, Felicity Jones, Fiona Shaw, Florence Henderson, Freida Pinto, Geena Davis, Gemma Arterton, Geri Halliwell, Glenn Close, Gloria Steinem, Greta Gerwig, Gugu Mbatha-Raw, Hans Zimmer, Harry Connick Jr., Harvey Keitel, Helena Bonham Carter, Henry Cavill, Hilary Swank, Hugh Bonneville, Idina Menzel, Imelda Staunton, Ingrid Bergman, Irrfan Khan, Isla Fisher, Iwan Rheon, Jack Lemmon, Janet Jackson, Jason Bateman, Jason Segel, Jennifer Coolidge, Johnny Galecki, Jon Favreau, Joseph Gordon-Levitt, Josh Brolin, Josh Gad, Josh Groban, Julia Louis-Dreyfus, Kristen Stewart, Kristen Wiig, Rooney Mara, Caitriona Balfe, J.J. Abrams, Zoe Saldana, SpongeBob SquarePants, Patrick Star, Squidward Tentacles, Homer Simpson, Bart Simpson, Peter Griffin, Stewie Griffin, Eric Cartman, Rick Sanchez, Bugs Bunny, Mickey Mouse, Donald Duck, Shrek, Donkey (Shrek), Elsa (Frozen), Woody (Toy Story), Buzz Lightyear, Scooby-Doo, Shaggy Rogers, Bender (Futurama), Optimus Prime, Batman (Animated), The Joker (Animated), Darth Vader, Yoda, Gollum Smeagol, Gandalf, Winnie the Pooh, Kermit the Frog, Elmo, SpiderMan (Tom Holland ver.), Mario, Luigi, Sonic the Hedgehog, Naruto Uzumaki, Goku, Vegeta, Light Yagami, Luffy (One Piece), Edward Elric, Eren Jaeger, Levi Ackerman, Tanjiro Kamado, All Might, GLaDOS, Master Chief, Kratos, Arthur Morgan, Geralt of Rivia, Dwayne 'The Rock' Johnson, LeBron James, Shaquille O'Neal, Conor McGregor, Mike Tyson, Kobe Bryant, Floyd Mayweather, Cristiano Ronaldo, Lionel Messi, Serena Williams, Tom Brady, Stephen Curry, John Cena, Hulk Hogan, Stone Cold Steve Austin, The Undertaker, Nate Diaz, Charles Barkley, Shannon Sharpe, Drake, Rihanna, Eminem, Snoop Dogg, Jay-Z, Ed Sheeran, Billie Eilish, Ariana Grande, Adele, Post Malone, Travis Scott, Nicki Minaj, Cardi B, Doja Cat, Bad Bunny, Justin Bieber, Sabrina Carpenter, Chappell Roan, Dua Lipa, The Weeknd, Miley Cyrus, Lady Gaga, Kendrick Lamar, Ozzy Osbourne, Freddie Mercury, Elvis Presley, Bob Marley, Frank Sinatra, MrBeast, PewDiePie, Kai Cenat, IShowSpeed, Markiplier, Jacksepticeye, KSI, Logan Paul, Jake Paul, Dream (Minecraft), Corpse Husband, xQc, Pokimane, Valkyrae, Ninja, Joe Scott, Linus (LTT), Ryan Reynolds, Tom Hanks, Robert Downey Jr., Will Smith, Denzel Washington, Leonardo DiCaprio, Brad Pitt, Keanu Reeves, Nicolas Cage, Al Pacino, Robert De Niro, Arnold Schwarzenegger, Sylvester Stallone, Vin Diesel, Jason Statham, Tom Cruise, Johnny Depp, Scarlett Johansson, Angelina Jolie, Jennifer Aniston, Emma Watson, Margot Robbie, Sydney Sweeney, Zendaya, Timothee Chalamet, Pedro Pascal, Oscar Isaac, Benedict Cumberbatch, Ian McKellen, Patrick Stewart, Christopher Walken, Matthew McConaughey, Harrison Ford, Mark Wahlberg, Owen Wilson, Seth Rogen, Kevin Hart, Adam Sandler, Jim Carrey, Eddie Murphy, Robin Williams, Will Ferrell, Melissa McCarthy, Awkwafina, Jason Momoa, Idris Elba, Tom Hardy, Michael B. Jordan, Austin Butler, Glen Powell, Paul Giamatti, Bryan Cranston, Bob Odenkirk, Vladimir Putin, Queen Elizabeth II, Winston Churchill, Martin Luther King Jr., Kamala Harris, Bernie Sanders, Alexandria Ocasio-Cortez, Narendra Modi, Oprah Winfrey, Ellen DeGeneres, Dr. Phil, Steve Harvey, Trevor Noah, John Oliver, James Corden, Ryan Seacrest, Howard Stern, Conan O'Brien, Seth Meyers, Bill Nye, Neil deGrasse Tyson, Guy Fieri, Dave Chappelle, Chris Rock, Jerry Seinfeld, Ali Wong, John Mulaney, Hasan Minhaj, Nikki Glaser, Matt Rife, Gabriel Iglesias, Bo Burnham, Jeff Bezos, Bill Gates, Steve Jobs, Tim Cook, Sam Altman, Jensen Huang, Gilbert Gottfried, James May, Jeremy Clarkson, Richard Hammond, Bob Ross, Anthony Bourdain, David Goggins, Jordan Peterson, Joe Pesci, Danny DeVito, Seth MacFarlane, Patrick Warburton, Keith David, Mark Hamill, Liam Neeson, Antonio Banderas, Sofia Vergara, Penelope Cruz, Gal Gadot, Cate Blanchett, Viola Davis, Meryl Streep, Sandra Bullock, Reese Witherspoon, Salma Hayek, Lupita Nyong'o, Florence Pugh, Jenna Ortega, Ana de Armas, Jacob Elordi, Barry White, Dolly Parton, Willie Nelson, Lil Wayne, 50 Cent, Ice Cube, Tupac Shakur, Notorious B.I.G., Bob Dylan, David Bowie, Michael Jackson, Whitney Houston, Amy Winehouse, SZA, Tyler, The Creator, Thanos, Tony Stark, Captain Jack Sparrow, Walter White, Tommy Shelby, Michael Scott, Dwight Schrute, Bowser, Usain Bolt, Tyson Fury, Dana White, Pat McAfee, Giannis Antetokounmpo, Lex Fridman, Ben Shapiro, Tucker Carlson, Martha Stewart, Gordon Lightfoot, Lizzo, Megan Thee Stallion, Ice Spice, 21 Savage, Metro Boomin, Jack Harlow, Peso Pluma, BTS Jungkook, Quentin Tarantino, Werner Herzog, Anderson Cooper, Rachel Maddow, Mahatma Gandhi, Muhammad Ali, Princess Diana, Nelson Mandela, Steve Irwin, Morty Smith, Andrew Huberman, Willem Dafoe, Mike Rowe, Terminator, Deadpool, Plankton, Mr. Krabs, Picard",
          "example": "Elon Musk"
        }
      },
      "description": "The content used to generate speech.",
      "example": {
        "prompt": "Hello, how are you?",
        "voice_name": "Elon Musk"
      }
    }
  },
  "required": [
    "style"
  ]
}

ai_voice_cloner_create_audio

Clone a voice from an audio sample and generate speech. * Each character costs 0.1 credits. * The cost is rounded up to the nearest whole number MCP guidance: - This starts an async audio generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_audio_project` helper with the returned id, or poll the matching `GET /v1/audio-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata. - For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.

Parameters3

name	string	optional	Give your audio a custom name for easy identification.
assets	object	required	Provide the assets for voice cloning.
style	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Give your audio a custom name for easy identification.",
      "default": "Voice Cloner - dateTime",
      "example": "My Voice Cloner audio"
    },
    "assets": {
      "required": [
        "audio_file_path"
      ],
      "type": "object",
      "properties": {
        "audio_file_path": {
          "minLength": 1,
          "type": "string",
          "description": "The audio used to clone the voice. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
          "example": "api-assets/id/1234.mp3"
        }
      },
      "description": "Provide the assets for voice cloning."
    },
    "style": {
      "required": [
        "prompt"
      ],
      "type": "object",
      "properties": {
        "prompt": {
          "maxLength": 1000,
          "minLength": 1,
          "type": "string",
          "description": "Text used to generate speech from the cloned voice. The character limit is 1000 characters.",
          "example": "Hello, this is my cloned voice."
        }
      }
    }
  },
  "required": [
    "assets",
    "style"
  ]
}

README.md4 KBView on GitHub

Magic Hour MCP Server

OpenAPI-backed MCP server for Magic Hour image, video, and audio generation.

At startup, this server reads docs/openapi.json and builds MCP tools with FastMCP.from_openapi(). The OpenAPI spec supplies endpoint coverage, while Magic Hour MCP policies add agent-facing guidance for async polling, uploads, and project downloads.

Docs:

Magic Hour agent skills - media workflows, published examples, and recovery guidance
user.md - hosted endpoint user guide
integration-handoff.md - FastAPI mount checklist
docs/detailed-step-by-step-integration.md - full backend integration guide
docs/api-reference.md - generated API reference

Setup

pip install -e .

Run locally

python main.py

Local MCP endpoint:

text

http://127.0.0.1:8000/

This local dev server runs at /, not /mcp. The host app adds /mcp when it mounts the server.

By default, requests go to the production Magic Hour API:

text

https://api.magichour.ai

Tool discovery is public. Tool calls must include your Magic Hour API key:

text

Authorization: Bearer <magic_hour_api_key>

Agents can discover the hosted server card at:

text

https://mcp.magichour.ai/.well-known/mcp/server-card.json

Environment variables:

MAGIC_HOUR_API_BASE_URL=https://api.magichour.ai
MAGIC_HOUR_OPENAPI_PATH=docs/openapi.json
MCP_OAUTH_ISSUER_URL=https://mcp.magichour.ai
MCP_OAUTH_RESOURCE_URL=https://mcp.magichour.ai

Override MAGIC_HOUR_API_BASE_URL to use a mock or another API base:

MAGIC_HOUR_API_BASE_URL=https://api.sideko.dev/v1/mock/magichour/magic-hour/latest python main.py

OAuth

This server is an OAuth protected resource only. The authorization server is the Magic Hour web app (https://magichour.ai): users sign in and consent there, and it returns a Magic Hour API key as the access token, which this server passes through to the API. Production requires MCP_OAUTH_ISSUER_URL and MCP_OAUTH_RESOURCE_URL. See docs/future-oauth-support.md.

Test with MCP Inspector

Start the server.
Run:
sh
```
npx @modelcontextprotocol/inspector
```
In Inspector:
- Transport: Streamable HTTP
- URL: http://127.0.0.1:8000/
- Header: Authorization: Bearer <magic_hour_api_key>
Call ping.
Call video_assets_generate_presigned_url or another generated tool.

Notes:

FastMCP generates endpoint tools from OpenAPI at startup.
Creation tools return id and credits_charged immediately.
OpenAPI operationId values are normalized to descriptive snake_case tool names.
The shared /v1/files/upload-urls endpoint is named video_assets_generate_presigned_url. It accepts video, audio, and image items.
Use wait_for_*_project to poll jobs. Use exact_download_urls exactly as returned; never append expiration metadata.
Image and audio wait tools also return inline media when supported.

Rebuild and type-check the MCP App UI with cd web && npm ci && npm run build.

File uploads

Magic Hour does not accept raw file bytes inside tool arguments. The flow is:

Call the generated shared upload-URL tool, video_assets_generate_presigned_url
Upload the file bytes to the returned upload_url
Pass the returned file_path into the generated creation tool

Direct public media URLs may work, but uploaded file_path values are more reliable. Upload bytes from the caller or a dedicated upload bridge; the hosted MCP server never reads caller-supplied local filesystem paths. Browser chat needs a separate upload UI or bridge; see docs/future-chat-ui-handoff.md.

Install

Tools (44)

pingwait_for_video_projectwait_for_image_projectwait_for_audio_projectupload_file_to_presigned_urlfetch_image_downloadfetch_audio_downloadfetch_video_download

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.magichour.ai/

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "magic-hour": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.magichour.ai/"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Magic Hour MCP Server (io.github.magichourhq/magic-hour)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

ping

wait_for_video_project

wait_for_image_project

wait_for_audio_project

upload_file_to_presigned_url

fetch_image_download

fetch_audio_download

fetch_video_download

video_assets_generate_presigned_url

face_detection_retrieve_details

face_detection_detect_faces

video_projects_retrieve_details

video_projects_delete

ai_talking_photo_create_talking_photo

ai_video_editor_create_video

animation_create_video

audio_to_video_create_video

auto_subtitle_generator_create_video

character_replace_create_video

face_swap_create_video

image_to_video_create_video

lip_sync_create_video

text_to_video_create_video

video_to_video_create_video

image_projects_retrieve_details

image_projects_delete

ai_clothes_changer_create_image

ai_face_editor_edit_image

ai_gif_generator_create_image

ai_image_editor_create_image

ai_headshot_generator_create_image

ai_image_generator_create_image

ai_image_upscaler_create_image

ai_meme_generator_create_image

ai_qr_code_generator_create_image

body_swap_create_image

face_swap_photo_create_image

head_swap_create_image

image_background_remover_create_image

photo_colorizer_create_image

audio_projects_retrieve_details

audio_projects_delete

ai_voice_generator_create_audio

ai_voice_cloner_create_audio

Magic Hour MCP Server

Setup

Run locally

OAuth

Test with MCP Inspector

File uploads

Install

Remote endpoint

Related servers