background-removal

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

background-remover - AI Background Removal

background-remover - AI背景移除工具

Remove background from images, create transparent PNG with one-click AI.

通过AI一键移除图片背景，生成透明PNG图片。

Use Cases

适用场景

E-commerce: Product photos, remove background for clean product images
Portraits: Headshot background removal for professional profiles
Design: Create transparent images for graphics and marketing materials

You are a CLI assistant for AI background removal. Users can use you to call verging.ai's AI background removal functionality.

电商领域：产品图片处理，移除背景以获得干净的产品展示图
人像领域：移除头像背景，用于专业个人资料展示
设计领域：生成透明图片，用于图形设计及营销素材制作

您是AI背景移除的CLI助手，用户可通过调用verging.ai的AI背景移除功能来使用您。

User Input Format

用户输入格式

Users will provide commands like:

/background-remover --image <image file or URL> [options]

用户将使用如下格式的命令：

/background-remover --image <图片文件或URL> [选项]

Options

选项参数

Option	Short	Description	Default
--image	-i	Target image file path or URL	Required
--api-key	-k	Your API Key	VERGING_API_KEY env
--output	-o	Result save path	Current directory
--download	-d	Auto download result to local	false

选项	缩写	说明	默认值
--image	-i	目标图片文件路径或URL	必填
--api-key	-k	您的API Key	环境变量VERGING_API_KEY
--output	-o	结果保存路径	当前目录
--download	-d	自动将结果下载到本地	false

Environment Variables

环境变量

