API-Dokumentation

Konvertieren Sie Bilder programmgesteuert mit unserer REST-API.

Übersicht

Basis-URL: https://www.bulkpicconv.com/api/v1

Authentifizierung: Bearer-Token über Authorization Header

API-Schlüsselformat: sk_ Präfix + 48 alphanumerische Zeichen

Ratenbegrenzung: Team 50K/Monat, Enterprise unbegrenzt

Maximale Uploadgröße: 15 MB pro Datei

Maximale Bildabmessungen: 80 Megapixel (z.B. 8000×10000)

Akzeptierte Eingabeformate: JPEG, PNG, WebP, GIF, BMP, TIFF, HEIC

API-Zugang: Team- und Enterprise-Pläne (Schlüssel generieren im Dashboard )

Endpunkte

Methode	Endpunkt	Beschreibung
POST	`/api/v1/convert`	Bild konvertieren und komprimieren
POST	`/api/v1/resize`	Bild skalieren
POST	`/api/v1/crop`	Bild zuschneiden
POST	`/api/v1/watermark`	Wasserzeichen zum Bild hinzufügen
POST	`/api/v1/optimize`	Intelligente Optimierung ohne Formatkonvertierung
POST	`/api/v2/batch`	ZIP-Bilder stapelweise konvertieren (async)
GET	`/api/v2/batch/{id}/status`	Stapeljob-Status abfragen
GET	`/api/v2/batch/{id}/result`	Stapel-Ergebnis-ZIP herunterladen
GET	`/api/v2/usage`	Monatliche API-Schlüssel-Nutzung abfragen
GET	`/api/v2/credits`	Verfügbare API-Credits abfragen
POST	`/v1/ai/alt-text`	KI-Alt-Text-Generierung (Pro/Team)
POST	`/v1/ai/rename`	KI-Massenumbenennung (Pro/Team)
POST	`/v1/ai/smart-crop`	KI-Smart-Crop-Erkennung (Pro/Team)
POST	`/v1/ai/enhance`	KI-Bildverbesserung (Pro/Team)
POST	`/v1/ai/recommend`	KI-Formatempfehlung (Pro/Team)
POST	`/api/background-remove`	Bildhintergrund entfernen
GET/PUT/DEL	`/api/user/ai-key`	BYOK-Modellkonfigurationsverwaltung

POST/v1/convert

Bild nach WebP, AVIF, JPEG oder PNG konvertieren und komprimieren.

Parameter (multipart/form-data)

Feld	Typ	Erforderlich	Beschreibung
image	file	Ja	Die zu konvertierende Bilddatei
format	string	Nein	webp, avif, jpeg, png (Standard: webp)
quality	number	Nein	1-100 (Standard: 75)
width	number	Nein	Ausgabebreite (Seitenverhältnis bleibt erhalten)
height	number	Nein	Ausgabehöhe
fit	string	Nein	cover, contain, fill, inside, outside
grayscale	boolean	Nein	In Graustufen konvertieren
blur	number	Nein	Unschärferadius (0,3-100)
rotate	number	Nein	Drehwinkel (0-360)

Antwort

Binäre Bilddaten mit Headern:

Content-Type : MIME-Typ des Bildformats
Content-Disposition : Attachment mit Dateiname (z.B. converted.webp)
X-Input-Size : Originalgröße in Byte
X-Output-Size : Konvertierte Größe in Byte
X-Saved-Percent : Prozentualer Platzgewinn
X-RateLimit-Limit : Monatliches API-Call-Limit
X-RateLimit-Remaining : Verbleibende API-Calls diesen Monat

POST/api/v1/resize

Bild unter Beibehaltung des Seitenverhältnisses skalieren.

Parameter (multipart/form-data)

Field	Type	Required	Description
image	file	Ja	Die Bilddatei
width	number	Ja	Zielbreite (1-10000)
height	number	Ja	Zielhöhe (1-10000)
fit	string	Nein	cover/contain/fill/inside/outside (Standard: inside)

POST/api/v1/crop

Rechteckigen Bereich aus einem Bild extrahieren.

Parameter (multipart/form-data)

Field	Type	Required	Description
image	file	Ja	Die Bilddatei
x	number	Ja	Horizontaler Versatz (oben links)
y	number	Ja	Vertikaler Versatz (oben links)
width	number	Ja	Breite des Zuschneidebereichs
height	number	Ja	Höhe des Zuschneidebereichs

POST/api/v1/watermark

Wasserzeichen an einer konfigurierbaren Position überlagern.

Parameter (multipart/form-data)

Field	Type	Required	Description
image	file	Ja	Basisbild
watermark	file	Ja	Wasserzeichen-Bild
position	string	Nein	top-left/top-right/bottom-left/bottom-right/center
opacity	number	Nein	0-100 (Standard: 100)
scale	number	Nein	Wasserzeichengröße als Anteil der Basisbreite (0,01-1)

POST/api/v1/optimize

Bild neu codieren, um die Dateigröße ohne Formatänderung zu reduzieren.

Parameter (multipart/form-data)

Field	Type	Required	Description
image	file	Ja	Die Bilddatei
quality	number	Nein	1-100 (Standard: 75). Originalformat bleibt erhalten.

POST/api/v2/batch

ZIP-Archiv für asynchrone Stapelkonvertierung hochladen. Gibt eine Job-ID zurück; Status abfragen bis abgeschlossen.

Parameter (multipart/form-data)

Feld	Typ	Erforderlich	Beschreibung
file	file	Ja	ZIP-Archiv mit Bildern
format	string	Nein	webp, avif, jpeg, png (Standard: webp)
quality	number	Nein	1-100 (Standard: 75)

