Clip sản phẩm từ một tấm ảnh

Mục tiêu

Biến một ảnh sản phẩm thành clip dọc ngắn để người bán đăng lên trang sản phẩm hoặc kênh video ngắn.

Trước khi bắt đầu

• Một token ở chế độ execute: báo giá và sản xuất là tool tính phí. Xem bắt đầu nhanh.
• Một ảnh sản phẩm (JPEG, PNG hoặc WebP) mà người bán có quyền sử dụng.

Thứ tự gọi MCP

Giá trị trong ngoặc nhọn là chỗ cần điền. Mỗi thao tác ghi dùng một request_key mới (UUIDv4); chỉ dùng lại key khi thử lại đúng lời gọi đó.

1. get_workspace

   Đọc mã workspace, tên và vai trò của bạn. Server lấy workspace từ token.

   {}

2. list_video_models

   Chọn một model đã sẵn sàng có thể biến ảnh thành video, giữ tên model để tạo dự án.

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

3. create_project

   Tạo dự án: một clip dọc khoảng 10 giây cho sản phẩm này. Giữ 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

   Đăng ký ảnh kèm kích thước và SHA-256. Giữ 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

   Gửi ảnh dạng base64, đúng kích thước đã đăng ký.

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

6. finalize_asset_upload

   Kiểm tra bản tải lên. attach: true thêm ảnh vào danh sách ảnh tham chiếu của dự án.

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

7. read_external_context

   Đọc ngữ cảnh dự án: brief, ảnh đã gắn, schema của storyboard, cùng handle, hash và revision cần gửi lại.

   {
     "project_id": "<project_id>"
   }

8. submit_external_composition

   Gửi storyboard với mã ảnh trong reference_asset_ids. Server kiểm tra miễn phí và trả về 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

   Tạo báo giá; giá được lưu trên báo giá. Dừng ở đây và cho người dùng xem tổng tiền.

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

10. approve_productionChỉ sau khi người dùng đồng ý

    Chỉ sau khi người dùng đồng ý với giá. Sản xuất bắt đầu ngay; không bao giờ gọi hai lần cho cùng một báo giá.

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

11. get_run_progress

    Hỏi tiến độ, mỗi lần chờ lâu hơn, cho đến khi lượt chạy ở trạng thái READY.

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

12. list_available_media

    Đọc clip đã được xác minh. Clip dở dang không phải kết quả cuối.

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

13. prepare_delivery

    Chuẩn bị gói bàn giao cho lượt chạy đã xong.

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

14. issue_deliveryChỉ sau khi người dùng đồng ý

    Chỉ sau khi người dùng đã xem clip và đồng ý. confirmed: true là quyết định của họ.

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

15. get_delivery_download

    Đọc thông tin tải xuống riêng tư của gói đã bàn giao.

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

Người dùng duyệt gì

• Báo giá: agent cho xem tổng tiền và chờ người dùng đồng ý rồi mới gọi approve_production.
• Clip: người dùng xem clip, sau đó agent gọi issue_delivery với confirmed: true.

Kết quả

• Một clip dọc (9:16) dài khoảng 10 giây làm từ ảnh, có trong list_available_media.
• Một gói bàn giao kèm thông tin tải xuống riêng tư.

Lưu ý

• Sản phẩm đứng yên trong khoảng giây đầu; mỗi cảnh chỉ một hành động. agent_preflight liệt kê các điểm chặn trước khi báo giá.
• Khi lời gọi lỗi, làm theo next_action trong lỗi. Sau WRITE_OUTCOME_UNKNOWN, đọc trạng thái trước và không thử lại. Xem mã lỗi.