Server definition
- Hash
- sha256:db0e18ba5e2df8c2d76d2bfe969a6b53b6900bf8879af82fece0341b8564cd9e
- What it is
- What a remote MCP server returned when asked what it offers: 44 tools
The blob, as servednamed by its sha256
{
"instructions": "Create and edit images, video, and audio with Magic Hour.\nTool calls require authentication.\nCreation tools are asynchronous; use the matching wait_for_*_project tool after starting a project.\nUpload local media before passing its file_path, and preserve signed download URLs exactly as returned.\nOmit optional resolution and model unless the user explicitly requests them, allowing the API to choose plan-compatible defaults.\nAfter a subscription-tier restriction, retry at most once after omitting only unrequested optional fields; explain the restriction instead of changing an explicit requirement or guessing alternatives.\n\nFor video creation, unless the user requests otherwise:\n\n- Prefer AI Image Editor followed by Image-to-Video.\n- Reuse reference images across scenes for visual consistency.\n- When the user asks for an image model recommendation, prefer nano-banana-2-lite only if account support is known; otherwise recommend default.\n- When the user asks for an Image-to-Video model recommendation, prefer ltx-2.5.\n- Let the narration finish each sentence. Never cut it off.\n- Use Text-to-Video only when consistency is unimportant.\n- Keep character identity, visual style, color palette, lighting, and aspect ratio consistent across scenes.",
"tools": [
{
"description": "Get the current credit balance and subscription details of the account that owns the API key.",
"inputSchema": {
"properties": {},
"required": [],
"type": "object"
},
"name": "account_retrieve",
"outputSchema": {
"properties": {
"credits": {
"description": "Credits currently available to spend. Includes subscription credits and any purchased credit packs.",
"example": 12500,
"minimum": 0,
"type": "integer"
},
"email": {
"description": "Email address of the account.",
"example": "[email protected]",
"type": [
"string",
"null"
]
},
"id": {
"description": "Unique ID of the account that owns the API key.",
"example": "cuid-example",
"type": "string"
},
"subscription": {
"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.",
"properties": {
"billing_interval": {
"description": "How often the subscription is billed. `null` if unknown.",
"enum": [
"month",
"year",
null
],
"example": "month",
"type": [
"string",
"null"
]
},
"cancel_at_period_end": {
"description": "Whether the subscription is scheduled to end at `current_period_end` instead of renewing. The subscription stays usable until then.",
"example": false,
"type": "boolean"
},
"current_period_end": {
"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`.",
"example": "2026-10-01T00:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"discount": {
"description": "Discount applied to the subscription. `null` if no discount is applied.",
"properties": {
"amount_off": {
"description": "Fixed amount taken off `price.amount` each billing interval, in the smallest unit of the currency. `null` if the discount is a percentage.",
"type": [
"integer",
"null"
]
},
"percent_off": {
"description": "Percentage taken off `price.amount` each billing interval. `null` if the discount is a fixed amount.",
"example": 20,
"type": [
"number",
"null"
]
}
},
"required": [
"percent_off",
"amount_off"
],
"type": [
"object",
"null"
]
},
"name": {
"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.",
"example": "Pro",
"type": [
"string",
"null"
]
},
"price": {
"properties": {
"amount": {
"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.",
"example": 4900,
"minimum": 0,
"type": "integer"
},
"currency": {
"description": "Three-letter ISO 4217 currency code, lowercase.",
"example": "usd",
"type": "string"
}
},
"required": [
"amount",
"currency"
],
"type": "object"
},
"status": {
"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.",
"enum": [
"active",
"past_due"
],
"example": "active",
"type": "string"
}
},
"required": [
"name",
"status",
"price",
"discount",
"billing_interval",
"current_period_end",
"cancel_at_period_end"
],
"type": [
"object",
"null"
]
},
"tier": {
"description": "Subscription tier in effect for the account. `free` if there is no active subscription, including while a subscription is `past_due`.",
"enum": [
"free",
"creator",
"pro",
"business"
],
"example": "pro",
"type": "string"
}
},
"required": [
"id",
"email",
"tier",
"credits",
"subscription"
],
"type": "object"
}
},
{
"description": "Change outfits in photos in seconds with just a photo reference. Each photo costs 25 credits.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for clothes changer",
"properties": {
"garment_file_path": {
"description": "The image of the outfit. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/outfit.png",
"minLength": 1,
"type": "string"
},
"garment_type": {
"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",
"enum": [
"entire_outfit",
"upper_body",
"lower_body",
"dresses"
],
"example": "entire_outfit",
"type": "string"
},
"person_file_path": {
"description": "The image with the person. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/model.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"person_file_path",
"garment_file_path"
],
"type": "object"
},
"name": {
"default": "Clothes Changer - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Clothes Changer image",
"type": "string"
}
},
"required": [
"assets"
],
"type": "object"
},
"name": "ai_clothes_changer_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 25,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Edit facial features of an image using AI. Each edit costs 1 frame. The height/width of the output image depends on your subscription. Please refer to our [pricing](https://magichour.ai/pricing) page for more details\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for face editor",
"properties": {
"image_file_path": {
"description": "This is the image whose face will be edited. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"image_file_path"
],
"type": "object"
},
"name": {
"default": "Face Editor - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Face Editor image",
"type": "string"
},
"style": {
"description": "Face editing parameters",
"properties": {
"enhance_face": {
"default": false,
"description": "Enhance face features",
"example": false,
"type": "boolean"
},
"eye_gaze_horizontal": {
"default": 0,
"description": "Horizontal eye gaze (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"eye_gaze_vertical": {
"default": 0,
"description": "Vertical eye gaze (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"eye_open_ratio": {
"default": 0,
"description": "Eye open ratio (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"eyebrow_direction": {
"default": 0,
"description": "Eyebrow direction (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"head_pitch": {
"default": 0,
"description": "Head pitch (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"head_roll": {
"default": 0,
"description": "Head roll (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"head_yaw": {
"default": 0,
"description": "Head yaw (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"lip_open_ratio": {
"default": 0,
"description": "Lip open ratio (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"mouth_grim": {
"default": 0,
"description": "Mouth grim (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"mouth_position_horizontal": {
"default": 0,
"description": "Horizontal mouth position (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"mouth_position_vertical": {
"default": 0,
"description": "Vertical mouth position (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"mouth_pout": {
"default": 0,
"description": "Mouth pout (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"mouth_purse": {
"default": 0,
"description": "Mouth purse (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
},
"mouth_smile": {
"default": 0,
"description": "Mouth smile (-100 to 100), in increments of 5",
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"type": "number"
}
},
"type": "object"
}
},
"required": [
"assets",
"style"
],
"type": "object"
},
"name": "ai_face_editor_edit_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 1,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Create an AI GIF. Each GIF costs 50 credits.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.",
"inputSchema": {
"properties": {
"name": {
"default": "Ai Gif - dateTime",
"description": "Give your gif a custom name for easy identification.",
"example": "My Ai Gif gif",
"type": "string"
},
"output_format": {
"default": "gif",
"description": "The output file format for the generated animation.",
"enum": [
"gif",
"mp4",
"webm"
],
"example": "gif",
"type": "string"
},
"style": {
"properties": {
"prompt": {
"description": "The prompt used for the GIF.",
"example": "Cute dancing cat, pixel art",
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"prompt"
],
"type": "object"
}
},
"required": [
"style"
],
"type": "object"
},
"name": "ai_gif_generator_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 50,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Create an AI headshot. Each headshot costs 50 credits.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for headshot photo",
"properties": {
"image_file_path": {
"description": "The image used to generate the headshot. This image must contain one detectable face. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"image_file_path"
],
"type": "object"
},
"name": {
"default": "Ai Headshot - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Ai Headshot image",
"type": "string"
},
"style": {
"properties": {
"prompt": {
"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.",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"assets"
],
"type": "object"
},
"name": "ai_headshot_generator_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 50,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Edit images with AI.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"aspect_ratio": {
"description": "The aspect ratio of the output image(s). If not specified, defaults to `auto`.",
"enum": [
"auto",
"16:9",
"9:16",
"4:3",
"3:2",
"1:1",
"4:5",
"2:3"
],
"example": "1:1",
"type": "string"
},
"assets": {
"description": "Provide the assets for image edit",
"properties": {
"image_file_paths": {
"description": "The image(s) used in the edit, maximum of 10 images. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": [
"api-assets/id/1234.png",
"api-assets/id/1235.png"
],
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 10,
"type": "array"
}
},
"type": "object"
},
"image_count": {
"default": 1,
"description": "Number of images to generate. Maximum varies by model. Defaults to 1 if not specified.",
"enum": [
1,
4,
9,
16
],
"example": 1,
"type": "number"
},
"model": {
"description": "The AI model to use for image editing. Each model has different capabilities and costs.\n\n**Models:**\n- `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior.\n- `flux-2-klein` - from 5 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: free, creator, pro, business\n - Max additional input images: 5\n- `gpt-image-2` - from 50 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n- `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-pro` - from 150 credits/image\n - Supported resolutions: 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n- `qwen-edit` - from 10 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: free, creator, pro, business\n - Max additional input images: 2\n- `seedream-v4` - from 40 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n- `seedream-v4.5` - from 50 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n- `seedream-v5-pro` - from 75 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n",
"enum": [
"default",
"qwen-edit",
"flux-2-klein",
"nano-banana-2-lite",
"nano-banana-2",
"krea-2",
"gpt-image-2.5-flare",
"gpt-image-2",
"seedream-v5-pro",
"seedream-v4.5",
"seedream-v4",
"nano-banana",
"nano-banana-pro"
],
"example": "default",
"type": "string"
},
"name": {
"default": "Ai Image Editor - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Ai Image Editor image",
"type": "string"
},
"resolution": {
"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-pro` - 1k, 2k, 4k\n- `qwen-edit` - 640px, 1k, 2k\n- `seedream-v4` - 640px, 1k, 2k, 4k\n- `seedream-v4.5` - 640px, 1k, 2k, 4k\n- `seedream-v5-pro` - 640px, 1k, 2k\n\nNote: Resolution availability depends on the model and your subscription tier.",
"enum": [
"auto",
"640px",
"1k",
"2k",
"4k"
],
"example": "1k",
"type": "string"
},
"style": {
"properties": {
"prompt": {
"description": "The prompt used to edit the image.",
"example": "Give me sunglasses",
"maxLength": 15000,
"minLength": 1,
"type": "string"
}
},
"required": [
"prompt"
],
"type": "object"
}
},
"required": [
"style",
"assets"
],
"type": "object"
},
"name": "ai_image_editor_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 50,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Create an AI image with advanced model selection and quality controls.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.",
"inputSchema": {
"properties": {
"aspect_ratio": {
"description": "The aspect ratio of the output image(s). If not specified, defaults to `1:1` (square).",
"enum": [
"1:1",
"16:9",
"9:16"
],
"example": "1:1",
"type": "string"
},
"image_count": {
"description": "Number of images to generate. Maximum varies by model.",
"example": 1,
"maximum": 16,
"minimum": 1,
"type": "integer"
},
"model": {
"description": "The AI model to use for image generation. Each model has different capabilities and costs.\n\n**Models:**\n- `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior.\n- `flux-2-klein` - from 5 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: free, creator, pro, business\n - Image count allowed: 1\n- `flux-schnell` - from 5 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: free, creator, pro, business\n - Image count allowed: 1, 2, 3, 4\n- `gpt-image-2` - from 50 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Image count allowed: 1, 2, 3, 4\n- `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-pro` - from 150 credits/image\n - Supported resolutions: 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Image count allowed: 1, 4, 9, 16\n- `seedream-v4` - from 40 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Image count allowed: 1, 2, 3, 4\n- `seedream-v5-pro` - from 75 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: creator, pro, business\n - Image count allowed: 1, 2, 3, 4\n- `z-image-turbo` - from 5 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: free, creator, pro, business\n - Image count allowed: 1, 2, 3, 4\n\n**Deprecated Enum Values:**\n- `seedream` - Use `seedream-v4` instead.\n",
"enum": [
"default",
"z-image-turbo",
"flux-2-klein",
"nano-banana-2-lite",
"nano-banana-2",
"krea-2",
"gpt-image-2.5-flare",
"gpt-image-2",
"seedream-v5-pro",
"seedream-v4",
"nano-banana",
"nano-banana-pro",
"flux-schnell",
"seedream"
],
"example": "default",
"type": "string"
},
"name": {
"default": "Ai Image - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Ai Image image",
"type": "string"
},
"resolution": {
"default": "auto",
"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-pro` - 1k, 2k, 4k\n- `seedream-v4` - 640px, 1k, 2k, 4k\n- `seedream-v5-pro` - 640px, 1k, 2k\n- `z-image-turbo` - 640px, 1k, 2k\n\nNote: Resolution availability depends on the model and your subscription tier.",
"enum": [
"auto",
"640px",
"1k",
"2k",
"4k"
],
"example": "1k",
"type": "string"
},
"style": {
"description": "The art style to use for image generation.",
"properties": {
"prompt": {
"description": "The prompt used for the image(s).",
"example": "Cool image",
"minLength": 1,
"type": "string"
},
"tool": {
"default": "general",
"description": "The art style to use for image generation. Defaults to 'general' if not provided.",
"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"
],
"example": "ai-anime-generator",
"type": "string"
}
},
"required": [
"prompt"
],
"type": "object"
}
},
"required": [
"image_count",
"style"
],
"type": "object"
},
"name": "ai_image_generator_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 5,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Upscale your image using AI. Each 2x upscale costs 50 credits for balanced/creative modes, and 25 credits for preserve. 4x upscale costs 200 and 100 credits respectively.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for upscaling",
"properties": {
"image_file_path": {
"description": "The image to upscale. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n. The maximum input image size is 4096x4096px.",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"image_file_path"
],
"type": "object"
},
"name": {
"default": "Image Upscaler - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Image Upscaler image",
"type": "string"
},
"scale_factor": {
"description": "How much to scale the image. Must be either 2 or 4.\n \nNote: 4x upscale is only available on Creator, Pro, or Business tier.",
"example": 2,
"type": "number"
},
"style": {
"default": {},
"description": "Style settings for the upscale. Use `mode` (`\"preserve\"`, `\"balanced\"`, or `\"creative\"`). Defaults to `\"balanced\"`.",
"properties": {
"mode": {
"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\"`.",
"enum": [
"pro",
"preserve",
"balanced",
"creative"
],
"example": "balanced",
"type": "string"
},
"prompt": {
"description": "A prompt to guide the final image. Only used when mode is `creative`.",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"scale_factor",
"assets"
],
"type": "object"
},
"name": "ai_image_upscaler_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 50,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Create an AI generated meme. Each meme costs 10 credits.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.",
"inputSchema": {
"properties": {
"name": {
"description": "The name of the meme.",
"example": "My Funny Meme",
"type": "string"
},
"style": {
"properties": {
"searchWeb": {
"default": false,
"description": "Whether to search the web for meme content.",
"example": false,
"type": "boolean"
},
"template": {
"description": "Select a random meme template.",
"enum": [
"Random"
],
"type": "string"
},
"topic": {
"description": "The topic of the meme.",
"example": "When the code finally works",
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
"required": [
"topic",
"template"
],
"type": "object"
}
},
"required": [
"style"
],
"type": "object"
},
"name": "ai_meme_generator_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 10,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Create an AI QR code. Each QR code costs 0 credits.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.",
"inputSchema": {
"properties": {
"content": {
"description": "The content of the QR code.",
"example": "https://magichour.ai",
"type": "string"
},
"name": {
"default": "Qr Code - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Qr Code image",
"type": "string"
},
"style": {
"properties": {
"art_style": {
"description": "To use our templates, pass in one of Watercolor, Cyberpunk City, Ink Landscape, Interior Painting, Japanese Street, Mech, Minecraft, Picasso Painting, Game Map, Spaceship, Chinese Painting, Winter Village, or pass any custom art style.",
"example": "Watercolor",
"type": "string"
}
},
"required": [
"art_style"
],
"type": "object"
}
},
"required": [
"content",
"style"
],
"type": "object"
},
"name": "ai_qr_code_generator_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 0,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Create a talking photo from an image and audio or text input.\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for creating a talking photo",
"properties": {
"audio_file_path": {
"description": "The audio file to sync with the image. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"type": "string"
},
"image_file_path": {
"description": "The source image to animate. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"image_file_path",
"audio_file_path"
],
"type": "object"
},
"end_seconds": {
"description": "The end time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 45s.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"max_resolution": {
"description": "Constrains the larger dimension (height or width) of the output video. Allows you to set a lower resolution than your plan's maximum if desired. The value is capped by your plan's max resolution.",
"example": 1024,
"type": "integer"
},
"name": {
"default": "Talking Photo - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Talking Photo image",
"type": "string"
},
"start_seconds": {
"description": "The start time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 45s.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"style": {
"description": "Attributes used to dictate the style of the output",
"properties": {
"generation_mode": {
"default": "realistic",
"description": "Controls overall motion style.\n* `realistic` - Maintains likeness well, high quality, and reliable.\n* `prompted` - Slightly lower likeness; allows option to prompt scene.\n\n**Deprecated values (maintained for backward compatibility):**\n* `pro` - Deprecated: use `realistic`\n* `standard` - Deprecated: use `prompted`\n* `stable` - Deprecated: use `realistic`\n* `expressive` - Deprecated: use `prompted`",
"enum": [
"realistic",
"prompted",
"pro",
"standard",
"stable",
"expressive"
],
"example": "realistic",
"type": "string"
},
"prompt": {
"description": "A text prompt to guide the generation. Only applicable when generation_mode is `prompted`.\nThis field is ignored for other modes.",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"start_seconds",
"end_seconds",
"assets"
],
"type": "object"
},
"name": "ai_talking_photo_create_talking_photo",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "**What this API does**\n\nCreate the same Video Editor you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.\n \n**Good for**\n- Automation and batch processing \n- Adding video editor into apps, pipelines, or tools \n\n**How it works (3 steps)**\n1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. \n2) Send a request to create a video editor job with the basic fields. \n3) Check the job status until it's `complete`, then download the result from `downloads`.\n\n**Key options**\n- Inputs: usually a file, sometimes a YouTube link, depending on project type \n- Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes \n- Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt \n\n**Cost** \nCredits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.\n\nFor detailed examples, see the [product page](https://magichour.ai/products/ai-video-editor).\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for video editing.",
"properties": {
"video_file_path": {
"description": "The video to edit. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"type": "string"
}
},
"required": [
"video_file_path"
],
"type": "object"
},
"end_seconds": {
"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: 20s.",
"example": 5,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"model": {
"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.",
"enum": [
"gemini-omni-1.1",
"gemini-omni",
"ltx-2.5",
"ltx-2.3"
],
"example": "gemini-omni-1.1",
"type": "string"
},
"name": {
"default": "Video Editor - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Video Editor video",
"type": "string"
},
"resolution": {
"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.",
"enum": [
"480p",
"720p",
"1080p"
],
"example": "720p",
"type": "string"
},
"start_seconds": {
"default": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"style": {
"properties": {
"prompt": {
"description": "The prompt used to edit the video.",
"example": "Change the car color to blue",
"minLength": 1,
"type": "string"
}
},
"required": [
"prompt"
],
"type": "object"
}
},
"required": [
"end_seconds",
"style",
"assets"
],
"type": "object"
},
"name": "ai_video_editor_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "**What this API does**\n\nCreate the same Video Translator you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.\n \n**Good for**\n- Automation and batch processing \n- Adding video translator into apps, pipelines, or tools \n\n**How it works (3 steps)**\n1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. \n2) Send a request to create a video translator job with the basic fields. \n3) Check the job status until it's `complete`, then download the result from `downloads`.\n\n**Key options**\n- Inputs: usually a file, sometimes a YouTube link, depending on project type \n- Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes \n- Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt \n\n**Cost** \nCredits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.\n\nFor detailed examples, see the [product page](https://magichour.ai/products/ai-video-translator).\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Source video for the translation job.",
"properties": {
"video_file_path": {
"description": "Source video containing the speech to translate. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"type": "string"
}
},
"required": [
"video_file_path"
],
"type": "object"
},
"end_seconds": {
"description": "End time of your clip (seconds). Must be greater than start_seconds. The clip must be 1-30 seconds long.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"name": {
"default": "Video Translator - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Video Translator video",
"type": "string"
},
"resolution": {
"description": "Output video resolution. Defaults to 480p. 720p and 1080p require a paid plan.",
"enum": [
"480p",
"720p",
"1080p"
],
"example": "720p",
"type": "string"
},
"start_seconds": {
"default": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"target_language": {
"description": "Language to translate the video's speech into.",
"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"
],
"example": "Spanish",
"type": "string"
}
},
"required": [
"end_seconds",
"target_language",
"assets"
],
"type": "object"
},
"name": "ai_video_translator_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Create a Animation video. The estimated frame cost is calculated based on the `fps` and `end_seconds` input.\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for animation.",
"properties": {
"audio_file_path": {
"description": "The path of the input audio. This field is required if `audio_source` is `file`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"type": "string"
},
"audio_source": {
"description": "Optionally add an audio source if you'd like to incorporate audio into your video",
"enum": [
"none",
"file",
"youtube"
],
"example": "file",
"type": "string"
},
"image_file_path": {
"description": "An initial image to use a the first frame of the video. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
},
"youtube_url": {
"description": "Using a youtube video as the input source. This field is required if `audio_source` is `youtube`",
"format": "uri",
"minLength": 1,
"type": "string"
}
},
"required": [
"audio_source"
],
"type": "object"
},
"end_seconds": {
"description": "This value determines the duration of the output video.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"fps": {
"description": "The desire output video frame rate",
"example": 12,
"minimum": 1,
"type": "number"
},
"height": {
"description": "The height of the final output video. The maximum height depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details",
"example": 960,
"minimum": 64,
"type": "integer"
},
"name": {
"default": "Animation - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Animation video",
"type": "string"
},
"style": {
"description": "Defines the style of the output video",
"properties": {
"art_style": {
"description": "The art style used to create the output video",
"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"
],
"example": "Painterly Illustration",
"type": "string"
},
"art_style_custom": {
"description": "Describe custom art style. This field is required if `art_style` is `Custom`",
"type": "string"
},
"camera_effect": {
"description": "The camera effect used to create the output video",
"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"
],
"example": "Simple Zoom In",
"type": "string"
},
"prompt": {
"description": "The prompt used for the video. Prompt is required if `prompt_type` is `custom`. Otherwise this value is ignored",
"example": "Cyberpunk city",
"type": "string"
},
"prompt_type": {
"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`.",
"enum": [
"custom",
"use_lyrics",
"ai_choose"
],
"example": "custom",
"type": "string"
},
"transition_speed": {
"description": "Change determines how quickly the video's content changes across frames. \n* Higher = more rapid transitions.\n* Lower = more stable visual experience.",
"example": 5,
"maximum": 10,
"minimum": 1,
"type": "integer"
}
},
"required": [
"art_style",
"camera_effect",
"prompt_type",
"transition_speed"
],
"type": "object"
},
"width": {
"description": "The width of the final output video. The maximum width depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details",
"example": 512,
"minimum": 64,
"type": "integer"
}
},
"required": [
"fps",
"end_seconds",
"height",
"width",
"style",
"assets"
],
"type": "object"
},
"name": "animation_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Permanently delete the rendered audio file(s). This action is not reversible, please be sure before deleting.",
"inputSchema": {
"properties": {
"id": {
"description": "Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "audio_projects_delete",
"outputSchema": null
},
{
"description": "Check the progress of a audio project. The `downloads` field is populated after a successful render.\n \n**Statuses**\n- `queued` — waiting to start\n- `rendering` — in progress\n- `complete` — ready; see `downloads`\n- `error` — a failure occurred (see `error`)\n- `canceled` — user canceled\n- `draft` — not used\n\nMCP guidance:\n- Use this after a create tool to poll job status. When status is `complete`, surface the `downloads` URLs to the user; if status is `error`, surface the error message.\n- Each `downloads[n].url` is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append `expires_at` onto the URL string.",
"inputSchema": {
"properties": {
"id": {
"description": "Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "audio_projects_retrieve_details",
"outputSchema": {
"description": "Success",
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"credits_charged": {
"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.",
"example": 2,
"type": "integer"
},
"downloads": {
"items": {
"description": "The download url and expiration date of the audio project",
"properties": {
"expires_at": {
"example": "2024-10-19T05:16:19.027Z",
"format": "date-time",
"type": "string"
},
"url": {
"example": "https://videos.magichour.ai/id/output.wav",
"format": "uri",
"type": "string"
}
},
"required": [
"url",
"expires_at"
],
"type": "object"
},
"type": "array"
},
"enabled": {
"description": "Whether this resource is active. If false, it is deleted.",
"type": "boolean"
},
"error": {
"description": "In the case of an error, this object will contain the error encountered during video render",
"properties": {
"code": {
"description": "An error code to indicate why a failure happened.",
"example": "no_source_face",
"type": "string"
},
"message": {
"description": "Details on the reason why a failure happened.",
"example": "Please use an image with a detectable face",
"type": "string"
}
},
"required": [
"message",
"code"
],
"type": [
"object",
"null"
]
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
},
"name": {
"description": "The name of the audio.",
"example": "Example Name",
"type": [
"string",
"null"
]
},
"status": {
"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.",
"enum": [
"draft",
"queued",
"rendering",
"complete",
"error",
"canceled"
],
"example": "complete",
"type": "string"
},
"type": {
"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",
"example": "VOICE_GENERATOR",
"type": "string"
}
},
"required": [
"id",
"name",
"status",
"type",
"created_at",
"enabled",
"credits_charged",
"downloads",
"error"
],
"type": "object"
}
},
{
"description": "**What this API does**\n\nCreate the same Audio To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.\n \n**Good for**\n- Automation and batch processing \n- Adding audio to video into apps, pipelines, or tools \n\n**How it works (3 steps)**\n1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. \n2) Send a request to create a audio to video job with the basic fields. \n3) Check the job status until it's `complete`, then download the result from `downloads`.\n\n**Key options**\n- Inputs: usually a file, sometimes a YouTube link, depending on project type \n- Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes \n- Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt \n\n**Cost** \nCredits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.\n\nFor detailed examples, see the [product page](https://magichour.ai/products/audio-to-video).\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the audio file and an optional reference image.",
"properties": {
"audio_file_path": {
"description": "The path of the audio file. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"type": "string"
},
"image_file_path": {
"description": "Reference image for the initial frame of the video. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"audio_file_path"
],
"type": "object"
},
"end_seconds": {
"description": "End time of your clip (seconds). Must be greater than start_seconds.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"name": {
"default": "Audio To Video - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Audio To Video video",
"type": "string"
},
"resolution": {
"description": "Output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers.",
"enum": [
"480p",
"720p",
"1080p"
],
"example": "720p",
"type": "string"
},
"start_seconds": {
"default": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"style": {
"description": "Attributes used to dictate the style of the output",
"properties": {
"prompt": {
"description": "Prompt to guide the visual style of the video.",
"example": "Car driving through a city",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"end_seconds",
"assets"
],
"type": "object"
},
"name": "audio_to_video_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Automatically generate subtitles for your video in multiple languages.\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for auto subtitle generator",
"properties": {
"video_file_path": {
"description": "This is the video used to add subtitles. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"type": "string"
}
},
"required": [
"video_file_path"
],
"type": "object"
},
"end_seconds": {
"description": "End time of your clip (seconds). Must be greater than start_seconds.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"name": {
"default": "Auto Subtitle - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Auto Subtitle video",
"type": "string"
},
"start_seconds": {
"description": "Start time of your clip (seconds). Must be ≥ 0.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"style": {
"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",
"properties": {
"custom_config": {
"description": "Custom subtitle configuration.",
"properties": {
"font": {
"description": "Font name from Google Fonts. Not all fonts support all languages or character sets. \nWe recommend verifying language support and appearance directly on https://fonts.google.com before use.",
"example": "Noto Sans",
"type": "string"
},
"font_size": {
"description": "Font size in pixels. If not provided, the font size is automatically calculated based on the video resolution.",
"example": 24,
"type": "number"
},
"font_style": {
"description": "Font style (e.g., normal, italic, bold)",
"example": "normal",
"type": "string"
},
"highlighted_text_color": {
"description": "Color used to highlight the current spoken text",
"example": "#FFD700",
"type": "string"
},
"horizontal_position": {
"description": "Horizontal alignment of the text (e.g., left, center, right)",
"example": "center",
"type": "string"
},
"stroke_color": {
"description": "Stroke (outline) color of the text",
"example": "#000000",
"type": "string"
},
"stroke_width": {
"description": "Width of the text stroke in pixels. If `stroke_color` is provided, but `stroke_width` is not, the `stroke_width` will be calculated automatically based on the font size.",
"example": 1,
"type": "number"
},
"text_color": {
"description": "Primary text color in hex format",
"example": "#FFFFFF",
"type": "string"
},
"vertical_position": {
"description": "Vertical alignment of the text (e.g., top, center, bottom)",
"example": "bottom",
"type": "string"
}
},
"type": "object"
},
"template": {
"description": "Preset subtitle templates. Please visit https://magichour.ai/create/auto-subtitle-generator to see the style of the existing templates.",
"enum": [
"karaoke",
"cinematic",
"minimalist",
"highlight"
],
"type": "string"
}
},
"type": "object"
}
},
"required": [
"start_seconds",
"end_seconds",
"assets",
"style"
],
"type": "object"
},
"name": "auto_subtitle_generator_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Swap a person into a scene image using Nano Banana 2 Lite (640px/1k) or Nano Banana 2 (2k/4k). Credits depend on `resolution` (from 50 credits at 640px upward).\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Person image and scene image for body swap",
"properties": {
"person_file_path": {
"description": "Image of the person to place into the scene. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
},
"scene_file_path": {
"description": "Original scene image (background). This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/5678.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"person_file_path",
"scene_file_path"
],
"type": "object"
},
"name": {
"default": "Body Swap - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Body Swap image",
"type": "string"
},
"resolution": {
"description": "Output resolution. Determines credits charged for the run.",
"enum": [
"640px",
"1k",
"2k",
"4k"
],
"example": "1k",
"type": "string"
}
},
"required": [
"resolution",
"assets"
],
"type": "object"
},
"name": "body_swap_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 50,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "**What this API does**\n\nCreate the same Character Replace you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.\n \n**Good for**\n- Automation and batch processing \n- Adding character replace into apps, pipelines, or tools \n\n**How it works (3 steps)**\n1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. \n2) Send a request to create a character replace job with the basic fields. \n3) Check the job status until it's `complete`, then download the result from `downloads`.\n\n**Key options**\n- Inputs: usually a file, sometimes a YouTube link, depending on project type \n- Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes \n- Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt \n\n**Cost** \nCredits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.\n\nFor detailed examples, see the [product page](https://magichour.ai/products/character-replace).\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Source video and reference character image for the job.",
"properties": {
"image_file_path": {
"description": "Reference character image used as the replacement or animation target. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/5678.png",
"minLength": 1,
"type": "string"
},
"video_file_path": {
"description": "Source video containing the subject to replace or animate. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"type": "string"
}
},
"required": [
"video_file_path",
"image_file_path"
],
"type": "object"
},
"end_seconds": {
"description": "End time of your clip (seconds). Must be greater than start_seconds.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"model": {
"default": "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.",
"enum": [
"wan-animate",
"kling-3.0"
],
"example": "wan-animate",
"type": "string"
},
"name": {
"default": "Character Replace - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Character Replace video",
"type": "string"
},
"resolution": {
"description": "Output video resolution. Must be supported by `model`. Defaults to the lowest resolution available on your plan for that model.",
"enum": [
"480p",
"720p",
"1080p"
],
"example": "720p",
"type": "string"
},
"start_seconds": {
"default": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"style": {
"description": "Optional style controls for replace vs animate mode and subject selection.",
"example": {
"mode": "replace",
"selection_mode": "auto"
},
"properties": {
"mode": {
"description": "Processing mode. `replace` swaps the detected subject with your reference character. `animate` transfers motion from the video onto your character image.",
"enum": [
"replace",
"animate"
],
"example": "replace",
"type": "string"
},
"points": {
"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`).",
"items": {
"properties": {
"position_x": {
"description": "Horizontal pixel coordinate in the source video frame at `time_seconds`, measured from the left edge.",
"example": 320,
"minimum": 0,
"type": "integer"
},
"position_y": {
"description": "Vertical pixel coordinate in the source video frame at `time_seconds`, measured from the top edge.",
"example": 180,
"minimum": 0,
"type": "integer"
},
"time_seconds": {
"description": "Timestamp on the source video timeline in seconds. Uses the same clock as `start_seconds` and `end_seconds`.",
"example": 2.5,
"format": "float",
"minimum": 0,
"type": "number"
}
},
"required": [
"position_x",
"position_y",
"time_seconds"
],
"type": "object"
},
"type": "array"
},
"selection_mode": {
"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`. Defaults to `auto`.",
"enum": [
"auto",
"point"
],
"example": "auto",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"end_seconds",
"assets"
],
"type": "object"
},
"name": "character_replace_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Detect faces in an image or video. \n \nUse this API to get the list of faces detected in the image or video to use in the [face swap photo](https://docs.magichour.ai/api-reference/image-projects/face-swap-photo) or [face swap video](https://docs.magichour.ai/api-reference/video-projects/face-swap-video) API calls for multi-face swaps.\n\nNote: Face detection is free to use for the near future. Pricing may change in the future.\n\nMCP guidance:\n- This starts an async face-detection task and returns an `id`. Use the face-detection details endpoint with that id to retrieve detected faces before doing individual face swaps.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for face detection",
"properties": {
"target_file_path": {
"description": "This is the image or video where the face will be detected. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"type": "string"
}
},
"required": [
"target_file_path"
],
"type": "object"
},
"confidence_score": {
"default": 0.5,
"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.",
"example": 0.5,
"maximum": 1,
"minimum": 0,
"multipleOf": 0.05,
"type": "number"
}
},
"required": [
"assets"
],
"type": "object"
},
"name": "face_detection_detect_faces",
"outputSchema": {
"properties": {
"credits_charged": {
"description": "The credits charged for the task.",
"type": "integer"
},
"id": {
"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.",
"example": "uuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Get the details of a face detection task. \n\nUse this API to get the list of faces detected in the image or video to use in the [face swap photo](https://docs.magichour.ai/api-reference/image-projects/face-swap-photo) or [face swap video](https://docs.magichour.ai/api-reference/video-projects/face-swap-video) API calls for multi-face swaps.",
"inputSchema": {
"properties": {
"id": {
"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).",
"example": "uuid-example",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "face_detection_retrieve_details",
"outputSchema": {
"properties": {
"credits_charged": {
"description": "The credits charged for the task.",
"example": 0,
"type": "integer"
},
"faces": {
"description": "The faces detected in the image or video. The list is populated as faces are detected.",
"example": [
{
"path": "api-assets/id/0-0.png",
"url": "https://videos.magichour.ai/api-assets/id/0-0.png"
}
],
"items": {
"properties": {
"path": {
"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": "api-assets/id/0-0.png",
"type": "string"
},
"url": {
"description": "The url to the face image. This is used to render the image in your applications.",
"example": "https://videos.magichour.ai/api-assets/id/0-0.png",
"type": "string"
}
},
"required": [
"path",
"url"
],
"type": "object"
},
"type": "array"
},
"id": {
"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).",
"example": "uuid-example",
"type": "string"
},
"status": {
"description": "The status of the detection.",
"enum": [
"queued",
"rendering",
"complete",
"error"
],
"example": "complete",
"type": "string"
}
},
"required": [
"id",
"credits_charged",
"status",
"faces"
],
"type": "object"
}
},
{
"description": "**What this API does**\n\nCreate the same Face Swap you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.\n \n**Good for**\n- Automation and batch processing \n- Adding face swap into apps, pipelines, or tools \n\n**How it works (3 steps)**\n1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. \n2) Send a request to create a face swap job with the basic fields. \n3) Check the job status until it's `complete`, then download the result from `downloads`.\n\n**Key options**\n- Inputs: usually a file, sometimes a YouTube link, depending on project type \n- Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes \n- Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt \n\n**Cost** \nCredits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.\n\nFor detailed examples, see the [product page](https://magichour.ai/products/face-swap).\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used",
"properties": {
"face_mappings": {
"description": "This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`.",
"example": [
{
"new_face": "api-assets/id/1234.png",
"original_face": "api-assets/id/0-0.png"
}
],
"items": {
"properties": {
"new_face": {
"description": "The face image that will be used to replace the face in the `original_face`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"type": "string"
},
"original_face": {
"description": "The face detected from the image in `target_file_path`. The file name is in the format of `<face_frame>-<face_index>.png`. This value is corresponds to the response in the [face detection API](https://docs.magichour.ai/api-reference/files/get-face-detection-details).\n\n* The face_frame is the frame number of the face in the target image. For images, the frame number is always 0.\n* The face_index is the index of the face in the target image, starting from 0 going left to right.",
"example": "api-assets/id/0-0.png",
"type": "string"
}
},
"required": [
"original_face",
"new_face"
],
"type": "object"
},
"maxItems": 5,
"type": "array"
},
"face_swap_mode": {
"default": "all-faces",
"description": "Choose how to swap faces:\n- **all-faces** (recommended) — swap all detected faces using one source image (`source_file_path` required)\n- **individual-faces** — specify exact mappings using `face_mappings`",
"enum": [
"all-faces",
"individual-faces"
],
"example": "all-faces",
"type": "string"
},
"image_file_path": {
"description": "The path of the input image with the face to be swapped. The value is required if `face_swap_mode` is `all-faces`.\n\nThis value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "image/id/1234.png",
"type": "string"
},
"video_file_path": {
"description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp4",
"type": "string"
},
"video_source": {
"description": "Choose your video source.",
"enum": [
"file",
"youtube"
],
"example": "file",
"type": "string"
},
"youtube_url": {
"description": "YouTube URL (required if `video_source` is `youtube`).",
"format": "uri",
"type": "string"
}
},
"required": [
"video_source"
],
"type": "object"
},
"end_seconds": {
"description": "End time of your clip (seconds). Must be greater than start_seconds.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"name": {
"default": "Face Swap - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Face Swap video",
"type": "string"
},
"start_seconds": {
"description": "Start time of your clip (seconds). Must be ≥ 0.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"style": {
"description": "Style of the face swap video.",
"example": {
"version": "default"
},
"properties": {
"version": {
"description": "* `v1` - May preserve skin detail and texture better, but weaker identity preservation.\n* `v2` - Faster, sharper, better handling of hair and glasses. stronger identity preservation.\n* `default` - Use the version we recommend, which will change over time. This is recommended unless you need a specific earlier version. This is the default behavior.",
"enum": [
"v1",
"v2",
"default"
],
"example": "default",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"start_seconds",
"end_seconds",
"assets"
],
"type": "object"
},
"name": "face_swap_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Create a face swap photo. Each photo costs 10 credits. The height/width of the output image depends on your subscription. Please refer to our [pricing](https://magichour.ai/pricing) page for more details\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for face swap photo",
"properties": {
"face_mappings": {
"description": "This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`.",
"example": [
{
"new_face": "api-assets/id/1234.png",
"original_face": "api-assets/id/0-0.png"
}
],
"items": {
"properties": {
"new_face": {
"description": "The face image that will be used to replace the face in the `original_face`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"type": "string"
},
"original_face": {
"description": "The face detected from the image in `target_file_path`. The file name is in the format of `<face_frame>-<face_index>.png`. This value is corresponds to the response in the [face detection API](https://docs.magichour.ai/api-reference/files/get-face-detection-details).\n\n* The face_frame is the frame number of the face in the target image. For images, the frame number is always 0.\n* The face_index is the index of the face in the target image, starting from 0 going left to right.",
"example": "api-assets/id/0-0.png",
"type": "string"
}
},
"required": [
"original_face",
"new_face"
],
"type": "object"
},
"maxItems": 5,
"type": "array"
},
"face_swap_mode": {
"default": "all-faces",
"description": "Choose how to swap faces:\n- **all-faces** (recommended) — swap all detected faces using one source image (`source_file_path` required)\n- **individual-faces** — specify exact mappings using `face_mappings`",
"enum": [
"all-faces",
"individual-faces"
],
"example": "all-faces",
"type": "string"
},
"source_file_path": {
"description": "This is the image from which the face is extracted. The value is required if `face_swap_mode` is `all-faces`.\n\nThis value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
},
"target_file_path": {
"description": "This is the image where the face from the source image will be placed. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"target_file_path"
],
"type": "object"
},
"name": {
"default": "Face Swap - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Face Swap image",
"type": "string"
}
},
"required": [
"assets"
],
"type": "object"
},
"name": "face_swap_photo_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 10,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Fetch a audio `downloads[n].url` from a completed audio project and return it as inline MCP audio content for compatible clients. Pass the exact full signed URL from `downloads[n].url` without trimming query parameters; `expires_at` is separate metadata, not part of the URL.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"download_url": {
"type": "string"
},
"max_bytes": {
"default": 15728640,
"type": "integer"
}
},
"required": [
"download_url"
],
"type": "object"
},
"name": "fetch_audio_download",
"outputSchema": null
},
{
"description": "Fetch a image `downloads[n].url` from a completed image project and return it as inline MCP image content for compatible clients. Pass the exact full signed URL from `downloads[n].url` without trimming query parameters; `expires_at` is separate metadata, not part of the URL.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"download_url": {
"type": "string"
},
"max_bytes": {
"default": 15728640,
"type": "integer"
}
},
"required": [
"download_url"
],
"type": "object"
},
"name": "fetch_image_download",
"outputSchema": null
},
{
"description": "Fetch a video `downloads[n].url` from a completed video project and return it as an embedded MCP binary resource for compatible clients. Pass the exact full signed URL from `downloads[n].url` without trimming query parameters; `expires_at` is separate metadata, not part of the URL.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"download_url": {
"type": "string"
},
"max_bytes": {
"default": 15728640,
"type": "integer"
}
},
"required": [
"download_url"
],
"type": "object"
},
"name": "fetch_video_download",
"outputSchema": null
},
{
"description": "Swap a head onto a body image. Each image costs 10 credits. Output resolution depends on your subscription; you may set `max_resolution` lower than your plan maximum if desired.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the body and head images for head swap",
"properties": {
"body_file_path": {
"description": "Image that receives the swapped head. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
},
"head_file_path": {
"description": "Image of the head to place on the body. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/5678.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"body_file_path",
"head_file_path"
],
"type": "object"
},
"max_resolution": {
"description": "Constrains the larger dimension (height or width) of the output. Omit to use the maximum allowed for your plan (capped at 2048px). Values above your plan maximum are clamped down to your plan's maximum.",
"example": 1024,
"type": "integer"
},
"name": {
"default": "Head Swap - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Head Swap image",
"type": "string"
}
},
"required": [
"assets"
],
"type": "object"
},
"name": "head_swap_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 10,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Remove background from image. Each image costs 5 credits.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for background removal",
"properties": {
"background_image_file_path": {
"description": "The image used as the new background for the image_file_path. This image will be resized to match the image in image_file_path. Please make sure the resolution between the images are similar.\n\nThis value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"type": "string"
},
"image_file_path": {
"description": "The image to remove the background. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"type": "string"
}
},
"required": [
"image_file_path"
],
"type": "object"
},
"name": {
"default": "Background Remover - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Background Remover image",
"type": "string"
}
},
"required": [
"assets"
],
"type": "object"
},
"name": "image_background_remover_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 5,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Permanently delete the rendered image(s). This action is not reversible, please be sure before deleting.",
"inputSchema": {
"properties": {
"id": {
"description": "Unique ID of the image project. This value is returned by all of the POST APIs that create an image.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "image_projects_delete",
"outputSchema": null
},
{
"description": "Check the progress of a image project. The `downloads` field is populated after a successful render.\n \n**Statuses**\n- `queued` — waiting to start\n- `rendering` — in progress\n- `complete` — ready; see `downloads`\n- `error` — a failure occurred (see `error`)\n- `canceled` — user canceled\n- `draft` — not used\n\nMCP guidance:\n- Use this after a create tool to poll job status. When status is `complete`, surface the `downloads` URLs to the user; if status is `error`, surface the error message.\n- Each `downloads[n].url` is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append `expires_at` onto the URL string.",
"inputSchema": {
"properties": {
"id": {
"description": "Unique ID of the image project. This value is returned by all of the POST APIs that create an image.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "image_projects_retrieve_details",
"outputSchema": {
"description": "Success",
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"credits_charged": {
"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.",
"example": 5,
"type": "integer"
},
"downloads": {
"items": {
"description": "The download url and expiration date of the image project",
"properties": {
"expires_at": {
"example": "2024-10-19T05:16:19.027Z",
"format": "date-time",
"type": "string"
},
"url": {
"example": "https://videos.magichour.ai/id/output.png",
"format": "uri",
"type": "string"
}
},
"required": [
"url",
"expires_at"
],
"type": "object"
},
"type": "array"
},
"enabled": {
"description": "Whether this resource is active. If false, it is deleted.",
"type": "boolean"
},
"error": {
"description": "In the case of an error, this object will contain the error encountered during video render",
"properties": {
"code": {
"description": "An error code to indicate why a failure happened.",
"example": "no_source_face",
"type": "string"
},
"message": {
"description": "Details on the reason why a failure happened.",
"example": "Please use an image with a detectable face",
"type": "string"
}
},
"required": [
"message",
"code"
],
"type": [
"object",
"null"
]
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
},
"image_count": {
"description": "Number of images generated",
"example": 1,
"type": "integer"
},
"name": {
"description": "The name of the image.",
"example": "Example Name",
"type": [
"string",
"null"
]
},
"status": {
"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.",
"enum": [
"draft",
"queued",
"rendering",
"complete",
"error",
"canceled"
],
"example": "complete",
"type": "string"
},
"type": {
"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",
"example": "AI_IMAGE",
"type": "string"
}
},
"required": [
"id",
"name",
"status",
"image_count",
"type",
"created_at",
"enabled",
"credits_charged",
"downloads",
"error"
],
"type": "object"
}
},
{
"description": "**What this API does**\n\nCreate the same Image To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.\n \n**Good for**\n- Automation and batch processing \n- Adding image to video into apps, pipelines, or tools \n\n**How it works (3 steps)**\n1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. \n2) Send a request to create a image to video job with the basic fields. \n3) Check the job status until it's `complete`, then download the result from `downloads`.\n\n**Key options**\n- Inputs: usually a file, sometimes a YouTube link, depending on project type \n- Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes \n- Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt \n\n**Cost** \nCredits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.\n\nFor detailed examples, see the [product page](https://magichour.ai/products/image-to-video).\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for image-to-video.",
"properties": {
"end_image_file_path": {
"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`**: Not supported\n* **`seedance-1.5`**: Supports 480p, 720p, 1080p.\n* **`seedance-2.0`**: Supports 480p, 720p, 1080p, 4k.\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",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
},
"image_file_path": {
"description": "The path of the image file. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"image_file_path"
],
"type": "object"
},
"audio": {
"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-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",
"example": true,
"type": "boolean"
},
"end_seconds": {
"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-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",
"example": 5,
"format": "float",
"maximum": 60,
"minimum": 1,
"type": "number"
},
"model": {
"default": "default",
"description": "The AI model to use for video generation.\n\n* `default`: uses our currently recommended model for general use. For paid tiers, defaults to `kling-3.0`. For free tiers, it defaults to `ltx-2.5`.\n* `gemini-omni-1.1`: Best for precise short clips, first/last frames, and high-resolution output.\n* `kling-2.6`: Best for action, motion blur, and controlled camera moves.\n* `kling-3.0`: Best for cinematic stories, references, and optional audio.\n* `ltx-2.5`: Fastest for general scenes, long clips, audio, and rapid iteration.\n* `minimax-h3`: Great for reference-driven clips with native audio and longer durations.\n* `seedance-1.5`: Best for smooth, consistent motion with an end frame.\n* `seedance-2.0`: Best for reference-led clips with precise subject control.\n* `seedance-2.0-mini`: Faster reference-led clips with consistent motion and audio.\n* `seedance-2.5`: Best for premium realism, detail, and natural motion.\n* `veo3.1`: Best for romantic interactions and expressive action, with realistic detail.\n* `veo3.1-lite`: Balanced realism and audio at a lower cost than Veo 3.1.\n* `wan-2.2`: Best for physical motion, action, and camera movement.\n* `wan-3.0`: High-quality video with native audio, long clips, and end-frame control.\n\nIf you specify the deprecated model value that includes the `-audio` suffix, this will be the same as included `audio` as `true`.",
"enum": [
"default",
"kling-3.0",
"ltx-2.5",
"seedance-2.0-mini",
"wan-3.0",
"seedance-2.5",
"gemini-omni-1.1",
"minimax-h3",
"wan-2.2",
"seedance-1.5",
"seedance-2.0",
"veo3.1-lite",
"sora-2",
"veo3.1",
"kling-2.6",
"ltx-2.3",
"ltx-2",
"kling-2.5",
"kling-1.6",
"seedance",
"kling-2.5-audio",
"veo3.1-audio"
],
"example": "kling-3.0",
"type": "string"
},
"name": {
"default": "Image To Video - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Image To Video video",
"type": "string"
},
"resolution": {
"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-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",
"enum": [
"360p",
"480p",
"720p",
"1080p",
"4k"
],
"example": "720p",
"type": "string"
},
"style": {
"description": "Attributed used to dictate the style of the output",
"properties": {
"prompt": {
"description": "The prompt used for the video.",
"example": "a dog running",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"end_seconds",
"assets"
],
"type": "object"
},
"name": "image_to_video_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "**What this API does**\n\nCreate the same Lip Sync you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.\n \n**Good for**\n- Automation and batch processing \n- Adding lip sync into apps, pipelines, or tools \n\n**How it works (3 steps)**\n1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. \n2) Send a request to create a lip sync job with the basic fields. \n3) Check the job status until it's `complete`, then download the result from `downloads`.\n\n**Key options**\n- Inputs: usually a file, sometimes a YouTube link, depending on project type \n- Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes \n- Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt \n\n**Cost** \nCredits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.\n\nFor detailed examples, see the [product page](https://magichour.ai/products/lip-sync).\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for lip-sync. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used",
"properties": {
"audio_file_path": {
"description": "The path of the audio file. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"type": "string"
},
"video_file_path": {
"description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp4",
"type": "string"
},
"video_source": {
"description": "Choose your video source.",
"enum": [
"file",
"youtube"
],
"example": "file",
"type": "string"
},
"youtube_url": {
"description": "YouTube URL (required if `video_source` is `youtube`).",
"format": "uri",
"type": "string"
}
},
"required": [
"audio_file_path",
"video_source"
],
"type": "object"
},
"end_seconds": {
"description": "End time of your clip (seconds). Must be greater than start_seconds.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"max_fps_limit": {
"description": "Defines the maximum FPS (frames per second) for the output video. If the input video's FPS is lower than this limit, the output video will retain the input FPS. This is useful for reducing unnecessary frame usage in scenarios where high FPS is not required.",
"example": 12,
"minimum": 1,
"type": "number"
},
"name": {
"default": "Lip Sync - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Lip Sync video",
"type": "string"
},
"start_seconds": {
"description": "Start time of your clip (seconds). Must be ≥ 0.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"style": {
"description": "Attributes used to dictate the style of the output",
"properties": {
"generation_mode": {
"default": "lite",
"description": "A specific version of our lip sync system, optimized for different needs.\n* `lite` - Fast lip sync - best for simple videos. Costs 1 credit per frame of video.\n* `standard` - Natural, accurate lip sync - best for most creators. Costs 1 credit per frame of video.\n* `pro` - Premium fidelity with enhanced detail - best for professionals. Costs 2 credits per frame of video.\n\nNote: `standard` and `pro` are only available for users on Creator, Pro, and Business tiers.\n ",
"enum": [
"lite",
"standard",
"pro"
],
"example": "lite",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"start_seconds",
"end_seconds",
"assets"
],
"type": "object"
},
"name": "lip_sync_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Colorize image. Each image costs 10 credits.\n\nMCP guidance:\n- This starts an async image generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_image_project` helper with the returned id, or poll the matching `GET /v1/image-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"description": "Provide the assets for photo colorization",
"properties": {
"image_file_path": {
"description": "The image used to generate the colorized image. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.png",
"minLength": 1,
"type": "string"
}
},
"required": [
"image_file_path"
],
"type": "object"
},
"name": {
"default": "Photo Colorizer - dateTime",
"description": "Give your image a custom name for easy identification.",
"example": "My Photo Colorizer image",
"type": "string"
}
},
"required": [
"assets"
],
"type": "object"
},
"name": "photo_colorizer_create_image",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 10,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Check that the Magic Hour MCP server is reachable.",
"inputSchema": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "ping",
"outputSchema": {
"properties": {
"result": {
"type": "string"
}
},
"required": [
"result"
],
"type": "object",
"x-fastmcp-wrap-result": true
}
},
{
"description": "Returns active saved items owned by the authenticated account, newest first. Each item includes every saved asset with a durable file_path for reuse in compatible generation APIs and a temporary signed URL for previewing or downloading. Filter by type to find characters, references, voices, moodboards, or brand kits. To fetch the next page, pass the response's next_cursor as cursor.",
"inputSchema": {
"properties": {
"cursor": {
"description": "Opaque pagination cursor from the previous response's next_cursor.",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 20,
"description": "Maximum number of saved items to return. Defaults to 20.",
"example": 20,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"type": {
"description": "Only return saved items of this type.",
"enum": [
"character",
"reference",
"voice",
"moodboard",
"brand_kit"
],
"example": "character",
"type": "string"
}
},
"required": [],
"type": "object"
},
"name": "saved_items_list",
"outputSchema": {
"properties": {
"items": {
"items": {
"properties": {
"assets": {
"items": {
"properties": {
"file_path": {
"description": "Durable asset path. Pass it to a compatible API asset field without uploading it again.",
"example": "saved-items/user-id/item-id/image.png",
"type": "string"
},
"is_primary": {
"description": "Whether this asset is the saved item's primary asset.",
"example": true,
"type": "boolean"
},
"media_kind": {
"description": "Media type of the asset.",
"enum": [
"IMAGE",
"VIDEO",
"AUDIO"
],
"example": "IMAGE",
"type": "string"
},
"url": {
"description": "Signed URL for previewing or downloading the asset. Expires after 24 hours.",
"format": "uri",
"type": "string"
},
"url_expires_at": {
"description": "When the signed URL expires. The saved asset and file_path do not expire.",
"example": "2026-09-17T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
},
"required": [
"file_path",
"media_kind",
"is_primary",
"url",
"url_expires_at"
],
"type": "object"
},
"type": "array"
},
"id": {
"description": "Unique ID of the saved item.",
"example": "cuid-example",
"type": "string"
},
"name": {
"description": "User-provided name of the saved item.",
"example": "Alex",
"type": [
"string",
"null"
]
},
"type": {
"description": "Saved item type.",
"enum": [
"character",
"reference",
"voice",
"moodboard",
"brand_kit"
],
"example": "character",
"type": "string"
}
},
"required": [
"id",
"type",
"name",
"assets"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"description": "Cursor for the next page, or null when there are no more saved items.",
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"type": "object"
}
},
{
"description": "**What this API does**\n\nCreate the same Text To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.\n \n**Good for**\n- Automation and batch processing \n- Adding text to video into apps, pipelines, or tools \n\n**How it works (3 steps)**\n1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. \n2) Send a request to create a text to video job with the basic fields. \n3) Check the job status until it's `complete`, then download the result from `downloads`.\n\n**Key options**\n- Inputs: usually a file, sometimes a YouTube link, depending on project type \n- Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes \n- Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt \n\n**Cost** \nCredits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.\n\nFor detailed examples, see the [product page](https://magichour.ai/products/text-to-video).\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.",
"inputSchema": {
"properties": {
"aspect_ratio": {
"description": "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-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",
"enum": [
"16:9",
"9:16",
"1:1"
],
"example": "16:9",
"type": "string"
},
"audio": {
"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-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",
"example": true,
"type": "boolean"
},
"end_seconds": {
"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-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",
"example": 5,
"format": "float",
"maximum": 60,
"minimum": 1,
"type": "number"
},
"model": {
"default": "default",
"description": "The AI model to use for video generation.\n\n* `default`: uses our currently recommended model for general use. For paid tiers, defaults to `kling-3.0`. For free tiers, it defaults to `ltx-2.5`.\n* `gemini-omni-1.1`: Best for precise short clips, first/last frames, and high-resolution output.\n* `kling-2.6`: Best for action, motion blur, and controlled camera moves.\n* `kling-3.0`: Best for cinematic stories, references, and optional audio.\n* `ltx-2.5`: Fastest for general scenes, long clips, audio, and rapid iteration.\n* `minimax-h3`: Great for reference-driven clips with native audio and longer durations.\n* `seedance-1.5`: Best for smooth, consistent motion with an end frame.\n* `seedance-2.0`: Best for reference-led clips with precise subject control.\n* `seedance-2.0-mini`: Faster reference-led clips with consistent motion and audio.\n* `seedance-2.5`: Best for premium realism, detail, and natural motion.\n* `veo3.1`: Best for romantic interactions and expressive action, with realistic detail.\n* `veo3.1-lite`: Balanced realism and audio at a lower cost than Veo 3.1.\n* `wan-2.2`: Best for physical motion, action, and camera movement.\n* `wan-3.0`: High-quality video with native audio, long clips, and end-frame control.\n\nIf you specify the deprecated model value that includes the `-audio` suffix, this will be the same as included `audio` as `true`.",
"enum": [
"default",
"kling-3.0",
"ltx-2.5",
"seedance-2.0-mini",
"wan-3.0",
"seedance-2.5",
"gemini-omni-1.1",
"minimax-h3",
"wan-2.2",
"seedance-1.5",
"seedance-2.0",
"veo3.1-lite",
"sora-2",
"veo3.1",
"kling-2.6",
"ltx-2.3",
"ltx-2",
"kling-2.5",
"kling-1.6",
"seedance",
"kling-2.5-audio",
"veo3.1-audio"
],
"example": "kling-3.0",
"type": "string"
},
"name": {
"default": "Text To Video - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Text To Video video",
"type": "string"
},
"references": {
"items": {
"properties": {
"file_path": {
"minLength": 1,
"type": "string"
},
"name": {
"pattern": "^[A-Za-z][\\w-]*$",
"type": "string"
}
},
"required": [
"name",
"file_path"
],
"type": "object"
},
"maxItems": 10,
"minItems": 1,
"type": "array"
},
"resolution": {
"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-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",
"enum": [
"360p",
"480p",
"720p",
"1080p",
"4k"
],
"example": "720p",
"type": "string"
},
"style": {
"properties": {
"prompt": {
"description": "The prompt used for the video.",
"example": "a dog running",
"maxLength": 20000,
"minLength": 1,
"type": "string"
}
},
"required": [
"prompt"
],
"type": "object"
}
},
"required": [
"end_seconds",
"style"
],
"type": "object"
},
"name": "text_to_video_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Generates a list of pre-signed upload URLs for the assets required. This API is only necessary if you want to upload to Magic Hour's storage. Refer to the [Input Files Guide](https://docs.magichour.ai/integration/inputs-and-outputs) for more details.\n\nThe response array will match the order of items in the request body.\n\n**Valid file extensions per asset type**:\n- video: mp4, m4v, mov, webm\n- audio: mp3, wav, aac, flac, webm, weba, m4a, opus, ogg, oga, aiff, amr\n- image: png, jpg, jpeg, jfif, heic, heif, webp, avif, jp2, tiff, tif, bmp\n- gif: gif, webp, webm\n\n> Note: `gif` is only supported for face swap API `video_file_path` field.\n\nOnce you receive an upload URL, send a `PUT` request to upload the file directly.\n\nExample:\n\n```\ncurl -X PUT --data '@/path/to/file/video.mp4' \\\n https://videos.magichour.ai/api-assets/id/video.mp4?<auth params from the API response>\n```\n\nMCP guidance:\n- This only creates presigned upload URLs. For local files, upload the raw bytes to each returned `upload_url` outside the generation call, then pass the matching `file_path` into the create tool.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"items": {
"description": "The list of assets to upload. The response array will match the order of items in the request body.",
"example": [
{
"extension": "mp4",
"type": "video"
},
{
"extension": "mp3",
"type": "audio"
}
],
"items": {
"properties": {
"extension": {
"description": "The extension of the file to upload. Do not include the dot (.) before the extension. Possible extensions are mp4,m4v,mov,webm,mp3,wav,aac,flac,webm,weba,m4a,opus,ogg,oga,aiff,amr,png,jpg,jpeg,jfif,heic,heif,webp,avif,jp2,tiff,tif,bmp,gif,webp,webm",
"example": "mp4",
"pattern": "^[a-z0-9]+$",
"type": "string"
},
"type": {
"description": "The type of asset to upload. Possible types are video, audio, image",
"enum": [
"video",
"audio",
"image"
],
"example": "video",
"type": "string"
}
},
"required": [
"type",
"extension"
],
"type": "object"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"name": "video_assets_generate_presigned_url",
"outputSchema": {
"description": "Success",
"properties": {
"items": {
"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.",
"example": [
{
"expires_at": "2024-07-25T16:56:21.932Z",
"file_path": "api-assets/id/video.mp4",
"upload_url": "https://videos.magichour.ai/api-assets/id/video.mp4?auth-value=1234567890"
},
{
"expires_at": "2024-07-25T16:56:21.932Z",
"file_path": "api-assets/id/audio.mp3",
"upload_url": "https://videos.magichour.ai/api-assets/id/audio.mp3?auth-value=1234567890"
}
],
"items": {
"properties": {
"expires_at": {
"description": "when the upload url expires, and will need to request a new one.",
"example": "2024-07-21T17:32:28Z",
"format": "date-time",
"type": "string"
},
"file_path": {
"description": "this value is used in APIs that needs assets, such as image_file_path, video_file_path, and audio_file_path",
"example": "video/id/1234.mp4",
"type": "string"
},
"upload_url": {
"description": "Used to upload the file to storage, send a PUT request with the file as data to upload.",
"example": "https://videos.magichour.ai/id/video.mp4?auth-value=1234567890",
"format": "uri",
"type": "string"
}
},
"required": [
"upload_url",
"expires_at",
"file_path"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
}
},
{
"description": "Permanently delete the rendered video. This action is not reversible, please be sure before deleting.",
"inputSchema": {
"properties": {
"id": {
"description": "Unique ID of the video project. This value is returned by all of the POST APIs that create a video.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "video_projects_delete",
"outputSchema": null
},
{
"description": "Check the progress of a video project. The `downloads` field is populated after a successful render.\n \n**Statuses**\n- `queued` — waiting to start\n- `rendering` — in progress\n- `complete` — ready; see `downloads`\n- `error` — a failure occurred (see `error`)\n- `canceled` — user canceled\n- `draft` — not used\n\nMCP guidance:\n- Use this after a create tool to poll job status. When status is `complete`, surface the `downloads` URLs to the user; if status is `error`, surface the error message.\n- Each `downloads[n].url` is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append `expires_at` onto the URL string.",
"inputSchema": {
"properties": {
"id": {
"description": "Unique ID of the video project. This value is returned by all of the POST APIs that create a video.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "video_projects_retrieve_details",
"outputSchema": {
"description": "Success",
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"downloads": {
"items": {
"description": "The download url and expiration date of the image project",
"properties": {
"expires_at": {
"example": "2024-10-19T05:16:19.027Z",
"format": "date-time",
"type": "string"
},
"url": {
"example": "https://videos.magichour.ai/id/output.mp4",
"format": "uri",
"type": "string"
}
},
"required": [
"url",
"expires_at"
],
"type": "object"
},
"type": "array"
},
"enabled": {
"description": "Whether this resource is active. If false, it is deleted.",
"type": "boolean"
},
"end_seconds": {
"description": "End time of your clip (seconds). Must be greater than start_seconds.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"error": {
"description": "In the case of an error, this object will contain the error encountered during video render",
"properties": {
"code": {
"description": "An error code to indicate why a failure happened.",
"example": "no_source_face",
"type": "string"
},
"message": {
"description": "Details on the reason why a failure happened.",
"example": "Please use an image with a detectable face",
"type": "string"
}
},
"required": [
"message",
"code"
],
"type": [
"object",
"null"
]
},
"fps": {
"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.",
"example": 30,
"type": "number"
},
"height": {
"description": "The height of the final output video. A value of -1 indicates the height can be ignored.",
"example": 960,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
},
"name": {
"description": "The name of the video.",
"example": "Example Name",
"type": [
"string",
"null"
]
},
"start_seconds": {
"description": "Start time of your clip (seconds). Must be ≥ 0.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"status": {
"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.",
"enum": [
"draft",
"queued",
"rendering",
"complete",
"error",
"canceled"
],
"example": "complete",
"type": "string"
},
"type": {
"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",
"example": "FACE_SWAP",
"type": "string"
},
"width": {
"description": "The width of the final output video. A value of -1 indicates the width can be ignored.",
"example": 512,
"type": "integer"
}
},
"required": [
"id",
"name",
"status",
"type",
"created_at",
"width",
"height",
"enabled",
"start_seconds",
"end_seconds",
"credits_charged",
"fps",
"error",
"downloads"
],
"type": "object"
}
},
{
"description": "**What this API does**\n\nCreate the same Video To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.\n \n**Good for**\n- Automation and batch processing \n- Adding video to video into apps, pipelines, or tools \n\n**How it works (3 steps)**\n1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. \n2) Send a request to create a video to video job with the basic fields. \n3) Check the job status until it's `complete`, then download the result from `downloads`.\n\n**Key options**\n- Inputs: usually a file, sometimes a YouTube link, depending on project type \n- Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes \n- Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt \n\n**Cost** \nCredits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.\n\nFor detailed examples, see the [product page](https://magichour.ai/products/video-to-video).\n\nMCP guidance:\n- This starts an async video generation job and returns `id` plus `credits_charged` immediately. If the user wants the finished result, call the `wait_for_video_project` helper with the returned id, or poll the matching `GET /v1/video-projects/{id}` endpoint until status is `complete`, `error`, or `canceled`. Completed projects include `downloads` with direct URLs. The custom wait helper also returns `exact_download_urls` separately from expiration metadata.\n- For `*_file_path` values, prefer an existing Magic Hour file path or a `file_path` returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned `file_path`.",
"inputSchema": {
"properties": {
"assets": {
"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",
"properties": {
"video_file_path": {
"description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the video file\n- `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).\n\nSee the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.\n",
"example": "api-assets/id/1234.mp4",
"type": "string"
},
"video_source": {
"description": "Choose your video source.",
"enum": [
"file",
"youtube"
],
"example": "file",
"type": "string"
},
"youtube_url": {
"description": "YouTube URL (required if `video_source` is `youtube`).",
"format": "uri",
"type": "string"
}
},
"required": [
"video_source"
],
"type": "object"
},
"end_seconds": {
"description": "End time of your clip (seconds). Must be greater than start_seconds.",
"example": 15,
"format": "float",
"minimum": 0.1,
"type": "number"
},
"fps_resolution": {
"default": "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",
"enum": [
"FULL",
"HALF"
],
"example": "HALF",
"type": "string"
},
"name": {
"default": "Video To Video - dateTime",
"description": "Give your video a custom name for easy identification.",
"example": "My Video To Video video",
"type": "string"
},
"start_seconds": {
"description": "Start time of your clip (seconds). Must be ≥ 0.",
"example": 0,
"format": "float",
"minimum": 0,
"type": "number"
},
"style": {
"properties": {
"art_style": {
"enum": [
"Minecraft",
"Watercolor",
"Pixel",
"Retro Sci-Fi",
"Lego",
"Origami",
"Ghost",
"Sub-Zero",
"Studio Ghibli",
"Comic",
"Impressionism",
"Master Chief",
"Solid Snake",
"Street Fighter",
"Hologram",
"GTA",
"Clay",
"Mystique",
"Dragonball Z",
"Mario",
"Samurai",
"Spartan",
"Boba Fett",
"3D Render",
"Airbender",
"Android",
"Anime Warrior",
"Armored Knight",
"Assassin's Creed",
"Avatar",
"Black Spiderman",
"Bold Anime",
"Celestial Skin",
"Chinese Swordsmen",
"Cyberpunk",
"Cypher",
"Dark Fantasy",
"Future Bot",
"Futuristic Fantasy",
"Ghibli Anime",
"Gundam",
"Illustration",
"Ink",
"Ink Poster",
"Jinx",
"Knight",
"Link",
"Marble",
"Mech",
"Naruto",
"Neon Dream",
"No Art Style",
"Oil Painting",
"On Fire",
"Painterly Anime",
"Pixar",
"Power Armor",
"Power Ranger",
"Radiant Anime",
"Realistic Anime",
"Realistic Pixar",
"Retro Anime",
"Samurai Bot",
"Sharp Anime",
"Soft Anime",
"Starfield",
"The Void",
"Tomb Raider",
"Underwater",
"Van Gogh",
"Viking",
"Western Anime",
"Wu Kong",
"Wuxia Anime",
"Zelda"
],
"type": "string"
},
"model": {
"default": "default",
"description": "* `Dreamshaper` - a good all-around model that works for both animations as well as realism.\n* `Absolute Reality` - better at realism, but you'll often get similar results with Dreamshaper as well.\n* `Flat 2D Anime` - best for a flat illustration style that's common in most anime.\n* `default` - use the default recommended model for the selected art style.",
"enum": [
"Dreamshaper",
"Absolute Reality",
"Flat 2D Anime",
"Soft Anime",
"Kaywaii",
"Western Anime",
"3D Anime",
"default"
],
"example": "default",
"type": "string"
},
"prompt": {
"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.",
"type": [
"string",
"null"
]
},
"prompt_type": {
"default": "default",
"description": "* `default` - Use the default recommended prompt for the art style.\n* `custom` - Only use the prompt passed in the API. Note: for v1, lora prompt will still be auto added to apply the art style properly.\n* `append_default` - Add the default recommended prompt to the end of the prompt passed in the API.",
"enum": [
"default",
"custom",
"append_default"
],
"example": "default",
"type": "string"
},
"version": {
"default": "default",
"description": "* `v1` - more detail, closer prompt adherence, and frame-by-frame previews.\n* `v2` - faster, more consistent, and less noisy.\n* `default` - use the default version for the selected art style.",
"enum": [
"v1",
"v2",
"default"
],
"example": "default",
"type": "string"
}
},
"required": [
"art_style"
],
"type": "object"
}
},
"required": [
"start_seconds",
"end_seconds",
"style",
"assets"
],
"type": "object"
},
"name": "video_to_video_create_video",
"outputSchema": {
"description": "Success",
"properties": {
"credits_charged": {
"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.",
"example": 450,
"type": "integer"
},
"id": {
"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.",
"example": "cuid-example",
"type": "string"
}
},
"required": [
"id",
"credits_charged"
],
"type": "object"
}
},
{
"description": "Poll an audio project until it completes, errors, is canceled, or times out. Returns the final project JSON and, when complete, attempts to inline audio downloads for Inspector or compatible clients. Returns sanitized download fields. Use `exact_download_urls[n]` or `downloads[n].url` exactly as returned; do not shorten it, remove query parameters, or append expiration metadata.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"include_inline_downloads": {
"default": true,
"type": "boolean"
},
"max_bytes_per_download": {
"default": 15728640,
"type": "integer"
},
"max_inline_downloads": {
"default": 4,
"type": "integer"
},
"poll_interval_seconds": {
"default": 2,
"type": "number"
},
"timeout_seconds": {
"default": 180,
"type": "number"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "wait_for_audio_project",
"outputSchema": null
},
{
"description": "Poll an image project until it completes, errors, is canceled, or times out. Returns the final project JSON and, when complete, attempts to inline image downloads for Inspector or compatible clients. Returns sanitized download fields. Use `exact_download_urls[n]` or `downloads[n].url` exactly as returned; do not shorten it, remove query parameters, or append expiration metadata.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"include_inline_downloads": {
"default": true,
"type": "boolean"
},
"max_bytes_per_download": {
"default": 15728640,
"type": "integer"
},
"max_inline_downloads": {
"default": 4,
"type": "integer"
},
"poll_interval_seconds": {
"default": 2,
"type": "number"
},
"timeout_seconds": {
"default": 180,
"type": "number"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "wait_for_image_project",
"outputSchema": null
},
{
"description": "Poll a video project until it completes, errors, is canceled, or times out. Returns sanitized download fields. Use `exact_download_urls[n]` or `downloads[n].url` exactly as returned; do not shorten it, remove query parameters, or append expiration metadata.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"include_inline_downloads": {
"default": false,
"type": "boolean"
},
"max_inline_downloads": {
"default": 0,
"type": "integer"
},
"poll_interval_seconds": {
"default": 2,
"type": "number"
},
"timeout_seconds": {
"default": 300,
"type": "number"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "wait_for_video_project",
"outputSchema": null
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:db0e18ba5e2df8c2d76d2bfe969a6b53b6900bf8879af82fece0341b8564cd9e | sha256sum