Documentación de la API

Convierta imágenes programáticamente con nuestra API REST.

Descripción general

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

Autenticación: Bearer token vía Authorization encabezado

Formato de clave API: sk_ prefijo + 48 caracteres alfanuméricos

Límites: Team 50K/mes, Enterprise ilimitado

Tamaño máximo: 15 MB por archivo

Dimensiones máx.: 80 megapíxeles (ej. 8000×10000)

Formatos aceptados: JPEG, PNG, WebP, GIF, BMP, TIFF, HEIC

Acceso API: planes Team y Enterprise (genere clave desde el Panel )

Puntos finales

Método	Punto final	Descripción
POST	`/api/v1/convert`	Convertir y comprimir una imagen
POST	`/api/v1/resize`	Redimensionar una imagen
POST	`/api/v1/crop`	Recortar una imagen
POST	`/api/v1/watermark`	Añadir marca de agua a una imagen
POST	`/api/v1/optimize`	Optimización inteligente sin conversión de formato
POST	`/api/v2/batch`	Conversión por lotes de ZIP (asíncrono)
GET	`/api/v2/batch/{id}/status`	Consultar estado del trabajo por lotes
GET	`/api/v2/batch/{id}/result`	Descargar ZIP de resultados
GET	`/api/v2/usage`	Consultar uso mensual de la clave API
GET	`/api/v2/credits`	Consultar créditos API disponibles
POST	`/v1/ai/alt-text`	Generación de texto alternativo IA (Pro/Team)
POST	`/v1/ai/rename`	Renombrado masivo IA (Pro/Team)
POST	`/v1/ai/smart-crop`	Detección de recorte inteligente IA (Pro/Team)
POST	`/v1/ai/enhance`	Mejora de imagen IA (Pro/Team)
POST	`/v1/ai/recommend`	Recomendación de formato IA (Pro/Team)
POST	`/api/background-remove`	Eliminar fondo de imagen
GET/PUT/DEL	`/api/user/ai-key`	Gestión de configuración de modelo BYOK

POST/v1/convert

Convertir y comprimir imagen a WebP, AVIF, JPEG o PNG.

Parámetros (multipart/form-data)

Campo	Tipo	Requerido	Descripción
image	file	Sí	El archivo de imagen a convertir
format	string	No	webp, avif, jpeg, png (predeterminado: webp)
quality	number	No	1-100 (predeterminado: 75)
width	number	No	Ancho de salida (mantiene proporción)
height	number	No	Alto de salida
fit	string	No	cover, contain, fill, inside, outside
grayscale	boolean	No	Convertir a escala de grises
blur	number	No	Radio de desenfoque (0,3-100)
rotate	number	No	Ángulo de rotación (0-360)

Respuesta

Datos binarios de imagen con encabezados:

Content-Type : Tipo MIME del formato de imagen
Content-Disposition : Adjunto con nombre de archivo (ej. converted.webp)
X-Input-Size : Tamaño original en bytes
X-Output-Size : Tamaño convertido en bytes
X-Saved-Percent : Porcentaje de espacio ahorrado
X-RateLimit-Limit : Límite mensual de llamadas API
X-RateLimit-Remaining : Llamadas API restantes este mes

POST/api/v1/resize

Redimensionar imagen manteniendo la proporción.

Parámetros (multipart/form-data)

Field	Type	Required	Description
image	file	Sí	El archivo de imagen
width	number	Sí	Ancho objetivo (1-10000)
height	number	Sí	Alto objetivo (1-10000)
fit	string	No	cover/contain/fill/inside/outside (predeterminado: inside)

POST/api/v1/crop

Extraer una región rectangular de una imagen.

Parámetros (multipart/form-data)

Field	Type	Required	Description
image	file	Sí	El archivo de imagen
x	number	Sí	Desplazamiento horizontal (esquina superior izquierda)
y	number	Sí	Desplazamiento vertical (esquina superior izquierda)
width	number	Sí	Ancho de la región de recorte
height	number	Sí	Alto de la región de recorte

POST/api/v1/watermark

Superponer marca de agua en posición configurable.

Parámetros (multipart/form-data)

Field	Type	Required	Description
image	file	Sí	Imagen base
watermark	file	Sí	Imagen de marca de agua
position	string	No	top-left/top-right/bottom-left/bottom-right/center
opacity	number	No	0-100 (predeterminado: 100)
scale	number	No	Tamaño de marca como fracción del ancho base (0,01-1)

POST/api/v1/optimize

