Magic Hour MCP
Hosted Streamable HTTP MCP server that allows AI agents to generate, edit, and manage images, videos, and audio using the Magic Hour API. It supports tools for creating media from text or stills, uploading source files, waiting for render jobs to complete, and retrieving signed download URLs.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
Do I need a Magic Hour API key? Yes.
MCP endpoint (Streamable HTTP)
https://mcp.magichour.ai/What you can do with it
- Generate cinematic images from text prompts
- Animate still images with camera movement
- Edit portraits by adding accessories like sunglasses
- Retrieve signed download URLs for completed video renders
Source and maintenance
Community listingRegistry 0.1.0
- Maintenance checked
Protocol and capabilities
- Server
- magic-hour 0.1.0
- MCP protocol
- 2025-06-18
- Tools
- 48 advertised
- Resources
- 2 advertised
- Resource templates
- 1 advertised
- Prompts
- 0 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": false,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/ui": {}
},
"experimental": {}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
48 advertised
get_workflow_guide — Choose a media workflow
Advertised read-only
Returns required inputs, ordered steps, example requests and review criteria for eight supported Magic Hour workflows. Use when planning a generation, not to run one. Requires authentication but does not check account eligibility or spend credits.
get_workflow_guide input schema
{
"type": "object",
"required": [
"workflow"
],
"properties": {
"workflow": {
"enum": [
"video-face-swap",
"image-editor",
"image-to-video",
"video-generator",
"lip-sync",
"ugc-ads",
"talking-photo",
"media-apis"
],
"type": "string"
}
},
"additionalProperties": false
}get_workflow_guide output schema
{
"type": "object",
"additionalProperties": true
}get_workflow_guide annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}ping — Ping
Advertised read-only
Checks that the Magic Hour server is reachable. Use for connectivity troubleshooting; it does not validate API credentials or account access. Makes no media or project changes.
ping input schema
{
"type": "object",
"properties": {},
"additionalProperties": false
}ping output schema
{
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
}ping annotations
{
"title": "Ping",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}wait_for_video_project — Wait for Video Project
Advertised read-only
Polls a video project until it completes, errors, is canceled or times out. Use with the id returned by a video create tool. Read-only; returns download URLs when complete. After a timeout, resume with the same id rather than creating another generation. Use signed download URLs exactly as returned. Does not inline video content.
wait_for_video_project input schema
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"timeout_seconds": {
"type": "number",
"default": 300
},
"max_inline_downloads": {
"type": "integer",
"default": 0
},
"poll_interval_seconds": {
"type": "number",
"default": 2
},
"include_inline_downloads": {
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}wait_for_video_project annotations
{
"title": "Wait for Video Project",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}wait_for_image_project — Wait for Image Project
Advertised read-only
Polls an image project until it completes, errors, is canceled or times out. Use with the id returned by an image create tool. Read-only; returns the project and download URLs, with optional inline image previews sharing an 8 MiB total limit. After a timeout, resume with the same id rather than creating another generation. Use signed download URLs exactly as returned.
wait_for_image_project input schema
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"timeout_seconds": {
"type": "number",
"default": 180
},
"max_inline_downloads": {
"type": "integer",
"default": 4
},
"poll_interval_seconds": {
"type": "number",
"default": 2
},
"max_bytes_per_download": {
"type": "integer",
"default": 8388608
},
"include_inline_downloads": {
"type": "boolean",
"default": true
}
},
"additionalProperties": false
}wait_for_image_project annotations
{
"title": "Wait for Image Project",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}wait_for_audio_project — Wait for Audio Project
Advertised read-only
Polls an audio project until it completes, errors, is canceled or times out. Use with the id returned by an audio create tool. Read-only; returns the project and download URLs, with optional inline audio previews sharing an 8 MiB total limit. After a timeout, resume with the same id rather than creating another generation. Use signed download URLs exactly as returned.
wait_for_audio_project input schema
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"timeout_seconds": {
"type": "number",
"default": 180
},
"max_inline_downloads": {
"type": "integer",
"default": 4
},
"poll_interval_seconds": {
"type": "number",
"default": 2
},
"max_bytes_per_download": {
"type": "integer",
"default": 8388608
},
"include_inline_downloads": {
"type": "boolean",
"default": true
}
},
"additionalProperties": false
}wait_for_audio_project annotations
{
"title": "Wait for Audio Project",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}fetch_image_download — Fetch Image Download
Advertised read-only
Fetch a completed project's image as inline MCP image content for compatible clients. Use the exact signed download URL, including query parameters. Requires HTTPS at the configured Magic Hour media host. Read-only; limited to 8 MiB, or a smaller requested max_bytes. Use the signed URL directly for larger files.
fetch_image_download input schema
{
"type": "object",
"required": [
"download_url"
],
"properties": {
"max_bytes": {
"type": "integer",
"default": 8388608
},
"download_url": {
"type": "string"
}
},
"additionalProperties": false
}fetch_image_download annotations
{
"title": "Fetch Image Download",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}fetch_audio_download — Fetch Audio Download
Advertised read-only
Fetch a completed project's audio as inline MCP audio content for compatible clients. Use the exact signed download URL, including query parameters. Requires HTTPS at the configured Magic Hour media host. Read-only; limited to 8 MiB, or a smaller requested max_bytes. Use the signed URL directly for larger files.
fetch_audio_download input schema
{
"type": "object",
"required": [
"download_url"
],
"properties": {
"max_bytes": {
"type": "integer",
"default": 8388608
},
"download_url": {
"type": "string"
}
},
"additionalProperties": false
}fetch_audio_download annotations
{
"title": "Fetch Audio Download",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}fetch_video_download — Fetch Video Download
Advertised read-only
Fetch a completed project's video as an embedded MCP binary resource for compatible clients. Use the exact signed download URL, including query parameters. Requires HTTPS at the configured Magic Hour media host. Read-only; limited to 8 MiB, or a smaller requested max_bytes. Use the signed URL directly for larger files.
fetch_video_download input schema
{
"type": "object",
"required": [
"download_url"
],
"properties": {
"max_bytes": {
"type": "integer",
"default": 8388608
},
"download_url": {
"type": "string"
}
},
"additionalProperties": false
}fetch_video_download annotations
{
"title": "Fetch Video Download",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}get_account_info — Get account info
Advertised read-only
Returns credit balance and subscription details for the connected account. Use to inspect account information before generation. Read-only; this is not a request-specific cost quote or model-eligibility check.
get_account_info input schema
{
"type": "object",
"required": [],
"properties": {}
}get_account_info output schema
{
"type": "object",
"required": [
"id",
"email",
"tier",
"credits",
"subscription"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the account that owns the API key."
},
"tier": {
"enum": [
"free",
"creator",
"pro",
"business"
],
"type": "string",
"example": "pro",
"description": "Subscription tier in effect for the account. `free` if there is no active subscription, including while a subscription is `past_due`."
},
"email": {
"type": [
"string",
"null"
],
"example": "user@example.com",
"description": "Email address of the account."
},
"credits": {
"type": "integer",
"example": 12500,
"minimum": 0,
"description": "Credits currently available to spend. Includes subscription credits and any purchased credit packs."
},
"subscription": {
"type": [
"object",
"null"
],
"required": [
"name",
"status",
"price",
"discount",
"billing_interval",
"current_period_end",
"cancel_at_period_end"
],
"properties": {
"name": {
"type": [
"string",
"null"
],
"example": "Pro",
"description": "Name of the current subscription plan, e.g. `Creator`, `Pro`, `Pro Plus`, `Business`. `null` if the plan cannot be determined. Use `tier` for a machine-readable value."
},
"price": {
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "integer",
"example": 4900,
"minimum": 0,
"description": "Price charged per billing interval, in the smallest unit of the currency (e.g. 4900 is $49.00 for `usd`). Discounts are not applied."
},
"currency": {
"type": "string",
"example": "usd",
"description": "Three-letter ISO 4217 currency code, lowercase."
}
}
},
"status": {
"enum": [
"active",
"past_due"
],
"type": "string",
"example": "active",
"description": "Status of the subscription.\n- `active`: payments are up to date.\n- `past_due`: the latest payment failed. `tier` is `free` until payment succeeds. The subscription is canceled if payment keeps failing."
},
"discount": {
"type": [
"object",
"null"
],
"required": [
"percent_off",
"amount_off"
],
"properties": {
"amount_off": {
"type": [
"integer",
"null"
],
"description": "Fixed amount taken off `price.amount` each billing interval, in the smallest unit of the currency. `null` if the discount is a percentage."
},
"percent_off": {
"type": [
"number",
"null"
],
"example": 20,
"description": "Percentage taken off `price.amount` each billing interval. `null` if the discount is a fixed amount."
}
},
"description": "Discount applied to the subscription. `null` if no discount is applied."
},
"billing_interval": {
"enum": [
"month",
"year",
null
],
"type": [
"string",
"null"
],
"example": "month",
"description": "How often the subscription is billed. `null` if unknown."
},
"current_period_end": {
"type": [
"string",
"null"
],
"format": "date-time",
"example": "2026-10-01T00:00:00.000Z",
"description": "End of the current billing period, in ISO 8601 format. The subscription renews at this time, or ends if `cancel_at_period_end` is `true`."
},
"cancel_at_period_end": {
"type": "boolean",
"example": false,
"description": "Whether the subscription is scheduled to end at `current_period_end` instead of renewing. The subscription stays usable until then."
}
},
"description": "Details of the account's subscription plan. `null` if the account has no subscription, e.g. a free account, an account that only purchased credit packs, or an account on usage-based API pricing.\n\nReflects the plan currently configured on the subscription. If a plan change is scheduled, `tier` stays on the current plan until the next payment succeeds, so `tier` and `name` can briefly disagree."
}
}
}get_account_info annotations
{
"title": "Get account info",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}list_saved_items — List saved items
Advertised read-only
Lists the account's active saved characters, references, voice recordings, moodboards and brand kits, newest first. Reusable paths are in each item's assets[].file_path; temporary signed URLs support preview/download. Read-only; pass next_cursor as cursor for the next page.
list_saved_items input schema
{
"type": "object",
"required": [],
"properties": {
"type": {
"enum": [
"character",
"reference",
"voice",
"moodboard",
"brand_kit"
],
"type": "string",
"example": "character",
"description": "Only return saved items of this type."
},
"limit": {
"type": "integer",
"default": 20,
"example": 20,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of saved items to return. Defaults to 20."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque pagination cursor from the previous response's next_cursor."
}
}
}list_saved_items output schema
{
"type": "object",
"required": [
"items",
"next_cursor"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"type",
"name",
"assets"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the saved item."
},
"name": {
"type": [
"string",
"null"
],
"example": "Alex",
"description": "User-provided name of the saved item."
},
"type": {
"enum": [
"character",
"reference",
"voice",
"moodboard",
"brand_kit"
],
"type": "string",
"example": "character",
"description": "Saved item type."
},
"assets": {
"type": "array",
"items": {
"type": "object",
"required": [
"file_path",
"media_kind",
"is_primary",
"url",
"url_expires_at"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Signed URL for previewing or downloading the asset. Expires after 24 hours."
},
"file_path": {
"type": "string",
"example": "saved-items/user-id/item-id/image.png",
"description": "Durable asset path. Pass it to a compatible API asset field without uploading it again."
},
"is_primary": {
"type": "boolean",
"example": true,
"description": "Whether this asset is the saved item's primary asset."
},
"media_kind": {
"enum": [
"IMAGE",
"VIDEO",
"AUDIO"
],
"type": "string",
"example": "IMAGE",
"description": "Media type of the asset."
},
"url_expires_at": {
"type": "string",
"format": "date-time",
"example": "2026-09-17T00:00:00.000Z",
"description": "When the signed URL expires. The saved asset and file_path do not expire."
}
}
}
}
}
}
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more saved items."
}
}
}list_saved_items annotations
{
"title": "List saved items",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}get_upload_urls — Get upload URLs
Creates presigned upload URL and file-path pairs for local media. Use when a generation needs a file the user has locally: upload raw bytes to the returned upload_url, then pass its file_path to the create tool. Does not upload file bytes or start a generation.
get_upload_urls input schema
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"extension"
],
"properties": {
"type": {
"enum": [
"video",
"audio",
"image"
],
"type": "string",
"example": "video",
"description": "The type of asset to upload. Possible types are video, audio, image"
},
"extension": {
"type": "string",
"example": "mp4",
"pattern": "^[a-z0-9]+$",
"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,jpe,jfif,heic,heif,webp,avif,jp2,tiff,tif,bmp,gif,webp,webm"
}
}
},
"example": [
{
"type": "video",
"extension": "mp4"
},
{
"type": "audio",
"extension": "mp3"
}
],
"minItems": 1,
"description": "The list of assets to upload. The response array will match the order of items in the request body."
}
}
}get_upload_urls output schema
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"upload_url",
"expires_at",
"file_path"
],
"properties": {
"file_path": {
"type": "string",
"example": "video/id/1234.mp4",
"description": "this value is used in APIs that needs assets, such as image_file_path, video_file_path, and audio_file_path"
},
"expires_at": {
"type": "string",
"format": "date-time",
"example": "2024-07-21T17:32:28Z",
"description": "when the upload url expires, and will need to request a new one."
},
"upload_url": {
"type": "string",
"format": "uri",
"example": "https://videos.magichour.ai/id/video.mp4?auth-value=1234567890",
"description": "Used to upload the file to storage, send a PUT request with the file as data to upload."
}
}
},
"example": [
{
"file_path": "api-assets/id/video.mp4",
"expires_at": "2024-07-25T16:56:21.932Z",
"upload_url": "https://videos.magichour.ai/api-assets/id/video.mp4?auth-value=1234567890"
},
{
"file_path": "api-assets/id/audio.mp3",
"expires_at": "2024-07-25T16:56:21.932Z",
"upload_url": "https://videos.magichour.ai/api-assets/id/audio.mp3?auth-value=1234567890"
}
],
"description": "The list of upload URLs and file paths for the assets. The response array will match the order of items in the request body. Refer to the [Input Files Guide](https://docs.magichour.ai/integration/inputs-and-outputs) for more details."
}
},
"description": "Success"
}get_upload_urls annotations
{
"title": "Get upload URLs",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}get_face_detection_results — Get face detection results
Advertised read-only
Returns a face-detection job's status and detected faces. Use with the id from detect_faces to inspect progress and choose face mappings before a selected-face swap. Read-only; faces may populate while processing.
get_face_detection_results input schema
{
"type": "object",
"required": [
"id"
],
"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)."
}
}
}get_face_detection_results output schema
{
"type": "object",
"required": [
"id",
"credits_charged",
"status",
"faces"
],
"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)."
},
"faces": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"url"
],
"properties": {
"url": {
"type": "string",
"example": "https://videos.magichour.ai/api-assets/id/0-0.png",
"description": "The url to the face image. This is used to render the image in your applications."
},
"path": {
"type": "string",
"example": "api-assets/id/0-0.png",
"description": "The path to the face image. This should be used in face swap photo/video API calls as `.assets.face_mappings.original_face`"
}
}
},
"example": [
{
"url": "https://videos.magichour.ai/api-assets/id/0-0.png",
"path": "api-assets/id/0-0.png"
}
],
"description": "The faces detected in the image or video. The list is populated as faces are detected."
},
"status": {
"enum": [
"queued",
"rendering",
"complete",
"error"
],
"type": "string",
"example": "complete",
"description": "The status of the detection."
},
"credits_charged": {
"type": "integer",
"example": 0,
"description": "The credits charged for the task."
}
}
}get_face_detection_results annotations
{
"title": "Get face detection results",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}detect_faces — Detect faces
Open-world
Starts an asynchronous face-detection task for a supplied image or video and returns its id and charge information. Use before a selected-face swap, then retrieve its status and detected faces with get_face_detection_results. Current API documentation describes detection as free; pricing may change.
detect_faces input schema
{
"type": "object",
"required": [
"assets"
],
"properties": {
"assets": {
"type": "object",
"required": [
"target_file_path"
],
"properties": {
"target_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"description": "This is the image or video where the face will be detected. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for face detection"
},
"confidence_score": {
"type": "number",
"default": 0.5,
"example": 0.5,
"maximum": 1,
"minimum": 0,
"multipleOf": 0.05,
"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."
}
}
}detect_faces output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "uuid-example",
"description": "The id of the task. Use this value in the [get face detection details API](https://docs.magichour.ai/api-reference/files/get-face-detection-details) to get the details of the face detection task."
},
"credits_charged": {
"type": "integer",
"description": "The credits charged for the task."
}
}
}detect_faces annotations
{
"title": "Detect faces",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}get_video_project — Get video project
Advertised read-only
Returns a video project's status and, once complete, its download URLs. Use to check progress with the id from a video create tool. Read-only.
get_video_project input schema
{
"type": "object",
"required": [
"id"
],
"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."
}
}
}get_video_project output schema
{
"type": "object",
"required": [
"id",
"name",
"status",
"type",
"created_at",
"width",
"height",
"enabled",
"start_seconds",
"end_seconds",
"credits_charged",
"fps",
"error",
"downloads"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"fps": {
"type": "number",
"example": 30,
"description": "Frame rate of the video. If the status is not 'complete', the frame rate is an estimate and will be adjusted when the video completes."
},
"name": {
"type": [
"string",
"null"
],
"example": "Example Name",
"description": "The name of the video."
},
"type": {
"type": "string",
"example": "FACE_SWAP",
"description": "The type of the video project. Possible values are ANIMATION, AUTO_SUBTITLE, VIDEO_TO_VIDEO, FACE_SWAP, TEXT_TO_VIDEO, IMAGE_TO_VIDEO, LIP_SYNC, TALKING_PHOTO, AVATAR, VIDEO_UPSCALER, VIDEO_EDITOR, CHARACTER_REPLACE, VIDEO_COLORIZER, VIDEO_WATERMARK_REMOVER, VIDEO_COLOR_GRADER, VIDEO_TRANSLATOR, MUSIC_VIDEO, EXTEND, AUDIO_TO_VIDEO, VIDEO_EXPANDER, UGC_AD"
},
"error": {
"type": [
"object",
"null"
],
"required": [
"message",
"code"
],
"properties": {
"code": {
"type": "string",
"example": "no_source_face",
"description": "An error code to indicate why a failure happened."
},
"message": {
"type": "string",
"example": "Please use an image with a detectable face",
"description": "Details on the reason why a failure happened."
}
},
"description": "In the case of an error, this object will contain the error encountered during video render"
},
"width": {
"type": "integer",
"example": 512,
"description": "The width of the final output video. A value of -1 indicates the width can be ignored."
},
"height": {
"type": "integer",
"example": 960,
"description": "The height of the final output video. A value of -1 indicates the height can be ignored."
},
"status": {
"enum": [
"draft",
"queued",
"rendering",
"complete",
"error",
"canceled"
],
"type": "string",
"example": "complete",
"description": "The status of the video.\n\n- `draft` - the project was created but has not been submitted for rendering\n- `queued` - the job is waiting for an available server\n- `rendering` - the job is being processed; the `video.started` webhook event fires when rendering begins\n- `complete` - the job finished successfully; fires `video.completed`\n- `error` - the job failed during processing; fires `video.errored`\n- `canceled` - the job was manually canceled (for example from the Magic Hour web app)\n\n**Note:** `rendering`, `complete`, and `error` have matching webhook events; `canceled` does not - a canceled job emits no webhook event, so poll this endpoint to detect cancellation."
},
"enabled": {
"type": "boolean",
"description": "Whether this resource is active. If false, it is deleted."
},
"downloads": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"expires_at"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"example": "https://videos.magichour.ai/id/output.mp4"
},
"expires_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-19T05:16:19.027Z"
}
},
"description": "The download url and expiration date of the image project"
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}get_video_project annotations
{
"title": "Get video project",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}delete_video_project — Delete video project
Advertised destructive
Deletes the video project and attempts to delete its completed output. Cannot be undone; confirm with the user first.
delete_video_project input schema
{
"type": "object",
"required": [
"id"
],
"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."
}
}
}delete_video_project annotations
{
"title": "Delete video project",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}create_talking_photo — Create talking photo
Open-world
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Animates a still portrait so it speaks an existing audio recording. Use with a portrait photo and an audio file; text alone is not accepted and this tool does not synthesize speech. Starts a background job that costs credits; returns a project id for wait_for_video_project.
create_talking_photo input schema
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Talking Photo - dateTime",
"example": "My Talking Photo video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"example": "A person smiling and speaking naturally to the camera",
"description": "A text prompt to guide the generation. Only applicable when generation_mode is `prompted`.\nThis field is ignored for other modes."
},
"generation_mode": {
"enum": [
"realistic",
"prompted",
"pro",
"standard",
"stable",
"expressive"
],
"type": "string",
"default": "realistic",
"example": "realistic",
"description": "Controls motion style. `realistic` animates the supplied portrait; `prompted` also accepts a scene prompt. Deprecated aliases remain supported: `pro` and `stable` select `realistic`; `standard` and `expressive` select `prompted`."
}
},
"description": "Attributes used to dictate the style of the output"
},
"assets": {
"type": "object",
"required": [
"image_file_path",
"audio_file_path"
],
"properties": {
"audio_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"description": "The audio file to sync with the image. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
},
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The source image to animate. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for creating a talking photo"
},
"resolution": {
"enum": [
"480p",
"720p"
],
"type": "string",
"example": "480p",
"description": "Output preset. Overrides `max_resolution`. Defaults to 480p in prompted mode; realistic mode uses the mapped plan maximum."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "The end time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 60s."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "The start time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 60s."
}
}
}create_talking_photo output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}create_talking_photo annotations
{
"title": "Create talking photo",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}create_spoken_ad_video — Create spoken ad video
Open-world
Creates a creator-style spoken ad video from a prepared image and a text script. Use when the image is ready and the dialogue should be generated from text. Starts a background job that costs credits; returns a project id for wait_for_video_project.
create_spoken_ad_video input schema
{
"type": "object",
"required": [
"assets",
"script",
"end_seconds"
],
"properties": {
"model": {
"enum": [
"kling-3.0",
"ltx-2.5",
"veo3.1"
],
"type": "string",
"description": "Defaults to kling-3.0 on paid plans and ltx-2.5 on free plans."
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/image.jpg",
"minLength": 1,
"description": "Prepared image to animate. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"additionalProperties": false
},
"script": {
"type": "string",
"example": "Meet your new everyday essential.",
"minLength": 1,
"description": "The words the actor should speak. Character limits apply after trimming:\n* kling-3.0: 2304 characters.\n* ltx-2.5: 1804 characters.\n* veo3.1: 2500 characters.\nLTX and Kling dialogue wrappers count toward their model prompt limit."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"description": "Defaults to 720p on paid plans and 480p on free plans. Unsupported model/resolution combinations and resolutions unavailable for your plan are rejected."
},
"end_seconds": {
"type": "number",
"example": 4,
"minimum": 1,
"description": "Video duration in seconds. Supported values by model:\n* kling-3.0: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 seconds.\n* ltx-2.5: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60 seconds.\n* veo3.1: 4, 6, 8, 15, 22, 29, 36, 43, 50, 57, 64, 71, 78, 85, 92, 99, 106, 113, 120, 127, 134, 141 seconds.\nFree plans are limited to 5 seconds unless a credit pack has been purchased."
}
}
}create_spoken_ad_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}create_spoken_ad_video annotations
{
"title": "Create spoken ad video",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}edit_video — Edit video
Open-world
Edits the appearance or content of a supplied video segment using a text prompt. Use with a source video, the requested changes and the clip end time. Starts a background job that costs credits; returns a project id for wait_for_video_project.
edit_video input schema
{
"type": "object",
"required": [
"end_seconds",
"style",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Video Editor - dateTime",
"example": "My Video Editor video",
"description": "Give your video a custom name for easy identification."
},
"model": {
"enum": [
"gemini-omni-1.1",
"ltx-2.5",
"gemini-omni",
"ltx-2.3"
],
"type": "string",
"example": "ltx-2.5",
"description": "Editing model. Defaults to LTX 2.5 for free tier and `gemini-omni-1.1` for paid. `gemini-omni` is deprecated; use `gemini-omni-1.1` instead."
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"prompt": {
"type": "string",
"example": "Change the car color to blue",
"minLength": 1,
"description": "The prompt used to edit the video."
}
}
},
"assets": {
"type": "object",
"required": [
"video_file_path"
],
"properties": {
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "The video to edit. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for video editing."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"example": "480p",
"description": "Output resolution. Defaults to `480p` for free tier and `720p` for paid. `gemini-omni-1.1` and deprecated `gemini-omni` support 720p and 1080p; LTX 2.5 supports 480p, 720p, and 1080p."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip in seconds. Must be greater than `start_seconds`. Minimum duration depends on model: `gemini-omni-1.1`: 3s, LTX 2.5: 0.5s. Maximum duration depends on model: `gemini-omni-1.1`: 10s, LTX 2.5: 60s (30s at 1080p)."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}edit_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}edit_video annotations
{
"title": "Edit video",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}translate_video — Translate video
Open-world
Translates speech in a supplied video segment into a supported target language. Starts a background job that costs credits; returns a project id for wait_for_video_project.
translate_video input schema
{
"type": "object",
"required": [
"end_seconds",
"target_language",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Video Translator - dateTime",
"example": "My Video Translator video",
"description": "Give your video a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"video_file_path"
],
"properties": {
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "Source video containing the speech to translate. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Source video for the translation job."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"example": "480p",
"description": "Output video resolution. Defaults to 480p. 720p and 1080p require a paid plan."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds. The clip must be 1-30 seconds long."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
},
"target_language": {
"enum": [
"English",
"Chinese (Simplified)",
"Hindi",
"Spanish",
"Arabic",
"French",
"Afrikaans",
"Bengali",
"Bulgarian",
"Catalan",
"Croatian",
"Czech",
"Danish",
"Dutch",
"Estonian",
"Finnish",
"German",
"Greek",
"Gujarati",
"Hebrew",
"Hungarian",
"Indonesian",
"Italian",
"Japanese",
"Kannada",
"Kazakh",
"Korean",
"Latvian",
"Lithuanian",
"Malay",
"Malayalam",
"Marathi",
"Norwegian",
"Persian",
"Polish",
"Portuguese",
"Punjabi",
"Romanian",
"Russian",
"Serbian",
"Slovak",
"Slovenian",
"Swahili",
"Swedish",
"Tamil",
"Telugu",
"Thai",
"Chinese (Traditional)",
"Turkish",
"Ukrainian",
"Urdu",
"Vietnamese",
"Welsh"
],
"type": "string",
"example": "Spanish",
"description": "Language to translate the video's speech into."
}
}
}translate_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}translate_video annotations
{
"title": "Translate video",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}upscale_video — Upscale video
Open-world
Upscales a supplied video segment to a selected output resolution while preserving its aspect ratio. Starts a background job that costs credits; returns a project id for wait_for_video_project.
upscale_video input schema
{
"type": "object",
"required": [
"end_seconds",
"resolution",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Video Upscaler - dateTime",
"example": "My Video Upscaler video",
"description": "Give your video a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"video_file_path"
],
"properties": {
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "Video to upscale. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Source video for the upscale job."
},
"resolution": {
"enum": [
"720p",
"1080p",
"2k",
"4k"
],
"type": "string",
"example": "1080p",
"description": "Output resolution. `720p` and `1080p` set the output's short side, `2k` and `4k` its long side; the aspect ratio is kept. Requires a paid plan."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}upscale_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}upscale_video annotations
{
"title": "Upscale video",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}create_animation — Create animation
Open-world
Creates a stylized animated video with art and camera settings, using a custom prompt or an audio-derived prompt mode. Can use an initial image and audio. Credits depend on frame rate and duration; returns a project id for wait_for_video_project.
create_animation input schema
{
"type": "object",
"required": [
"fps",
"end_seconds",
"height",
"width",
"style",
"assets"
],
"properties": {
"fps": {
"type": "number",
"example": 12,
"minimum": 1,
"description": "The desire output video frame rate"
},
"name": {
"type": "string",
"default": "Animation - dateTime",
"example": "My Animation video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"art_style",
"camera_effect",
"prompt_type",
"transition_speed"
],
"properties": {
"prompt": {
"type": "string",
"example": "Cyberpunk city",
"description": "The prompt used for the video. Prompt is required if `prompt_type` is `custom`. Otherwise this value is ignored"
},
"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",
"example": "Painterly Illustration",
"description": "The art style used to create the output video"
},
"prompt_type": {
"enum": [
"custom",
"use_lyrics",
"ai_choose"
],
"type": "string",
"example": "custom",
"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`."
},
"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",
"example": "Simple Zoom In",
"description": "The camera effect used to create the output video"
},
"art_style_custom": {
"type": "string",
"example": "Watercolor painting with soft pastel colors",
"description": "Describe custom art style. This field is required if `art_style` is `Custom`"
},
"transition_speed": {
"type": "integer",
"example": 5,
"maximum": 10,
"minimum": 1,
"description": "Change determines how quickly the video's content changes across frames. \n* Higher = more rapid transitions.\n* Lower = more stable visual experience."
}
},
"description": "Defines the style of the output video"
},
"width": {
"type": "integer",
"example": 512,
"minimum": 64,
"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"
},
"assets": {
"type": "object",
"example": {
"audio_source": "file",
"audio_file_path": "api-assets/id/1234.mp3",
"image_file_path": "api-assets/id/1234.png"
},
"required": [
"audio_source"
],
"properties": {
"youtube_url": {
"type": "string",
"format": "uri",
"minLength": 1,
"description": "Using a youtube video as the input source. This field is required if `audio_source` is `youtube`"
},
"audio_source": {
"enum": [
"none",
"file",
"youtube"
],
"type": "string",
"example": "file",
"description": "Optionally add an audio source if you'd like to incorporate audio into your video"
},
"audio_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"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 file. The URL path must end in a supported file extension.\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"
},
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "An initial image to use a the first frame of the video. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for animation."
},
"height": {
"type": "integer",
"example": 512,
"minimum": 64,
"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"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "This value determines the duration of the output video."
}
}
}create_animation output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}create_animation annotations
{
"title": "Create animation",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}create_video_from_audio — Create video from audio
Open-world
Generates an audio-guided video from a supplied audio track, with an optional starting image and visual prompt. Starts a background job that costs credits; returns a project id for wait_for_video_project.
create_video_from_audio input schema
{
"type": "object",
"required": [
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Audio To Video - dateTime",
"example": "My Audio To Video video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"example": "Car driving through a city",
"description": "Prompt to guide the visual style of the video."
}
},
"description": "Attributes used to dictate the style of the output"
},
"assets": {
"type": "object",
"required": [
"audio_file_path"
],
"properties": {
"audio_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"description": "The path of the audio file. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
},
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "Reference image for the initial frame of the video. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the audio file and an optional reference image."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"example": "480p",
"description": "Output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}create_video_from_audio output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}create_video_from_audio annotations
{
"title": "Create video from audio",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}add_subtitles_to_video — Add subtitles to video
Open-world
Adds automatically generated subtitles to a supplied video segment using a subtitle preset or custom text styling. Starts a background job that costs credits; returns a project id for wait_for_video_project.
add_subtitles_to_video input schema
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"assets",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Auto Subtitle - dateTime",
"example": "My Auto Subtitle video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"template": {
"enum": [
"karaoke",
"cinematic",
"minimalist",
"highlight"
],
"type": "string",
"example": "karaoke",
"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",
"example": "Noto Sans",
"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."
},
"font_size": {
"type": "number",
"example": 24,
"description": "Font size in pixels. If not provided, the font size is automatically calculated based on the video resolution."
},
"font_style": {
"type": "string",
"example": "normal",
"description": "Font style (e.g., normal, italic, bold)"
},
"text_color": {
"type": "string",
"example": "#FFFFFF",
"description": "Primary text color in hex format"
},
"stroke_color": {
"type": "string",
"example": "#000000",
"description": "Stroke (outline) color of the text"
},
"stroke_width": {
"type": "number",
"example": 1,
"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."
},
"vertical_position": {
"type": "string",
"example": "bottom",
"description": "Vertical alignment of the text (e.g., top, center, bottom)"
},
"horizontal_position": {
"type": "string",
"example": "center",
"description": "Horizontal alignment of the text (e.g., left, center, right)"
},
"highlighted_text_color": {
"type": "string",
"example": "#FFD700",
"description": "Color used to highlight the current spoken text"
}
},
"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"
},
"assets": {
"type": "object",
"required": [
"video_file_path"
],
"properties": {
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "This is the video used to add subtitles. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for auto subtitle generator"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}add_subtitles_to_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}add_subtitles_to_video annotations
{
"title": "Add subtitles to video",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}replace_character_in_video — Replace character in video
Open-world
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Replaces a subject in a video with a character from a reference image, or transfers the video's motion onto that character. Starts a background job that costs credits; returns a project id for wait_for_video_project.
replace_character_in_video input schema
{
"type": "object",
"required": [
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Character Replace - dateTime",
"example": "My Character Replace video",
"description": "Give your video a custom name for easy identification."
},
"model": {
"enum": [
"wan-animate",
"kling-3.0",
"minimax-h3"
],
"type": "string",
"default": "wan-animate",
"example": "wan-animate",
"description": "Model to use. Defaults to `wan-animate`.\n\n* **`wan-animate`**: 480p, 720p. Supports `points` subject selection.\n* **`kling-3.0`**: 720p, 1080p. Clips of 3–10 seconds in `replace` mode or 3–30 seconds in `animate` mode. Picks the main person automatically, so `points` are rejected.\n* **`minimax-h3`**: 480p, 720p, 1080p. Clips of 1–60 seconds in `replace` mode or 1–60 seconds in `animate` mode. Subject `points` are `replace`-only; `animate` with `selection_mode` `point` returns 422, and with `auto` or no `selection_mode` the points are ignored."
},
"style": {
"type": "object",
"example": {
"mode": "replace",
"selection_mode": "auto"
},
"properties": {
"mode": {
"enum": [
"replace",
"animate"
],
"type": "string",
"example": "replace",
"description": "Processing mode. `replace` swaps the detected subject with your reference character. `animate` transfers motion from the video onto your character image."
},
"points": {
"type": "array",
"items": {
"type": "object",
"required": [
"position_x",
"position_y",
"time_seconds"
],
"properties": {
"position_x": {
"type": "integer",
"example": 320,
"minimum": 0,
"description": "Horizontal pixel coordinate in the source video frame at `time_seconds`, measured from the left edge."
},
"position_y": {
"type": "integer",
"example": 180,
"minimum": 0,
"description": "Vertical pixel coordinate in the source video frame at `time_seconds`, measured from the top edge."
},
"time_seconds": {
"type": "number",
"format": "float",
"example": 2.5,
"minimum": 0,
"description": "Timestamp on the source video timeline in seconds. Uses the same clock as `start_seconds` and `end_seconds`."
}
}
},
"description": "On-frame markers for manual subject selection. Required when `selection_mode` is `point`. Ignored when `selection_mode` is `auto` or omitted. Rejected for models without subject selection (supported by `wan-animate`, `minimax-h3`). `minimax-h3` subject `points` are `replace`-only; `animate` with `selection_mode` `point` returns 422, and with `auto` or no `selection_mode` the points are ignored."
},
"prompt": {
"type": "string",
"maxLength": 2000,
"description": "Optional direction. Supported by kling-3.0, minimax-h3."
},
"selection_mode": {
"enum": [
"auto",
"point"
],
"type": "string",
"example": "auto",
"description": "How to locate the subject in the source video. `auto` detects a person automatically. `point` uses your `points` to mark the subject and is supported by `wan-animate`, `minimax-h3`. `minimax-h3` subject `points` are `replace`-only; `animate` with `selection_mode` `point` returns 422, and with `auto` or no `selection_mode` the points are ignored. Defaults to `auto`."
}
},
"description": "Optional style controls for replace vs animate mode and subject selection."
},
"assets": {
"type": "object",
"required": [
"video_file_path",
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/5678.png",
"minLength": 1,
"description": "Reference character image used as the replacement or animation target. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
},
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "Source video containing the subject to replace or animate. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Source video and reference character image for the job."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"example": "480p",
"description": "Output video resolution. Must be supported by `model`. Defaults to the lowest resolution available on your plan for that model."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}replace_character_in_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}replace_character_in_video annotations
{
"title": "Replace character in video",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}swap_face_in_video — Swap face in video
Open-world
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Swaps faces in an existing video: all faces with a reference image, or selected faces using detect_faces results. Starts a background job that costs credits; returns a project id for wait_for_video_project.
swap_face_in_video input schema
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Face Swap - dateTime",
"example": "My Face Swap video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"example": {
"version": "default"
},
"properties": {
"version": {
"enum": [
"v1",
"v2",
"default"
],
"type": "string",
"example": "default",
"description": "Select face-swap version `v1` or `v2`. `default` uses the server-selected version, which may change over time."
}
},
"description": "Style of the face swap video."
},
"assets": {
"type": "object",
"example": {
"video_source": "file",
"face_swap_mode": "all-faces",
"image_file_path": "api-assets/id/1234.png",
"video_file_path": "api-assets/id/1234.mp4"
},
"required": [
"video_source"
],
"properties": {
"youtube_url": {
"type": "string",
"format": "uri",
"description": "YouTube URL (required if `video_source` is `youtube`)."
},
"video_source": {
"enum": [
"file",
"youtube"
],
"type": "string",
"example": "file",
"description": "Choose your video source."
},
"face_mappings": {
"type": "array",
"items": {
"type": "object",
"required": [
"original_face",
"new_face"
],
"properties": {
"new_face": {
"type": "string",
"example": "api-assets/id/1234.png",
"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 file. The URL path must end in a supported file extension.\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"
},
"original_face": {
"type": "string",
"example": "api-assets/id/0-0.png",
"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": [
{
"new_face": "api-assets/id/1234.png",
"original_face": "api-assets/id/0-0.png"
}
],
"maxItems": 5,
"description": "This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`."
},
"face_swap_mode": {
"enum": [
"all-faces",
"individual-faces"
],
"type": "string",
"default": "all-faces",
"example": "all-faces",
"description": "Choose which faces to swap. `all-faces` uses one source image for all detected faces (`image_file_path` required). `individual-faces` uses exact `face_mappings`."
},
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"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 file. The URL path must end in a supported file extension.\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"
},
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}swap_face_in_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}swap_face_in_video annotations
{
"title": "Swap face in video",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}create_video_from_image — Create video from image
Open-world
Animates a supplied image into a video using motion instructions and available model options. Starts a background job that costs credits; returns a project id for wait_for_video_project.
create_video_from_image input schema
{
"type": "object",
"required": [
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Image To Video - dateTime",
"example": "My Image To Video video",
"description": "Give your video a custom name for easy identification."
},
"audio": {
"type": "boolean",
"example": true,
"description": "Whether to include audio in the video. Defaults to `false` if not specified.\n\nAudio support varies by model:\n* **`gemini-omni-1.1`**: Not supported\n* **`kling-2.6`**: Not supported\n* **`kling-3.0`**: Toggle-able: audio adds extra credits when enabled\n* **`ltx-2.5`**: 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-fast`**: 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* **`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* **`wan-3.0`**: Toggle-able: no additional credits for audio\n"
},
"model": {
"enum": [
"default",
"minimax-h3",
"kling-3.0",
"ltx-2.5",
"wan-2.2",
"seedance-2.5",
"wan-3.0",
"seedance-2.0-mini",
"veo3.1",
"veo3.1-lite",
"seedance-2.0",
"kling-2.6",
"gemini-omni-1.1",
"seedance-2.0-fast",
"seedance-1.5",
"sora-2",
"ltx-2.3",
"ltx-2",
"kling-2.5",
"kling-1.6",
"seedance",
"kling-2.5-audio",
"veo3.1-audio"
],
"type": "string",
"default": "default",
"example": "ltx-2.5",
"description": "The video generation model. With `default`, paid tiers use `kling-3.0` and Free uses `ltx-2.5`. Duration, resolution, audio and reference support depend on the selected model. Deprecated model values ending in `-audio` enable `audio`."
},
"style": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"example": "a dog running",
"description": "The prompt used for the video."
}
},
"description": "Attributed used to dictate the style of the output"
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The path of the image file. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
},
"end_image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The image to use as the last frame of the video.\n\n* **`gemini-omni-1.1`**: Supports 360p, 720p, 1080p, 4k.\n* **`kling-2.6`**: Supports 1080p.\n* **`kling-3.0`**: Supports 720p, 1080p, 4k.\n* **`ltx-2.5`**: 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, 1080p, 4k.\n* **`seedance-2.0-fast`**: Supports 480p, 720p.\n* **`seedance-2.0-mini`**: Supports 480p, 720p.\n* **`seedance-2.5`**: Supports 480p, 720p, 1080p.\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* **`wan-3.0`**: Supports 480p, 720p, 1080p.\n\nThis value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for image-to-video."
},
"resolution": {
"enum": [
"360p",
"480p",
"720p",
"1080p",
"4k"
],
"type": "string",
"example": "480p",
"description": "Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers.\n\n* **`gemini-omni-1.1`**: Supports 360p, 720p, 1080p, 4k.\n* **`kling-2.6`**: Supports 720p, 1080p.\n* **`kling-3.0`**: Supports 720p, 1080p, 4k.\n* **`ltx-2.5`**: 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, 1080p, 4k.\n* **`seedance-2.0-fast`**: Supports 480p, 720p.\n* **`seedance-2.0-mini`**: Supports 480p, 720p.\n* **`seedance-2.5`**: Supports 480p, 720p, 1080p.\n* **`veo3.1`**: Supports 720p, 1080p.\n* **`veo3.1-lite`**: Supports 720p, 1080p.\n* **`wan-2.2`**: Supports 480p, 720p, 1080p.\n* **`wan-3.0`**: Supports 480p, 720p, 1080p.\n"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"maximum": 60,
"minimum": 1,
"description": "The total duration of the output video in seconds. Supported durations depend on the chosen model:\n\n* **`gemini-omni-1.1`**: any integer from 3 to 10\n* **`kling-2.6`**: 5, 10\n* **`kling-3.0`**: any integer from 3 to 15\n* **`ltx-2.5`**: any integer from 1 to 60\n* **`minimax-h3`**: any integer from 1 to 30\n* **`seedance-1.5`**: any integer from 4 to 12\n* **`seedance-2.0`**: any integer from 4 to 15\n* **`seedance-2.0-fast`**: any integer from 4 to 15\n* **`seedance-2.0-mini`**: any integer from 4 to 15\n* **`seedance-2.5`**: any integer from 4 to 30\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* **`wan-3.0`**: 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30\n"
}
}
}create_video_from_image output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}create_video_from_image annotations
{
"title": "Create video from image",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}create_lip_sync_video — Create lip sync video
Open-world
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Adjusts an existing video's lip movements to match supplied replacement audio. For a still portrait plus audio, use create_talking_photo. Starts a background job that costs credits; returns a project id for wait_for_video_project.
create_lip_sync_video input schema
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Lip Sync - dateTime",
"example": "My Lip Sync video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"generation_mode": {
"enum": [
"lite",
"standard",
"pro"
],
"type": "string",
"default": "lite",
"example": "lite",
"description": "Select the lip-sync mode. `lite` costs 1 credit per video frame. `standard` costs 1 credit per video frame; `pro` costs 2. Both `standard` and `pro` require visible mouth movement in the opening seconds of the input video. `pro` requires a Creator, Pro or Business tier. For a still image, including a static image saved as video, use `create_talking_photo` with the original image and audio."
}
},
"description": "Attributes used to dictate the style of the output"
},
"assets": {
"type": "object",
"example": {
"video_source": "file",
"audio_file_path": "api-assets/id/1234.mp3",
"video_file_path": "api-assets/id/1234.mp4"
},
"required": [
"audio_file_path",
"video_source"
],
"properties": {
"youtube_url": {
"type": "string",
"format": "uri",
"description": "YouTube URL (required if `video_source` is `youtube`)."
},
"video_source": {
"enum": [
"file",
"youtube"
],
"type": "string",
"example": "file",
"description": "Choose your video source."
},
"audio_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"description": "The path of the audio file. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
},
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for lip-sync. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"max_fps_limit": {
"type": "number",
"example": 12,
"minimum": 1,
"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."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}create_lip_sync_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}create_lip_sync_video annotations
{
"title": "Create lip sync video",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}create_video_from_text — Create video from text
Open-world
Generates a video from a text prompt, with optional supported reference inputs and model settings. To animate an existing starting image, use create_video_from_image. Starts a background job that costs credits; returns a project id for wait_for_video_project.
create_video_from_text input schema
{
"type": "object",
"required": [
"end_seconds",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Text To Video - dateTime",
"example": "My Text To Video video",
"description": "Give your video a custom name for easy identification."
},
"audio": {
"type": "boolean",
"example": true,
"description": "Whether to include audio in the video. Defaults to `false` if not specified.\n\nAudio support varies by model:\n* **`gemini-omni-1.1`**: Not supported\n* **`kling-2.6`**: Not supported\n* **`kling-3.0`**: Toggle-able: audio adds extra credits when enabled\n* **`ltx-2.5`**: 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-fast`**: 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* **`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* **`wan-3.0`**: Toggle-able: no additional credits for audio\n"
},
"model": {
"enum": [
"default",
"minimax-h3",
"kling-3.0",
"ltx-2.5",
"wan-2.2",
"seedance-2.5",
"wan-3.0",
"seedance-2.0-mini",
"veo3.1",
"veo3.1-lite",
"seedance-2.0",
"kling-2.6",
"gemini-omni-1.1",
"seedance-2.0-fast",
"seedance-1.5",
"sora-2",
"ltx-2.3",
"ltx-2",
"kling-2.5",
"kling-1.6",
"seedance",
"kling-2.5-audio",
"veo3.1-audio"
],
"type": "string",
"default": "default",
"example": "ltx-2.5",
"description": "The video generation model. With `default`, paid tiers use `kling-3.0` and Free uses `ltx-2.5`. Duration, resolution, audio and reference support depend on the selected model. Deprecated model values ending in `-audio` enable `audio`."
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"prompt": {
"type": "string",
"example": "a dog running",
"maxLength": 20000,
"minLength": 1,
"description": "The prompt used for the video."
}
}
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"file_path"
],
"properties": {
"name": {
"type": "string",
"example": "hero",
"pattern": "^[A-Za-z][\\w-]*$"
},
"file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
}
},
"maxItems": 10,
"minItems": 1,
"description": "Reference media for video generation. Name references without @ and refer to them as @name in style.prompt. Maximum 10 references total.\n\nSupported models and reference media:\n* **`gemini-omni-1.1`**: Supports images, videos. Up to 10 references.\n* **`kling-3.0`**: Supports images, videos.\n* **`minimax-h3`**: Supports images, videos, audio.\n* **`seedance-2.0`**: Supports images, videos, audio.\n* **`seedance-2.0-fast`**: Supports images, videos, audio.\n* **`seedance-2.0-mini`**: Supports images, videos, audio.\n* **`seedance-2.5`**: Supports images, videos, audio.\n* **`veo3.1`**: Supports images. Up to 3 references. Requires `end_seconds` of 8.\n* **`wan-3.0`**: Supports images, videos, audio."
},
"resolution": {
"enum": [
"360p",
"480p",
"720p",
"1080p",
"4k"
],
"type": "string",
"example": "480p",
"description": "Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers.\n\n* **`gemini-omni-1.1`**: Supports 360p, 720p, 1080p, 4k.\n* **`kling-2.6`**: Supports 720p, 1080p.\n* **`kling-3.0`**: Supports 720p, 1080p, 4k.\n* **`ltx-2.5`**: 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, 1080p, 4k.\n* **`seedance-2.0-fast`**: Supports 480p, 720p.\n* **`seedance-2.0-mini`**: Supports 480p, 720p.\n* **`seedance-2.5`**: Supports 480p, 720p, 1080p.\n* **`veo3.1`**: Supports 720p, 1080p.\n* **`veo3.1-lite`**: Supports 720p, 1080p.\n* **`wan-2.2`**: Supports 480p, 720p, 1080p.\n* **`wan-3.0`**: Supports 480p, 720p, 1080p.\n"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"maximum": 60,
"minimum": 1,
"description": "The total duration of the output video in seconds. Supported durations depend on the chosen model:\n\n* **`gemini-omni-1.1`**: any integer from 3 to 10\n* **`kling-2.6`**: 5, 10\n* **`kling-3.0`**: any integer from 3 to 15\n* **`ltx-2.5`**: any integer from 1 to 60\n* **`minimax-h3`**: any integer from 1 to 30\n* **`seedance-1.5`**: any integer from 4 to 12\n* **`seedance-2.0`**: any integer from 4 to 15\n* **`seedance-2.0-fast`**: any integer from 4 to 15\n* **`seedance-2.0-mini`**: any integer from 4 to 15\n* **`seedance-2.5`**: any integer from 4 to 30\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* **`wan-3.0`**: 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30\n"
},
"aspect_ratio": {
"enum": [
"16:9",
"9:16",
"1:1"
],
"type": "string",
"example": "16:9",
"description": "Provide `aspect_ratio` to set the video’s aspect ratio. Determines the aspect ratio of the output video.\n\n* **`gemini-omni-1.1`**: Supports 16:9, 9:16.\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.5`**: 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-fast`**: 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* **`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* **`wan-3.0`**: Supports 16:9, 9:16, 1:1.\n"
}
}
}create_video_from_text output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}create_video_from_text annotations
{
"title": "Create video from text",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}restyle_video — Restyle video
Open-world
Restyles an existing video clip with an art-style preset or a custom prompt. Supports v1/v2 presets, not v3. Starts a background job that costs credits; returns a project id for wait_for_video_project.
restyle_video input schema
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"style",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Video To Video - dateTime",
"example": "My Video To Video video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"art_style"
],
"properties": {
"model": {
"enum": [
"Dreamshaper",
"Absolute Reality",
"Flat 2D Anime",
"Soft Anime",
"Kaywaii",
"Western Anime",
"3D Anime",
"default"
],
"type": "string",
"default": "default",
"example": "default",
"description": "Select a listed rendering model for the art style. `default` uses the selected art style's default model."
},
"prompt": {
"type": [
"string",
"null"
],
"example": "A cinematic scene with warm lighting",
"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."
},
"version": {
"enum": [
"v1",
"v2",
"default"
],
"type": "string",
"default": "default",
"example": "default",
"description": "Select restyling version `v1` or `v2`. `default` uses the selected art style's default version. Some styles default to v3, which this API does not support. For `Studio Ghibli`, explicitly set `version` to `v2` for its supported preset."
},
"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",
"example": "Minecraft"
},
"prompt_type": {
"enum": [
"default",
"custom",
"append_default"
],
"type": "string",
"default": "default",
"example": "default",
"description": "`default` uses the art style's preset prompt and ignores `prompt`. `custom` uses the supplied `prompt`; v1 still adds its LoRA prompt to apply the art style. `append_default` appends the preset prompt to the supplied `prompt`."
}
}
},
"assets": {
"type": "object",
"example": {
"video_source": "file",
"video_file_path": "api-assets/id/1234.mp4"
},
"required": [
"video_source"
],
"properties": {
"youtube_url": {
"type": "string",
"format": "uri",
"description": "YouTube URL (required if `video_source` is `youtube`)."
},
"video_source": {
"enum": [
"file",
"youtube"
],
"type": "string",
"example": "file",
"description": "Choose your video source."
},
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"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"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
},
"fps_resolution": {
"enum": [
"FULL",
"HALF"
],
"type": "string",
"default": "HALF",
"example": "HALF",
"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"
}
}
}restyle_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 450,
"description": "The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. \n\nIf video generation fails, credits will be refunded, and this field will be updated to include the refund."
}
},
"description": "Success"
}restyle_video annotations
{
"title": "Restyle video",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}get_image_project — Get image project
Advertised read-only
Returns an image project's status and, once complete, its download URLs. Use to check progress with the id from an image create tool. Read-only.
get_image_project input schema
{
"type": "object",
"required": [
"id"
],
"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."
}
}
}get_image_project output schema
{
"type": "object",
"required": [
"id",
"name",
"status",
"image_count",
"type",
"created_at",
"enabled",
"credits_charged",
"downloads",
"error"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"name": {
"type": [
"string",
"null"
],
"example": "Example Name",
"description": "The name of the image."
},
"type": {
"type": "string",
"example": "AI_IMAGE",
"description": "The type of the image project. Possible values are FACE_EDITOR, AI_IMAGE_EDITOR, GENERATIVE_FILL, AI_SELFIE, AI_HEADSHOT, AI_INFLUENCER, AI_IMAGE, AI_MEME, CLOTHES_CHANGER, BACKGROUND_REMOVER, FACE_SWAP, IMAGE_UPSCALER, IMAGE_ENHANCER, AI_GIF, QR_CODE, PHOTO_EDITOR, PHOTO_COLORIZER, IMAGE_COLOR_GRADER, HEAD_SWAP, BODY_SWAP, STORYBOARD, IMAGE_EXPANDER"
},
"error": {
"type": [
"object",
"null"
],
"required": [
"message",
"code"
],
"properties": {
"code": {
"type": "string",
"example": "no_source_face",
"description": "An error code to indicate why a failure happened."
},
"message": {
"type": "string",
"example": "Please use an image with a detectable face",
"description": "Details on the reason why a failure happened."
}
},
"description": "In the case of an error, this object will contain the error encountered during video render"
},
"status": {
"enum": [
"draft",
"queued",
"rendering",
"complete",
"error",
"canceled"
],
"type": "string",
"example": "complete",
"description": "The status of the image.\n\n- `draft` - the project was created but has not been submitted for rendering\n- `queued` - the job is waiting for an available server\n- `rendering` - the job is being processed; the `image.started` webhook event fires when rendering begins\n- `complete` - the job finished successfully; fires `image.completed`\n- `error` - the job failed during processing; fires `image.errored`\n- `canceled` - the job was manually canceled (for example from the Magic Hour web app)\n\n**Note:** `rendering`, `complete`, and `error` have matching webhook events; `canceled` does not - a canceled job emits no webhook event, so poll this endpoint to detect cancellation."
},
"enabled": {
"type": "boolean",
"description": "Whether this resource is active. If false, it is deleted."
},
"downloads": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"expires_at"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"example": "https://videos.magichour.ai/id/output.png"
},
"expires_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-19T05:16:19.027Z"
}
},
"description": "The download url and expiration date of the image project"
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"image_count": {
"type": "integer",
"example": 1,
"description": "Number of images generated"
},
"credits_charged": {
"type": "integer",
"example": 5,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}get_image_project annotations
{
"title": "Get image project",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}delete_image_project — Delete image project
Advertised destructive
Deletes the image project and attempts to delete its completed output. Cannot be undone; confirm with the user first.
delete_image_project input schema
{
"type": "object",
"required": [
"id"
],
"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."
}
}
}delete_image_project annotations
{
"title": "Delete image project",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}change_clothes_in_photo — Change clothes in photo
Open-world
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Changes clothing in a person photo using a supplied garment reference image. Costs 25 credits. Starts a background job; returns a project id for wait_for_image_project.
change_clothes_in_photo input schema
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Clothes Changer - dateTime",
"example": "My Clothes Changer image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"person_file_path",
"garment_file_path"
],
"properties": {
"garment_type": {
"enum": [
"entire_outfit",
"upper_body",
"lower_body",
"dresses"
],
"type": "string",
"example": "entire_outfit",
"description": "Type of clothing item 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"
},
"person_file_path": {
"type": "string",
"example": "api-assets/id/model.png",
"minLength": 1,
"description": "The image with the person. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
},
"garment_file_path": {
"type": "string",
"example": "api-assets/id/outfit.png",
"minLength": 1,
"description": "The image of the outfit. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for clothes changer"
}
}
}change_clothes_in_photo output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 25,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}change_clothes_in_photo annotations
{
"title": "Change clothes in photo",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}edit_face_in_photo — Edit face in photo
Open-world
Adjusts facial expression, pose and gaze in a supplied photo using numeric controls. Costs 1 credit per edit; output size depends on the subscription tier. Starts a background job; returns a project id for wait_for_image_project.
edit_face_in_photo input schema
{
"type": "object",
"required": [
"assets",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Face Editor - dateTime",
"example": "My Face Editor image",
"description": "Give your image a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"head_yaw": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Head yaw (-100 to 100), in increments of 5"
},
"head_roll": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Head roll (-100 to 100), in increments of 5"
},
"head_pitch": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Head pitch (-100 to 100), in increments of 5"
},
"mouth_grim": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Mouth grim (-100 to 100), in increments of 5"
},
"mouth_pout": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Mouth pout (-100 to 100), in increments of 5"
},
"mouth_purse": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Mouth purse (-100 to 100), in increments of 5"
},
"mouth_smile": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Mouth smile (-100 to 100), in increments of 5"
},
"enhance_face": {
"type": "boolean",
"default": false,
"example": false,
"description": "Enhance face features"
},
"eye_open_ratio": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Eye open ratio (-100 to 100), in increments of 5"
},
"lip_open_ratio": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Lip open ratio (-100 to 100), in increments of 5"
},
"eye_gaze_vertical": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Vertical eye gaze (-100 to 100), in increments of 5"
},
"eyebrow_direction": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Eyebrow direction (-100 to 100), in increments of 5"
},
"eye_gaze_horizontal": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Horizontal eye gaze (-100 to 100), in increments of 5"
},
"mouth_position_vertical": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Vertical mouth position (-100 to 100), in increments of 5"
},
"mouth_position_horizontal": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Horizontal mouth position (-100 to 100), in increments of 5"
}
},
"description": "Face editing parameters"
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "This is the image whose face will be edited. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for face editor"
}
}
}edit_face_in_photo output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 1,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}edit_face_in_photo annotations
{
"title": "Edit face in photo",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}create_gif_or_short_video — Create GIF or short video
Generates a short animation from a text prompt, with GIF, MP4 or WebM output. Costs 50 credits. Starts a background job; returns a project id for wait_for_image_project.
create_gif_or_short_video input schema
{
"type": "object",
"required": [
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Ai Gif - dateTime",
"example": "My Ai Gif gif",
"description": "Give your gif a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"prompt": {
"type": "string",
"example": "Cute dancing cat, pixel art",
"maxLength": 500,
"minLength": 1,
"description": "The prompt used for the GIF."
}
}
},
"output_format": {
"enum": [
"gif",
"mp4",
"webm"
],
"type": "string",
"default": "gif",
"example": "gif",
"description": "The output file format for the generated animation."
}
}
}create_gif_or_short_video output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 50,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}create_gif_or_short_video annotations
{
"title": "Create GIF or short video",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}edit_image — Edit image
Open-world
Edits one or more supplied images using a text prompt. For prompt-only creation use generate_image. Costs credits; returns a project id for wait_for_image_project. Model eligibility depends on the account plan; the default model is not available on every plan.
edit_image input schema
{
"type": "object",
"required": [
"style",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Ai Image Editor - dateTime",
"example": "My Ai Image Editor image",
"description": "Give your image a custom name for easy identification."
},
"model": {
"enum": [
"default",
"qwen-image-2.1",
"gpt-image-2",
"nano-banana-2",
"flux-2-klein",
"nano-banana-pro",
"seedream-v5-pro",
"seedream-v4.5",
"nano-banana-2.1",
"qwen-edit",
"nano-banana-2-lite",
"krea-2",
"gpt-image-2.5-flare",
"seedream-v4",
"nano-banana"
],
"type": "string",
"example": "flux-2-klein",
"description": "The AI model to use for image editing. Each model has different capabilities and costs.\n\n**Models:**\n- `default` - Uses the server-selected default model, which may change over time.\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- `gpt-image-2.5-flare` - 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- `krea-2` - from 10 credits/image\n - Supported resolutions: 640px, 1k\n - Available for tiers: free, creator, pro, business\n - Max additional input images: 1\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-2.1` - 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-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- `qwen-image-2.1` - 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"
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"prompt": {
"type": "string",
"example": "Give me sunglasses",
"maxLength": 15000,
"minLength": 1,
"description": "The prompt used to edit the image."
}
}
},
"assets": {
"type": "object",
"properties": {
"image_file_paths": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"example": [
"api-assets/id/1234.png",
"api-assets/id/1235.png"
],
"maxItems": 10,
"description": "The image(s) used in the edit, maximum of 10 images. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for image edit"
},
"resolution": {
"enum": [
"auto",
"640px",
"1k",
"2k",
"4k"
],
"type": "string",
"example": "640px",
"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- `gpt-image-2.5-flare` - 640px, 1k, 2k, 4k\n- `krea-2` - 640px, 1k\n- `nano-banana` - 640px, 1k\n- `nano-banana-2` - 640px, 1k, 2k, 4k\n- `nano-banana-2-lite` - 640px, 1k\n- `nano-banana-2.1` - 640px, 1k, 2k, 4k\n- `nano-banana-pro` - 1k, 2k, 4k\n- `qwen-edit` - 640px, 1k, 2k\n- `qwen-image-2.1` - 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."
},
"image_count": {
"enum": [
1,
4,
9,
16
],
"type": "number",
"default": 1,
"example": 1,
"description": "Number of images to generate. Maximum varies by model. Defaults to 1 if not specified."
},
"aspect_ratio": {
"enum": [
"auto",
"16:9",
"9:16",
"4:3",
"3:2",
"1:1",
"4:5",
"2:3"
],
"type": "string",
"example": "1:1",
"description": "The aspect ratio of the output image(s). If not specified, defaults to `auto`."
}
}
}edit_image output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 5,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}edit_image annotations
{
"title": "Edit image",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}generate_headshot — Generate headshot
Open-world
Creates a headshot from a supplied photo containing one detectable face, with optional appearance instructions. Costs 50 credits. Starts a background job; returns a project id for wait_for_image_project.
generate_headshot input schema
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Ai Headshot - dateTime",
"example": "My Ai Headshot image",
"description": "Give your image a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"example": "Professional studio headshot with soft lighting and a neutral background",
"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": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"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 file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for headshot photo"
}
}
}generate_headshot output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 50,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}generate_headshot annotations
{
"title": "Generate headshot",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}generate_image — Generate image
Generates one or more images from a text prompt, with model, output size and image count options. Costs credits; returns a project id for wait_for_image_project.
generate_image input schema
{
"type": "object",
"required": [
"image_count",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Ai Image - dateTime",
"example": "My Ai Image image",
"description": "Give your image a custom name for easy identification."
},
"model": {
"enum": [
"default",
"z-image-turbo",
"gpt-image-2",
"qwen-image-2.1",
"flux-2-klein",
"nano-banana-2",
"nano-banana-2.1",
"nano-banana-pro",
"krea-2",
"seedream-v5-pro",
"nano-banana-2-lite",
"gpt-image-2.5-flare",
"seedream-v4",
"nano-banana",
"flux-schnell",
"seedream"
],
"type": "string",
"example": "z-image-turbo",
"description": "The AI model to use for image generation. Each model has different capabilities and costs.\n\n**Models:**\n- `default` - Uses the server-selected default model, which may change over time.\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- `gpt-image-2.5-flare` - from 100 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- `krea-2` - from 10 credits/image\n - Supported resolutions: 640px, 1k\n - Available for tiers: free, creator, pro, business\n - Image count allowed: 1\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-2.1` - from 50 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-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- `qwen-image-2.1` - from 10 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- `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"
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"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",
"default": "general",
"example": "ai-anime-generator",
"description": "The art style to use for image generation. Defaults to 'general' if not provided."
},
"prompt": {
"type": "string",
"example": "Cool image",
"minLength": 1,
"description": "The prompt used for the image(s)."
}
},
"description": "The art style to use for image generation."
},
"resolution": {
"enum": [
"auto",
"640px",
"1k",
"2k",
"4k"
],
"type": "string",
"default": "auto",
"example": "640px",
"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- `gpt-image-2.5-flare` - 640px, 1k, 2k, 4k\n- `krea-2` - 640px, 1k\n- `nano-banana` - 640px, 1k\n- `nano-banana-2` - 640px, 1k, 2k, 4k\n- `nano-banana-2-lite` - 640px, 1k\n- `nano-banana-2.1` - 640px, 1k, 2k, 4k\n- `nano-banana-pro` - 1k, 2k, 4k\n- `qwen-image-2.1` - 640px, 1k, 2k\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."
},
"image_count": {
"type": "integer",
"example": 1,
"maximum": 16,
"minimum": 1,
"description": "Number of images to generate. Maximum varies by model."
},
"aspect_ratio": {
"enum": [
"1:1",
"16:9",
"9:16"
],
"type": "string",
"example": "1:1",
"description": "The aspect ratio of the output image(s). If not specified, defaults to `1:1` (square)."
}
}
}generate_image output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 5,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}generate_image annotations
{
"title": "Generate image",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}upscale_image — Upscale image
Open-world
Upscales a supplied image 2x or 4x. Cost depends on scale and mode (25-200 credits); returns a project id for wait_for_image_project.
upscale_image input schema
{
"type": "object",
"required": [
"scale_factor",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Image Upscaler - dateTime",
"example": "My Image Upscaler image",
"description": "Give your image a custom name for easy identification."
},
"style": {
"type": "object",
"default": {},
"example": {
"mode": "preserve"
},
"properties": {
"mode": {
"enum": [
"pro",
"preserve",
"balanced",
"creative"
],
"type": "string",
"example": "preserve",
"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\"`."
},
"prompt": {
"type": "string",
"example": "Enhance fine details and keep the image natural",
"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\"`."
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The image to upscale. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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."
}
},
"description": "Provide the assets for upscaling"
},
"scale_factor": {
"type": "number",
"example": 2,
"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."
}
}
}upscale_image output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 25,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}upscale_image annotations
{
"title": "Upscale image",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}create_meme — Create meme
Open-world
Creates a meme from a topic and template selection. Costs 10 credits. Starts a background job; returns a project id for wait_for_image_project.
create_meme input schema
{
"type": "object",
"required": [
"style"
],
"properties": {
"name": {
"type": "string",
"example": "My Funny Meme",
"description": "The name of the meme."
},
"style": {
"type": "object",
"required": [
"topic",
"template"
],
"properties": {
"topic": {
"type": "string",
"example": "When the code finally works",
"maxLength": 200,
"minLength": 1,
"description": "The topic of the meme."
},
"template": {
"enum": [
"Random"
],
"type": "string",
"description": "Select a random meme template."
},
"searchWeb": {
"type": "boolean",
"default": false,
"example": false,
"description": "Whether to search the web for meme content."
}
}
}
}
}create_meme output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 10,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}create_meme annotations
{
"title": "Create meme",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}create_qr_code — Create QR code
Creates a stylized QR code from supplied text or a URL and an art-style description. Currently costs 0 credits. Starts a background job; returns a project id for wait_for_image_project.
create_qr_code input schema
{
"type": "object",
"required": [
"content",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Qr Code - dateTime",
"example": "My Qr Code image",
"description": "Give your image a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"art_style"
],
"properties": {
"art_style": {
"type": "string",
"example": "Watercolor",
"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."
}
}
},
"content": {
"type": "string",
"example": "https://magichour.ai",
"description": "The content of the QR code."
}
}
}create_qr_code output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 0,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}create_qr_code annotations
{
"title": "Create QR code",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}place_person_in_scene — Place person in scene
Open-world
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Places a person from one supplied photo into a supplied scene image. Cost depends on resolution (from 50 credits at 640px); returns a project id for wait_for_image_project.
place_person_in_scene input schema
{
"type": "object",
"required": [
"resolution",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Body Swap - dateTime",
"example": "My Body Swap image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"person_file_path",
"scene_file_path"
],
"properties": {
"scene_file_path": {
"type": "string",
"example": "api-assets/id/5678.png",
"minLength": 1,
"description": "Original scene image (background). This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
},
"person_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "Image of the person to place into the scene. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Person image and scene image for body swap"
},
"resolution": {
"enum": [
"640px",
"1k",
"2k",
"4k"
],
"type": "string",
"example": "640px",
"description": "Output resolution. Determines credits charged for the run."
}
}
}place_person_in_scene output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 50,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}place_person_in_scene annotations
{
"title": "Place person in scene",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}swap_face_in_photo — Swap face in photo
Open-world
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Swaps faces in a supplied photo using a source face image or selected face mappings. Costs 10 credits; output size depends on subscription. Returns a project id for wait_for_image_project.
swap_face_in_photo input schema
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Face Swap - dateTime",
"example": "My Face Swap image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"example": {
"face_swap_mode": "all-faces",
"source_file_path": "api-assets/id/1234.png",
"target_file_path": "api-assets/id/1234.png"
},
"required": [
"target_file_path"
],
"properties": {
"face_mappings": {
"type": "array",
"items": {
"type": "object",
"required": [
"original_face",
"new_face"
],
"properties": {
"new_face": {
"type": "string",
"example": "api-assets/id/1234.png",
"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 file. The URL path must end in a supported file extension.\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"
},
"original_face": {
"type": "string",
"example": "api-assets/id/0-0.png",
"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": [
{
"new_face": "api-assets/id/1234.png",
"original_face": "api-assets/id/0-0.png"
}
],
"maxItems": 5,
"description": "This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`."
},
"face_swap_mode": {
"enum": [
"all-faces",
"individual-faces"
],
"type": "string",
"default": "all-faces",
"example": "all-faces",
"description": "Choose which faces to swap. `all-faces` uses one source image for all detected faces (`source_file_path` required). `individual-faces` uses exact `face_mappings`."
},
"source_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"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 file. The URL path must end in a supported file extension.\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"
},
"target_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"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 file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for face swap photo"
}
}
}swap_face_in_photo output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 10,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}swap_face_in_photo annotations
{
"title": "Swap face in photo",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}swap_head_in_photo — Swap head in photo
Open-world
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Swaps a head from a supplied image onto a supplied body image. Costs 10 credits; returns a project id for wait_for_image_project.
swap_head_in_photo input schema
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Head Swap - dateTime",
"example": "My Head Swap image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"body_file_path",
"head_file_path"
],
"properties": {
"body_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "Image that receives the swapped head. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
},
"head_file_path": {
"type": "string",
"example": "api-assets/id/5678.png",
"minLength": 1,
"description": "Image of the head to place on the body. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the body and head images for head swap"
},
"max_resolution": {
"type": "integer",
"example": 1024,
"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."
}
}
}swap_head_in_photo output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 10,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}swap_head_in_photo annotations
{
"title": "Swap head in photo",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}remove_image_background — Remove image background
Open-world
Removes an image's background, optionally replacing it with another supplied image. Costs 5 credits. Starts a background job; returns a project id for wait_for_image_project.
remove_image_background input schema
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Background Remover - dateTime",
"example": "My Background Remover image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"description": "The image to remove the background. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
},
"background_image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"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 file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for background removal"
}
}
}remove_image_background output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 5,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}remove_image_background annotations
{
"title": "Remove image background",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}colorize_photo — Colorize photo
Open-world
Colorizes a black-and-white or faded photo. Costs 10 credits; returns a project id for wait_for_image_project.
colorize_photo input schema
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Photo Colorizer - dateTime",
"example": "My Photo Colorizer image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The image used to generate the colorized image. This value is either\n- a direct URL to the file. The URL path must end in a supported file extension.\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"
}
},
"description": "Provide the assets for photo colorization"
}
}
}colorize_photo output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 10,
"description": "The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. \n\nIf an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}colorize_photo annotations
{
"title": "Colorize photo",
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}get_audio_project — Get audio project
Advertised read-only
Returns an audio project's status and, once complete, its download URLs. Use to check progress with the id from an audio create tool. Read-only.
get_audio_project input schema
{
"type": "object",
"required": [
"id"
],
"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."
}
}
}get_audio_project output schema
{
"type": "object",
"required": [
"id",
"name",
"status",
"type",
"created_at",
"enabled",
"credits_charged",
"downloads",
"error"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the audio. Use it with the [Get audio Project API](https://docs.magichour.ai/api-reference/audio-projects/get-audio-details) to fetch status and downloads."
},
"name": {
"type": [
"string",
"null"
],
"example": "Example Name",
"description": "The name of the audio."
},
"type": {
"type": "string",
"example": "VOICE_GENERATOR",
"description": "The type of the audio project. Possible values are AUDIO_TRANSLATOR, VOICE_GENERATOR, VOICE_CHANGER, VOICE_CLONER, VIDEO_TO_AUDIO, MUSIC_GENERATOR, SOUND_EFFECT_GENERATOR"
},
"error": {
"type": [
"object",
"null"
],
"required": [
"message",
"code"
],
"properties": {
"code": {
"type": "string",
"example": "no_source_face",
"description": "An error code to indicate why a failure happened."
},
"message": {
"type": "string",
"example": "Please use an image with a detectable face",
"description": "Details on the reason why a failure happened."
}
},
"description": "In the case of an error, this object will contain the error encountered during video render"
},
"status": {
"enum": [
"draft",
"queued",
"rendering",
"complete",
"error",
"canceled"
],
"type": "string",
"example": "complete",
"description": "The status of the audio.\n\n- `draft` - the project was created but has not been submitted for rendering\n- `queued` - the job is waiting for an available server\n- `rendering` - the job is being processed; the `audio.started` webhook event fires when rendering begins\n- `complete` - the job finished successfully; fires `audio.completed`\n- `error` - the job failed during processing; fires `audio.errored`\n- `canceled` - the job was manually canceled (for example from the Magic Hour web app)\n\n**Note:** `rendering`, `complete`, and `error` have matching webhook events; `canceled` does not - a canceled job emits no webhook event, so poll this endpoint to detect cancellation."
},
"enabled": {
"type": "boolean",
"description": "Whether this resource is active. If false, it is deleted."
},
"downloads": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"expires_at"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"example": "https://videos.magichour.ai/id/output.wav"
},
"expires_at": {
"type": "string",
"format": "date-time",
"example": "2024-10-19T05:16:19.027Z"
}
},
"description": "The download url and expiration date of the audio project"
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"credits_charged": {
"type": "integer",
"example": 2,
"description": "The amount of credits deducted from your account to generate the audio. We charge credits right when the request is made. \n\nIf an error occurred while generating the audio, credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}get_audio_project annotations
{
"title": "Get audio project",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}delete_audio_project — Delete audio project
Advertised destructive
Deletes the audio project and attempts to delete its completed output. Cannot be undone; confirm with the user first.
delete_audio_project input schema
{
"type": "object",
"required": [
"id"
],
"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."
}
}
}delete_audio_project annotations
{
"title": "Delete audio project",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}generate_music — Generate music
Generates music from a description, with optional custom lyrics or instrumental-only output. Costs 1 credit per requested second; returns a project id for wait_for_audio_project.
generate_music input schema
{
"type": "object",
"required": [
"duration",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "AI Music Generator",
"example": "My Music Generator audio",
"description": "Give your audio a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"lyrics": {
"type": "string",
"example": "City lights are fading...",
"description": "Custom lyrics. Omit or leave blank for AI-generated lyrics when instrumental is false."
},
"prompt": {
"type": "string",
"example": "Dreamy synthwave with warm bass and soft vocals",
"minLength": 1,
"description": "Describe the song, including genre, mood, and instruments."
},
"instrumental": {
"type": "boolean",
"default": false,
"example": false,
"description": "Generate music without vocals. When true, lyrics is ignored."
}
},
"additionalProperties": false
},
"duration": {
"type": "integer",
"example": 120,
"maximum": 300,
"minimum": 15,
"description": "Requested track duration in seconds, from 15 to 300. Determines credits charged."
}
}
}generate_music output schema
{
"type": "object",
"required": [
"id",
"credits_charged"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the audio. Use it with the [Get audio Project API](https://docs.magichour.ai/api-reference/audio-projects/get-audio-details) to fetch status and downloads."
},
"credits_charged": {
"type": "integer",
"example": 120,
"description": "The amount of credits deducted from your account to generate the audio. We charge credits right when the request is made. \n\nIf an error occurred while generating the audio, credits will be refunded and this field will be updated to include the refund."
}
},
"description": "Success"
}generate_music annotations
{
"title": "Generate music",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}Prompts
0 advertised
Resources
2 advertised
Magic Hour workflow index
Discover task-specific workflow guides and their resource URIs.
Magic Hour workflow index URI
magic-hour://workflows/indexMagic Hour project result
Render completed or terminal Magic Hour project results in MCP Apps hosts.
Magic Hour project result URI
ui://magic-hour/project-result-v1.htmlMagic Hour workflow guide
Read workflow inputs, tool steps, example requests, follow-up edits and review criteria.
Magic Hour workflow guide URI template
magic-hour://workflows/{workflow}30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 1274 ms
- 95th percentile latency
- 1274 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 1274 ms · metadata changed · 48 tool(s), 2 resource(s), 1 resource template(s), 0 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http magic-hour-mcp https://mcp.magichour.ai/Codex
Codex configuration
codex mcp add magic-hour-mcp --url https://mcp.magichour.ai/Cursor
Cursor configuration
{
"mcpServers": {
"magic-hour-mcp": {
"url": "https://mcp.magichour.ai/"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"magic-hour-mcp": {
"type": "streamableHttp",
"url": "https://mcp.magichour.ai/",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"magic-hour-mcp": {
"type": "http",
"url": "https://mcp.magichour.ai/"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http magic-hour-mcp https://mcp.magichour.ai/Claude Desktop
Claude Desktop configuration
{
"mcpServers": {
"magic-hour-mcp": {
"url": "https://mcp.magichour.ai/"
}
}
}Windsurf
Windsurf configuration
{
"mcpServers": {
"magic-hour-mcp": {
"serverUrl": "https://mcp.magichour.ai/"
}
}
}Let your agent find its tools
Find servers like Magic Hour MCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.