API Documentation

Convert images programmatically with our REST API.

Overview

Base URL: https://www.bulkpicconv.com/api/v1

Authentication: Bearer token via Authorization header

API Key format: sk_ prefix + 48 alphanumeric characters

Rate limits: Team 50K/month, Enterprise unlimited

Max upload size: 15 MB per file

Max image dimensions: 80 megapixels (e.g. 8000×10000)

Accepted input formats: JPEG, PNG, WebP, GIF, BMP, TIFF, HEIC

API access: Team and Enterprise plans (generate key from Dashboard )

Endpoints

Method	Endpoint	Description
POST	`/api/v1/convert`	Convert and compress an image
POST	`/api/v1/resize`	Resize an image
POST	`/api/v1/crop`	Crop an image
POST	`/api/v1/watermark`	Add watermark to an image
POST	`/api/v1/optimize`	Smart optimization without format conversion
POST	`/api/v2/batch`	Batch convert ZIP of images (async)
GET	`/api/v2/batch/{id}/status`	Query batch job status
GET	`/api/v2/batch/{id}/result`	Download batch result ZIP
GET	`/api/v2/usage`	Query API key monthly usage
GET	`/api/v2/credits`	Query available API credits
POST	`/v1/ai/alt-text`	AI alt text generation (Pro/Team)
POST	`/v1/ai/rename`	AI batch rename (Pro/Team)
POST	`/v1/ai/smart-crop`	AI smart crop detection (Pro/Team)
POST	`/v1/ai/enhance`	AI image enhancement (Pro/Team)
POST	`/v1/ai/recommend`	AI format recommendation (Pro/Team)
POST	`/api/background-remove`	Remove image background
GET/PUT/DEL	`/api/user/ai-key`	BYOK model config management

POST/v1/convert

Convert and compress an image to WebP, AVIF, JPEG, or PNG.

Parameters (multipart/form-data)

Field	Type	Required	Description
image	file	Yes	The image file to convert
format	string	No	webp, avif, jpeg, png (default: webp)
quality	number	No	1-100 (default: 75)
width	number	No	Output width (maintains aspect ratio)
height	number	No	Output height
fit	string	No	cover, contain, fill, inside, outside
grayscale	boolean	No	Convert to grayscale
blur	number	No	Blur radius (0.3-100)
rotate	number	No	Rotation angle (0-360)

Response

Binary image data with headers:

Content-Type : image format MIME type
Content-Disposition : attachment with filename (e.g. converted.webp)
X-Input-Size : original size in bytes
X-Output-Size : converted size in bytes
X-Saved-Percent : space saved percentage
X-RateLimit-Limit : monthly API call limit
X-RateLimit-Remaining : remaining API calls this month

POST/api/v1/resize

Resize an image while preserving aspect ratio.

Parameters (multipart/form-data)

Field	Type	Required	Description
image	file	Yes	The image file
width	number	Yes	Target width (1-10000)
height	number	Yes	Target height (1-10000)
fit	string	No	cover/contain/fill/inside/outside (default: inside)

POST/api/v1/crop

Extract a rectangular region from an image.

Parameters (multipart/form-data)

Field	Type	Required	Description
image	file	Yes	The image file
x	number	Yes	Horizontal offset (top-left)
y	number	Yes	Vertical offset (top-left)
width	number	Yes	Crop region width
height	number	Yes	Crop region height

POST/api/v1/watermark

Overlay a watermark image at a configurable position.

Parameters (multipart/form-data)

Field	Type	Required	Description
image	file	Yes	Base image
watermark	file	Yes	Watermark image
position	string	No	top-left/top-right/bottom-left/bottom-right/center
opacity	number	No	0-100 (default: 100)
scale	number	No	Watermark size as fraction of base width (0.01-1)

POST/api/v1/optimize

Re-encode image to reduce file size without changing format.

Parameters (multipart/form-data)

Field	Type	Required	Description
image	file	Yes	The image file
quality	number	No	1-100 (default: 75). Original format preserved.

