Magic Hour

AI UGC Ad Generator

ai_ugc_ad_create_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.

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.

Input Schema

Name	Required	Description
`model`	No	Defaults to kling-3.0 on paid plans and ltx-2.5 on free plans.
`assets`	Yes
`script`	Yes	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`	No	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`	Yes	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.

Output Schema

Name	Required	Description	Default
`id`	Yes	Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads.
`credits_charged`	Yes	The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. If video generation fails, credits will be refunded, and this field will be updated to include the refund.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 22, 2026

changedInput schema / properties / script / description

Previous value: -"The words the actor should speak. Character limits apply after trimming:\n* kling-3.0: 2500 characters.\n* ltx-2.5: 1981 characters.\n* veo3.1: 2500 characters.\nLTX's dialogue wrapper counts toward its model prompt limit."New value: +"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."

removedOutput schema / properties / estimated_frame_cost

Removed value: -{
-  "description": "Deprecated: Previously represented the number of frames (original name of our credit system) used for video generation. Use 'credits_charged' instead.\n\nThe amount of frames used to generate the video. If the status is not 'complete', the cost is an estimate and will be adjusted when the video completes.",
-  "type": "integer"
-}

changedOutput schema / required

Previous value: -[
-  "id",
-  "estimated_frame_cost",
-  "credits_charged"
-]New value: +[
+  "id",
+  "credits_charged"
+]

AddedOct 17, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover readOnly=false, destructive=false, openWorld=true; the description adds far more: it is an async job returning `id` and `credits_charged`, it terminates in complete/error/canceled, wait helpers add `exact_download_urls`, signed URLs must keep their query parameters, and unsupported model/resolution/plan combinations are rejected. These are non-obvious operational facts that materially change how an agent invokes the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is useful but the shape is poor: a 'MCP guidance' preamble arrives before the tool's own purpose sentence, and the async behavior is stated twice ('Starts an async video job; returns `id`' in the first bullet, then 'Returns a project ID; poll GET /v1/video-projects/{id}' in the last sentence). Roughly a third of the text is duplicated across the two blocks.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Against a nested-schema, 5-parameter tool with an output schema and partial annotations, the description covers the async lifecycle, the retrieval path, file-input sourcing, image composition prerequisites, and credit charging. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the schema already documents model defaults, script character limits, and per-model duration values. The description adds real value on the highest-risk parameter by explaining that `*_file_path` accepts an existing Magic Hour path or the `file_path` from the upload-URL endpoint, and that hotlinked URLs can fail as raw-byte fetches.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Create a spoken UGC video from a prepared image and script,' and adds the distinguishing constraint that the image must be prepared separately (via the Image Editor API), which separates it from text_to_video, image_to_video, and ai_talking_photo siblings. An agent can route to this tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit alternatives and conditions: it names `wait_for_video_project` and the polling endpoint for finished results, points to the Image Editor API for composing the source image, and tells the agent to use the upload-URL endpoint (rather than a hotlinked URL) when the path source is uncertain. When-to-use versus when-not-to-use is fully specified.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Magic Hour tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?