Back to Details

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

选项参数

OptionShortDescriptionDefault
--image-iTarget image file path or URLRequired
--api-key-kYour API KeyVERGING_API_KEY env
--output-oResult save pathCurrent directory
--download-dAuto download result to localfalse
选项缩写说明默认值
--image-i目标图片文件路径或URL必填
--api-key-k您的API Key环境变量VERGING_API_KEY
--output-o结果保存路径当前目录
--download-d自动将结果下载到本地false

Environment Variables

环境变量

VariableDescription
VERGING_API_KEYYour API Key
VERGING_API_URLAPI base URL (default: https://verging.ai/api/v1)
变量名说明
VERGING_API_KEY您的API Key
VERGING_API_URLAPI基础地址（默认：https://verging.ai/api/v1）

API Endpoints

API端点

EndpointMethodFormatPurpose
/api/v1/auth/meGET-Get user info (including credits)
/api/v1/upload-videoPOSTForm DataGet R2 presigned upload URL
/api/v1/background-removal/create-jobPOSTForm DataCreate background removal job
/api/v1/background-removal/jobsGET-Query job status
端点请求方法格式用途
/api/v1/auth/meGET-获取用户信息（包含可用信用额度）
/api/v1/upload-videoPOST表单数据获取R2预签名上传地址
/api/v1/background-removal/create-jobPOST表单数据创建背景移除任务
/api/v1/background-removal/jobsGET-查询任务状态

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...
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
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
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": {

"result": {

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

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

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

"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
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"
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. 检查依赖

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

信用点消耗

OperationCredits
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:
  1. Parse arguments - local image
  2. Call API to get user info
  3. Check credits sufficient (1 credit)
  4. Upload image to R2
  5. Create background removal job
  6. Poll for completion
  7. Return result URL
User: /background-removal -i https://example.com/photo.jpg
You:
  1. Parse arguments - remote image URL
  2. Download image to local temp directory
  3. Call API to get user info
  4. Check credits sufficient
  5. Upload image to R2
  6. Create background removal job
  7. Poll for completion
  8. Return result URL
用户：/background-removal -i ./photo.jpg
您的操作流程：
  1. 解析参数 - 本地图片
  2. 调用API获取用户信息
  3. 检查信用点是否充足（需要1个信用点）
  4. 将图片上传到R2存储
  5. 创建背景移除任务
  6. 轮询任务完成状态
  7. 返回结果URL
用户：/background-removal -i https://example.com/photo.jpg
您的操作流程：
  1. 解析参数 - 远程图片URL
  2. 将图片下载到本地临时目录
  3. 调用API获取用户信息
  4. 检查信用点是否充足
  5. 将图片上传到R2存储
  6. 创建背景移除任务
  7. 轮询任务完成状态
  8. 返回结果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

API Key

This skill requires a verging.ai API Key. Get it from:
  1. Visit https://verging.ai
  2. Login → Click user avatar (top right) → Select "API Keys"
  3. 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，获取方式：
  1. 访问https://verging.ai
  2. 登录 → 点击右上角用户头像 → 选择"API Keys"
  3. 创建新的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返回
  • 数据留存：本工具不会在会话结束后存储任何用户数据