A Python CLI skill for Cutout.Pro visual APIs — background removal, face cutout, and photo enhancement. Supports file upload & image URL input.

Call Cutout.Pro visual processing APIs to perform background removal, face cutout, and photo enhancement. Supports both file upload and image URL input, retu...

Security Scan

The skill mostly does what it claims (calls Cutout.Pro APIs) but the package metadata and instructions are inconsistent about required environment variables and a few setup notes; review the API‑key handling, output file writes, and privacy implications before installing.

Purpose & Capability

The name/description and the code match: the CLI calls Cutout.Pro endpoints for background removal, face cutout, and enhancement. However, the published manifest lists no required environment variables while the code and README/SKILL.md expect a CUTOUT_API_KEY (and references CUTOUT_MAX_IMAGES_PER_DAY in docs). The missing declaration of the API key in the skill metadata is an incoherence.

Instruction Scope

SKILL.md and the scripts limit actions to: reading a local image file or providing an image URL to Cutout.Pro, calling the Cutout.Pro endpoints, and saving outputs/metadata into data/outputs/. The runtime instructions do not ask the agent to read unrelated system files or send data to unexpected external endpoints (all network calls go to https://www.cutout.pro).

Install Mechanism

No install script is provided; this is instruction+scripts only. The only declared dependency is the widely used 'requests' library in requirements.txt. There are no downloads from arbitrary URLs or archive extraction steps in the manifest.

Credentials

The code requires a Cutout.Pro API key (CUTOUT_API_KEY) accessed from the environment or a .env file, but the skill metadata declares no required env vars. The docs also mention a CUTOUT_MAX_IMAGES_PER_DAY variable that is not present in the provided code. This mismatch could confuse users and automated permission systems; an explicit required-env declaration for CUTOUT_API_KEY is missing and should be present.

Persistence & Privilege

The skill does not request 'always: true' and does not modify other skills or system-wide settings. It writes outputs and metadata under its own data/outputs directory only, which is expected for a CLI tool.

What to consider before installing

What to check before installing: - This skill requires a Cutout.Pro API key (CUTOUT_API_KEY). The published metadata omits that requirement — confirm the platform will prompt for or protect that secret before use. - The tool will write processed images and .meta.json files into data/outputs/ (metadata includes original image path/URL and parameters). If you process sensitive images or facial data, be aware of local storage and privacy implications. - Network traffic goes to https://www.cutout.pro only. If you do not trust that service, do not provide your API key or images. - The README/SKILL.md mentions CUTOUT_MAX_IMAGES_PER_DAY but the provided code does not implement it — treat that doc entry as stale. - If you want stricter assurance: review the full (untruncated) scripts/cutout.py to confirm there are no hidden endpoints or unexpected behaviors, and verify .env handling (ensure .env is not accidentally committed and that the key is not being printed or logged). - Recommended mitigation: only provide a limited key or account with minimal credits, and test with non-sensitive images first.

Cutout.Pro Visual API — Image Processing Toolkit

Overview

Access three core image processing capabilities via the Cutout.Pro REST API:

1. Background Remover — Automatically detects the foreground, removes the background, and returns a transparent PNG
2. Face Cutout — Precisely segments the face and hair region, with support for 68-point facial landmark detection
3. Photo Enhancer — AI super-resolution enhancement that transforms blurry, low-quality photos into high-definition images

When to Use This Skill

• When the user needs to remove an image background
• When the user needs to extract a face or avatar region
• When the user needs to improve photo clarity or resolution
• When the user mentions "background removal", "cutout", "portrait segmentation", or related topics
• When the user mentions "image enhancement", "super resolution", "photo restoration", or related topics

Do Not Use This Skill When

• The task is unrelated to image processing
• The user needs to generate a new image (not process an existing one)
• The user needs video processing (use another tool)

How It Works

Images are processed by the Cutout.Pro API using AI. Each call consumes credits (standard: 1 credit/image; preview mode: 0.25 credits/image).

API Comparison

Use Case	Recommended API
Remove background from products, people, or animals	Background Remover
Extract face/hair region for avatars	Face Cutout
Turn a blurry photo into HD	Photo Enhancer
Super-resolution for anime/cartoon images	Photo Enhancer (faceModel=anime)
Get facial landmark coordinates	Face Cutout (faceAnalysis=true)

Quick Start

1. Go to https://www.cutout.pro/user/secret-key to get your API Key
2. Add it to your .env file: CUTOUT_API_KEY=your_key_here
3. Install dependencies: pip install -r scripts/requirements.txt
4. Run the script: python scripts/cutout.py --api bg-remover --image photo.jpg

See references/setup-guide.md for full setup instructions.

1. Operation Modes

CLI Argument	Function	Endpoint
--api bg-remover	Background removal (file upload, binary response)	/api/v1/matting?mattingType=6
--api bg-remover --base64	Background removal (file upload, Base64 response)	/api/v1/matting2?mattingType=6
--api bg-remover --url	Background removal (image URL, Base64 response)	/api/v1/mattingByUrl?mattingType=6
--api face-cutout	Face cutout (file upload, binary response)	/api/v1/matting?mattingType=3
--api face-cutout --base64	Face cutout (file upload, Base64 response)	/api/v1/matting2?mattingType=3
--api face-cutout --url	Face cutout (image URL, Base64 response)	/api/v1/mattingByUrl?mattingType=3
--api photo-enhancer	Photo enhancement (file upload, binary response)	/api/v1/photoEnhance
--api photo-enhancer --base64	Photo enhancement (file upload, Base64 response)	/api/v1/photoEnhance2
--api photo-enhancer --url	Photo enhancement (image URL, Base64 response)	/api/v1/photoEnhanceByUrl

2. Usage Examples

# Background removal — upload file, save as PNG
python scripts/cutout.py --api bg-remover --image product.jpg --output out.png

# Background removal — pass image URL, get Base64
python scripts/cutout.py --api bg-remover --url "https://example.com/photo.jpg"

# Background removal — crop whitespace, add white background
python scripts/cutout.py --api bg-remover --image photo.jpg --crop --bgcolor FFFFFF

# Face cutout — upload file, save as PNG
python scripts/cutout.py --api face-cutout --image portrait.jpg --output face.png

# Face cutout — get Base64 + 68 facial landmarks
python scripts/cutout.py --api face-cutout --image portrait.jpg --base64 --face-analysis

# Photo enhancement — upload file, save HD image
python scripts/cutout.py --api photo-enhancer --image blurry.jpg --output hd.png

# Photo enhancement — anime/cartoon super-resolution
python scripts/cutout.py --api photo-enhancer --image anime.jpg --face-model anime

# Preview mode (0.25 credits, max 500×500)
python scripts/cutout.py --api bg-remover --image photo.jpg --preview

3. Parameters

Parameter	Description	Default
--api	Select API: bg-remover, face-cutout, photo-enhancer	Required
--image	Local image file path	—
--url	Image URL (replaces --image in URL mode)	—
--output	Output file path	data/outputs/
--base64	Return Base64 JSON instead of binary stream	false
--crop	Crop whitespace (bg-remover/face-cutout only)	false
--bgcolor	Background color, hex (e.g. FFFFFF) or blur	—
--preview	Preview mode, max 500×500, costs 0.25 credits	false
--output-format	Output format: png, webp, jpg_75, etc.	png
--face-analysis	Return facial landmarks (face-cutout --base64 only)	false
--face-model	Enhancement model: quality or anime (photo-enhancer only)	quality

4. Output

Images are saved to data/outputs/ with the naming pattern: {api}_{timestamp}.png

Metadata is saved in a .meta.json file containing: API type, parameters, processing time, and file size.

Integration with Other Tools

• Image editing: Use background removal first, then composite a new background
• Avatar generation: Face cutout → crop → generate avatar
• Photo restoration: Photo enhancement → background removal → composite

Limits & Quotas

• Supported formats: PNG, JPG, JPEG, BMP, WEBP
• Maximum resolution: 4096×4096 pixels
• Maximum file size: 15 MB
• QPS limit: up to 5 concurrent requests per second
• Credit cost: 1 credit/image (standard), 0.25 credits/image (preview mode)

File Reference

File	Purpose
references/setup-guide.md	Initial setup, API Key retrieval, troubleshooting
references/api-reference.md	Full API docs, parameters, response formats, error codes
scripts/cutout.py	Main script
scripts/config.py	Configuration management (API Key, endpoints, limits)
scripts/requirements.txt	Python dependencies