Documentazione API

Converti immagini programmaticamente con la nostra API REST.

Panoramica

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

Autenticazione: Bearer token via Authorization header

Formato chiave API: sk_ prefisso + 48 caratteri alfanumerici

Limiti: Team 50K/mese, Enterprise illimitato

Dimensione max: 15 MB per file

Dimensioni max: 80 megapixel (es. 8000×10000)

Formati accettati: JPEG, PNG, WebP, GIF, BMP, TIFF, HEIC

Accesso API: piani Team e Enterprise (genera chiave dal Dashboard )

Endpoint

Metodo	Endpoint	Descrizione
POST	`/api/v1/convert`	Converti e comprimi un'immagine
POST	`/api/v1/resize`	Ridimensiona un'immagine
POST	`/api/v1/crop`	Ritaglia un'immagine
POST	`/api/v1/watermark`	Aggiungi filigrana a un'immagine
POST	`/api/v1/optimize`	Ottimizzazione intelligente senza conversione formato
POST	`/api/v2/batch`	Conversione batch di ZIP (asincrono)
GET	`/api/v2/batch/{id}/status`	Consulta stato job batch
GET	`/api/v2/batch/{id}/result`	Scarica ZIP risultati batch
GET	`/api/v2/usage`	Consulta utilizzo mensile chiave API
GET	`/api/v2/credits`	Consulta crediti API disponibili
POST	`/v1/ai/alt-text`	Generazione testo alternativo IA (Pro/Team)
POST	`/v1/ai/rename`	Rinomina batch IA (Pro/Team)
POST	`/v1/ai/smart-crop`	Rilevamento ritaglio intelligente IA (Pro/Team)
POST	`/v1/ai/enhance`	Miglioramento immagine IA (Pro/Team)
POST	`/v1/ai/recommend`	Raccomandazione formato IA (Pro/Team)
POST	`/api/background-remove`	Rimuovi sfondo immagine
GET/PUT/DEL	`/api/user/ai-key`	Gestione configurazione modello BYOK

POST/v1/convert

Converti e comprimi immagine in WebP, AVIF, JPEG o PNG.

Parametri (multipart/form-data)

Campo	Tipo	Obbligatorio	Descrizione
image	file	Sì	Il file immagine da convertire
format	string	No	webp, avif, jpeg, png (predefinito: webp)
quality	number	No	1-100 (predefinito: 75)
width	number	No	Larghezza output (mantiene proporzioni)
height	number	No	Altezza output
fit	string	No	cover, contain, fill, inside, outside
grayscale	boolean	No	Converti in scala di grigi
blur	number	No	Raggio sfocatura (0,3-100)
rotate	number	No	Angolo rotazione (0-360)

Risposta

Dati immagine binari con header:

Content-Type : Tipo MIME del formato immagine
Content-Disposition : Allegato con nome file (es. converted.webp)
X-Input-Size : Dimensione originale in byte
X-Output-Size : Dimensione convertita in byte
X-Saved-Percent : Percentuale spazio risparmiato
X-RateLimit-Limit : Limite mensile chiamate API
X-RateLimit-Remaining : Chiamate API rimanenti questo mese

POST/api/v1/resize

Ridimensiona immagine mantenendo le proporzioni.

Parametri (multipart/form-data)

Field	Type	Required	Description
image	file	Sì	Il file immagine
width	number	Sì	Larghezza target (1-10000)
height	number	Sì	Altezza target (1-10000)
fit	string	No	cover/contain/fill/inside/outside (predefinito: inside)

POST/api/v1/crop

Estrai una regione rettangolare da un'immagine.

Parametri (multipart/form-data)

Field	Type	Required	Description
image	file	Sì	Il file immagine
x	number	Sì	Offset orizzontale (in alto a sinistra)
y	number	Sì	Offset verticale (in alto a sinistra)
width	number	Sì	Larghezza area di ritaglio
height	number	Sì	Altezza area di ritaglio

POST/api/v1/watermark

Sovrapponi filigrana in posizione configurabile.

Parametri (multipart/form-data)

Field	Type	Required	Description
image	file	Sì	Immagine base
watermark	file	Sì	Immagine filigrana
position	string	No	top-left/top-right/bottom-left/bottom-right/center
opacity	number	No	0-100 (predefinito: 100)
scale	number	No	Dimensione filigrana come frazione larghezza base (0,01-1)

POST/api/v1/optimize

Ricodifica immagine per ridurre dimensione senza cambiare formato.

