API 文档

通过我们的 REST API 以编程方式转换图片。

概览

基础 URL： https://www.bulkpicconv.com/api/v1

认证方式：通过 Authorization 请求头传递 Bearer 令牌

API 密钥格式： sk_ 前缀 + 48 位字母数字字符

速率限制：Team 50,000次/月，Enterprise 无限制

最大上传大小：每文件 15 MB

最大图片尺寸：8000万像素（如 8000×10000）

支持的输入格式：JPEG、PNG、WebP、GIF、BMP、TIFF、HEIC

API 访问权限：Team 和 Enterprise 计划（从控制台生成密钥）

端点

方法	端点	描述
POST	`/api/v1/convert`	转换和压缩图片
POST	`/api/v1/resize`	调整图片大小
POST	`/api/v1/crop`	裁剪图片
POST	`/api/v1/watermark`	为图片添加水印
POST	`/api/v1/optimize`	智能优化（不转换格式）
POST	`/api/v2/batch`	批量转换 ZIP 图片包（异步）
GET	`/api/v2/batch/{id}/status`	查询批量任务状态
GET	`/api/v2/batch/{id}/result`	下载批量结果 ZIP
GET	`/api/v2/usage`	查询 API 密钥月度用量
GET	`/api/v2/credits`	查询可用 API 额度
POST	`/v1/ai/alt-text`	AI 生成替代文本（Pro/Team）
POST	`/v1/ai/rename`	AI 批量重命名（Pro/Team）
POST	`/v1/ai/smart-crop`	AI 智能裁剪检测（Pro/Team）
POST	`/v1/ai/enhance`	AI 图片增强（Pro/Team）
POST	`/v1/ai/recommend`	AI 格式推荐（Pro/Team）
POST	`/api/background-remove`	移除图片背景
GET/PUT/DEL	`/api/user/ai-key`	BYOK 模型配置管理

POST/v1/convert

将图片转换并压缩为 WebP、AVIF、JPEG 或 PNG。

参数（multipart/form-data）

字段	类型	必填	描述
image	file	是	要转换的图片文件
format	string	否	webp、avif、jpeg、png（默认：webp）
quality	number	否	1-100（默认：75）
width	number	否	输出宽度（保持宽高比）
height	number	否	输出高度
fit	string	否	cover、contain、fill、inside、outside
grayscale	boolean	否	转换为灰度图
blur	number	否	模糊半径（0.3-100）
rotate	number	否	旋转角度（0-360）

响应

二进制图片数据，包含以下响应头：

Content-Type : 图片格式 MIME 类型
Content-Disposition : 附件形式返回，含文件名（如 converted.webp）
X-Input-Size : 原始大小（字节）
X-Output-Size : 转换后大小（字节）
X-Saved-Percent : 节省空间百分比
X-RateLimit-Limit : 月度 API 调用上限
X-RateLimit-Remaining : 本月剩余 API 调用次数

POST/api/v1/resize

在保持宽高比的情况下调整图片大小。

参数（multipart/form-data）

Field	Type	Required	Description
image	file	是	图片文件
width	number	是	目标宽度（1-10000）
height	number	是	目标高度（1-10000）
fit	string	否	cover/contain/fill/inside/outside（默认：inside）

POST/api/v1/crop

从图片中提取一个矩形区域。

参数（multipart/form-data）

Field	Type	Required	Description
image	file	是	图片文件
x	number	是	水平偏移量（左上角）
y	number	是	垂直偏移量（左上角）
width	number	是	裁剪区域宽度
height	number	是	裁剪区域高度

POST/api/v1/watermark

在可配置位置叠加水印图片。

参数（multipart/form-data）

Field	Type	Required	Description
image	file	是	底图
watermark	file	是	水印图片
position	string	否	top-left/top-right/bottom-left/bottom-right/center
opacity	number	否	0-100（默认：100）
scale	number	否	水印大小占底图宽度的比例（0.01-1）

POST/api/v1/optimize

重新编码图片以减小文件大小，不改变格式。

参数（multipart/form-data）

Field	Type	Required	Description
image	file	是	图片文件
quality	number	否	1-100（默认：75）。保留原始格式。

