Magic Hour

by ai.magichour.mcp

video_projects_retrieve_details

Check the progress of a video project. The downloads field is populated after a successful render.

Statuses

queued — waiting to start
rendering — in progress
complete — ready; see downloads
error — a failure occurred (see error)
canceled — user canceled
draft — not used

MCP guidance:

Use this after a create tool to poll job status. When status is complete, surface the downloads URLs to the user; if status is error, surface the error message.
Each downloads[n].url is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append expires_at onto the URL string.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes	Unique ID of the video project. This value is returned by all of the POST APIs that create a video.

Output Schema

TableJSON Schema

Name	Required	Description
`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.
`fps`	Yes	Frame rate of the video. If the status is not 'complete', the frame rate is an estimate and will be adjusted when the video completes.
`name`	Yes	The name of the video.
`type`	Yes	The type of the video project. Possible values are ANIMATION, AUTO_SUBTITLE, VIDEO_TO_VIDEO, FACE_SWAP, TEXT_TO_VIDEO, IMAGE_TO_VIDEO, LIP_SYNC, TALKING_PHOTO, AVATAR, VIDEO_UPSCALER, VIDEO_EDITOR, CHARACTER_REPLACE, VIDEO_COLORIZER, VIDEO_TRANSLATOR, MUSIC_VIDEO, EXTEND, AUDIO_TO_VIDEO, VIDEO_EXPANDER, UGC_AD
`error`	Yes	In the case of an error, this object will contain the error encountered during video render
`width`	Yes	The width of the final output video. A value of -1 indicates the width can be ignored.
`height`	Yes	The height of the final output video. A value of -1 indicates the height can be ignored.
`status`	Yes	The status of the video. - `draft` - the project was created but has not been submitted for rendering - `queued` - the job is waiting for an available server - `rendering` - the job is being processed; the `video.started` webhook event fires when rendering begins - `complete` - the job finished successfully; fires `video.completed` - `error` - the job failed during processing; fires `video.errored` - `canceled` - the job was manually canceled (for example from the Magic Hour web app) Note: `rendering`, `complete`, and `error` have matching webhook events; `canceled` does not - a canceled job emits no webhook event, so poll this endpoint to detect cancellation.
`enabled`	Yes	Whether this resource is active. If false, it is deleted.
`downloads`	Yes
`created_at`	Yes
`end_seconds`	Yes	End time of your clip (seconds). Must be greater than start_seconds.
`start_seconds`	Yes	Start time of your clip (seconds). Must be ≥ 0.
`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.

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It details the complete status vocabulary, states that `downloads` only appears after a successful render, and warns that each URL is a full signed URL that must be used exactly as returned. This exceeds a generic read-tool description, though it omits details like permissions or the shape of the `error` object.

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

Conciseness5/5

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

The description is front-loaded with the core action, then structured with a status list and two guidance bullets. Every element earns its place: statuses enable agent branching, and the URL-handling caution prevents a concrete failure mode. No filler or redundant information.

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?

Given an output schema exists and only one well-documented parameter is needed, the description covers everything necessary to invoke the tool and act on the result: what to poll, what statuses are possible, and how to interpret the `downloads` field. No external assumptions are required.

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

Parameters3/5

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

The single parameter `id` is already fully described in the schema: 'Unique ID of the video project. This value is returned by all of the POST APIs that create a video.' The description only indirectly references it through 'after a create tool', adding no new semantic detail. With 100% schema coverage, baseline 3 is appropriate.

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?

The opening sentence 'Check the progress of a video project' uses a specific verb and resource, immediately signaling this is a status-retrieval tool. The note about the `downloads` field being populated after a successful render further distinguishes it from creation tools and from sibling retrieve_details tools for other resource types.

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

Usage Guidelines4/5

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

The MCP guidance explicitly says 'Use this after a create tool to poll job status' and provides clear instructions for handling terminal statuses ('surface the downloads URLs to the user; if status is error, surface the error message'). It does not explicitly name alternatives or exclusions, such as when to prefer wait_for_video_project, so it stops short of a 5.

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

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.9/5.0

Disambiguation3/5

Most tools are differentiated by product-specific prefixes (e.g., lip_sync, text_to_video, image_upscaler), but the set contains many overlapping create_image/create_video tools, and generic editors like ai_image_editor_create_image and ai_video_editor_create_video blur boundaries with their more specific counterparts. Face/body swapping tools also occupy a similar conceptual space, requiring careful description reading to avoid misselection.

Naming Consistency4/5

Names generally follow a descriptive snake_case pattern of feature plus action (e.g., text_to_video_create_video, image_projects_delete, wait_for_image_project). Minor inconsistencies like ai_face_editor_edit_image versus the dominant create_image suffix, and the mixed ai_ prefix usage across tools, prevent a perfect score.

Tool Count2/5

44 tools is a large surface for an MCP server, even for a broad media-generation API. The count exceeds the 25+ threshold and creates a heavy selection burden, especially with over a dozen create tools for images and videos.

Completeness4/5

The surface covers the full create-to-download workflow for image, video, and audio: creation, status polling, wait helpers, fetch helpers, delete, and asset upload support. Minor gaps include no list/cancel endpoints and no general project search, but agents can complete core tasks without dead ends.

Resources

Need Help?