Parametri (multipart/form-data)

Field	Type	Required	Description
image	file	Sì	Il file immagine
quality	number	No	1-100 (predefinito: 75). Formato originale preservato.

POST/api/v2/batch

Carica archivio ZIP per conversione batch asincrona. Restituisce ID job; consulta stato fino al completamento.

Parametri (multipart/form-data)

Campo	Tipo	Obbligatorio	Descrizione
file	file	Sì	Archivio ZIP di immagini
format	string	No	webp, avif, jpeg, png (predefinito: webp)
quality	number	No	1-100 (predefinito: 75)

GET /api/v2/batch/{id}/status — Consulta stato job (in coda → in elaborazione → completato)
GET /api/v2/batch/{id}/result — Scarica ZIP risultati

Funzionalità IA Pro / Team

Analisi immagini IA con GPT-4o Vision. Tutti gli endpoint IA accettano body JSON con URI dati Base64. Supporta BYOK (Bring Your Own Key) — usa il tuo modello compatibile OpenAI per accesso illimitato gratuito.

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[]	Sì	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[]	Sì	{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	Sì	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	Sì	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[]	Sì	{data, filename, width, height, fileSize, mimeType} (1-20)
useCase	string	No	web/ecommerce/social-media/print/archive/general
userProvider	object	No	BYOK config

BYOK: Oggetto userProvider (opzionale)

Includi in qualsiasi richiesta IA per usare il tuo modello. Salta controllo Pro e quota giornaliera.

Campo	Tipo	Obbligatorio	Descrizione
baseUrl	string	Sì	URL base API compatibile OpenAI
model	string	Sì	Nome modello Vision
apiKey	string	†	Chiave API (modalità locale, inviata con richiesta)
useAccountKey	boolean	†	Usa chiave crittografata salvata nell'account

† apiKey o useAccountKey è obbligatorio.

Rimozione sfondo

POST/api/background-remove

Rimuovi sfondo immagine. Usa API remove.bg con fallback sharp. Quota mensile (configurata da admin).

Parametri (multipart/form-data)

Campo	Tipo	Obbligatorio	Descrizione
image	file	Sì	File immagine (max 10 MB)
format	string	No	Formato output: png (predefinito), webp

Gestione account

GETPUTDELETE/api/user/ai-key

Gestisci configurazione modello BYOK salvata (crittografata AES-256-GCM).

GET — Ottieni config salvata (chiave mascherata, es. sk-12****abcd)
PUT — Salva/aggiorna config (body: baseUrl, model, apiKey). Restituisce chiave mascherata.
DELETE — Elimina config salvata (irreversibile)

Risposte di errore

Tutti gli errori restituiscono JSON con { "statusCode": 4xx, "statusMessage": "..." }

Codice	Errore	Descrizione
400	`missing_form_data`	Il body deve essere multipart/form-data
400	`missing_image_file`	Nessun file immagine trovato (campo: "image")
400	`file_too_large`	Il file supera il limite di 15 MB
400	`invalid_image_type`	Il file non è un'immagine valida
400	`invalid_image`	Immagine corrotta o illeggibile
400	`image_too_large`	L'immagine supera 80 megapixel
400	`invalid_params`	Valori parametro non validi (vedi campo issues)
401	`missing_or_invalid_api_key`	Header Authorization mancante o malformato
401	`invalid_or_revoked_api_key`	Chiave API non trovata o revocata
401	`api_access_not_available`	Il tuo piano non include accesso API (solo Team/Enterprise)
429	`rate_limited`	Troppe richieste (limite: 30/minuto)
429	`monthly_limit_exceeded`	Quota API mensile esaurita
500	`conversion_failed`	Errore elaborazione immagine lato server
Errori funzionalità IA
403	`ai_access_denied`	Piano Pro/Team richiesto (o modalità BYOK: login richiesto)
429	`ai_daily_limit_exceeded`	Quota IA giornaliera esaurita (solo modalità piattaforma; BYOK illimitato)
503	`ai_service_unavailable`	Servizio IA non configurato sul server
403	`no_saved_ai_key`	BYOK: useAccountKey=true ma nessuna chiave salvata
503	`ai_key_encryption_disabled`	AI_KEY_ENCRYPTION_SECRET non configurato sul server

Esempi di codice

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

Testo alternativo IA (body 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: Usa il tuo modello

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

Provalo

Registro modifiche 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

Hai bisogno di una chiave API? Vai alla dashboard

Senza abbonamento? Acquista prepagato Crediti API