Product clip from one photo

Goal

Turn one product photo into a short vertical clip a seller can post on a product page or a short-video channel.

Before you start

• A token in execute mode: quotes and production are paid tools. See the quickstart.
• One product photo (JPEG, PNG or WebP) that the seller has the rights to use.

MCP calls, in order

Values in angle brackets are placeholders. Every write gets its own new request_key (a UUIDv4); reuse a key only to retry the identical call.

1. get_workspace

   Read the workspace id, its name and your role. The server takes the workspace from the token.

   {}

2. list_video_models

   Pick a ready model that turns an image into video, and keep its name for the project.

   {
     "workspace_id": "<workspace_id from get_workspace>"
   }

3. create_project

   Create the project: a vertical clip of about 10 seconds for this product. Keep project_id.

   {
     "workspace_id": "<workspace_id from get_workspace>",
     "title": "<product name> clip",
     "product": "<product name>",
     "brief": "<one sentence: who it is for and what to show>",
     "duration": 10,
     "ratio": "9:16",
     "video_model": "<image-to-video model from list_video_models>",
     "request_key": "<new UUIDv4>"
   }

4. create_asset_upload_intent

   Register the photo with its size and SHA-256. Keep asset_id.

   {
     "project_id": "<project_id>",
     "filename": "product.jpg",
     "mime": "image/jpeg",
     "size": 482113,
     "sha256": "<sha256 of the file>",
     "request_key": "<new UUIDv4>"
   }

5. upload_asset_content

   Send the photo as base64, exactly the registered size.

   {
     "project_id": "<project_id>",
     "asset_id": "<asset_id>",
     "content_base64": "<file as base64>",
     "request_key": "<new UUIDv4>"
   }

6. finalize_asset_upload

   Check the upload. attach: true adds the photo to the project’s references.

   {
     "project_id": "<project_id>",
     "asset_id": "<asset_id>",
     "attach": true,
     "request_key": "<new UUIDv4>"
   }

7. read_external_context

   Read the project context: the brief, the attached photo, the storyboard schema, and the handle, hash and revisions to send back.

   {
     "project_id": "<project_id>"
   }

8. submit_external_composition

   Submit the storyboard with the photo’s id in reference_asset_ids. The server checks it for free and returns composition_id.

   {
     "project_id": "<project_id>",
     "expected_project_revision": "<project revision from the context>",
     "expected_composition_revision": "<composition revision from the context>",
     "context_handle": "<context_handle>",
     "context_hash": "<context_hash>",
     "composition": {
       "shots": [
         {
           "reference_asset_ids": [
             "<asset_id>"
           ],
           "...": "<fields from the schema in the context>"
         }
       ]
     },
     "client_task_id": "<your task id>",
     "request_key": "<new UUIDv4>"
   }

9. create_quote

   Create the quote; the price is stored on it. Stop here and show the person the total.

   {
     "project_id": "<project_id>",
     "composition_id": "<composition_id>",
     "candidates": 1,
     "request_key": "<new UUIDv4>"
   }

10. approve_productionOnly after the person says yes

    Only after the person agrees to the price. Production starts at once; never call it twice for the same quote.

    {
      "project_id": "<project_id>",
      "quote_id": "<quote_id>",
      "expected_content_hash": "<content_hash from the quote>",
      "request_key": "<new UUIDv4>"
    }

11. get_run_progress

    Poll with a growing wait until the run is READY.

    {
      "project_id": "<project_id>",
      "run_id": "<run_id from approve_production>"
    }

12. list_available_media

    Read the verified clip. Partial clips are not final output.

    {
      "project_id": "<project_id>",
      "run_id": "<run_id from approve_production>"
    }

13. prepare_delivery

    Prepare the delivery package for the ready run.

    {
      "project_id": "<project_id>",
      "run_id": "<run_id from approve_production>",
      "request_key": "<new UUIDv4>"
    }

14. issue_deliveryOnly after the person says yes

    Only after the person has watched the clip and said yes. confirmed: true is their decision.

    {
      "project_id": "<project_id>",
      "run_id": "<run_id from approve_production>",
      "confirmed": true,
      "request_key": "<new UUIDv4>"
    }

15. get_delivery_download

    Read the private download details of the issued delivery.

    {
      "project_id": "<project_id>",
      "delivery_id": "<delivery_id>",
      "request_key": "<new UUIDv4>"
    }

What the person approves

• The quote: the agent shows the total and waits for a yes before approve_production.
• The clip: the person watches it, then the agent calls issue_delivery with confirmed: true.

Expected output

• One vertical clip (9:16) of about 10 seconds made from the photo, listed by list_available_media.
• An issued delivery with its private download details.

Good to know

• The product holds still for about the first second; plan one action per shot. agent_preflight lists blockers before you quote.
• When a call fails, follow next_action in the error. After WRITE_OUTCOME_UNKNOWN, read the state first and do not retry. See error codes.