SKILL.md
background-removal - AI Background Removal
Remove image backgrounds with AI via verging.ai. Returns transparent PNG.
Command Format
/background-removal --image <image file or URL> [options]Options
| Option | Short | Description | Default |
|---|---|---|---|
| --image | -i | Image file path or URL | Required |
| --api-key | -k | API Key | $VERGINGAPIKEY |
| --output | -o | Save path for result | Current directory |
| --download | -d | Auto download result | false |
Authentication
Recommended: Authorization: ApiKey <your_key>
# ✅ Recommended (canonical form)
curl -H "Authorization: ApiKey vrg_sk_your_key_here" https://verging.ai/api/v1/auth/me
# ✅ Also works (Bearer with API key is supported)
curl -H "Authorization: Bearer vrg_sk_your_key_here" https://verging.ai/api/v1/auth/meGet your API key: https://verging.ai → Login → Avatar → API Keys
API Reference (Exact Formats)
1. Check Credits
curl -H "Authorization: ApiKey $VERGING_API_KEY" \
https://verging.ai/api/v1/auth/meResponse: {"email":"...","name":"...","credits":100}
2. Create Background Removal Job (Multipart with file — direct upload)
# ⚠️ image is a FILE upload (@path) — server handles R2 upload internally
# ⚠️ You do NOT need to use /upload-video separately for background removal
curl -X POST https://verging.ai/api/v1/background-removal/create-job \
-H "Authorization: ApiKey $VERGING_API_KEY" \
-F "image=@/tmp/verging-bg-removal/photo.jpg" \
-F "file_name=photo.jpg" \
-F "job_type=background-removal"Response: {"code":10000,"result":{"job_id":"456"},"message":{"en":"Request Success","zh":"提交任务成功"}}
3. Poll Job Status
curl -H "Authorization: ApiKey $VERGING_API_KEY" \
"https://verging.ai/api/v1/background-removal/jobs?job_ids=456"Response: [{"id":456,"status":"COMPLETED","progress":100,"resulturl":"https://...","imageurl":"https://...","createdat":"...","updatedat":"..."}]
Status values: PENDING → PROCESSING → COMPLETED (or FAILED)
Execution Flow (Follow Exactly)
- Parse args → extract image path/URL
- Download remote image (if URL):
curl -L -o /tmp/verging-bg-removal/photo.jpg "URL" - Validate → check file exists, format is JPG/PNG/WebP, size < 10MB
- Check credits → GET /api/v1/auth/me (needs 1 credit)
- Create job → POST /background-removal/create-job (Multipart with
image=@path— server uploads to R2 internally, no separate upload step needed) - Poll status → GET /background-removal/jobs?job_ids=X every 5 seconds until COMPLETED
- Return/download result → show result_url, optionally curl download
Critical Notes
- Use
Authorization: ApiKey <key>(recommended) —Bearer <key>also works - No separate upload step needed — create-job handles R2 upload internally when you provide
image=@path imagemust be a file upload (@path) — NOT a URL string- Cost: 1 credit per image (fixed)
- Supported formats: JPG, PNG, WebP (max 10MB)
- Temp directory:
/tmp/verging-bg-removal/
Privacy & Security
- Set key via env:
export VERGINGAPIKEY="your_key" - Never expose API key in public repos
- Temp files cleaned up after use