POST/api/v2/batch

Upload a ZIP archive for async batch conversion. Returns a job ID; poll status until completed.

Parameters (multipart/form-data)

Field	Type	Required	Description
file	file	Yes	ZIP archive of images
format	string	No	webp, avif, jpeg, png (default: webp)
quality	number	No	1-100 (default: 75)

GET /api/v2/batch/{id}/status — Poll job status (queued → processing → completed)
GET /api/v2/batch/{id}/result — Download result ZIP

AI Features Pro / Team

AI-powered image analysis using GPT-4o Vision. All AI endpoints accept JSON body with Base64 data URIs. Supports BYOK (Bring Your Own Key) — use your own OpenAI-compatible model for free unlimited access.

POST/v1/ai/alt-text

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

Body (application/json)

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

POST/v1/ai/rename

Generate SEO-friendly filenames based on image content.

Body (application/json)

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

POST/v1/ai/smart-crop

Detect subject and generate platform-specific crop recommendations.

Body (application/json)

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

POST/v1/ai/enhance

Upscale, denoise, or deblur images.

Body (application/json)

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

POST/v1/ai/recommend

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

Body (application/json)

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

BYOK: userProvider Object (optional)

Include in any AI request to use your own model. Skips Pro check and daily quota.

Field	Type	Required	Description
baseUrl	string	Yes	OpenAI-compatible API base URL
model	string	Yes	Vision model name
apiKey	string	†	API key (local mode, sent with request)
useAccountKey	boolean	†	Use account-saved encrypted key

† One of apiKey or useAccountKey is required.

Background Removal

POST/api/background-remove

Remove image background. Uses remove.bg API with sharp fallback. Monthly quota applies (configured by admin).

Parameters (multipart/form-data)

Field	Type	Required	Description
image	file	Yes	Image file (max 10 MB)
format	string	No	Output format: png (default), webp

Account Management

GETPUTDELETE/api/user/ai-key

Manage saved BYOK model configuration (encrypted with AES-256-GCM).

GET — Get saved config (key shown as mask only, e.g. sk-12****abcd)
PUT — Save/update config (body: baseUrl, model, apiKey). Returns masked key.
DELETE — Delete saved config (irreversible)

Error Responses

All errors return JSON with { "statusCode": 4xx, "statusMessage": "..." }

Code	Error	Description
400	`missing_form_data`	Request body must be multipart/form-data
400	`missing_image_file`	No image file found in form data (field name: "image")
400	`file_too_large`	File exceeds 15 MB upload limit
400	`invalid_image_type`	File is not a valid image
400	`invalid_image`	Image is corrupted or unreadable
400	`image_too_large`	Image exceeds 80 megapixels
400	`invalid_params`	Invalid parameter values (see issues field)
401	`missing_or_invalid_api_key`	Missing or malformed Authorization header
401	`invalid_or_revoked_api_key`	API key not found or has been revoked
401	`api_access_not_available`	Your plan does not include API access (Team/Enterprise only)
429	`rate_limited`	Too many requests (burst limit: 30/minute)
429	`monthly_limit_exceeded`	Monthly API call quota exhausted
500	`conversion_failed`	Server-side image processing error
AI Feature Errors
403	`ai_access_denied`	Pro/Team plan required (or BYOK mode: login required)
429	`ai_daily_limit_exceeded`	Daily AI quota exhausted (platform mode only; BYOK unlimited)
503	`ai_service_unavailable`	AI service not configured on server
403	`no_saved_ai_key`	BYOK: useAccountKey=true but no key saved to account
503	`ai_key_encryption_disabled`	Server AI_KEY_ENCRYPTION_SECRET not configured

Code Examples

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 Alt Text (JSON body)

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: Use Your Own Model

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"
    }
  }'

Try It Out

API Changelog

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

Need an API key? Go to Dashboard

Don't have a subscription? Buy pay-as-you-go API Credits