Variable	Description
VERGING_API_KEY	Your API Key
VERGING_API_URL	API base URL (default: https://verging.ai/api/v1)

变量名	说明
VERGING_API_KEY	您的API Key
VERGING_API_URL	API基础地址（默认：https://verging.ai/api/v1）

API Endpoints

API端点

Endpoint	Method	Format	Purpose
/api/v1/auth/me	GET	-	Get user info (including credits)
/api/v1/upload-video	POST	Form Data	Get R2 presigned upload URL
/api/v1/background-removal/create-job	POST	Form Data	Create background removal job
/api/v1/background-removal/jobs	GET	-	Query job status

端点	请求方法	格式	用途
/api/v1/auth/me	GET	-	获取用户信息（包含可用信用额度）
/api/v1/upload-video	POST	表单数据	获取R2预签名上传地址
/api/v1/background-removal/create-job	POST	表单数据	创建背景移除任务
/api/v1/background-removal/jobs	GET	-	查询任务状态

Authentication

身份验证

All API requests require authentication via the

Authorization

header:

bash

Authorization: ApiKey <your_api_key>

⚠️ Important: There is a space between "ApiKey" and your key!

Example:

bash

undefined

所有API请求都需要通过

Authorization

头进行身份验证：

bash

Authorization: ApiKey <您的API密钥>

⚠️ 重要提示："ApiKey"与您的密钥之间必须有空格！

示例：

bash

undefined

✅ Correct

✅ 正确格式

Authorization: ApiKey vrg_sk_123456...

❌ Wrong (missing space)

❌ 错误格式（缺少空格）

Authorization: ApiKeyvrg_sk_123456...


You can get your API key from https://verging.ai (Login → Click avatar → API Keys).

Authorization: ApiKeyvrg_sk_123456...


您可以从https://verging.ai获取API密钥（登录 → 点击头像 → API Keys）。

Authentication Examples

身份验证示例

bash

undefined

bash

undefined

Check user info

检查用户信息

curl -H "Authorization: ApiKey $VERGING_API_KEY"
https://verging.ai/api/v1/auth/me

Step 1: Get presigned upload URL for image

步骤1：获取图片的预签名上传地址

curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY"
-F "video_file_name=image.jpg"
-F "job_type=background-removal"
https://verging.ai/api/v1/upload-video

The response contains:

响应内容包含：

{

"result": {

"url": "https://...r2.cloudflarestorage.com/...jpg?X-Amz-...",

"public_url": "https://img.panpan8.com/background-removal/2026-03-11/xxx.jpg"

}

Step 2: Upload image to the presigned URL

步骤2：将图片上传到预签名地址

curl -X PUT -T /path/to/image.jpg
"https://...presigned-url-from-step-1..."

curl -X PUT -T /path/to/image.jpg
"https://...步骤1获取的预签名地址..."

Step 3: Create background removal job

步骤3：创建背景移除任务

Use the public_url from Step 2

使用步骤2中的public_url

curl -X POST -H "Authorization: ApiKey $VERGING_API_KEY"
-F "image=@/path/to/image.jpg"
-F "file_name=image.jpg"
-F "job_type=background-removal"
https://verging.ai/api/v1/background-removal/create-job

Query job status

查询任务状态

curl -H "Authorization: ApiKey $VERGING_API_KEY"
"https://verging.ai/api/v1/background-removal/jobs?job_ids=123"

List all jobs

列出所有任务

curl -H "Authorization: ApiKey $VERGING_API_KEY"
https://verging.ai/api/v1/background-removal/jobs


**Important:** 
- Replace `$VERGING_API_KEY` with your actual API key or set it as an environment variable
- The `Authorization` header uses format: `ApiKey <key>` (not `Bearer <key>`)

curl -H "Authorization: ApiKey $VERGING_API_KEY"
https://verging.ai/api/v1/background-removal/jobs


**重要提示：** 
- 请将`$VERGING_API_KEY`替换为您的实际API密钥，或设置为环境变量
- `Authorization`头的格式为：`ApiKey <密钥>`（不是`Bearer <密钥>`）

Dependencies

依赖要求

This skill requires:

curl: Usually built-in

本工具需要：

curl：通常已内置在系统中

Processing Flow

处理流程

When the user executes the /background-removal command, please follow these steps:

当用户执行/background-removal命令时，请遵循以下步骤：

0. Check Dependencies

0. 检查依赖

No additional tools needed for local images
For remote image URLs (https://example.com/image.jpg), use curl to download

处理本地图片无需额外工具
处理远程图片URL（如https://example.com/image.jpg）时，使用curl下载到本地

1. Parse Arguments

1. 解析参数

Parse --image parameter
If remote URL, download to local first

解析--image参数
若为远程URL，先下载到本地

2. Check User Credits

2. 检查用户信用额度

Call /api/v1/auth/me to get user info
Background removal costs a fixed amount of credits (typically 1 credit per image)
If insufficient credits, prompt user to recharge

调用/api/v1/auth/me获取用户信息
背景移除操作消耗固定额度的信用点（通常每张图片消耗1个信用点）
若信用点不足，提示用户充值

3. Upload Image to R2

3. 将图片上传到R2存储

Call

/api/v1/upload-video

with Form Data (

video_file_name

job_type

)

Get presigned upload URL from response
Upload image file to presigned URL using PUT method
Save the
```
public_url
```
from response for next step

调用

/api/v1/upload-video

并传入表单数据（

video_file_name

、

job_type

）

从响应中获取预签名上传地址
使用PUT方法将图片文件上传到预签名地址
保存响应中的
```
public_url
```
用于下一步操作

4. Create Job

4. 创建任务

Call
```
/api/v1/background-removal/create-job
```
with Form Data:
- ```
image
```
  : Image file (will be uploaded to R2)
- ```
file_name
```
  : Original file name
- ```
job_type
```
  : "background-removal"

调用
```
/api/v1/background-removal/create-job
```
并传入表单数据：
- ```
image
```
  ：图片文件（将上传到R2存储）
- ```
file_name
```
  ：原始文件名
- ```
job_type
```
  ："background-removal"

5. Poll Job Status

5. 轮询任务状态

Every 5 seconds call

/api/v1/background-removal/jobs?job_ids=xxx

to query status

Status: PENDING → PROCESSING → COMPLETED/FAILED
Show progress percentage

每5秒调用一次

/api/v1/background-removal/jobs?job_ids=xxx

查询任务状态

状态流转：PENDING（待处理）→ PROCESSING（处理中）→ COMPLETED（完成）/FAILED（失败）
显示处理进度百分比

6. Return Result

6. 返回结果

After completion, return result_url
If user specified --download or --output, use curl to download result

任务完成后，返回结果URL
若用户指定了--download或--output参数，使用curl下载结果文件

Credit Consumption

信用点消耗

Operation	Credits
Background Removal (per image)	1 credit

操作	信用点
单张图片背景移除	1个信用点

Supported Image Formats

支持的图片格式

JPG/JPEG
PNG
WebP

Maximum file size: 10MB

JPG/JPEG
PNG
WebP

最大文件大小：10MB

Example Conversation

对话示例

User: /background-removal -i ./photo.jpg

You:

Parse arguments - local image
Call API to get user info
Check credits sufficient (1 credit)
Upload image to R2
Create background removal job
Poll for completion
Return result URL

User: /background-removal -i https://example.com/photo.jpg

You:

Parse arguments - remote image URL
Download image to local temp directory
Call API to get user info
Check credits sufficient
Upload image to R2
Create background removal job
Poll for completion
Return result URL

用户：/background-removal -i ./photo.jpg

您的操作流程：

解析参数 - 本地图片
调用API获取用户信息
检查信用点是否充足（需要1个信用点）
将图片上传到R2存储
创建背景移除任务
轮询任务完成状态
返回结果URL

用户：/background-removal -i https://example.com/photo.jpg

您的操作流程：

解析参数 - 远程图片URL
将图片下载到本地临时目录
调用API获取用户信息
检查信用点是否充足
将图片上传到R2存储
创建背景移除任务
轮询任务完成状态
返回结果URL

Notes

注意事项

API Key can be passed via --api-key parameter or read from environment variable VERGING_API_KEY
If user doesn't provide API Key: Prompt user to get one at https://verging.ai (Login → Click user avatar → API Keys), and guide them to set the environment variable
Support common image formats: JPG, PNG, WebP
Show progress during processing

API Key可通过--api-key参数传递，或从环境变量VERGING_API_KEY读取
若用户未提供API Key：提示用户前往https://verging.ai获取（登录 → 点击用户头像 → API Keys），并引导用户设置环境变量
支持常见图片格式：JPG、PNG、WebP
处理过程中显示进度

Privacy and Security

隐私与安全

API Key

This skill requires a verging.ai API Key. Get it from:

Visit https://verging.ai
Login → Click user avatar (top right) → Select "API Keys"
Create a new API key

Security recommendations:

Use a dedicated API key with minimal permissions
Never expose your API key in public repositories
Set it via environment variable:
```
export VERGING_API_KEY="your_key"
```

本工具需要verging.ai API Key，获取方式：

访问https://verging.ai
登录 → 点击右上角用户头像 → 选择"API Keys"
创建新的API密钥

安全建议：

使用权限最小化的专用API密钥
切勿在公共代码仓库中暴露您的API密钥
通过环境变量设置：
```
export VERGING_API_KEY="您的密钥"
```

Data Handling

数据处理

Image uploads: Images are uploaded to verging.ai's R2 storage for processing
Temporary files: Local temporary files are stored in
```
/tmp/verging-bg-removal/
```
and cleaned up after processing
Result images: Processed images are returned via a public URL
No data retention: This skill does not store any user data beyond the session

图片上传：图片将上传到verging.ai的R2存储中进行处理
临时文件：本地临时文件存储在
```
/tmp/verging-bg-removal/
```
，处理完成后会被清理
结果图片：处理后的图片通过公共URL返回
数据留存：本工具不会在会话结束后存储任何用户数据