SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbyted-kickart-saliency-segmenter

byted-kickart-saliency-segmenter

Design & creation

View repository

Updated 10-15 17:30

About this skill

Smart Matting SKILL

📋 Tool Description

Core Features

Performs matting from a specified image file.

Available Commands

Command Feature Description
python3.12 ./scripts/plan.py Package Query Query the user's current Ark Claw package
python3.12 ./scripts/upload.py --file <图片路径> Image Upload Upload a local image file to obtain the media asset ID
python3.12 ./scripts/segment.py --media-ids <媒资ID列表> Batch Image Matting Supports concurrent matting of multiple images; separate multiple media asset IDs with commas

🚨 Mandatory Pre-check Process (must be executed in order; if any check fails, terminate the process immediately)

All user requests must first complete the following 3 verification steps; they must not be skipped:

1. Volcano Authentication Verification

  • Execute the environment variable check command: 
    echo "ACCESS_KEY_ID: $ACCESS_KEY_ID" && echo "SECRET_ACCESS_KEY: $SECRET_ACCESS_KEY"
  • Determine the authentication result:
    • Authentication passed：ACCESS_KEY_ID and SECRET_ACCESS_KEY are both non-empty values → Authentication passed
    • Authentication failed: Execute the following guidance plan

❌ Guidance Plan When Authentication Is Not Configured

  1. Guide the user to send the ACCESS_KEY_ID/SECRET_ACCESS_KEY content directly in the chat:

    Please provide your Volcano account AK&SK, used to check whether the Volcano Creation Agent has an activated package and available creation points

  2. After receiving the ACCESS_KEY_ID/SECRET_ACCESS_KEY sent by the user, execute the configuration command: 
    export ACCESS_KEY_ID=用户提供的ACCESS_KEY_ID值
export SECRET_ACCESS_KEY=用户提供的SECRET_ACCESS_KEY值
  3. After configuration is complete, inform the user:

    AK&SK temporary configuration has been completed. The current configuration is effective only for this session and will not be persistently stored. Please use it with confidence

  4. During all subsequent related script executions, it will automatically pass throughexportSpecify these two environment variables to ensure normal authentication, without requiring the user to configure them repeatedly

2. Package Validity Verification

  • Step 1: Python version verification 
    python3.12 --version || (echo "❌ Python 3.12+ 未安装，请先安装Python 3.12" && exit 1)
  • Step 2: Dependency package installation verification 
    python3.12 -m pip install -r ./scripts/requirements.txt
  • Step 3: Execute the package query command 
    python3.12 -m ./scripts/plan.py
  • Step 4: Result processing logic
    • ✅ Package valid: The message field in the returned result is the validity deadline (Beijing time); verification passed
    • ❌ Package expired：message is less than or equal to the current time; guide the user to activate a package and terminate the process
    • ❌ API call error: Refer to the "Error Handling Specification" to match the error code, clearly inform the user of the error cause and solution, and terminate the process

3. Skill Version Verification

  • Step 1: Execute the version check command 
    python3.12 -m ./scripts/upgrade.py
  • Step 2: Parse the returned result Return format example: 
    {"code":"0","message":"success","data":"{\"install_command\":\"\",\"latest_version\":\"1.0.0\",\"latest_version_number\":100000000,\"update_message\":\"\"}"}
    • latest_version: Latest version number (e.g. "1.0.0")
    • install_command: New version installation instruction
  • Step 3: Version comparison logic
    • ✅ Current version >= Latest version: Version verification passed; continue the subsequent process
    • ⚠️ Current version < Latest version: Execute the following update inquiry process
      1. Ask the user whether to update to the latest version:

        A new version of the skill was detected: {latest_version}. Update? (Yes/No)

      2. User confirms update (Yes): execute install_command install the new version
      3. User does not update (No): skip the update and continue with the subsequent process

🛠️ Image matting execution process

Complete process overview

用户请求 → 强制前置校验 → 用户提供图片 → 图片抠图 → 结果返回

Prerequisites

  1. Ensure the output directory exists:mkdir -p /tmp/openclaw/byted-kickart-saliency-segmenter/output
  2. Generate a unique output file name:segment_<timestamp>_<random>.json

