Create and edit images, videos, and audio through Magic Hour's hosted Streamable HTTP MCP server.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Get the current credit balance and subscription details of the account that owns the API key.
This tool takes no arguments.
Get the current credit balance and subscription details of the account that owns the API key.
No arguments.
{
"type": "object",
"required": [],
"properties": {}
}Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Change outfits in photos in seconds with just a photo reference. Each photo costs 25 credits.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| assets* | object | Provide the assets for clothes changer |
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Clothes Changer - dateTime",
"example": "My Clothes Changer image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"person_file_path",
"garment_file_path"
],
"properties": {
"garment_type": {
"enum": [
"entire_outfit",
"upper_body",
"lower_body",
"dresses"
],
"type": "string",
"example": "entire_outfit",
"description": "Type of clothing item to swap. If not provided, swaps the entire outfit. \n* `upper_body` - for shirts/jackets \n* `lower_body` - for pants/skirts \n* `dresses` - for entire outfit (deprecated, use `entire_outfit` instead) \n* `entire_outfit` - for entire outfit"
},
"person_file_path": {
"type": "string",
"example": "api-assets/id/model.png",
"minLength": 1,
"description": "The image with the person. This value is either\n- a direct URL to the 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"
},
"garment_file_path": {
"type": "string",
"example": "api-assets/id/outfit.png",
"minLength": 1,
"description": "The image of the outfit. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for clothes changer"
}
}
}MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. 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
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| style* | object | Face editing parameters |
| assets* | object | Provide the assets for face editor |
{
"type": "object",
"required": [
"assets",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Face Editor - dateTime",
"example": "My Face Editor image",
"description": "Give your image a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"head_yaw": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Head yaw (-100 to 100), in increments of 5"
},
"head_roll": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Head roll (-100 to 100), in increments of 5"
},
"head_pitch": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Head pitch (-100 to 100), in increments of 5"
},
"mouth_grim": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Mouth grim (-100 to 100), in increments of 5"
},
"mouth_pout": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Mouth pout (-100 to 100), in increments of 5"
},
"mouth_purse": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Mouth purse (-100 to 100), in increments of 5"
},
"mouth_smile": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Mouth smile (-100 to 100), in increments of 5"
},
"enhance_face": {
"type": "boolean",
"default": false,
"example": false,
"description": "Enhance face features"
},
"eye_open_ratio": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Eye open ratio (-100 to 100), in increments of 5"
},
"lip_open_ratio": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Lip open ratio (-100 to 100), in increments of 5"
},
"eye_gaze_vertical": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Vertical eye gaze (-100 to 100), in increments of 5"
},
"eyebrow_direction": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Eyebrow direction (-100 to 100), in increments of 5"
},
"eye_gaze_horizontal": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Horizontal eye gaze (-100 to 100), in increments of 5"
},
"mouth_position_vertical": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Vertical mouth position (-100 to 100), in increments of 5"
},
"mouth_position_horizontal": {
"type": "number",
"default": 0,
"example": 0,
"maximum": 100,
"minimum": -100,
"multipleOf": 5,
"description": "Horizontal mouth position (-100 to 100), in increments of 5"
}
},
"description": "Face editing parameters"
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "This is the image whose face will be edited. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for face editor"
}
}
}MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. Create an AI GIF. Each GIF costs 50 credits.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your gif a custom name for easy identification. |
| style* | object | |
| output_format | string | The output file format for the generated animation. |
{
"type": "object",
"required": [
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Ai Gif - dateTime",
"example": "My Ai Gif gif",
"description": "Give your gif a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"prompt": {
"type": "string",
"example": "Cute dancing cat, pixel art",
"maxLength": 500,
"minLength": 1,
"description": "The prompt used for the GIF."
}
}
},
"output_format": {
"enum": [
"gif",
"mp4",
"webm"
],
"type": "string",
"default": "gif",
"example": "gif",
"description": "The output file format for the generated animation."
}
}
}MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Create an AI headshot. Each headshot costs 50 credits.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| style | object | |
| assets* | object | Provide the assets for headshot photo |
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Ai Headshot - dateTime",
"example": "My Ai Headshot image",
"description": "Give your image a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"example": "Professional studio headshot with soft lighting and a neutral background",
"description": "Prompt used to guide the style of your headshot. We recommend omitting the prompt unless you want to customize your headshot. You can visit [AI headshot generator](https://magichour.ai/create/ai-headshot-generator) to view an example of a good prompt used for our 'Professional' style."
}
}
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The image used to generate the headshot. This image must contain one detectable face. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for headshot photo"
}
}
}MCP guidance: - Requires one or more source images in `assets.image_file_paths`. For prompt-only creation, use `ai_image_generator_create_image` instead. - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Edit supplied images using `assets.image_file_paths` and `style.prompt`. For prompt-only creation use `ai_image_generator_create_image`. Editing is not a required preparation step before image-to-video when the approved source already meets the brief. Check model eligibility: the omitted/default model is not universally available on Free.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| model | string | The AI model to use for image editing. Each model has different capabilities and costs. **Models:** - `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior. - `flux-2-klein` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Max additional input images: 5 - `gpt-image-2` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `gpt-image-2.5-flare` - from 100 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `krea-2` - from 10 credits/image - Supported resolutions: 640px, 1k - Available for tiers: free, creator, pro, business - Max additional input images: 1 - `nano-banana` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-2` - from 100 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-2-lite` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-2.1` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-pro` - from 150 credits/image - Supported resolutions: 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `qwen-edit` - from 10 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Max additional input images: 2 - `qwen-image-2.1` - from 10 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Max additional input images: 2 - `seedream-v4` - from 40 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `seedream-v4.5` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `seedream-v5-pro` - from 75 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: creator, pro, business - Max additional input images: 9 |
MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. Create an AI image with advanced model selection and quality controls.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| model | string | The AI model to use for image generation. Each model has different capabilities and costs. **Models:** - `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior. - `flux-2-klein` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Image count allowed: 1 - `flux-schnell` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 2, 3, 4 - `gpt-image-2` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `gpt-image-2.5-flare` - from 100 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `krea-2` - from 10 credits/image - Supported resolutions: 640px, 1k - Available for tiers: free, creator, pro, business - Image count allowed: 1 - `nano-banana` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `nano-banana-2` - from 100 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 4, 9, 16 - `nano-banana-2-lite` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `nano-banana-2.1` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 4, 9, 16 - `nano-banana-pro` - from 150 credits/image - Supported resolutions: 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 4, 9, 16 - `qwen-image-2.1` - from 10 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 2, 3, 4 - `seedream-v4` - from 40 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `seedream-v5-pro` - from 75 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 - `z-image-turbo` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 2, 3, 4 **Deprecated Enum Values:** - `seedream` - Use `seedream-v4` instead. |
MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. 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.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| style | object | Style settings for the upscale. Use `mode` (`"preserve"`, `"balanced"`, or `"creative"`). Defaults to `"balanced"`. |
| assets* | object | Provide the assets for upscaling |
| scale_factor* | number | How much to scale the image. Must be either 2 or 4. Note: 4x upscale is only available on Creator, Pro, or Business tier. |
{
"type": "object",
"required": [
"scale_factor",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Image Upscaler - dateTime",
"example": "My Image Upscaler image",
"description": "Give your image a custom name for easy identification."
},
"style": {
"type": "object",
"default": {},
"example": {
"mode": "preserve"
},
"properties": {
"mode": {
"enum": [
"pro",
"preserve",
"balanced",
"creative"
],
"type": "string",
"example": "preserve",
"description": "The upscaling mode. `\"preserve\"` uses the fast pro pipeline (1× credit multiplier). `\"balanced\"` and `\"creative\"` use the creative pipeline (2× credit multiplier). `\"pro\"` is deprecated and maps to `\"preserve\"`. Defaults to `\"balanced\"`."
},
"prompt": {
"type": "string",
"example": "Enhance fine details and keep the image natural",
"description": "A prompt to guide the final image. Only used when mode is `creative`."
}
},
"description": "Style settings for the upscale. Use `mode` (`\"preserve\"`, `\"balanced\"`, or `\"creative\"`). Defaults to `\"balanced\"`."
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The image to upscale. This value is either\n- a direct URL to the 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."
}
},
"description": "Provide the assets for upscaling"
},
"scale_factor": {
"type": "number",
"example": 2,
"description": "How much to scale the image. Must be either 2 or 4.\n \nNote: 4x upscale is only available on Creator, Pro, or Business tier."
}
}
}MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. Create an AI generated meme. Each meme costs 10 credits.
| Argument | Type | Description |
|---|---|---|
| name | string | The name of the meme. |
| style* | object |
{
"type": "object",
"required": [
"style"
],
"properties": {
"name": {
"type": "string",
"example": "My Funny Meme",
"description": "The name of the meme."
},
"style": {
"type": "object",
"required": [
"topic",
"template"
],
"properties": {
"topic": {
"type": "string",
"example": "When the code finally works",
"maxLength": 200,
"minLength": 1,
"description": "The topic of the meme."
},
"template": {
"enum": [
"Random"
],
"type": "string",
"description": "Select a random meme template."
},
"searchWeb": {
"type": "boolean",
"default": false,
"example": false,
"description": "Whether to search the web for meme content."
}
}
}
}
}MCP guidance: - Starts an async audio job; returns `id` and `credits_charged`. For finished results, call `wait_for_audio_project` with that id or poll `GET /v1/audio-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. Generate music from a description, with optional custom lyrics or instrumental-only output. Costs 1 credits per requested second. Returns a project ID; poll GET /v1/audio-projects/{id} for status and downloads.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your audio a custom name for easy identification. |
| style* | object | |
| duration* | integer | Requested track duration in seconds, from 15 to 300. Determines credits charged. |
{
"type": "object",
"required": [
"duration",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "AI Music Generator",
"example": "My Music Generator audio",
"description": "Give your audio a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"lyrics": {
"type": "string",
"example": "City lights are fading...",
"description": "Custom lyrics. Omit or leave blank for AI-generated lyrics when instrumental is false."
},
"prompt": {
"type": "string",
"example": "Dreamy synthwave with warm bass and soft vocals",
"minLength": 1,
"description": "Describe the song, including genre, mood, and instruments."
},
"instrumental": {
"type": "boolean",
"default": false,
"example": false,
"description": "Generate music without vocals. When true, lyrics is ignored."
}
},
"additionalProperties": false
},
"duration": {
"type": "integer",
"example": 120,
"maximum": 300,
"minimum": 15,
"description": "Requested track duration in seconds, from 15 to 300. Determines credits charged."
}
}
}MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. Create an AI QR code. Each QR code costs 0 credits.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| style* | object | |
| content* | string | The content of the QR code. |
{
"type": "object",
"required": [
"content",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Qr Code - dateTime",
"example": "My Qr Code image",
"description": "Give your image a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"art_style"
],
"properties": {
"art_style": {
"type": "string",
"example": "Watercolor",
"description": "To use our templates, pass in one of Watercolor, Cyberpunk City, Ink Landscape, Interior Painting, Japanese Street, Mech, Minecraft, Picasso Painting, Game Map, Spaceship, Chinese Painting, Winter Village, or pass any custom art style."
}
}
},
"content": {
"type": "string",
"example": "https://magichour.ai",
"description": "The content of the QR code."
}
}
}Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Requires a still portrait in `assets.image_file_path` and an existing recording in `assets.audio_file_path`, plus `start_seconds` and `end_seconds`. Text alone is not accepted; this tool does not synthesize speech. For existing video plus replacement audio, use `lip_sync_create_video` instead.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| style | object | Attributes used to dictate the style of the output |
| assets* | object | Provide the assets for creating a talking photo |
| resolution | string | Output preset. Overrides `max_resolution`. Defaults to 480p in prompted mode; realistic mode uses the mapped plan maximum. |
| end_seconds* | number |
MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Create a spoken UGC video from a prepared image and script. Returns a project ID; poll GET /v1/video-projects/{id} for status and downloads. To compose an image, generate the image separately with the Image Editor API and supply its download URL.
| Argument | Type | Description |
|---|---|---|
| model | string | Defaults to kling-3.0 on paid plans and ltx-2.5 on free plans. |
| assets* | object | |
| script* | string | The words the actor should speak. Character limits apply after trimming: * kling-3.0: 2500 characters. * ltx-2.5: 1804 characters. * veo3.1: 2500 characters. LTX's dialogue wrapper counts toward its model prompt limit. |
| resolution | string | Defaults to 720p on paid plans and 480p on free plans. Unsupported model/resolution combinations and resolutions unavailable for your plan are rejected. |
| end_seconds* | number | Video duration in seconds. Supported values by model: * kling-3.0: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 seconds. * ltx-2.5: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60 seconds. * veo3.1: 4, 6, 8, 15, 22, 29, 36, 43, 50, 57, 64, 71, 78, 85, 92, 99, 106, 113, 120, 127, 134, 141 seconds. Free plans are limited to 5 seconds unless a credit pack has been purchased. |
MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. **What this API does** Create the same Video Editor you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding video editor into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a video editor job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: usually a file, sometimes a YouTube link, depending on project type - Resolution: output size and plan requirements vary by workflow and model. Some workflows derive output size from the input video. - Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt **Cost** Credits are charged when the job is queued (`credits_charged` in the response). Tools billed per frame charge an estimate and settle to the frames that actually render once the job finishes; tools billed per second charge the final amount upfront. Failed jobs are refunded. For detailed examples, see the [product page](https://magichour.ai/products/ai-video-editor).
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| model |
MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. **What this API does** Create 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. **Good for** - Automation and batch processing - Adding video translator into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a video translator job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: usually a file, sometimes a YouTube link, depending on project type - Resolution: output size and plan requirements vary by workflow and model. Some workflows derive output size from the input video. - Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt **Cost** Credits are charged when the job is queued (`credits_charged` in the response). Tools billed per frame charge an estimate and settle to the frames that actually render once the job finishes; tools billed per second charge the final amount upfront. Failed jobs are refunded. For detailed examples, see the [product page](https://magichour.ai/products/ai-video-translator).
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| assets |
MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. **What this API does** Create the same Video Upscaler you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding video upscaler into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a video upscaler job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: usually a file, sometimes a YouTube link, depending on project type - Resolution: output size and plan requirements vary by workflow and model. Some workflows derive output size from the input video. - Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt **Cost** Credits are charged when the job is queued (`credits_charged` in the response). Tools billed per frame charge an estimate and settle to the frames that actually render once the job finishes; tools billed per second charge the final amount upfront. Failed jobs are refunded. For detailed examples, see the [product page](https://magichour.ai/products/video-upscaler).
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| assets |
MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Create a Animation video. The estimated frame cost is calculated based on the `fps` and `end_seconds` input.
| Argument | Type | Description |
|---|---|---|
| fps* | number | The desire output video frame rate |
| name | string | Give your video a custom name for easy identification. |
| style* | object | Defines the style of the output video |
| width* | integer | The width of the final output video. The maximum width depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details |
| assets* | object | Provide the assets for animation. |
| height* | integer | 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 |
Permanently delete the rendered audio file(s). This action is not reversible, please be sure before deleting.
| Argument | Type | Description |
|---|---|---|
| id* | string | Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio."
}
}
}MCP guidance: - Use this after a create tool to poll job status. When status is `complete`, surface the `downloads` URLs to the user; if status is `error`, surface the error message. - Each `downloads[n].url` is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append `expires_at` onto the URL string. Check the progress of a audio project. The `downloads` field is populated after a successful render. **Statuses** - `queued` — waiting to start - `rendering` — in progress - `complete` — ready; see `downloads` - `error` — a failure occurred (see `error`) - `canceled` — user canceled - `draft` — not used
| Argument | Type | Description |
|---|---|---|
| id* | string | Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the audio project. This value is returned by all of the POST APIs that create an audio."
}
}
}MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. **What this API does** Create the same Audio To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding audio to video into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a audio to video job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: usually a file, sometimes a YouTube link, depending on project type - Resolution: output size and plan requirements vary by workflow and model. Some workflows derive output size from the input video. - Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt **Cost** Credits are charged when the job is queued (`credits_charged` in the response). Tools billed per frame charge an estimate and settle to the frames that actually render once the job finishes; tools billed per second charge the final amount upfront. Failed jobs are refunded. For detailed examples, see the [product page](https://magichour.ai/products/audio-to-video).
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| style |
MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Automatically generate subtitles for your video in multiple languages.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| style* | object | Style of the subtitle. At least one of `.style.template` or `.style.custom_config` must be provided. * If only `.style.template` is provided, default values for the template will be used. * If both are provided, the fields in `.style.custom_config` will be used to overwrite the fields in `.style.template`. * If only `.style.custom_config` is provided, then all fields in `.style.custom_config` will be used. To use custom config only, the following `custom_config` params are required: * `.style.custom_config.font` * `.style.custom_config.text_color` * `.style.custom_config.vertical_position` * `.style.custom_config.horizontal_position` |
| assets* | object | Provide the assets for auto subtitle generator |
| end_seconds* | number | End time of your clip (seconds). Must be greater than start_seconds. |
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. 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).
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| assets* | object | Person image and scene image for body swap |
| resolution* | string | Output resolution. Determines credits charged for the run. |
{
"type": "object",
"required": [
"resolution",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Body Swap - dateTime",
"example": "My Body Swap image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"person_file_path",
"scene_file_path"
],
"properties": {
"scene_file_path": {
"type": "string",
"example": "api-assets/id/5678.png",
"minLength": 1,
"description": "Original scene image (background). This value is either\n- a direct URL to the 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"
},
"person_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "Image of the person to place into the scene. This value is either\n- a direct URL to the 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"
}
},
"description": "Person image and scene image for body swap"
},
"resolution": {
"enum": [
"640px",
"1k",
"2k",
"4k"
],
"type": "string",
"example": "640px",
"description": "Output resolution. Determines credits charged for the run."
}
}
}Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Replace a video subject or transfer video motion onto a reference character image. Requires `assets.video_file_path`, `assets.image_file_path` and `end_seconds`. Model support controls duration, resolution and subject selection; see parameter schemas. Generation consumes credits; the queued video charge is an estimate, with the final charge available on the completed project.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| model | string | Model to use. Defaults to `wan-animate`. * **`wan-animate`**: 480p, 720p. Supports `points` subject selection. * **`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. |
| style | object | Optional style controls for replace vs animate mode and subject selection. |
| assets* | object |
MCP guidance: - This starts an async face-detection task and returns an `id`. Use the face-detection details endpoint with that id to retrieve detected faces before doing individual face swaps. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Detect faces in an image or video. Use this API to get the list of faces detected in the image or video to use in the [face swap photo](https://docs.magichour.ai/api-reference/image-projects/face-swap-photo) or [face swap video](https://docs.magichour.ai/api-reference/video-projects/face-swap-video) API calls for multi-face swaps. Note: Face detection is free to use for the near future. Pricing may change in the future.
| Argument | Type | Description |
|---|---|---|
| assets* | object | Provide the assets for face detection |
| confidence_score | number | Confidence threshold for filtering detected faces. * Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives. * Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections. |
{
"type": "object",
"required": [
"assets"
],
"properties": {
"assets": {
"type": "object",
"required": [
"target_file_path"
],
"properties": {
"target_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"description": "This is the image or video where the face will be detected. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for face detection"
},
"confidence_score": {
"type": "number",
"default": 0.5,
"example": 0.5,
"maximum": 1,
"minimum": 0,
"multipleOf": 0.05,
"description": "Confidence threshold for filtering detected faces. \n* Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives. \n* Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections."
}
}
}Get the details of a face detection task. Use this API to get the list of faces detected in the image or video to use in the [face swap photo](https://docs.magichour.ai/api-reference/image-projects/face-swap-photo) or [face swap video](https://docs.magichour.ai/api-reference/video-projects/face-swap-video) API calls for multi-face swaps.
| Argument | Type | Description |
|---|---|---|
| id* | string | 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). |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "uuid-example",
"description": "The id of the task. This value is returned by the [face detection API](https://docs.magichour.ai/api-reference/files/face-detection#response-id)."
}
}
}Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Requires `start_seconds`, `end_seconds` and `assets.video_source` with its matching `assets.video_file_path` or `assets.youtube_url`. Use `assets.image_file_path` for all-faces mode, or `assets.face_mappings` for individual-faces mode after face detection. Generation consumes credits; the queued video charge is an estimate, with the final charge available on the completed project.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| style | object | Style of the face swap video. |
| assets* | object | Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used |
| end_seconds* | number | End time of your clip (seconds). Must be greater than start_seconds. |
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. 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
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| assets* | object | Provide the assets for face swap photo |
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Face Swap - dateTime",
"example": "My Face Swap image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"example": {
"face_swap_mode": "all-faces",
"source_file_path": "api-assets/id/1234.png",
"target_file_path": "api-assets/id/1234.png"
},
"required": [
"target_file_path"
],
"properties": {
"face_mappings": {
"type": "array",
"items": {
"type": "object",
"required": [
"original_face",
"new_face"
],
"properties": {
"new_face": {
"type": "string",
"example": "api-assets/id/1234.png",
"description": "The face image that will be used to replace the face in the `original_face`. This value is either\n- a direct URL to the 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"
},
"original_face": {
"type": "string",
"example": "api-assets/id/0-0.png",
"description": "The face detected from the image in `target_file_path`. The file name is in the format of `<face_frame>-<face_index>.png`. This value is corresponds to the response in the [face detection API](https://docs.magichour.ai/api-reference/files/get-face-detection-details).\n\n* The face_frame is the frame number of the face in the target image. For images, the frame number is always 0.\n* The face_index is the index of the face in the target image, starting from 0 going left to right."
}
}
},
"example": [
{
"new_face": "api-assets/id/1234.png",
"original_face": "api-assets/id/0-0.png"
}
],
"maxItems": 5,
"description": "This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`."
},
"face_swap_mode": {
"enum": [
"all-faces",
"individual-faces"
],
"type": "string",
"default": "all-faces",
"example": "all-faces",
"description": "Choose 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`"
},
"source_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "This is the image from which the face is extracted. The value is required if `face_swap_mode` is `all-faces`.\n\nThis value is either\n- a direct URL to the 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"
},
"target_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "This is the image where the face from the source image will be placed. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for face swap photo"
}
}
}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. Inline media is capped at 8 MiB; use the signed URL directly for larger downloads.
| Argument | Type | Description |
|---|---|---|
| max_bytes | integer | |
| download_url* | string |
{
"type": "object",
"required": [
"download_url"
],
"properties": {
"max_bytes": {
"type": "integer",
"default": 8388608
},
"download_url": {
"type": "string"
}
},
"additionalProperties": false
}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. Inline media is capped at 8 MiB; use the signed URL directly for larger downloads.
| Argument | Type | Description |
|---|---|---|
| max_bytes | integer | |
| download_url* | string |
{
"type": "object",
"required": [
"download_url"
],
"properties": {
"max_bytes": {
"type": "integer",
"default": 8388608
},
"download_url": {
"type": "string"
}
},
"additionalProperties": false
}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. Inline media is capped at 8 MiB; use the signed URL directly for larger downloads.
| Argument | Type | Description |
|---|---|---|
| max_bytes | integer | |
| download_url* | string |
{
"type": "object",
"required": [
"download_url"
],
"properties": {
"max_bytes": {
"type": "integer",
"default": 8388608
},
"download_url": {
"type": "string"
}
},
"additionalProperties": false
}Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. 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.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| assets* | object | Provide the body and head images for head swap |
| max_resolution | integer | 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. |
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Head Swap - dateTime",
"example": "My Head Swap image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"body_file_path",
"head_file_path"
],
"properties": {
"body_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "Image that receives the swapped head. This value is either\n- a direct URL to the 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"
},
"head_file_path": {
"type": "string",
"example": "api-assets/id/5678.png",
"minLength": 1,
"description": "Image of the head to place on the body. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the body and head images for head swap"
},
"max_resolution": {
"type": "integer",
"example": 1024,
"description": "Constrains the larger dimension (height or width) of the output. Omit to use the maximum allowed for your plan (capped at 2048px). Values above your plan maximum are clamped down to your plan's maximum."
}
}
}MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Remove background from image. Each image costs 5 credits.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| assets* | object | Provide the assets for background removal |
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Background Remover - dateTime",
"example": "My Background Remover image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"description": "The image to remove the background. This value is either\n- a direct URL to the 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"
},
"background_image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"description": "The image used as the new background for the image_file_path. This image will be resized to match the image in image_file_path. Please make sure the resolution between the images are similar.\n\nThis value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for background removal"
}
}
}Permanently delete the rendered image(s). This action is not reversible, please be sure before deleting.
| Argument | Type | Description |
|---|---|---|
| id* | string | Unique ID of the image project. This value is returned by all of the POST APIs that create an image. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image project. This value is returned by all of the POST APIs that create an image."
}
}
}MCP guidance: - Use this after a create tool to poll job status. When status is `complete`, surface the `downloads` URLs to the user; if status is `error`, surface the error message. - Each `downloads[n].url` is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append `expires_at` onto the URL string. Check the progress of a image project. The `downloads` field is populated after a successful render. **Statuses** - `queued` — waiting to start - `rendering` — in progress - `complete` — ready; see `downloads` - `error` — a failure occurred (see `error`) - `canceled` — user canceled - `draft` — not used
| Argument | Type | Description |
|---|---|---|
| id* | string | Unique ID of the image project. This value is returned by all of the POST APIs that create an image. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the image project. This value is returned by all of the POST APIs that create an image."
}
}
}MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Animate a supplied product photo, portrait or scene. Requires `assets.image_file_path` and `end_seconds`. Use the approved image directly; edit only for a requested visual change or a source problem that prevents the shot. Prompt for motion while preserving the supplied appearance. Model, duration, resolution and audio support vary. Generation consumes credits; the queued video charge is an estimate, with the final charge available on the completed project.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| audio | boolean | Whether to include audio in the video. Defaults to `false` if not specified. Audio support varies by model: * **`gemini-omni-1.1`**: Not supported * **`kling-2.6`**: Not supported * **`kling-3.0`**: Toggle-able: audio adds extra credits when enabled * **`ltx-2.5`**: Toggle-able: no additional credits for audio * **`minimax-h3`**: Toggle-able: no additional credits for audio * **`seedance-1.5`**: Toggle-able: audio adds extra credits when enabled * **`seedance-2.0`**: Toggle-able: no additional credits for audio * **`seedance-2.0-fast`**: Toggle-able: no additional credits for audio * **`seedance-2.0-mini`**: Toggle-able: no additional credits for audio * **`seedance-2.5`**: Toggle-able: no additional credits for audio * **`veo3.1`**: Toggle-able: audio adds extra credits when enabled * **`veo3.1-lite`**: Toggle-able: audio adds extra credits when enabled * **`wan-2.2`**: Not supported * **`wan-3.0`**: Toggle-able: no additional credits for audio |
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Match existing video to replacement audio. Requires `assets.audio_file_path`, `assets.video_source` and its matching `assets.video_file_path` or `assets.youtube_url`, plus `start_seconds` and `end_seconds`. For a still portrait plus audio, use `ai_talking_photo_create_talking_photo`. Text alone is not an audio input. Generation consumes credits; the queued video charge is an estimate, with the final charge available on the completed project.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| style | object | Attributes used to dictate the style of the output |
| assets* | object | Provide the assets for lip-sync. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used |
| end_seconds* | number | End time of your clip (seconds). Must be greater than start_seconds. |
MCP guidance: - Starts an async image job; returns `id` and `credits_charged`. For finished results, call `wait_for_image_project` with that id or poll `GET /v1/image-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Colorize image. Each image costs 10 credits.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your image a custom name for easy identification. |
| assets* | object | Provide the assets for photo colorization |
{
"type": "object",
"required": [
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Photo Colorizer - dateTime",
"example": "My Photo Colorizer image",
"description": "Give your image a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The image used to generate the colorized image. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for photo colorization"
}
}
}Check that the Magic Hour MCP server is reachable.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| type | string | Only return saved items of this type. |
| limit | integer | Maximum number of saved items to return. Defaults to 20. |
| cursor | string | Opaque pagination cursor from the previous response's next_cursor. |
{
"type": "object",
"required": [],
"properties": {
"type": {
"enum": [
"character",
"reference",
"voice",
"moodboard",
"brand_kit"
],
"type": "string",
"example": "character",
"description": "Only return saved items of this type."
},
"limit": {
"type": "integer",
"default": 20,
"example": 20,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of saved items to return. Defaults to 20."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque pagination cursor from the previous response's next_cursor."
}
}
}MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. Generate a new scene from `style.prompt` and `end_seconds` when no supplied starting image is required. To animate an approved product photo or portrait, use `image_to_video_create_video` instead.
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| audio | boolean | Whether to include audio in the video. Defaults to `false` if not specified. Audio support varies by model: * **`gemini-omni-1.1`**: Not supported * **`kling-2.6`**: Not supported * **`kling-3.0`**: Toggle-able: audio adds extra credits when enabled * **`ltx-2.5`**: Toggle-able: no additional credits for audio * **`minimax-h3`**: Toggle-able: no additional credits for audio * **`seedance-1.5`**: Toggle-able: audio adds extra credits when enabled * **`seedance-2.0`**: Toggle-able: no additional credits for audio * **`seedance-2.0-fast`**: Toggle-able: no additional credits for audio * **`seedance-2.0-mini`**: Toggle-able: no additional credits for audio * **`seedance-2.5`**: Toggle-able: no additional credits for audio * **`veo3.1`**: Toggle-able: audio adds extra credits when enabled * **`veo3.1-lite`**: Toggle-able: audio adds extra credits when enabled * **`wan-2.2`**: Not supported * **`wan-3.0`**: Toggle-able: no additional credits for audio |
| model | string | The AI model to use for video generation. * `default`: uses our currently recommended model for general use. For paid tiers, defaults to `kling-3.0`. For free tiers, it defaults to `ltx-2.5`. * `gemini-omni-1.1`: Best for precise short clips, first/last frames, and high-resolution output. * `kling-2.6`: Best for action, motion blur, and controlled camera moves. * `kling-3.0`: Best for cinematic stories, references, and optional audio. * `ltx-2.5`: Fastest for general scenes, long clips, audio, and rapid iteration. * `minimax-h3`: Great for reference-driven clips with native audio and longer durations. * `seedance-1.5`: Best for smooth, consistent motion with an end frame. * `seedance-2.0`: Best for reference-led clips with precise subject control. * `seedance-2.0-fast`: Fast reference-led clips with consistent motion and audio. * `seedance-2.0-mini`: Faster reference-led clips with consistent motion and audio. * `seedance-2.5`: Best for premium realism, detail, and natural motion. * `veo3.1`: Best for romantic interactions and expressive action, with realistic detail. * `veo3.1-lite`: Balanced realism and audio at a lower cost than Veo 3.1. * `wan-2.2`: Best for physical motion, action, and camera movement. * `wan-3.0`: High-quality video with native audio, long clips, and end-frame control. If you specify the deprecated model value that includes the `-audio` suffix, this will be the same as included `audio` as `true`. |
MCP guidance: - This only creates presigned upload URLs. For local files, upload the raw bytes to each returned `upload_url` outside the generation call, then pass the matching `file_path` into the create tool. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. Generates a list of pre-signed upload URLs for the assets required. This API is only necessary if you want to upload to Magic Hour's storage. Refer to the [Input Files Guide](https://docs.magichour.ai/integration/inputs-and-outputs) for more details. The response array will match the order of items in the request body. **Valid file extensions per asset type**: - video: mp4, m4v, mov, webm - audio: mp3, wav, aac, flac, webm, weba, m4a, opus, ogg, oga, aiff, amr - image: png, jpg, jpeg, jfif, heic, heif, webp, avif, jp2, tiff, tif, bmp - gif: gif, webp, webm > Note: `gif` is only supported for face swap API `video_file_path` field. Once you receive an upload URL, send a `PUT` request to upload the file directly. Example: ``` curl -X PUT --data '@/path/to/file/video.mp4' \ https://videos.magichour.ai/api-assets/id/video.mp4?<auth params from the API response> ```
| Argument | Type | Description |
|---|---|---|
| items* | array | The list of assets to upload. The response array will match the order of items in the request body. |
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"extension"
],
"properties": {
"type": {
"enum": [
"video",
"audio",
"image"
],
"type": "string",
"example": "video",
"description": "The type of asset to upload. Possible types are video, audio, image"
},
"extension": {
"type": "string",
"example": "mp4",
"pattern": "^[a-z0-9]+$",
"description": "The extension of the file to upload. Do not include the dot (.) before the extension. Possible extensions are mp4,m4v,mov,webm,mp3,wav,aac,flac,webm,weba,m4a,opus,ogg,oga,aiff,amr,png,jpg,jpeg,jfif,heic,heif,webp,avif,jp2,tiff,tif,bmp,gif,webp,webm"
}
}
},
"example": [
{
"type": "video",
"extension": "mp4"
},
{
"type": "audio",
"extension": "mp3"
}
],
"minItems": 1,
"description": "The list of assets to upload. The response array will match the order of items in the request body."
}
}
}Permanently delete the rendered video. This action is not reversible, please be sure before deleting.
| Argument | Type | Description |
|---|---|---|
| id* | string | Unique ID of the video project. This value is returned by all of the POST APIs that create a video. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video project. This value is returned by all of the POST APIs that create a video."
}
}
}MCP guidance: - Use this after a create tool to poll job status. When status is `complete`, surface the `downloads` URLs to the user; if status is `error`, surface the error message. - Each `downloads[n].url` is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append `expires_at` onto the URL string. Check the progress of a video project. The `downloads` field is populated after a successful render. **Statuses** - `queued` — waiting to start - `rendering` — in progress - `complete` — ready; see `downloads` - `error` — a failure occurred (see `error`) - `canceled` — user canceled - `draft` — not used
| Argument | Type | Description |
|---|---|---|
| id* | string | Unique ID of the video project. This value is returned by all of the POST APIs that create a video. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "cuid-example",
"description": "Unique ID of the video project. This value is returned by all of the POST APIs that create a video."
}
}
}MCP guidance: - Starts an async video job; returns `id` and `credits_charged`. For finished results, call `wait_for_video_project` with that id or poll `GET /v1/video-projects/{id}` until `complete`, `error`, or `canceled`. Results include `downloads`; wait helpers add `exact_download_urls`. Preserve signed URLs and query parameters; never append expiration metadata. - For `*_file_path`, use an existing Magic Hour path or the upload-URL endpoint's `file_path` after uploading raw bytes to its presigned URL. Direct public media URLs may work if stable and fetchable as raw bytes; hotlinked URLs can fail. Prefer the upload-URL endpoint when unsure. **What this API does** Create the same Video To Video you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow. **Good for** - Automation and batch processing - Adding video to video into apps, pipelines, or tools **How it works (3 steps)** 1) Upload your inputs (video, image, or audio) with [Generate Upload URLs](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls) and copy the `file_path`. 2) Send a request to create a video to video job with the basic fields. 3) Check the job status until it's `complete`, then download the result from `downloads`. **Key options** - Inputs: usually a file, sometimes a YouTube link, depending on project type - Resolution: output size and plan requirements vary by workflow and model. Some workflows derive output size from the input video. - Extra fields: e.g. `face_swap_mode`, `start_seconds`/`end_seconds`, or a text prompt **Cost** Credits are charged when the job is queued (`credits_charged` in the response). Tools billed per frame charge an estimate and settle to the frames that actually render once the job finishes; tools billed per second charge the final amount upfront. Failed jobs are refunded. For detailed examples, see the [product page](https://magichour.ai/products/video-to-video).
| Argument | Type | Description |
|---|---|---|
| name | string | Give your video a custom name for easy identification. |
| style |
Poll an audio project until it completes, errors, is canceled, or times out. After a timeout, resume with the same id; do not create another generation. 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. Inline previews share an 8 MiB limit; all download URLs remain available.
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| timeout_seconds | number | |
| max_inline_downloads | integer | |
| poll_interval_seconds | number | |
| max_bytes_per_download | integer | |
| include_inline_downloads | boolean |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"timeout_seconds": {
"type": "number",
"default": 180
},
"max_inline_downloads": {
"type": "integer",
"default": 4
},
"poll_interval_seconds": {
"type": "number",
"default": 2
},
"max_bytes_per_download": {
"type": "integer",
"default": 8388608
},
"include_inline_downloads": {
"type": "boolean",
"default": true
}
},
"additionalProperties": false
}Poll an image project until it completes, errors, is canceled, or times out. After a timeout, resume with the same id; do not create another generation. 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. Inline previews share an 8 MiB limit; all download URLs remain available.
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| timeout_seconds | number | |
| max_inline_downloads | integer | |
| poll_interval_seconds | number | |
| max_bytes_per_download | integer | |
| include_inline_downloads | boolean |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"timeout_seconds": {
"type": "number",
"default": 180
},
"max_inline_downloads": {
"type": "integer",
"default": 4
},
"poll_interval_seconds": {
"type": "number",
"default": 2
},
"max_bytes_per_download": {
"type": "integer",
"default": 8388608
},
"include_inline_downloads": {
"type": "boolean",
"default": true
}
},
"additionalProperties": false
}Poll a video project until it completes, errors, is canceled, or times out. After a timeout, resume with the same id; do not create another generation. 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. Inline previews share an 8 MiB limit; all download URLs remain available.
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| timeout_seconds | number | |
| max_inline_downloads | integer | |
| poll_interval_seconds | number | |
| include_inline_downloads | boolean |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"timeout_seconds": {
"type": "number",
"default": 300
},
"max_inline_downloads": {
"type": "integer",
"default": 0
},
"poll_interval_seconds": {
"type": "number",
"default": 2
},
"include_inline_downloads": {
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}Read Magic Hour workflow guidance for face swap, image editing, image-to-video, video generation, lip sync, UGC ads, talking photos or API integration. Returns product and documentation URLs, exact tool names, ordered steps, example requests, follow-up edits and review criteria; does not generate media, spend credits or check account access.
| Argument | Type | Description |
|---|---|---|
| workflow* | string |
{
"type": "object",
"required": [
"workflow"
],
"properties": {
"workflow": {
"enum": [
"video-face-swap",
"image-editor",
"image-to-video",
"video-generator",
"lip-sync",
"ugc-ads",
"talking-photo",
"media-apis"
],
"type": "string"
}
},
"additionalProperties": false
}| style* | object |
| assets* | object | Provide the assets for image edit |
| resolution | string | Maximum resolution (longest edge) for the output image. **Options:** - `640px` — up to 640px - `1k` — up to 1024px - `2k` — up to 2048px - `4k` — up to 4096px - `auto` — **Deprecated.** Mapped server-side from your subscription tier to the best matching resolution the model supports **Per-model support:** - `flux-2-klein` - 640px, 1k, 2k - `gpt-image-2` - 640px, 1k, 2k, 4k - `gpt-image-2.5-flare` - 640px, 1k, 2k, 4k - `krea-2` - 640px, 1k - `nano-banana` - 640px, 1k - `nano-banana-2` - 640px, 1k, 2k, 4k - `nano-banana-2-lite` - 640px, 1k - `nano-banana-2.1` - 640px, 1k, 2k, 4k - `nano-banana-pro` - 1k, 2k, 4k - `qwen-edit` - 640px, 1k, 2k - `qwen-image-2.1` - 640px, 1k, 2k - `seedream-v4` - 640px, 1k, 2k, 4k - `seedream-v4.5` - 640px, 1k, 2k, 4k - `seedream-v5-pro` - 640px, 1k, 2k Note: Resolution availability depends on the model and your subscription tier. |
| image_count | number | Number of images to generate. Maximum varies by model. Defaults to 1 if not specified. |
| aspect_ratio | string | The aspect ratio of the output image(s). If not specified, defaults to `auto`. |
{
"type": "object",
"required": [
"style",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Ai Image Editor - dateTime",
"example": "My Ai Image Editor image",
"description": "Give your image a custom name for easy identification."
},
"model": {
"enum": [
"default",
"qwen-image-2.1",
"gpt-image-2",
"nano-banana-2",
"flux-2-klein",
"nano-banana-pro",
"seedream-v5-pro",
"seedream-v4.5",
"nano-banana-2.1",
"qwen-edit",
"nano-banana-2-lite",
"krea-2",
"gpt-image-2.5-flare",
"seedream-v4",
"nano-banana"
],
"type": "string",
"example": "flux-2-klein",
"description": "The AI model to use for image editing. Each model has different capabilities and costs.\n\n**Models:**\n- `default` - 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-2.1` - from 50 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n- `nano-banana-pro` - from 150 credits/image\n - Supported resolutions: 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n- `qwen-edit` - from 10 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: free, creator, pro, business\n - Max additional input images: 2\n- `qwen-image-2.1` - from 10 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: free, creator, pro, business\n - Max additional input images: 2\n- `seedream-v4` - from 40 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n- `seedream-v4.5` - from 50 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n- `seedream-v5-pro` - from 75 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: creator, pro, business\n - Max additional input images: 9\n"
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"prompt": {
"type": "string",
"example": "Give me sunglasses",
"maxLength": 15000,
"minLength": 1,
"description": "The prompt used to edit the image."
}
}
},
"assets": {
"type": "object",
"properties": {
"image_file_paths": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"example": [
"api-assets/id/1234.png",
"api-assets/id/1235.png"
],
"maxItems": 10,
"description": "The image(s) used in the edit, maximum of 10 images. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for image edit"
},
"resolution": {
"enum": [
"auto",
"640px",
"1k",
"2k",
"4k"
],
"type": "string",
"example": "640px",
"description": "Maximum resolution (longest edge) for the output image.\n\n**Options:**\n- `640px` — up to 640px\n- `1k` — up to 1024px\n- `2k` — up to 2048px\n- `4k` — up to 4096px\n- `auto` — **Deprecated.** Mapped server-side from your subscription tier to the best matching resolution the model supports\n\n**Per-model support:**\n- `flux-2-klein` - 640px, 1k, 2k\n- `gpt-image-2` - 640px, 1k, 2k, 4k\n- `gpt-image-2.5-flare` - 640px, 1k, 2k, 4k\n- `krea-2` - 640px, 1k\n- `nano-banana` - 640px, 1k\n- `nano-banana-2` - 640px, 1k, 2k, 4k\n- `nano-banana-2-lite` - 640px, 1k\n- `nano-banana-2.1` - 640px, 1k, 2k, 4k\n- `nano-banana-pro` - 1k, 2k, 4k\n- `qwen-edit` - 640px, 1k, 2k\n- `qwen-image-2.1` - 640px, 1k, 2k\n- `seedream-v4` - 640px, 1k, 2k, 4k\n- `seedream-v4.5` - 640px, 1k, 2k, 4k\n- `seedream-v5-pro` - 640px, 1k, 2k\n\nNote: Resolution availability depends on the model and your subscription tier."
},
"image_count": {
"enum": [
1,
4,
9,
16
],
"type": "number",
"default": 1,
"example": 1,
"description": "Number of images to generate. Maximum varies by model. Defaults to 1 if not specified."
},
"aspect_ratio": {
"enum": [
"auto",
"16:9",
"9:16",
"4:3",
"3:2",
"1:1",
"4:5",
"2:3"
],
"type": "string",
"example": "1:1",
"description": "The aspect ratio of the output image(s). If not specified, defaults to `auto`."
}
}
}| style* | object | The art style to use for image generation. |
| resolution | string | Maximum resolution (longest edge) for the output image. **Options:** - `640px` — up to 640px - `1k` — up to 1024px - `2k` — up to 2048px - `4k` — up to 4096px - `auto` — **Deprecated.** Mapped server-side from your subscription tier to the best matching resolution the model supports **Per-model support:** - `flux-2-klein` - 640px, 1k, 2k - `flux-schnell` - 640px, 1k, 2k - `gpt-image-2` - 640px, 1k, 2k, 4k - `gpt-image-2.5-flare` - 640px, 1k, 2k, 4k - `krea-2` - 640px, 1k - `nano-banana` - 640px, 1k - `nano-banana-2` - 640px, 1k, 2k, 4k - `nano-banana-2-lite` - 640px, 1k - `nano-banana-2.1` - 640px, 1k, 2k, 4k - `nano-banana-pro` - 1k, 2k, 4k - `qwen-image-2.1` - 640px, 1k, 2k - `seedream-v4` - 640px, 1k, 2k, 4k - `seedream-v5-pro` - 640px, 1k, 2k - `z-image-turbo` - 640px, 1k, 2k Note: Resolution availability depends on the model and your subscription tier. |
| image_count* | integer | Number of images to generate. Maximum varies by model. |
| aspect_ratio | string | The aspect ratio of the output image(s). If not specified, defaults to `1:1` (square). |
{
"type": "object",
"required": [
"image_count",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Ai Image - dateTime",
"example": "My Ai Image image",
"description": "Give your image a custom name for easy identification."
},
"model": {
"enum": [
"default",
"z-image-turbo",
"gpt-image-2",
"qwen-image-2.1",
"flux-2-klein",
"nano-banana-2",
"nano-banana-2.1",
"nano-banana-pro",
"krea-2",
"seedream-v5-pro",
"nano-banana-2-lite",
"gpt-image-2.5-flare",
"seedream-v4",
"nano-banana",
"flux-schnell",
"seedream"
],
"type": "string",
"example": "z-image-turbo",
"description": "The AI model to use for image generation. Each model has different capabilities and costs.\n\n**Models:**\n- `default` - 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-2.1` - from 50 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Image count allowed: 1, 4, 9, 16\n- `nano-banana-pro` - from 150 credits/image\n - Supported resolutions: 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Image count allowed: 1, 4, 9, 16\n- `qwen-image-2.1` - from 10 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: free, creator, pro, business\n - Image count allowed: 1, 2, 3, 4\n- `seedream-v4` - from 40 credits/image\n - Supported resolutions: 640px, 1k, 2k, 4k\n - Available for tiers: creator, pro, business\n - Image count allowed: 1, 2, 3, 4\n- `seedream-v5-pro` - from 75 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: creator, pro, business\n - Image count allowed: 1, 2, 3, 4\n- `z-image-turbo` - from 5 credits/image\n - Supported resolutions: 640px, 1k, 2k\n - Available for tiers: free, creator, pro, business\n - Image count allowed: 1, 2, 3, 4\n\n**Deprecated Enum Values:**\n- `seedream` - Use `seedream-v4` instead.\n"
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"tool": {
"enum": [
"ai-anime-generator",
"ai-art-generator",
"ai-background-generator",
"ai-character-generator",
"ai-face-generator",
"ai-fashion-generator",
"ai-icon-generator",
"ai-illustration-generator",
"ai-interior-design-generator",
"ai-landscape-generator",
"ai-logo-generator",
"ai-manga-generator",
"ai-outfit-generator",
"ai-pattern-generator",
"ai-photo-generator",
"ai-sketch-generator",
"ai-tattoo-generator",
"album-cover-generator",
"animated-characters-generator",
"architecture-generator",
"book-cover-generator",
"comic-book-generator",
"dark-fantasy-ai",
"disney-ai-generator",
"dnd-ai-art-generator",
"emoji-generator",
"fantasy-map-generator",
"graffiti-generator",
"movie-poster-generator",
"optical-illusion-generator",
"pokemon-generator",
"south-park-character-generator",
"superhero-generator",
"thumbnail-maker",
"general"
],
"type": "string",
"default": "general",
"example": "ai-anime-generator",
"description": "The art style to use for image generation. Defaults to 'general' if not provided."
},
"prompt": {
"type": "string",
"example": "Cool image",
"minLength": 1,
"description": "The prompt used for the image(s)."
}
},
"description": "The art style to use for image generation."
},
"resolution": {
"enum": [
"auto",
"640px",
"1k",
"2k",
"4k"
],
"type": "string",
"default": "auto",
"example": "640px",
"description": "Maximum resolution (longest edge) for the output image.\n\n**Options:**\n- `640px` — up to 640px\n- `1k` — up to 1024px\n- `2k` — up to 2048px\n- `4k` — up to 4096px\n- `auto` — **Deprecated.** Mapped server-side from your subscription tier to the best matching resolution the model supports\n\n**Per-model support:**\n- `flux-2-klein` - 640px, 1k, 2k\n- `flux-schnell` - 640px, 1k, 2k\n- `gpt-image-2` - 640px, 1k, 2k, 4k\n- `gpt-image-2.5-flare` - 640px, 1k, 2k, 4k\n- `krea-2` - 640px, 1k\n- `nano-banana` - 640px, 1k\n- `nano-banana-2` - 640px, 1k, 2k, 4k\n- `nano-banana-2-lite` - 640px, 1k\n- `nano-banana-2.1` - 640px, 1k, 2k, 4k\n- `nano-banana-pro` - 1k, 2k, 4k\n- `qwen-image-2.1` - 640px, 1k, 2k\n- `seedream-v4` - 640px, 1k, 2k, 4k\n- `seedream-v5-pro` - 640px, 1k, 2k\n- `z-image-turbo` - 640px, 1k, 2k\n\nNote: Resolution availability depends on the model and your subscription tier."
},
"image_count": {
"type": "integer",
"example": 1,
"maximum": 16,
"minimum": 1,
"description": "Number of images to generate. Maximum varies by model."
},
"aspect_ratio": {
"enum": [
"1:1",
"16:9",
"9:16"
],
"type": "string",
"example": "1:1",
"description": "The aspect ratio of the output image(s). If not specified, defaults to `1:1` (square)."
}
}
}| The end time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 45s. |
| start_seconds* | number | The start time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 45s. |
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Talking Photo - dateTime",
"example": "My Talking Photo video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"example": "A person smiling and speaking naturally to the camera",
"description": "A text prompt to guide the generation. Only applicable when generation_mode is `prompted`.\nThis field is ignored for other modes."
},
"generation_mode": {
"enum": [
"realistic",
"prompted",
"pro",
"standard",
"stable",
"expressive"
],
"type": "string",
"default": "realistic",
"example": "realistic",
"description": "Controls 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`"
}
},
"description": "Attributes used to dictate the style of the output"
},
"assets": {
"type": "object",
"required": [
"image_file_path",
"audio_file_path"
],
"properties": {
"audio_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"description": "The audio file to sync with the image. This value is either\n- a direct URL to the 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"
},
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The source image to animate. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for creating a talking photo"
},
"resolution": {
"enum": [
"480p",
"720p"
],
"type": "string",
"example": "480p",
"description": "Output preset. Overrides `max_resolution`. Defaults to 480p in prompted mode; realistic mode uses the mapped plan maximum."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "The end time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 45s."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "The start time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 45s."
}
}
}{
"type": "object",
"required": [
"assets",
"script",
"end_seconds"
],
"properties": {
"model": {
"enum": [
"kling-3.0",
"ltx-2.5",
"veo3.1"
],
"type": "string",
"description": "Defaults to kling-3.0 on paid plans and ltx-2.5 on free plans."
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/image.jpg",
"minLength": 1,
"description": "Prepared image to animate. This value is either\n- a direct URL to the 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"
}
},
"additionalProperties": false
},
"script": {
"type": "string",
"example": "Meet your new everyday essential.",
"minLength": 1,
"description": "The words the actor should speak. Character limits apply after trimming:\n* kling-3.0: 2500 characters.\n* ltx-2.5: 1804 characters.\n* veo3.1: 2500 characters.\nLTX's dialogue wrapper counts toward its model prompt limit."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"description": "Defaults to 720p on paid plans and 480p on free plans. Unsupported model/resolution combinations and resolutions unavailable for your plan are rejected."
},
"end_seconds": {
"type": "number",
"example": 4,
"minimum": 1,
"description": "Video duration in seconds. Supported values by model:\n* kling-3.0: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 seconds.\n* ltx-2.5: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60 seconds.\n* veo3.1: 4, 6, 8, 15, 22, 29, 36, 43, 50, 57, 64, 71, 78, 85, 92, 99, 106, 113, 120, 127, 134, 141 seconds.\nFree plans are limited to 5 seconds unless a credit pack has been purchased."
}
}
}| string |
| Editing model. Defaults to LTX 2.5 for free tier and `gemini-omni-1.1` for paid. `gemini-omni` is deprecated; use `gemini-omni-1.1` instead. |
| style* | object |
| assets* | object | Provide the assets for video editing. |
| resolution | string | Output resolution. Defaults to `480p` for free tier and `720p` for paid. `gemini-omni-1.1` and deprecated `gemini-omni` support 720p and 1080p; LTX 2.5 supports 480p, 720p, and 1080p. |
| end_seconds* | number | 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. |
| start_seconds | number | Start time of your clip (seconds). Must be ≥ 0. |
{
"type": "object",
"required": [
"end_seconds",
"style",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Video Editor - dateTime",
"example": "My Video Editor video",
"description": "Give your video a custom name for easy identification."
},
"model": {
"enum": [
"gemini-omni-1.1",
"gemini-omni",
"ltx-2.5",
"ltx-2.3"
],
"type": "string",
"example": "ltx-2.5",
"description": "Editing model. Defaults to LTX 2.5 for free tier and `gemini-omni-1.1` for paid. `gemini-omni` is deprecated; use `gemini-omni-1.1` instead."
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"prompt": {
"type": "string",
"example": "Change the car color to blue",
"minLength": 1,
"description": "The prompt used to edit the video."
}
}
},
"assets": {
"type": "object",
"required": [
"video_file_path"
],
"properties": {
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "The video to edit. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for video editing."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"example": "480p",
"description": "Output resolution. Defaults to `480p` for free tier and `720p` for paid. `gemini-omni-1.1` and deprecated `gemini-omni` support 720p and 1080p; LTX 2.5 supports 480p, 720p, and 1080p."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip in seconds. Must be greater than `start_seconds`. Minimum duration depends on model: `gemini-omni-1.1`: 3s, LTX 2.5: 0.5s. Maximum duration depends on model: `gemini-omni-1.1`: 10s, LTX 2.5: 20s."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}| object |
| Source video for the translation job. |
| resolution | string | Output video resolution. Defaults to 480p. 720p and 1080p require a paid plan. |
| end_seconds* | number | End time of your clip (seconds). Must be greater than start_seconds. The clip must be 1-30 seconds long. |
| start_seconds | number | Start time of your clip (seconds). Must be ≥ 0. |
| target_language* | string | Language to translate the video's speech into. |
{
"type": "object",
"required": [
"end_seconds",
"target_language",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Video Translator - dateTime",
"example": "My Video Translator video",
"description": "Give your video a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"video_file_path"
],
"properties": {
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "Source video containing the speech to translate. This value is either\n- a direct URL to the 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"
}
},
"description": "Source video for the translation job."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"example": "480p",
"description": "Output video resolution. Defaults to 480p. 720p and 1080p require a paid plan."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds. The clip must be 1-30 seconds long."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
},
"target_language": {
"enum": [
"English",
"Chinese (Simplified)",
"Hindi",
"Spanish",
"Arabic",
"French",
"Afrikaans",
"Bengali",
"Bulgarian",
"Catalan",
"Croatian",
"Czech",
"Danish",
"Dutch",
"Estonian",
"Finnish",
"German",
"Greek",
"Gujarati",
"Hebrew",
"Hungarian",
"Indonesian",
"Italian",
"Japanese",
"Kannada",
"Kazakh",
"Korean",
"Latvian",
"Lithuanian",
"Malay",
"Malayalam",
"Marathi",
"Norwegian",
"Persian",
"Polish",
"Portuguese",
"Punjabi",
"Romanian",
"Russian",
"Serbian",
"Slovak",
"Slovenian",
"Swahili",
"Swedish",
"Tamil",
"Telugu",
"Thai",
"Chinese (Traditional)",
"Turkish",
"Ukrainian",
"Urdu",
"Vietnamese",
"Welsh"
],
"type": "string",
"example": "Spanish",
"description": "Language to translate the video's speech into."
}
}
}| object |
| Source video for the upscale job. |
| resolution* | string | Output resolution. `720p` and `1080p` set the output's short side, `2k` and `4k` its long side; the aspect ratio is kept. Requires a paid plan. |
| end_seconds* | number | End time of your clip (seconds). Must be greater than start_seconds. |
| start_seconds | number | Start time of your clip (seconds). Must be ≥ 0. |
{
"type": "object",
"required": [
"end_seconds",
"resolution",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Video Upscaler - dateTime",
"example": "My Video Upscaler video",
"description": "Give your video a custom name for easy identification."
},
"assets": {
"type": "object",
"required": [
"video_file_path"
],
"properties": {
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "Video to upscale. This value is either\n- a direct URL to the 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"
}
},
"description": "Source video for the upscale job."
},
"resolution": {
"enum": [
"720p",
"1080p",
"2k",
"4k"
],
"type": "string",
"example": "1080p",
"description": "Output resolution. `720p` and `1080p` set the output's short side, `2k` and `4k` its long side; the aspect ratio is kept. Requires a paid plan."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}| end_seconds* | number | This value determines the duration of the output video. |
{
"type": "object",
"required": [
"fps",
"end_seconds",
"height",
"width",
"style",
"assets"
],
"properties": {
"fps": {
"type": "number",
"example": 12,
"minimum": 1,
"description": "The desire output video frame rate"
},
"name": {
"type": "string",
"default": "Animation - dateTime",
"example": "My Animation video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"art_style",
"camera_effect",
"prompt_type",
"transition_speed"
],
"properties": {
"prompt": {
"type": "string",
"example": "Cyberpunk city",
"description": "The prompt used for the video. Prompt is required if `prompt_type` is `custom`. Otherwise this value is ignored"
},
"art_style": {
"enum": [
"Custom",
"Painterly Illustration",
"Vibrant Matte Illustration",
"Traditional Watercolor",
"Cyberpunk",
"Ink and Watercolor Portrait",
"Intricate Abstract Lines Portrait",
"3D Render",
"Old School Comic",
"Bold Colored Illustration",
"Synthwave",
"Minimal Cold Futurism",
"Futuristic Anime",
"Cinematic Miyazaki",
"Studio Ghibli Film Still",
"Soft Delicate Matte Portrait",
"Cinematic Landscape",
"Landscape Painting",
"Photograph",
"Jackson Pollock",
"Cubist",
"Abstract Minimalist",
"Impressionism",
"Van Gogh",
"Woodcut",
"Oil Painting",
"Vintage Japanese Anime",
"Pixar",
"Cosmic",
"Pixel Art",
"Fantasy",
"Arcane",
"Sin City",
"Double Exposure",
"Painted Cityscape",
"90s Streets",
"Overgrown",
"Postapocalyptic",
"Spooky",
"Miniatures",
"Low Poly",
"Art Deco",
"Inkpunk",
"Dark Graphic Illustration",
"Dark Watercolor",
"Faded Illustration",
"Directed by AI"
],
"type": "string",
"example": "Painterly Illustration",
"description": "The art style used to create the output video"
},
"prompt_type": {
"enum": [
"custom",
"use_lyrics",
"ai_choose"
],
"type": "string",
"example": "custom",
"description": "\n* `custom` - Use your own prompt for the video.\n* `use_lyrics` - Use the lyrics of the audio to create the prompt. If this option is selected, then `assets.audio_source` must be `file` or `youtube`.\n* `ai_choose` - Let AI write the prompt. If this option is selected, then `assets.audio_source` must be `file` or `youtube`."
},
"camera_effect": {
"enum": [
"Simple Zoom Out",
"Simple Zoom In",
"Bounce Out",
"Spin Bounce",
"Rolling Bounces",
"Rise and Climb",
"Dramatic Zoom In",
"Dramatic Zoom Out",
"Sway Out",
"Boost Zoom In",
"Boost Zoom Out",
"Heartbeat",
"Bounce in Place",
"Earthquake Bounce",
"Slice Bounce",
"Bounce In And Out",
"Jump",
"Road Trip",
"Traverse",
"Rubber Band",
"Rodeo",
"Accelerate",
"Speed of Light",
"Drift Spin",
"Vertigo",
"Cog in the Machine",
"Quadrant",
"Tron",
"Pusher",
"Roll In",
"Hesitate In",
"Zoom In - Audio Sync",
"Pulse - Audio Sync",
"Aggressive Zoom In - Audio Sync",
"Roll In - Audio Sync",
"Zoom Out - Audio Sync",
"Aggressive Zoom Out - Audio Sync",
"Sway Out - Audio Sync",
"Bounce and Spin - Audio Sync",
"Zoom In and Spin - Audio Sync",
"Vertigo - Audio Sync",
"Bounce Out - Audio Sync",
"Earthquake Bounce - Audio Sync",
"Pusher - Audio Sync",
"Evolve - Audio Sync",
"Devolve - Audio Sync",
"Slideshow",
"Pan Left",
"Pan Right",
"Tilt Up",
"Tilt Down",
"Directed by AI"
],
"type": "string",
"example": "Simple Zoom In",
"description": "The camera effect used to create the output video"
},
"art_style_custom": {
"type": "string",
"example": "Watercolor painting with soft pastel colors",
"description": "Describe custom art style. This field is required if `art_style` is `Custom`"
},
"transition_speed": {
"type": "integer",
"example": 5,
"maximum": 10,
"minimum": 1,
"description": "Change determines how quickly the video's content changes across frames. \n* Higher = more rapid transitions.\n* Lower = more stable visual experience."
}
},
"description": "Defines the style of the output video"
},
"width": {
"type": "integer",
"example": 512,
"minimum": 64,
"description": "The width of the final output video. The maximum width depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details"
},
"assets": {
"type": "object",
"example": {
"audio_source": "file",
"audio_file_path": "api-assets/id/1234.mp3",
"image_file_path": "api-assets/id/1234.png"
},
"required": [
"audio_source"
],
"properties": {
"youtube_url": {
"type": "string",
"format": "uri",
"minLength": 1,
"description": "Using a youtube video as the input source. This field is required if `audio_source` is `youtube`"
},
"audio_source": {
"enum": [
"none",
"file",
"youtube"
],
"type": "string",
"example": "file",
"description": "Optionally add an audio source if you'd like to incorporate audio into your video"
},
"audio_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"description": "The path of the input audio. This field is required if `audio_source` is `file`. This value is either\n- a direct URL to the 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"
},
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "An initial image to use a the first frame of the video. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for animation."
},
"height": {
"type": "integer",
"example": 512,
"minimum": 64,
"description": "The height of the final output video. The maximum height depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "This value determines the duration of the output video."
}
}
}| object |
| Attributes used to dictate the style of the output |
| assets* | object | Provide the audio file and an optional reference image. |
| resolution | string | Output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers. |
| end_seconds* | number | End time of your clip (seconds). Must be greater than start_seconds. |
| start_seconds | number | Start time of your clip (seconds). Must be ≥ 0. |
{
"type": "object",
"required": [
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Audio To Video - dateTime",
"example": "My Audio To Video video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"example": "Car driving through a city",
"description": "Prompt to guide the visual style of the video."
}
},
"description": "Attributes used to dictate the style of the output"
},
"assets": {
"type": "object",
"required": [
"audio_file_path"
],
"properties": {
"audio_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"description": "The path of the audio file. This value is either\n- a direct URL to the 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"
},
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "Reference image for the initial frame of the video. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the audio file and an optional reference image."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"example": "480p",
"description": "Output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}| start_seconds* | number | Start time of your clip (seconds). Must be ≥ 0. |
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"assets",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Auto Subtitle - dateTime",
"example": "My Auto Subtitle video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"template": {
"enum": [
"karaoke",
"cinematic",
"minimalist",
"highlight"
],
"type": "string",
"example": "karaoke",
"description": "Preset subtitle templates. Please visit https://magichour.ai/create/auto-subtitle-generator to see the style of the existing templates."
},
"custom_config": {
"type": "object",
"properties": {
"font": {
"type": "string",
"example": "Noto Sans",
"description": "Font name from Google Fonts. Not all fonts support all languages or character sets. \nWe recommend verifying language support and appearance directly on https://fonts.google.com before use."
},
"font_size": {
"type": "number",
"example": 24,
"description": "Font size in pixels. If not provided, the font size is automatically calculated based on the video resolution."
},
"font_style": {
"type": "string",
"example": "normal",
"description": "Font style (e.g., normal, italic, bold)"
},
"text_color": {
"type": "string",
"example": "#FFFFFF",
"description": "Primary text color in hex format"
},
"stroke_color": {
"type": "string",
"example": "#000000",
"description": "Stroke (outline) color of the text"
},
"stroke_width": {
"type": "number",
"example": 1,
"description": "Width of the text stroke in pixels. If `stroke_color` is provided, but `stroke_width` is not, the `stroke_width` will be calculated automatically based on the font size."
},
"vertical_position": {
"type": "string",
"example": "bottom",
"description": "Vertical alignment of the text (e.g., top, center, bottom)"
},
"horizontal_position": {
"type": "string",
"example": "center",
"description": "Horizontal alignment of the text (e.g., left, center, right)"
},
"highlighted_text_color": {
"type": "string",
"example": "#FFD700",
"description": "Color used to highlight the current spoken text"
}
},
"description": "Custom subtitle configuration."
}
},
"description": "Style of the subtitle. At least one of `.style.template` or `.style.custom_config` must be provided. \n* If only `.style.template` is provided, default values for the template will be used.\n* If both are provided, the fields in `.style.custom_config` will be used to overwrite the fields in `.style.template`.\n* If only `.style.custom_config` is provided, then all fields in `.style.custom_config` will be used.\n\nTo use custom config only, the following `custom_config` params are required:\n* `.style.custom_config.font`\n* `.style.custom_config.text_color`\n* `.style.custom_config.vertical_position`\n* `.style.custom_config.horizontal_position`\n"
},
"assets": {
"type": "object",
"required": [
"video_file_path"
],
"properties": {
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "This is the video used to add subtitles. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for auto subtitle generator"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}| Source video and reference character image for the job. |
| resolution | string | Output video resolution. Must be supported by `model`. Defaults to the lowest resolution available on your plan for that model. |
| end_seconds* | number | End time of your clip (seconds). Must be greater than start_seconds. |
| start_seconds | number | Start time of your clip (seconds). Must be ≥ 0. |
{
"type": "object",
"required": [
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Character Replace - dateTime",
"example": "My Character Replace video",
"description": "Give your video a custom name for easy identification."
},
"model": {
"enum": [
"wan-animate",
"kling-3.0"
],
"type": "string",
"default": "wan-animate",
"example": "wan-animate",
"description": "Model to use. Defaults to `wan-animate`.\n\n* **`wan-animate`**: 480p, 720p. Supports `points` subject selection.\n* **`kling-3.0`**: 720p, 1080p. Clips of 3–10 seconds in `replace` mode or 3–30 seconds in `animate` mode. Picks the main person automatically, so `points` are rejected."
},
"style": {
"type": "object",
"example": {
"mode": "replace",
"selection_mode": "auto"
},
"properties": {
"mode": {
"enum": [
"replace",
"animate"
],
"type": "string",
"example": "replace",
"description": "Processing mode. `replace` swaps the detected subject with your reference character. `animate` transfers motion from the video onto your character image."
},
"points": {
"type": "array",
"items": {
"type": "object",
"required": [
"position_x",
"position_y",
"time_seconds"
],
"properties": {
"position_x": {
"type": "integer",
"example": 320,
"minimum": 0,
"description": "Horizontal pixel coordinate in the source video frame at `time_seconds`, measured from the left edge."
},
"position_y": {
"type": "integer",
"example": 180,
"minimum": 0,
"description": "Vertical pixel coordinate in the source video frame at `time_seconds`, measured from the top edge."
},
"time_seconds": {
"type": "number",
"format": "float",
"example": 2.5,
"minimum": 0,
"description": "Timestamp on the source video timeline in seconds. Uses the same clock as `start_seconds` and `end_seconds`."
}
}
},
"description": "On-frame markers for manual subject selection. Required when `selection_mode` is `point`. Ignored when `selection_mode` is `auto` or omitted. Rejected for models without subject selection (supported by `wan-animate`)."
},
"selection_mode": {
"enum": [
"auto",
"point"
],
"type": "string",
"example": "auto",
"description": "How to locate the subject in the source video. `auto` detects a person automatically. `point` uses your `points` to mark the subject and is supported by `wan-animate`. Defaults to `auto`."
}
},
"description": "Optional style controls for replace vs animate mode and subject selection."
},
"assets": {
"type": "object",
"required": [
"video_file_path",
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/5678.png",
"minLength": 1,
"description": "Reference character image used as the replacement or animation target. This value is either\n- a direct URL to the 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"
},
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"minLength": 1,
"description": "Source video containing the subject to replace or animate. This value is either\n- a direct URL to the 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"
}
},
"description": "Source video and reference character image for the job."
},
"resolution": {
"enum": [
"480p",
"720p",
"1080p"
],
"type": "string",
"example": "480p",
"description": "Output video resolution. Must be supported by `model`. Defaults to the lowest resolution available on your plan for that model."
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"default": 0,
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}| start_seconds* |
| number |
| Start time of your clip (seconds). Must be ≥ 0. |
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Face Swap - dateTime",
"example": "My Face Swap video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"example": {
"version": "default"
},
"properties": {
"version": {
"enum": [
"v1",
"v2",
"default"
],
"type": "string",
"example": "default",
"description": "* `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."
}
},
"description": "Style of the face swap video."
},
"assets": {
"type": "object",
"example": {
"video_source": "file",
"face_swap_mode": "all-faces",
"image_file_path": "api-assets/id/1234.png",
"video_file_path": "api-assets/id/1234.mp4"
},
"required": [
"video_source"
],
"properties": {
"youtube_url": {
"type": "string",
"format": "uri",
"description": "YouTube URL (required if `video_source` is `youtube`)."
},
"video_source": {
"enum": [
"file",
"youtube"
],
"type": "string",
"example": "file",
"description": "Choose your video source."
},
"face_mappings": {
"type": "array",
"items": {
"type": "object",
"required": [
"original_face",
"new_face"
],
"properties": {
"new_face": {
"type": "string",
"example": "api-assets/id/1234.png",
"description": "The face image that will be used to replace the face in the `original_face`. This value is either\n- a direct URL to the 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"
},
"original_face": {
"type": "string",
"example": "api-assets/id/0-0.png",
"description": "The face detected from the image in `target_file_path`. The file name is in the format of `<face_frame>-<face_index>.png`. This value is corresponds to the response in the [face detection API](https://docs.magichour.ai/api-reference/files/get-face-detection-details).\n\n* The face_frame is the frame number of the face in the target image. For images, the frame number is always 0.\n* The face_index is the index of the face in the target image, starting from 0 going left to right."
}
}
},
"example": [
{
"new_face": "api-assets/id/1234.png",
"original_face": "api-assets/id/0-0.png"
}
],
"maxItems": 5,
"description": "This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`."
},
"face_swap_mode": {
"enum": [
"all-faces",
"individual-faces"
],
"type": "string",
"default": "all-faces",
"example": "all-faces",
"description": "Choose 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`"
},
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"description": "The path of the input image with the face to be swapped. The value is required if `face_swap_mode` is `all-faces`.\n\nThis value is either\n- a direct URL to the 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"
},
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}| model | string | The AI model to use for video generation. * `default`: uses our currently recommended model for general use. For paid tiers, defaults to `kling-3.0`. For free tiers, it defaults to `ltx-2.5`. * `gemini-omni-1.1`: Best for precise short clips, first/last frames, and high-resolution output. * `kling-2.6`: Best for action, motion blur, and controlled camera moves. * `kling-3.0`: Best for cinematic stories, references, and optional audio. * `ltx-2.5`: Fastest for general scenes, long clips, audio, and rapid iteration. * `minimax-h3`: Great for reference-driven clips with native audio and longer durations. * `seedance-1.5`: Best for smooth, consistent motion with an end frame. * `seedance-2.0`: Best for reference-led clips with precise subject control. * `seedance-2.0-fast`: Fast reference-led clips with consistent motion and audio. * `seedance-2.0-mini`: Faster reference-led clips with consistent motion and audio. * `seedance-2.5`: Best for premium realism, detail, and natural motion. * `veo3.1`: Best for romantic interactions and expressive action, with realistic detail. * `veo3.1-lite`: Balanced realism and audio at a lower cost than Veo 3.1. * `wan-2.2`: Best for physical motion, action, and camera movement. * `wan-3.0`: High-quality video with native audio, long clips, and end-frame control. If you specify the deprecated model value that includes the `-audio` suffix, this will be the same as included `audio` as `true`. |
| style | object | Attributed used to dictate the style of the output |
| assets* | object | Provide the assets for image-to-video. |
| resolution | string | Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers. * **`gemini-omni-1.1`**: Supports 360p, 720p, 1080p, 4k. * **`kling-2.6`**: Supports 720p, 1080p. * **`kling-3.0`**: Supports 720p, 1080p, 4k. * **`ltx-2.5`**: Supports 480p, 720p, 1080p. * **`minimax-h3`**: Supports 480p, 720p, 1080p. * **`seedance-1.5`**: Supports 480p, 720p, 1080p. * **`seedance-2.0`**: Supports 480p, 720p, 1080p, 4k. * **`seedance-2.0-fast`**: Supports 480p, 720p. * **`seedance-2.0-mini`**: Supports 480p, 720p. * **`seedance-2.5`**: Supports 480p, 720p, 1080p. * **`veo3.1`**: Supports 720p, 1080p. * **`veo3.1-lite`**: Supports 720p, 1080p. * **`wan-2.2`**: Supports 480p, 720p, 1080p. * **`wan-3.0`**: Supports 480p, 720p, 1080p. |
| end_seconds* | number | The total duration of the output video in seconds. Supported durations depend on the chosen model: * **`gemini-omni-1.1`**: any integer from 3 to 10 * **`kling-2.6`**: 5, 10 * **`kling-3.0`**: any integer from 3 to 15 * **`ltx-2.5`**: any integer from 1 to 60 * **`minimax-h3`**: any integer from 1 to 30 * **`seedance-1.5`**: any integer from 4 to 12 * **`seedance-2.0`**: any integer from 4 to 15 * **`seedance-2.0-fast`**: any integer from 4 to 15 * **`seedance-2.0-mini`**: any integer from 4 to 15 * **`seedance-2.5`**: any integer from 4 to 30 * **`veo3.1`**: 4, 6, 8, 16, 24, 32, 40, 48, 56 * **`veo3.1-lite`**: 4, 6, 8, 16, 24, 32, 40, 48, 56 * **`wan-2.2`**: 3, 4, 5, 6, 7, 8, 9, 10, 15 * **`wan-3.0`**: 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30 |
{
"type": "object",
"required": [
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Image To Video - dateTime",
"example": "My Image To Video video",
"description": "Give your video a custom name for easy identification."
},
"audio": {
"type": "boolean",
"example": true,
"description": "Whether to include audio in the video. Defaults to `false` if not specified.\n\nAudio support varies by model:\n* **`gemini-omni-1.1`**: Not supported\n* **`kling-2.6`**: Not supported\n* **`kling-3.0`**: Toggle-able: audio adds extra credits when enabled\n* **`ltx-2.5`**: Toggle-able: no additional credits for audio\n* **`minimax-h3`**: Toggle-able: no additional credits for audio\n* **`seedance-1.5`**: Toggle-able: audio adds extra credits when enabled\n* **`seedance-2.0`**: Toggle-able: no additional credits for audio\n* **`seedance-2.0-fast`**: Toggle-able: no additional credits for audio\n* **`seedance-2.0-mini`**: Toggle-able: no additional credits for audio\n* **`seedance-2.5`**: Toggle-able: no additional credits for audio\n* **`veo3.1`**: Toggle-able: audio adds extra credits when enabled\n* **`veo3.1-lite`**: Toggle-able: audio adds extra credits when enabled\n* **`wan-2.2`**: Not supported\n* **`wan-3.0`**: Toggle-able: no additional credits for audio\n"
},
"model": {
"enum": [
"default",
"minimax-h3",
"kling-3.0",
"ltx-2.5",
"wan-2.2",
"seedance-2.5",
"wan-3.0",
"seedance-2.0-mini",
"veo3.1",
"veo3.1-lite",
"seedance-2.0",
"kling-2.6",
"gemini-omni-1.1",
"seedance-2.0-fast",
"seedance-1.5",
"sora-2",
"ltx-2.3",
"ltx-2",
"kling-2.5",
"kling-1.6",
"seedance",
"kling-2.5-audio",
"veo3.1-audio"
],
"type": "string",
"default": "default",
"example": "ltx-2.5",
"description": "The 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-fast`: Fast reference-led clips with consistent motion and audio.\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`."
},
"style": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"example": "a dog running",
"description": "The prompt used for the video."
}
},
"description": "Attributed used to dictate the style of the output"
},
"assets": {
"type": "object",
"required": [
"image_file_path"
],
"properties": {
"image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The path of the image file. This value is either\n- a direct URL to the 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"
},
"end_image_file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1,
"description": "The image to use as the last frame of the video.\n\n* **`gemini-omni-1.1`**: Supports 360p, 720p, 1080p, 4k.\n* **`kling-2.6`**: Supports 1080p.\n* **`kling-3.0`**: Supports 720p, 1080p, 4k.\n* **`ltx-2.5`**: Supports 480p, 720p, 1080p.\n* **`minimax-h3`**: Supports 480p, 720p, 1080p.\n* **`seedance-1.5`**: Supports 480p, 720p, 1080p.\n* **`seedance-2.0`**: Supports 480p, 720p, 1080p, 4k.\n* **`seedance-2.0-fast`**: Supports 480p, 720p.\n* **`seedance-2.0-mini`**: Supports 480p, 720p.\n* **`seedance-2.5`**: Supports 480p, 720p, 1080p.\n* **`veo3.1`**: Supports 720p, 1080p. Requires a duration of 8 seconds or less.\n* **`veo3.1-lite`**: Supports 720p, 1080p. Requires a duration of 8 seconds or less.\n* **`wan-2.2`**: Not supported\n* **`wan-3.0`**: Supports 480p, 720p, 1080p.\n"
}
},
"description": "Provide the assets for image-to-video."
},
"resolution": {
"enum": [
"360p",
"480p",
"720p",
"1080p",
"4k"
],
"type": "string",
"example": "480p",
"description": "Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers.\n\n* **`gemini-omni-1.1`**: Supports 360p, 720p, 1080p, 4k.\n* **`kling-2.6`**: Supports 720p, 1080p.\n* **`kling-3.0`**: Supports 720p, 1080p, 4k.\n* **`ltx-2.5`**: Supports 480p, 720p, 1080p.\n* **`minimax-h3`**: Supports 480p, 720p, 1080p.\n* **`seedance-1.5`**: Supports 480p, 720p, 1080p.\n* **`seedance-2.0`**: Supports 480p, 720p, 1080p, 4k.\n* **`seedance-2.0-fast`**: Supports 480p, 720p.\n* **`seedance-2.0-mini`**: Supports 480p, 720p.\n* **`seedance-2.5`**: Supports 480p, 720p, 1080p.\n* **`veo3.1`**: Supports 720p, 1080p.\n* **`veo3.1-lite`**: Supports 720p, 1080p.\n* **`wan-2.2`**: Supports 480p, 720p, 1080p.\n* **`wan-3.0`**: Supports 480p, 720p, 1080p.\n"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"maximum": 60,
"minimum": 1,
"description": "The total duration of the output video in seconds. Supported durations depend on the chosen model:\n\n* **`gemini-omni-1.1`**: any integer from 3 to 10\n* **`kling-2.6`**: 5, 10\n* **`kling-3.0`**: any integer from 3 to 15\n* **`ltx-2.5`**: any integer from 1 to 60\n* **`minimax-h3`**: any integer from 1 to 30\n* **`seedance-1.5`**: any integer from 4 to 12\n* **`seedance-2.0`**: any integer from 4 to 15\n* **`seedance-2.0-fast`**: any integer from 4 to 15\n* **`seedance-2.0-mini`**: any integer from 4 to 15\n* **`seedance-2.5`**: any integer from 4 to 30\n* **`veo3.1`**: 4, 6, 8, 16, 24, 32, 40, 48, 56\n* **`veo3.1-lite`**: 4, 6, 8, 16, 24, 32, 40, 48, 56\n* **`wan-2.2`**: 3, 4, 5, 6, 7, 8, 9, 10, 15\n* **`wan-3.0`**: 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30\n"
}
}
}| max_fps_limit | number | Defines the maximum FPS (frames per second) for the output video. If the input video's FPS is lower than this limit, the output video will retain the input FPS. This is useful for reducing unnecessary frame usage in scenarios where high FPS is not required. |
| start_seconds* | number | Start time of your clip (seconds). Must be ≥ 0. |
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Lip Sync - dateTime",
"example": "My Lip Sync video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"properties": {
"generation_mode": {
"enum": [
"lite",
"standard",
"pro"
],
"type": "string",
"default": "lite",
"example": "lite",
"description": "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. Requires visible mouth movement in the opening seconds of the input video. Costs 1 credit per frame of video.\n* `pro` - Premium fidelity with enhanced detail - best for professionals. Requires visible mouth movement in the opening seconds of the input video. Costs 2 credits per frame of video.\n\nIf your source is a still image, including a still image saved as a static video, use [AI Talking Photo](https://docs.magichour.ai/api-reference/video-projects/ai-talking-photo) with the original image and your audio instead.\n\nNote: `pro` is only available for users on Creator, Pro, and Business tiers.\n "
}
},
"description": "Attributes used to dictate the style of the output"
},
"assets": {
"type": "object",
"example": {
"video_source": "file",
"audio_file_path": "api-assets/id/1234.mp3",
"video_file_path": "api-assets/id/1234.mp4"
},
"required": [
"audio_file_path",
"video_source"
],
"properties": {
"youtube_url": {
"type": "string",
"format": "uri",
"description": "YouTube URL (required if `video_source` is `youtube`)."
},
"video_source": {
"enum": [
"file",
"youtube"
],
"type": "string",
"example": "file",
"description": "Choose your video source."
},
"audio_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp3",
"minLength": 1,
"description": "The path of the audio file. This value is either\n- a direct URL to the 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"
},
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for lip-sync. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"max_fps_limit": {
"type": "number",
"example": 12,
"minimum": 1,
"description": "Defines the maximum FPS (frames per second) for the output video. If the input video's FPS is lower than this limit, the output video will retain the input FPS. This is useful for reducing unnecessary frame usage in scenarios where high FPS is not required."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
}
}
}| style* | object |
| references | array | Reference media for video generation. Name references without @ and refer to them as @name in style.prompt. Maximum 10 references total. Supported models and reference media: * **`gemini-omni-1.1`**: Supports images, videos. Up to 10 references. * **`kling-3.0`**: Supports images, videos. * **`minimax-h3`**: Supports images, videos, audio. * **`seedance-2.0`**: Supports images, videos, audio. * **`seedance-2.0-fast`**: Supports images, videos, audio. * **`seedance-2.0-mini`**: Supports images, videos, audio. * **`seedance-2.5`**: Supports images, videos, audio. * **`veo3.1`**: Supports images. Up to 3 references. Requires `end_seconds` of 8. * **`wan-3.0`**: Supports images, videos, audio. |
| resolution | string | Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers. * **`gemini-omni-1.1`**: Supports 360p, 720p, 1080p, 4k. * **`kling-2.6`**: Supports 720p, 1080p. * **`kling-3.0`**: Supports 720p, 1080p, 4k. * **`ltx-2.5`**: Supports 480p, 720p, 1080p. * **`minimax-h3`**: Supports 480p, 720p, 1080p. * **`seedance-1.5`**: Supports 480p, 720p, 1080p. * **`seedance-2.0`**: Supports 480p, 720p, 1080p, 4k. * **`seedance-2.0-fast`**: Supports 480p, 720p. * **`seedance-2.0-mini`**: Supports 480p, 720p. * **`seedance-2.5`**: Supports 480p, 720p, 1080p. * **`veo3.1`**: Supports 720p, 1080p. * **`veo3.1-lite`**: Supports 720p, 1080p. * **`wan-2.2`**: Supports 480p, 720p, 1080p. * **`wan-3.0`**: Supports 480p, 720p, 1080p. |
| end_seconds* | number | The total duration of the output video in seconds. Supported durations depend on the chosen model: * **`gemini-omni-1.1`**: any integer from 3 to 10 * **`kling-2.6`**: 5, 10 * **`kling-3.0`**: any integer from 3 to 15 * **`ltx-2.5`**: any integer from 1 to 60 * **`minimax-h3`**: any integer from 1 to 30 * **`seedance-1.5`**: any integer from 4 to 12 * **`seedance-2.0`**: any integer from 4 to 15 * **`seedance-2.0-fast`**: any integer from 4 to 15 * **`seedance-2.0-mini`**: any integer from 4 to 15 * **`seedance-2.5`**: any integer from 4 to 30 * **`veo3.1`**: 4, 6, 8, 16, 24, 32, 40, 48, 56 * **`veo3.1-lite`**: 4, 6, 8, 16, 24, 32, 40, 48, 56 * **`wan-2.2`**: 3, 4, 5, 6, 7, 8, 9, 10, 15 * **`wan-3.0`**: 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30 |
| aspect_ratio | string | Provide `aspect_ratio` to set the video’s aspect ratio. Determines the aspect ratio of the output video. * **`gemini-omni-1.1`**: Supports 16:9, 9:16. * **`kling-2.6`**: Supports 9:16, 16:9, 1:1. * **`kling-3.0`**: Supports 9:16, 16:9, 1:1. * **`ltx-2.5`**: Supports 9:16, 16:9, 1:1. * **`minimax-h3`**: Supports 16:9, 9:16, 1:1. * **`seedance-1.5`**: Supports 9:16, 16:9, 1:1. * **`seedance-2.0`**: Supports 9:16, 16:9, 1:1. * **`seedance-2.0-fast`**: Supports 9:16, 16:9, 1:1. * **`seedance-2.0-mini`**: Supports 9:16, 16:9, 1:1. * **`seedance-2.5`**: Supports 9:16, 16:9, 1:1. * **`veo3.1`**: Supports 9:16, 16:9. * **`veo3.1-lite`**: Supports 9:16, 16:9. * **`wan-2.2`**: Supports 9:16, 16:9, 1:1. * **`wan-3.0`**: Supports 16:9, 9:16, 1:1. |
{
"type": "object",
"required": [
"end_seconds",
"style"
],
"properties": {
"name": {
"type": "string",
"default": "Text To Video - dateTime",
"example": "My Text To Video video",
"description": "Give your video a custom name for easy identification."
},
"audio": {
"type": "boolean",
"example": true,
"description": "Whether to include audio in the video. Defaults to `false` if not specified.\n\nAudio support varies by model:\n* **`gemini-omni-1.1`**: Not supported\n* **`kling-2.6`**: Not supported\n* **`kling-3.0`**: Toggle-able: audio adds extra credits when enabled\n* **`ltx-2.5`**: Toggle-able: no additional credits for audio\n* **`minimax-h3`**: Toggle-able: no additional credits for audio\n* **`seedance-1.5`**: Toggle-able: audio adds extra credits when enabled\n* **`seedance-2.0`**: Toggle-able: no additional credits for audio\n* **`seedance-2.0-fast`**: Toggle-able: no additional credits for audio\n* **`seedance-2.0-mini`**: Toggle-able: no additional credits for audio\n* **`seedance-2.5`**: Toggle-able: no additional credits for audio\n* **`veo3.1`**: Toggle-able: audio adds extra credits when enabled\n* **`veo3.1-lite`**: Toggle-able: audio adds extra credits when enabled\n* **`wan-2.2`**: Not supported\n* **`wan-3.0`**: Toggle-able: no additional credits for audio\n"
},
"model": {
"enum": [
"default",
"minimax-h3",
"kling-3.0",
"ltx-2.5",
"wan-2.2",
"seedance-2.5",
"wan-3.0",
"seedance-2.0-mini",
"veo3.1",
"veo3.1-lite",
"seedance-2.0",
"kling-2.6",
"gemini-omni-1.1",
"seedance-2.0-fast",
"seedance-1.5",
"sora-2",
"ltx-2.3",
"ltx-2",
"kling-2.5",
"kling-1.6",
"seedance",
"kling-2.5-audio",
"veo3.1-audio"
],
"type": "string",
"default": "default",
"example": "ltx-2.5",
"description": "The 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-fast`: Fast reference-led clips with consistent motion and audio.\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`."
},
"style": {
"type": "object",
"required": [
"prompt"
],
"properties": {
"prompt": {
"type": "string",
"example": "a dog running",
"maxLength": 20000,
"minLength": 1,
"description": "The prompt used for the video."
}
}
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"file_path"
],
"properties": {
"name": {
"type": "string",
"example": "hero",
"pattern": "^[A-Za-z][\\w-]*$"
},
"file_path": {
"type": "string",
"example": "api-assets/id/1234.png",
"minLength": 1
}
}
},
"maxItems": 10,
"minItems": 1,
"description": "Reference media for video generation. Name references without @ and refer to them as @name in style.prompt. Maximum 10 references total.\n\nSupported models and reference media:\n* **`gemini-omni-1.1`**: Supports images, videos. Up to 10 references.\n* **`kling-3.0`**: Supports images, videos.\n* **`minimax-h3`**: Supports images, videos, audio.\n* **`seedance-2.0`**: Supports images, videos, audio.\n* **`seedance-2.0-fast`**: Supports images, videos, audio.\n* **`seedance-2.0-mini`**: Supports images, videos, audio.\n* **`seedance-2.5`**: Supports images, videos, audio.\n* **`veo3.1`**: Supports images. Up to 3 references. Requires `end_seconds` of 8.\n* **`wan-3.0`**: Supports images, videos, audio."
},
"resolution": {
"enum": [
"360p",
"480p",
"720p",
"1080p",
"4k"
],
"type": "string",
"example": "480p",
"description": "Controls the output video resolution. Defaults to `720p` on paid tiers and `480p` on free tiers.\n\n* **`gemini-omni-1.1`**: Supports 360p, 720p, 1080p, 4k.\n* **`kling-2.6`**: Supports 720p, 1080p.\n* **`kling-3.0`**: Supports 720p, 1080p, 4k.\n* **`ltx-2.5`**: Supports 480p, 720p, 1080p.\n* **`minimax-h3`**: Supports 480p, 720p, 1080p.\n* **`seedance-1.5`**: Supports 480p, 720p, 1080p.\n* **`seedance-2.0`**: Supports 480p, 720p, 1080p, 4k.\n* **`seedance-2.0-fast`**: Supports 480p, 720p.\n* **`seedance-2.0-mini`**: Supports 480p, 720p.\n* **`seedance-2.5`**: Supports 480p, 720p, 1080p.\n* **`veo3.1`**: Supports 720p, 1080p.\n* **`veo3.1-lite`**: Supports 720p, 1080p.\n* **`wan-2.2`**: Supports 480p, 720p, 1080p.\n* **`wan-3.0`**: Supports 480p, 720p, 1080p.\n"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"maximum": 60,
"minimum": 1,
"description": "The total duration of the output video in seconds. Supported durations depend on the chosen model:\n\n* **`gemini-omni-1.1`**: any integer from 3 to 10\n* **`kling-2.6`**: 5, 10\n* **`kling-3.0`**: any integer from 3 to 15\n* **`ltx-2.5`**: any integer from 1 to 60\n* **`minimax-h3`**: any integer from 1 to 30\n* **`seedance-1.5`**: any integer from 4 to 12\n* **`seedance-2.0`**: any integer from 4 to 15\n* **`seedance-2.0-fast`**: any integer from 4 to 15\n* **`seedance-2.0-mini`**: any integer from 4 to 15\n* **`seedance-2.5`**: any integer from 4 to 30\n* **`veo3.1`**: 4, 6, 8, 16, 24, 32, 40, 48, 56\n* **`veo3.1-lite`**: 4, 6, 8, 16, 24, 32, 40, 48, 56\n* **`wan-2.2`**: 3, 4, 5, 6, 7, 8, 9, 10, 15\n* **`wan-3.0`**: 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30\n"
},
"aspect_ratio": {
"enum": [
"16:9",
"9:16",
"1:1"
],
"type": "string",
"example": "16:9",
"description": "Provide `aspect_ratio` to set the video’s aspect ratio. Determines the aspect ratio of the output video.\n\n* **`gemini-omni-1.1`**: Supports 16:9, 9:16.\n* **`kling-2.6`**: Supports 9:16, 16:9, 1:1.\n* **`kling-3.0`**: Supports 9:16, 16:9, 1:1.\n* **`ltx-2.5`**: Supports 9:16, 16:9, 1:1.\n* **`minimax-h3`**: Supports 16:9, 9:16, 1:1.\n* **`seedance-1.5`**: Supports 9:16, 16:9, 1:1.\n* **`seedance-2.0`**: Supports 9:16, 16:9, 1:1.\n* **`seedance-2.0-fast`**: Supports 9:16, 16:9, 1:1.\n* **`seedance-2.0-mini`**: Supports 9:16, 16:9, 1:1.\n* **`seedance-2.5`**: Supports 9:16, 16:9, 1:1.\n* **`veo3.1`**: Supports 9:16, 16:9.\n* **`veo3.1-lite`**: Supports 9:16, 16:9.\n* **`wan-2.2`**: Supports 9:16, 16:9, 1:1.\n* **`wan-3.0`**: Supports 16:9, 9:16, 1:1.\n"
}
}
}| object |
| assets* | object | Provide the assets for video-to-video. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used |
| end_seconds* | number | End time of your clip (seconds). Must be greater than start_seconds. |
| start_seconds* | number | Start time of your clip (seconds). Must be ≥ 0. |
| fps_resolution | string | Determines whether the resulting video will have the same frame per second as the original video, or half. * `FULL` - the result video will have the same FPS as the input video * `HALF` - the result video will have half the FPS as the input video |
{
"type": "object",
"required": [
"start_seconds",
"end_seconds",
"style",
"assets"
],
"properties": {
"name": {
"type": "string",
"default": "Video To Video - dateTime",
"example": "My Video To Video video",
"description": "Give your video a custom name for easy identification."
},
"style": {
"type": "object",
"required": [
"art_style"
],
"properties": {
"model": {
"enum": [
"Dreamshaper",
"Absolute Reality",
"Flat 2D Anime",
"Soft Anime",
"Kaywaii",
"Western Anime",
"3D Anime",
"default"
],
"type": "string",
"default": "default",
"example": "default",
"description": "* `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."
},
"prompt": {
"type": [
"string",
"null"
],
"example": "A cinematic scene with warm lighting",
"description": "The prompt used for the video. Prompt is required if `prompt_type` is `custom` or `append_default`. If `prompt_type` is `default`, then the `prompt` value passed will be ignored."
},
"version": {
"enum": [
"v1",
"v2",
"default"
],
"type": "string",
"default": "default",
"example": "default",
"description": "* `v1` - more detail, closer prompt adherence, and frame-by-frame previews.\n* `v2` - faster, more consistent, and less noisy.\n* `default` - use the selected art style's default version. Some art styles default to v3, which is unavailable through this API. For `Studio Ghibli`, explicitly set `version` to `v2` to use its supported preset."
},
"art_style": {
"enum": [
"Minecraft",
"Watercolor",
"Pixel",
"Retro Sci-Fi",
"Lego",
"Origami",
"Ghost",
"Sub-Zero",
"Studio Ghibli",
"Comic",
"Impressionism",
"Master Chief",
"Solid Snake",
"Street Fighter",
"Hologram",
"GTA",
"Clay",
"Mystique",
"Dragonball Z",
"Mario",
"Samurai",
"Spartan",
"Boba Fett",
"3D Render",
"Airbender",
"Android",
"Anime Warrior",
"Armored Knight",
"Assassin's Creed",
"Avatar",
"Black Spiderman",
"Bold Anime",
"Celestial Skin",
"Chinese Swordsmen",
"Cyberpunk",
"Cypher",
"Dark Fantasy",
"Future Bot",
"Futuristic Fantasy",
"Ghibli Anime",
"Gundam",
"Illustration",
"Ink",
"Ink Poster",
"Jinx",
"Knight",
"Link",
"Marble",
"Mech",
"Naruto",
"Neon Dream",
"No Art Style",
"Oil Painting",
"On Fire",
"Painterly Anime",
"Pixar",
"Power Armor",
"Power Ranger",
"Radiant Anime",
"Realistic Anime",
"Realistic Pixar",
"Retro Anime",
"Samurai Bot",
"Sharp Anime",
"Soft Anime",
"Starfield",
"The Void",
"Tomb Raider",
"Underwater",
"Van Gogh",
"Viking",
"Western Anime",
"Wu Kong",
"Wuxia Anime",
"Zelda"
],
"type": "string",
"example": "Minecraft"
},
"prompt_type": {
"enum": [
"default",
"custom",
"append_default"
],
"type": "string",
"default": "default",
"example": "default",
"description": "* `default` - 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."
}
}
},
"assets": {
"type": "object",
"example": {
"video_source": "file",
"video_file_path": "api-assets/id/1234.mp4"
},
"required": [
"video_source"
],
"properties": {
"youtube_url": {
"type": "string",
"format": "uri",
"description": "YouTube URL (required if `video_source` is `youtube`)."
},
"video_source": {
"enum": [
"file",
"youtube"
],
"type": "string",
"example": "file",
"description": "Choose your video source."
},
"video_file_path": {
"type": "string",
"example": "api-assets/id/1234.mp4",
"description": "Your video file. Required if `video_source` is `file`. This value is either\n- a direct URL to the 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"
}
},
"description": "Provide the assets for video-to-video. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used"
},
"end_seconds": {
"type": "number",
"format": "float",
"example": 5,
"minimum": 0.1,
"description": "End time of your clip (seconds). Must be greater than start_seconds."
},
"start_seconds": {
"type": "number",
"format": "float",
"example": 0,
"minimum": 0,
"description": "Start time of your clip (seconds). Must be ≥ 0."
},
"fps_resolution": {
"enum": [
"FULL",
"HALF"
],
"type": "string",
"default": "HALF",
"example": "HALF",
"description": "Determines whether the resulting video will have the same frame per second as the original video, or half.\n* `FULL` - the result video will have the same FPS as the input video\n* `HALF` - the result video will have half the FPS as the input video"
}
}
}