POST/api/v2/batch

上传 ZIP 图片包进行异步批量转换。返回任务 ID；轮询状态直至完成。

参数（multipart/form-data）

字段	类型	必填	描述
file	file	是	图片 ZIP 压缩包
format	string	否	webp、avif、jpeg、png（默认：webp）
quality	number	否	1-100（默认：75）

GET /api/v2/batch/{id}/status — 轮询任务状态（排队中 → 处理中 → 已完成）
GET /api/v2/batch/{id}/result — 下载结果 ZIP

AI 功能 Pro / Team

基于 GPT-4o Vision 的 AI 图片分析。所有 AI 端点接受包含 Base64 数据 URI 的 JSON 请求体。支持 BYOK（自带密钥）— 使用您自己的 OpenAI 兼容模型，免费无限访问。

POST/v1/ai/alt-text

Generate SEO-friendly alt text with keywords using GPT-4o Vision.

请求体（application/json）

Field	Type	Required	Description
images	string[]	是	Base64 data URIs (1-10 images)
language	string	否	en/zh/es/fr/de/ja/ko/pt/it (default: en)
style	string	否	descriptive/concise/seo (default: descriptive)
userProvider	object	否	BYOK config (see below)

POST/v1/ai/rename

Generate SEO-friendly filenames based on image content.

请求体（application/json）

Field	Type	Required	Description
images	object[]	是	{data, originalName} (1-20 images)
rules	object	否	{prefix, includeSequence, style}
userProvider	object	否	BYOK config

POST/v1/ai/smart-crop

Detect subject and generate platform-specific crop recommendations.

请求体（application/json）

Field	Type	Required	Description
image	string	是	Base64 data URI
platforms	string[]	否	instagram-square/twitter/facebook/youtube-thumbnail/etc.
customRatio	object	否	{width, height}
returnCroppedImage	boolean	否	Return cropped result (default: false)
userProvider	object	否	BYOK config

POST/v1/ai/enhance

Upscale, denoise, or deblur images.

请求体（application/json）

Field	Type	Required	Description
image	string	是	Base64 data URI
mode	string	否	upscale/denoise/deblur/auto (default: auto)
intensity	number	否	1=Light, 2=Medium, 3=Strong (default: 2)
returnPreview	boolean	否	Return enhanced image (default: true)

POST/v1/ai/recommend

Deep analysis to recommend optimal format, quality, and compression.

请求体（application/json）

Field	Type	Required	Description
images	object[]	是	{data, filename, width, height, fileSize, mimeType} (1-20)
useCase	string	否	web/ecommerce/social-media/print/archive/general
userProvider	object	否	BYOK config

BYOK：userProvider 对象（可选）

在任何 AI 请求中包含此对象以使用您自己的模型。跳过 Pro 检查和每日配额。

字段	类型	必填	描述
baseUrl	string	是	OpenAI 兼容 API 基础 URL
model	string	是	视觉模型名称
apiKey	string	†	API 密钥（本地模式，随请求发送）
useAccountKey	boolean	†	使用账户保存的加密密钥

† apiKey 或 useAccountKey 二选一必填。

背景移除

POST/api/background-remove

移除图片背景。使用 remove.bg API，并以 sharp 作为备选。月度配额限制（由管理员配置）。

参数（multipart/form-data）

字段	类型	必填	描述
image	file	是	图片文件（最大 10 MB）
format	string	否	输出格式：png（默认）、webp

账户管理

GETPUTDELETE/api/user/ai-key

管理保存的 BYOK 模型配置（使用 AES-256-GCM 加密）。

GET — 获取已保存配置（密钥仅显示掩码，如 sk-12****abcd）
PUT — 保存/更新配置（请求体：baseUrl、model、apiKey）。返回掩码密钥。
DELETE — 删除已保存配置（不可恢复）

错误响应

所有错误均以 JSON 返回 { "statusCode": 4xx, "statusMessage": "..." }

