Pixly

Cinematic Motion

cinematic_motion

Photo to video: turn a single listing photo into a short cinematic real estate video with a professional camera move (zoom, orbit, fly-through, crane up…). No second frame needed. Costs credits from the user's Pixly balance.

Input Schema

Name	Required	Description	Default
`format`	No	Video shape. original (default) keeps the photo's own shape; 9:16 or 16:9 crop the photo, centred, to that shape before it is animated.	original
`r2Path`	No	Storage path of a photo already in the user's Pixly library (from list_library, or returned by an upload ticket) — the alternative to imageUrl.
`imageUrl`	No	Public https URL of the source photo, or a data: URI. Either imageUrl or r2Path is required.
`direction`	No	The direction the camera travels, for the moves that have one (orbit, pan, drone-orbit). 'left-to-right' sends the camera rightward, 'right-to-left' leftward. Ignored by every other move; omit to use the move's own default.
`listingId`	No	A property folder (from list_listings or create_listing) to put the result in. Results of a photo that is already in a folder go there by themselves.
`cameraMove`	No	Camera-move preset	zoom
`durationSeconds`	No	Clip length in seconds. Leave out for the default 5 s; 10 s costs about twice as much — use it only when the user asks for a longer video.

Output Schema

Name	Required	Description
`jobs`	No	Several jobs at once (get_job with jobIds, or a plan's steps): each one's jobId, status and results
`note`	No
`type`	No
`error`	No
`jobId`	Yes	Pass to get_job to poll
`quote`	No	Present when status is "awaiting_confirmation": nothing ran and nothing was charged yet — the price and settings the user is asked to confirm
`status`	Yes	pending \| processing \| completed \| failed — anything not completed/failed is still running
`createdAt`	No
`resultUrls`	No	Present when completed; valid 7 days
`completedAt`	No
`resultPaths`	No	Storage path of each result — pass one as r2Path (or beforeR2Path, a photos[] item) to run another tool on this result
`creditsCharged`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 11, 2026

addedInput schema / properties / listingId

Added value: +{
+  "description": "A property folder (from list_listings or create_listing) to put the result in. Results of a photo that is already in a folder go there by themselves.",
+  "type": "string"
+}

addedOutput schema / properties / jobs

Added value: +{
+  "description": "Several jobs at once (get_job with jobIds, or a plan's steps): each one's jobId, status and results",
+  "items": {
+    "type": "object"
+  },
+  "type": "array"
+}

Changed3 schema fields changedOct 7, 2026

changedInput schema / properties / format / default
```
Previous value: -"9:16"New value: +"original"
```

changedInput schema / properties / format / description

Previous value: -"Aspect ratio"New value: +"Video shape. original (default) keeps the photo's own shape; 9:16 or 16:9 crop the photo, centred, to that shape before it is animated."

changedInput schema / properties / format / enum

Previous value: -[
-  "9:16",
-  "16:9"
-]New value: +[
+  "original",
+  "9:16",
+  "16:9"
+]

Changed2 schema fields changedOct 6, 2026

changedInput schema / properties / durationSeconds / description

Previous value: -"Clip length; the routed model validates its supported tiers"New value: +"Clip length in seconds. Leave out for the default 5 s; 10 s costs about twice as much — use it only when the user asks for a longer video."

addedOutput schema / properties / quote

Added value: +{
+  "description": "Present when status is \"awaiting_confirmation\": nothing ran and nothing was charged yet — the price and settings the user is asked to confirm",
+  "type": "object"
+}

Changed1 schema field changedOct 2, 2026

addedOutput schema / properties / resultPaths

Added value: +{
+  "description": "Storage path of each result — pass one as r2Path (or beforeR2Path, a photos[] item) to run another tool on this result",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedSep 23, 2026

changedInput schema / properties / r2Path / description

Previous value: -"R2 object path from an upload ticket (the create_upload_ticket tool, or POST /api/v1/uploads over REST) — the alternative to imageUrl when the photo is a local file."New value: +"Storage path of a photo already in the user's Pixly library (from list_library, or returned by an upload ticket) — the alternative to imageUrl."

Changed1 schema field changedSep 21, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "completedAt": {
+      "type": "string"
+    },
+    "createdAt": {
+      "type": "string"
+    },
+    "creditsCharged": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "error": {
+      "type": "string"
+    },
+    "jobId": {
+      "description": "Pass to get_job to poll",
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "resultUrls": {
+      "description": "Present when completed; valid 7 days",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "status": {
+      "description": "pending | processing | completed | failed — anything not completed/failed is still running",
+      "type": "string"
+    },
+    "type": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "jobId",
+    "status"
+  ],
+  "type": "object"
+}

Changed1 schema field changedSep 20, 2026

changedInput schema / properties / r2Path / description

Previous value: -"R2 object path from an upload ticket (POST /api/v1/uploads) — the alternative to imageUrl when the photo is a local file."New value: +"R2 object path from an upload ticket (the create_upload_ticket tool, or POST /api/v1/uploads over REST) — the alternative to imageUrl when the photo is a local file."

Changed1 schema field changedAug 14, 2026

changedInput schema / properties / direction / description

Previous value: -"Horizontal direction, for the moves that have one (currently 'pan'). Ignored by every other move; omit for the default."New value: +"The direction the camera travels, for the moves that have one (orbit, pan, drone-orbit). 'left-to-right' sends the camera rightward, 'right-to-left' leftward. Ignored by every other move; omit to use the move's own default."

Changed1 schema field changedAug 14, 2026

addedInput schema / properties / direction

Added value: +{
+  "description": "Horizontal direction, for the moves that have one (currently 'pan'). Ignored by every other move; omit for the default.",
+  "enum": [
+    "left-to-right",
+    "right-to-left"
+  ],
+  "type": "string"
+}

First observedAug 12, 2026

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the write/non-repeatable nature is known. The description adds one genuinely useful non-annotation fact — that the call consumes credits from the user's Pixly balance — but says nothing about synchronous vs. job-based execution even though a get_job sibling exists.

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

Conciseness4/5

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

Two tight sentences that lead with the transformation and the key differentiator (single photo, no second frame), then append the cost note. No filler, though the parenthetical example list is slightly redundant with the enum.

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?

With output schema present, return values need no explanation, and the cost warning plus the single-image constraint cover most agent needs. The one real gap is execution model — whether the result is immediate or must be polled via get_job — for a tool annotated as non-idempotent and open-world.

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 description coverage is 100%, so the schema already documents format, direction, listingId, duration and the imageUrl/r2Path choice, making 3 the baseline. The description only echoes the camera-move family ("zoom, orbit, fly-through, crane up"), adding no syntax or constraint detail beyond the schema.

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?

Specific verb+resource: turns one listing photo into a short cinematic video via a named camera move, with example moves matching the cameraMove enum. The phrase "No second frame needed" implicitly separates it from the before/after tools, but it never names or differentiates itself from the closest siblings photo_to_video and flythrough_video.

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?

"No second frame needed" gives implied guidance that this is the single-image path versus the before/after siblings, and the durationSeconds text states when to pick 10 s ("only when the user asks for a longer video"). However, nothing tells the agent when to choose this over photo_to_video or flythrough_video, which is the actual ambiguity among siblings.

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

All Pixly 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?