Recodificar imagen para reducir tamaño sin cambiar formato.

Parámetros (multipart/form-data)

Field	Type	Required	Description
image	file	Sí	El archivo de imagen
quality	number	No	1-100 (predeterminado: 75). Formato original conservado.

POST/api/v2/batch

Subir archivo ZIP para conversión por lotes asíncrona. Devuelve ID de trabajo; consultar estado hasta completar.

Parámetros (multipart/form-data)

Campo	Tipo	Requerido	Descripción
file	file	Sí	Archivo ZIP de imágenes
format	string	No	webp, avif, jpeg, png (predeterminado: webp)
quality	number	No	1-100 (predeterminado: 75)

GET /api/v2/batch/{id}/status — Consultar estado (en cola → procesando → completado)
GET /api/v2/batch/{id}/result — Descargar ZIP de resultados

Funciones de IA Pro / Team

Análisis de imágenes con IA usando GPT-4o Vision. Todos los puntos finales IA aceptan cuerpo JSON con URI de datos Base64. Soporta BYOK (Bring Your Own Key) — use su propio modelo compatible con OpenAI para acceso ilimitado gratuito.

POST/v1/ai/alt-text

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

Cuerpo (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.

Cuerpo (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.

Cuerpo (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.

Cuerpo (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.

Cuerpo (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: Objeto userProvider (opcional)

Incluir en cualquier solicitud IA para usar su propio modelo. Omite verificación Pro y cuota diaria.

Campo	Tipo	Requerido	Descripción
baseUrl	string	Sí	URL base API compatible con OpenAI
model	string	Sí	Nombre del modelo Vision
apiKey	string	†	Clave API (modo local, enviada con la solicitud)
useAccountKey	boolean	†	Usar clave cifrada guardada en la cuenta

† Se requiere apiKey o useAccountKey.

Eliminación de fondo

POST/api/background-remove

Eliminar fondo de imagen. Usa API remove.bg con fallback sharp. Cuota mensual (configurado por admin).

Parámetros (multipart/form-data)

Campo	Tipo	Requerido	Descripción
image	file	Sí	Archivo de imagen (máx. 10 MB)
format	string	No	Formato de salida: png (predeterminado), webp

Gestión de cuenta

GETPUTDELETE/api/user/ai-key

Gestionar configuración de modelo BYOK guardada (cifrado con AES-256-GCM).

GET — Obtener config guardada (clave enmascarada, ej. sk-12****abcd)
PUT — Guardar/actualizar config (cuerpo: baseUrl, model, apiKey). Devuelve clave enmascarada.
DELETE — Eliminar config guardada (irreversible)

Respuestas de error

Todos los errores devuelven JSON con { "statusCode": 4xx, "statusMessage": "..." }

Código	Error	Descripción
400	`missing_form_data`	El cuerpo debe ser multipart/form-data
400	`missing_image_file`	No se encontró archivo de imagen (campo: "image")
400	`file_too_large`	El archivo supera el límite de 15 MB
400	`invalid_image_type`	El archivo no es una imagen válida
400	`invalid_image`	Imagen corrupta o ilegible
400	`image_too_large`	La imagen supera 80 megapíxeles
400	`invalid_params`	Valores de parámetros inválidos (ver campo issues)
401	`missing_or_invalid_api_key`	Encabezado Authorization faltante o malformado
401	`invalid_or_revoked_api_key`	Clave API no encontrada o revocada
401	`api_access_not_available`	Su plan no incluye acceso API (solo Team/Enterprise)
429	`rate_limited`	Demasiadas solicitudes (límite: 30/minuto)
429	`monthly_limit_exceeded`	Cuota API mensual agotada
500	`conversion_failed`	Error de procesamiento de imagen del servidor
Errores de funciones IA
403	`ai_access_denied`	Plan Pro/Team requerido (o modo BYOK: login requerido)
429	`ai_daily_limit_exceeded`	Cuota IA diaria agotada (solo modo plataforma; BYOK ilimitado)
503	`ai_service_unavailable`	Servicio IA no configurado en el servidor
403	`no_saved_ai_key`	BYOK: useAccountKey=true pero no hay clave guardada
503	`ai_key_encryption_disabled`	AI_KEY_ENCRYPTION_SECRET no configurado en el servidor

Ejemplos de código

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

Texto alternativo IA (cuerpo 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: Usar su propio modelo

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

Pruébelo

Registro de cambios de 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

¿Necesita una clave API? Ir al panel

¿Sin suscripción? Compre prepago Créditos API