代码	错误	描述
400	`missing_form_data`	请求体必须为 multipart/form-data
400	`missing_image_file`	表单数据中未找到图片文件（字段名："image"）
400	`file_too_large`	文件超过 15 MB 上传限制
400	`invalid_image_type`	文件不是有效的图片
400	`invalid_image`	图片已损坏或无法读取
400	`image_too_large`	图片超过 8000万像素
400	`invalid_params`	参数值无效（详见 issues 字段）
401	`missing_or_invalid_api_key`	Authorization 请求头缺失或格式错误
401	`invalid_or_revoked_api_key`	API 密钥未找到或已被撤销
401	`api_access_not_available`	您的计划不包含 API 访问权限（仅限 Team/Enterprise）
429	`rate_limited`	请求过于频繁（突发限制：30次/分钟）
429	`monthly_limit_exceeded`	月度 API 调用额度已用尽
500	`conversion_failed`	服务器端图片处理错误
AI 功能错误
403	`ai_access_denied`	需要 Pro/Team 计划（或 BYOK 模式：需要登录）
429	`ai_daily_limit_exceeded`	每日 AI 配额已用尽（仅限平台模式；BYOK 无限制）
503	`ai_service_unavailable`	AI 服务未在服务器上配置
403	`no_saved_ai_key`	BYOK：useAccountKey=true 但账户未保存密钥
503	`ai_key_encryption_disabled`	服务器 AI_KEY_ENCRYPTION_SECRET 未配置

代码示例

curl -X POST https://www.bulkpicconv.com/api/v1/convert \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "image=@photo.jpg" \
  -F "format=webp" \
  -F "quality=80" \
  -F "width=1920" \
  -o converted.webp

AI 替代文本（JSON 请求体）

curl -X POST https://www.bulkpicconv.com/v1/ai/alt-text \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"images":["data:image/jpeg;base64,/9j/4AAQ..."],"language":"en","style":"seo"}'

BYOK：使用您自己的模型

curl -X POST https://www.bulkpicconv.com/v1/ai/alt-text \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["data:image/jpeg;base64,..."],
    "userProvider": {
      "baseUrl": "https://api.siliconflow.cn/v1",
      "model": "Qwen/Qwen3-VL-32B-Instruct",
      "apiKey": "sk-your-provider-key"
    }
  }'

在线试用

API 更新日志

v3.0.02026-08-21

addedPOST /v1/ai/alt-text: AI alt text generation with GPT-4o Vision (Pro/Team or BYOK)
addedPOST /v1/ai/rename: AI batch rename based on image content
addedPOST /v1/ai/smart-crop: AI smart crop detection with platform presets
addedPOST /v1/ai/enhance: AI image enhancement (upscale, denoise, deblur)
addedPOST /v1/ai/recommend: AI format and quality recommendation
addedBYOK (Bring Your Own Key): use your own OpenAI-compatible model via userProvider object
addedGET/PUT/DELETE /api/user/ai-key: manage saved BYOK config (AES-256-GCM encrypted)
addedPOST /api/background-remove: remove image background

v2.1.02026-08-12

addedBatch webhook callback: pass `webhook_url` in batch creation to receive POST notifications on completion or failure
addedAutomatic cleanup of stale batch jobs (30-minute timeout) and result files (24-hour retention)
addedGET /api/v2/usage: query API key monthly usage and recent calls
addedGET /api/v2/credits: query available API credits and package details

v2.0.02026-08-12

addedPOST /api/v2/batch: upload ZIP, async batch conversion
addedGET /api/v2/batch/{id}/status: query batch job status
addedGET /api/v2/batch/{id}/result: download result ZIP

v1.4.02026-08-12

addedPOST /api/v1/resize: resize images via API
addedPOST /api/v1/crop: crop images via API
addedPOST /api/v1/watermark: add watermark to images via API
addedPOST /api/v1/optimize: smart optimization without format conversion

v1.0.02026-08-11

addedPOST /api/v1/convert: convert images to WebP/AVIF/JPEG/PNG
addedAPI key authentication with sk_ prefix
addedRate limiting: 60 requests/min per IP, monthly limits per plan
addedAPI credits for non-subscription users

需要 API 密钥？前往控制台

没有订阅？购买按需付费 API 额度