Execution steps

  1. Step 0: Mandatory pre-checks(Must be executed in order; if any check fails, terminate the process immediately)

    • Execute all verification steps in the "🚨 Mandatory pre-check process"
    • ✅ Volcano authentication verification passed
    • ✅ Package validity verification passed
    • ✅ Skill version verification passed
    • Only after all checks pass can you proceed to the next step

  2. Step 1: Image upload guidance

    • Ask the user: "Please first provide the image to be intelligently matted: you can send me an image TOS link, or upload a JPEG/PNG/WEBP file (≤8MB), or upload a ZIP archive containing images; batch processing of multiple images is supported"
    • Three upload methods are supported:
      • Local file: directly provide the absolute path of the local image file (e.g., /Users/user/image1.jpg,/Users/user/image2.jpg）
      • Public URL: provide a directly accessible image link (e.g., https://example.com/image1.jpg,https://example.com/image2.jpg）
      • ZIP archive: provide the path or URL of a ZIP file containing images (e.g., /Users/user/images.zip）
    • Batch upload is supported; separate multiple file paths or URLs with commas

  3. Step 2: Image preprocessing

    • Determine the file type: check whether the user provided an image file, a list of images, or a ZIP archive
    • ZIP extraction processing(if it is a ZIP file): 
      mkdir -p /tmp/openclaw/byted-kickart-saliency-segmenter/input
unzip -o "<ZIP文件路径>" -d /tmp/openclaw/byted-kickart-saliency-segmenter/input/extracted/
    • Image download processing(if it is a public URL): 
      mkdir -p /tmp/openclaw/byted-kickart-saliency-segmenter/input
curl -L -o /tmp/openclaw/byted-kickart-saliency-segmenter/input/downloaded_image_<index>.jpg "<图片URL>"
    • Collect all image files: traverse the input directory and collect all images in JPEG/PNG/WEBP format
    • Check file validity：
      • Check whether each file exists:ls -la "<图片路径>"
      • Check whether the file type is a valid image:file "<图片路径>" | grep -qE "image" && echo "valid" || echo "invalid"
    • If any file does not exist or its type is invalid,terminate the process and prompt the user：

      The file is unavailable. Please check whether the path is correct, or confirm that the file is in a valid image format (JPEG/PNG/WEBP)

  4. Step 3: Upload images to obtain media asset information

    • Traverse all images and execute python3.12 ./scripts/upload.py --file <图片路径> command in sequence
    • Collect all media asset IDs
    • Returned field description:
      Field Type Description
      id string Media asset ID (unique identifier)
      url string Image access URL

  5. Step 4: Call the tool for batch image matting

    • Execute the batch matting command:

      python3.12 ./scripts/segment.py --media-ids <媒资ID1>,<媒资ID2>,<媒资ID3>

    • Parameter description:

      Parameter Type Description
      --media-ids string The list of media asset IDs obtained in step 3, separated by commas

    • Execution flow:

      1. Call the ICCP service to concurrently submit multiple matting tasks
      2. Concurrently poll the status of all tasks (query once every 30 seconds, up to 5 minutes)
      3. Aggregate the results of all tasks

    • Return result description (JSON format):

      {
  "code": "0",
  "message": "success",
  "data": {
    "total_count": 3,
    "success_count": 2,
    "failed_count": 1,
    "results": [
      {
        "media_id": "<媒资ID1>",
        "success": true,
        "data": "<抠图结果数据1>"
      },
      {
        "media_id": "<媒资ID2>",
        "success": false,
        "error": "错误信息"
      }
    ]
  }
}

Agent execution special requirements

  1. Timeout setting: When calling the exec tool to start the script, set yieldMs to ≥180000ms (3 minutes)
  2. Friendly prompt: If the script does not return a result immediately, first reply to the user: "We are analyzing your video for you. The task may take a long time to execute. Please wait a moment~"
  3. Exception handling: If the script exits due to timeout/exception, immediately use the persisted Task ID to call the task query API to confirm the backend status. Do not directly determine that the task has failed

📝 User display message template

Single image upload success template:

📤 图片上传成功！

🆔 媒资ID: {media_id}
🔗 图片URL: [点击查看]({url})
📊 分辨率: {width}x{height}

Batch image upload success template:

📤 批量图片上传成功！

共上传 {count} 张图片，媒资ID列表：
{media_id_list}

Single image matting success template:

✨ 智能抠图成功！

🎯 主体图片：[点击预览]({subject_url})
🎭 蒙版图片：[点击预览]({mask_url})

📂 文件空间路径：
- 主体图片：media/outbound/{task_id}/subject.png
- 蒙版图片：media/outbound/{task_id}/mask.png

Batch image matting success template:

✨ 批量智能抠图完成！

📊 处理结果：
- 总数：{total_count} 张
- 成功：{success_count} 张
- 失败：{failed_count} 张

{success_results}

{failed_results}

Batch matting success result list (each item):

✅ 图片 {index}：
   🎯 主体：[点击预览]({subject_url})
   🎭 蒙版：[点击预览]({mask_url})
   📂 文件路径：media/outbound/{task_id}/

Batch matting failure result list (each item):

❌ 图片 {index}：{error_code} - {error_message}
💡 处理建议：{suggestion}

Failed result handling description: For failed images, match the corresponding error code in the "Error Handling Specification" according to the error code, and display the complete error description and user handling suggestions. Example:

  • Error code 1402: Display "Insufficient Creative Points", handling suggestion "Please go to the Creative Points recharge page to recharge Creative Points or upgrade your plan"
  • Error code 1501: Display "User plan expired", handling suggestion "Please go to the Plan activation page to activate a plan"
  • Error code 1411: Display "Input resolution error", handling suggestion "Please check whether the material resolution meets the specification requirements (e.g. ≥480p)"
  • Other errors: Display the original error information, handling suggestion "Please retry later. If the problem persists, please contact Volcano Technical Support"

⚠️ Error handling specification

All errors must clearly inform the cause and provide actionable solutions. Vague prompts are prohibited!!!

Error code Error description Detailed description User handling suggestion
0 No return value The API call succeeded, but the service returned an empty result Please retry later. If the problem persists, please contact Volcano Technical Support
1400 ParamErr parameter error Parameter error Contact technical support
1402 Insufficient Creative Points When calling the API, the user account's Creative Points balance is insufficient Please go to the Creative Points recharge page to recharge Creative Points or upgrade your plan
1410 Service ID does not exist When calling the API, the input parameters contain a non-existent service ID
1411 Input resolution error When calling the API, the image or video resolution in the input parameters does not meet the requirements Please check whether the material resolution meets the specification requirements (e.g. ≥480p)
1412 Image format error When calling the interface, the input parameters contained an unsupported image format Please check whether the image format is a supported format such as jpg or png
1413 Invalid media URL error When calling the interface, the input parameters contained an invalid media URL Please check whether the URL you provided is correct and avoid special characters or formatting errors
1414 Input contains sensitive information error When calling the interface, the input parameters contained sensitive information, such as personal privacy data Marketing videos with people cannot be generated for now. Please wait for a future version update
1415 Output contains sensitive information error When calling the interface, the service returned results that contained sensitive information, such as personal privacy data Marketing videos with people cannot be generated for now. Please wait for a future version update
1416 Input media quantity error The amount of material input by the user exceeds the limit The number of media materials provided exceeds the limit; the excess materials may not be used
1417 Large model call error Model call error, usually due to incorrect input parameters There is a problem with media material processing. Please try again. If the problem persists, please contact Volcano technical support
1418 Duration billing parameter error There is a problem with the input parameter time at submission The required finished video duration does not meet the skill requirements. Please submit the production request according to the 0-60s duration limit. If the problem persists, please contact Volcano technical support
1501 User package expired When calling the interface, the user package has expired Please go to Package activation page to activate a package
100010 Signature verification failed AK/SK signature verification failed Please check whether the Volcano authentication AK/SK you provided is correct. You can visitVolcano Engine Consoleto confirm
100013 Missing service permission Missing the RegisterArkClawCombo permission for the iccloud_muse service Your enterprise account has not activated Kickart permissions. Please contact the Volcano main account administrator to activate it for you, or consult Volcano technical support for details
x01001 AK/SK not configured The user has not configured AK/SK Please enter the Volcano authentication AK/SK. You can visitVolcano Engine Consoleto obtain
x01010 Valid package missing An error occurred during material upload, usually due to the package Please go to Package activation page to activate a package
A0101 Session metadata format error The Session metadata format passed to the interface is incorrect Please try again later. If the problem persists, please contact Volcano technical support
1600 Task does not exist When querying the task status, the specified task ID does not exist Please confirm whether the task ID is correct, or the task may have been deleted
Other - Other error cases not explicitly listed Please try again later. If the problem persists, please contact Volcano technical support