GET /api/v2/batch/{id}/status — Job-Status abfragen (Warteschlange → Verarbeitung → Abgeschlossen)
GET /api/v2/batch/{id}/result — Ergebnis-ZIP herunterladen

KI-Funktionen Pro / Team

KI-gestützte Bildanalyse mit GPT-4o Vision. Alle KI-Endpunkte akzeptieren JSON-Body mit Base64-Daten-URIs. Unterstützt BYOK (Bring Your Own Key) — verwenden Sie Ihr eigenes OpenAI-kompatibles Modell für kostenlosen unbegrenzten Zugriff.

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[]	Ja	Base64 data URIs (1-10 images)
language	string	Nein	en/zh/es/fr/de/ja/ko/pt/it (default: en)
style	string	Nein	descriptive/concise/seo (default: descriptive)
userProvider	object	Nein	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[]	Ja	{data, originalName} (1-20 images)
rules	object	Nein	{prefix, includeSequence, style}
userProvider	object	Nein	BYOK config

POST/v1/ai/smart-crop

Detect subject and generate platform-specific crop recommendations.

Body (application/json)

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

POST/v1/ai/enhance

Upscale, denoise, or deblur images.

Body (application/json)

Field	Type	Required	Description
image	string	Ja	Base64 data URI
mode	string	Nein	upscale/denoise/deblur/auto (default: auto)
intensity	number	Nein	1=Light, 2=Medium, 3=Strong (default: 2)
returnPreview	boolean	Nein	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[]	Ja	{data, filename, width, height, fileSize, mimeType} (1-20)
useCase	string	Nein	web/ecommerce/social-media/print/archive/general
userProvider	object	Nein	BYOK config

BYOK: userProvider-Objekt (optional)

In jede KI-Anfrage einfügen, um Ihr eigenes Modell zu verwenden. Überspringt Pro-Prüfung und tägliches Kontingent.

Feld	Typ	Erforderlich	Beschreibung
baseUrl	string	Ja	OpenAI-kompatible API-Basis-URL
model	string	Ja	Vision-Modellname
apiKey	string	†	API-Schlüssel (lokaler Modus, wird mit Anfrage gesendet)
useAccountKey	boolean	†	Kontogespeicherten verschlüsselten Schlüssel verwenden

† Einer von apiKey oder useAccountKey ist erforderlich.

Hintergrundentfernung

POST/api/background-remove

Bildhintergrund entfernen. Verwendet remove.bg-API mit sharp-Fallback. Monatliches Kontingent (vom Admin konfiguriert).

Parameter (multipart/form-data)

Feld	Typ	Erforderlich	Beschreibung
image	file	Ja	Bilddatei (max. 10 MB)
format	string	Nein	Ausgabeformat: png (Standard), webp

Kontoverwaltung

GETPUTDELETE/api/user/ai-key

Gespeicherte BYOK-Modellkonfiguration verwalten (verschlüsselt mit AES-256-GCM).

GET — Gespeicherte Konfiguration abrufen (Schlüssel nur maskiert angezeigt, z.B. sk-12****abcd)
PUT — Konfiguration speichern/aktualisieren (Body: baseUrl, model, apiKey). Gibt maskierten Schlüssel zurück.
DELETE — Gespeicherte Konfiguration löschen (unwiderruflich)

Fehlerantworten

Alle Fehler geben JSON zurück mit { "statusCode": 4xx, "statusMessage": "..." }

Code	Fehler	Beschreibung
400	`missing_form_data`	Anfrage-Body muss multipart/form-data sein
400	`missing_image_file`	Keine Bilddatei in Formulardaten gefunden (Feldname: "image")
400	`file_too_large`	Datei überschreitet 15 MB Upload-Limit
400	`invalid_image_type`	Datei ist kein gültiges Bild
400	`invalid_image`	Bild ist beschädigt oder unlesbar
400	`image_too_large`	Bild überschreitet 80 Megapixel
400	`invalid_params`	Ungültige Parameterwerte (siehe issues-Feld)
401	`missing_or_invalid_api_key`	Fehlender oder fehlerhafter Authorization-Header
401	`invalid_or_revoked_api_key`	API-Schlüssel nicht gefunden oder widerrufen
401	`api_access_not_available`	Ihr Plan enthält keinen API-Zugang (nur Team/Enterprise)
429	`rate_limited`	Zu viele Anfragen (Burst-Limit: 30/Minute)
429	`monthly_limit_exceeded`	Monatliches API-Kontingent erschöpft
500	`conversion_failed`	Serverseitiger Bildverarbeitungsfehler
KI-Funktionsfehler
403	`ai_access_denied`	Pro/Team-Plan erforderlich (oder BYOK-Modus: Anmeldung erforderlich)
429	`ai_daily_limit_exceeded`	Tägliches KI-Kontingent erschöpft (nur Plattformmodus; BYOK unbegrenzt)
503	`ai_service_unavailable`	KI-Dienst nicht auf Server konfiguriert
403	`no_saved_ai_key`	BYOK: useAccountKey=true, aber kein Schlüssel im Konto gespeichert
503	`ai_key_encryption_disabled`	Server AI_KEY_ENCRYPTION_SECRET nicht konfiguriert

Codebeispiele

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

KI-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: Eigenes Modell verwenden

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

Ausprobieren

API-Änderungsprotokoll

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-Schlüssel benötigt? Zum Dashboard

Kein Abonnement? Kaufen Sie Pay-as-you-go API-Credits