Magic Hour

head_swap_create_image

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.

MCP guidance:

This starts an async image generation job and returns id plus credits_charged immediately. If the user wants the finished result, call the wait_for_image_project helper with the returned id, or poll the matching GET /v1/image-projects/{id} endpoint until status is complete, error, or canceled. Completed projects include downloads with direct URLs. The custom wait helper also returns exact_download_urls separately from expiration metadata.
For *_file_path values, prefer an existing Magic Hour file path or a file_path returned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returned file_path.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	No	Give your image a custom name for easy identification.	Head Swap - dateTime
`assets`	Yes	Provide the body and head images for head swap
`max_resolution`	No	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.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`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.
`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.2/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does an excellent job: it discloses the 10-credit cost, async job behavior, immediate return of id and credits_charged, subscription-dependent resolution, clamping behavior, download URL availability, and caveats about hotlinked URLs. This is far beyond the minimum.

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 dense but appropriately sized for an async tool with nontrivial input requirements. It front-loads the core operation and cost, then organizes workflow guidance in a clear 'MCP guidance' block. Every sentence adds useful information and nothing feels redundant or filler.

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 the tool's complexity, the description covers everything an agent needs to call it correctly: async result retrieval, cost, file input constraints, resolution behavior, and download URLs. The presence of an output schema means the description need not enumerate return fields, and it still provides enough context to complete the full workflow.

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?

The input schema already documents all parameters at 100% coverage, which sets the baseline at 3. The description adds meaningful extra guidance beyond the schema, especially around preferring Magic Hour file paths, using the presigned upload flow, warning that hotlinked URLs can fail, and clarifying the credit cost tied to image generation.

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

Purpose4/5

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

The description clearly states the operation: swapping a head onto a body image, with the verb 'Swap' and the specific resource. However, it does not differentiate this tool from closely related siblings like body_swap_create_image or face_swap_photo_create_image, so it stops just short of the highest clarity score.

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

Usage Guidelines3/5

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

The description provides strong workflow guidance: it explains the async nature, how to retrieve results via wait_for_image_project or polling, and how to handle file paths. However, it never explicitly says when to choose this tool over alternatives or when not to use it, so the selection guidance is implied rather than explicit.

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?