Magic Hour

by ai.magichour.mcp

image_projects_retrieve_details

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

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 image project. This value is returned by all of the POST APIs that create an image.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads.
`name`	Yes	The name of the image.
`type`	Yes	The type of the image project. Possible values are FACE_EDITOR, AI_IMAGE_EDITOR, AI_SELFIE, AI_HEADSHOT, AI_INFLUENCER, AI_IMAGE, AI_MEME, CLOTHES_CHANGER, BACKGROUND_REMOVER, FACE_SWAP, IMAGE_UPSCALER, IMAGE_ENHANCER, AI_GIF, QR_CODE, PHOTO_EDITOR, PHOTO_COLORIZER, HEAD_SWAP, BODY_SWAP, STORYBOARD, IMAGE_EXPANDER
`error`	Yes	In the case of an error, this object will contain the error encountered during video render
`status`	Yes	The status of the image. - `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 `image.started` webhook event fires when rendering begins - `complete` - the job finished successfully; fires `image.completed` - `error` - the job failed during processing; fires `image.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
`image_count`	Yes	Number of images generated
`credits_charged`	Yes	The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. If an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund.

TDQS

A4.4/5.0

Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so well. It explains the status lifecycle, when `downloads` is populated, and warns that returned URLs are already signed and must not be altered. This goes far beyond a generic 'retrieve details' statement.

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 well-structured and front-loaded: a one-sentence purpose, a compact status list, and direct MCP guidance. Every sentence earns its place, and the critical URL-handling warning is included without padding.

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

Completeness4/5

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

The description is complete enough for a simple one-parameter polling tool, covering statuses, the `downloads` field, and error handling. A slight gap is not naming the likely alternative `wait_for_image_project` for agents deciding between polling and waiting, but this is a minor omission.

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?

Schema coverage is 100%, so the schema fully documents the `id` parameter as the unique ID returned by create APIs. The description adds workflow context ('use after a create tool') but no new parameter-level semantics beyond what the schema already provides.

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 description begins with a specific verb and resource: 'Check the progress of a image project.' It clearly distinguishes this retrieval/polling tool from the many create_* siblings by focusing on status and downloads. The status list and MCP guidance make the purpose unmistakable.

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 description gives explicit guidance to use this after a create tool to poll job status and what to do on `complete` vs `error`. It provides clear context for when to call it, though it does not explicitly contrast with sibling `wait_for_image_project` or say when not to use it.

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?