Documentação da API

Converta imagens programaticamente com nossa API REST.

Visão geral

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

Autenticação: Bearer token via Authorization header

Formato da chave API: sk_ prefixo + 48 caracteres alfanuméricos

Limites: Team 50K/mês, Enterprise ilimitado

Tamanho máx.: 15 MB por arquivo

Dimensões máx.: 80 megapixels (ex. 8000×10000)

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

Acesso API: planos Team e Enterprise (gere chave no Painel )

Endpoints

Método	Endpoint	Descrição
POST	`/api/v1/convert`	Converter e comprimir imagem
POST	`/api/v1/resize`	Redimensionar imagem
POST	`/api/v1/crop`	Cortar imagem
POST	`/api/v1/watermark`	Adicionar marca d'água à imagem
POST	`/api/v1/optimize`	Otimização inteligente sem conversão de formato
POST	`/api/v2/batch`	Conversão em lote de ZIP (assíncrono)
GET	`/api/v2/batch/{id}/status`	Consultar status do job em lote
GET	`/api/v2/batch/{id}/result`	Baixar ZIP de resultados
GET	`/api/v2/usage`	Consultar uso mensal da chave API
GET	`/api/v2/credits`	Consultar créditos API disponíveis
POST	`/v1/ai/alt-text`	Geração de texto alternativo IA (Pro/Team)
POST	`/v1/ai/rename`	Renomeação em massa IA (Pro/Team)
POST	`/v1/ai/smart-crop`	Detecção de corte inteligente IA (Pro/Team)
POST	`/v1/ai/enhance`	Melhoria de imagem IA (Pro/Team)
POST	`/v1/ai/recommend`	Recomendação de formato IA (Pro/Team)
POST	`/api/background-remove`	Remover fundo da imagem
GET/PUT/DEL	`/api/user/ai-key`	Gestão de configuração modelo BYOK

POST/v1/convert

Converter e comprimir imagem para WebP, AVIF, JPEG ou PNG.

Parâmetros (multipart/form-data)

Campo	Tipo	Obrigatório	Descrição
image	file	Sim	O arquivo de imagem a converter
format	string	Não	webp, avif, jpeg, png (padrão: webp)
quality	number	Não	1-100 (padrão: 75)
width	number	Não	Largura de saída (mantém proporção)
height	number	Não	Altura de saída
fit	string	Não	cover, contain, fill, inside, outside
grayscale	boolean	Não	Converter para escala de cinza
blur	number	Não	Raio de desfoque (0,3-100)
rotate	number	Não	Ângulo de rotação (0-360)

Resposta

Dados binários de imagem com headers:

Content-Type : Tipo MIME do formato de imagem
Content-Disposition : Anexo com nome de arquivo (ex. converted.webp)
X-Input-Size : Tamanho original em bytes
X-Output-Size : Tamanho convertido em bytes
X-Saved-Percent : Porcentagem de espaço economizado
X-RateLimit-Limit : Limite mensal de chamadas API
X-RateLimit-Remaining : Chamadas API restantes este mês

POST/api/v1/resize

Redimensionar imagem mantendo proporção.

Parâmetros (multipart/form-data)

Field	Type	Required	Description
image	file	Sim	O arquivo de imagem
width	number	Sim	Largura alvo (1-10000)
height	number	Sim	Altura alvo (1-10000)
fit	string	Não	cover/contain/fill/inside/outside (padrão: inside)

POST/api/v1/crop

Extrair região retangular de uma imagem.

Parâmetros (multipart/form-data)

Field	Type	Required	Description
image	file	Sim	O arquivo de imagem
x	number	Sim	Offset horizontal (canto superior esquerdo)
y	number	Sim	Offset vertical (canto superior esquerdo)
width	number	Sim	Largura da região de corte
height	number	Sim	Altura da região de corte

POST/api/v1/watermark

Sobrepor marca d'água em posição configurável.

Parâmetros (multipart/form-data)

Field	Type	Required	Description
image	file	Sim	Imagem base
watermark	file	Sim	Imagem de marca d'água
position	string	Não	top-left/top-right/bottom-left/bottom-right/center
opacity	number	Não	0-100 (padrão: 100)
scale	number	Não	Tamanho da marca como fração da largura base (0,01-1)

POST/api/v1/optimize

Recodificar imagem para reduzir tamanho sem mudar formato.

Parâmetros (multipart/form-data)

Field	Type	Required	Description
image	file	Sim	O arquivo de imagem
quality	number	Não	1-100 (padrão: 75). Formato original preservado.

POST/api/v2/batch

Enviar arquivo ZIP para conversão em lote assíncrona. Retorna ID do job; consulte status até concluir.

Parâmetros (multipart/form-data)

Campo	Tipo	Obrigatório	Descrição
file	file	Sim	Arquivo ZIP de imagens
format	string	Não	webp, avif, jpeg, png (padrão: webp)
quality	number	Não	1-100 (padrão: 75)

GET /api/v2/batch/{id}/status — Consultar status (na fila → processando → concluído)
GET /api/v2/batch/{id}/result — Baixar ZIP de resultados

Recursos de IA Pro / Team

Análise de imagem com IA usando GPT-4o Vision. Todos os endpoints IA aceitam body JSON com URIs de dados Base64. Suporta BYOK (Bring Your Own Key) — use seu próprio modelo compatível com OpenAI para acesso ilimitado 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[]	Sim	Base64 data URIs (1-10 images)
language	string	Não	en/zh/es/fr/de/ja/ko/pt/it (default: en)
style	string	Não	descriptive/concise/seo (default: descriptive)
userProvider	object	Não	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[]	Sim	{data, originalName} (1-20 images)
rules	object	Não	{prefix, includeSequence, style}
userProvider	object	Não	BYOK config

POST/v1/ai/smart-crop

Detect subject and generate platform-specific crop recommendations.

Body (application/json)

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

POST/v1/ai/enhance

Upscale, denoise, or deblur images.

Body (application/json)

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

BYOK: Objeto userProvider (opcional)

Inclua em qualquer requisição IA para usar seu próprio modelo. Ignora verificação Pro e cota diária.

Campo	Tipo	Obrigatório	Descrição
baseUrl	string	Sim	URL base API compatível com OpenAI
model	string	Sim	Nome do modelo Vision
apiKey	string	†	Chave API (modo local, enviada com requisição)
useAccountKey	boolean	†	Usar chave criptografada salva na conta

† apiKey ou useAccountKey é obrigatório.

Remoção de fundo

POST/api/background-remove

Remover fundo da imagem. Usa API remove.bg com fallback sharp. Cota mensal (configurada pelo admin).

Parâmetros (multipart/form-data)

Campo	Tipo	Obrigatório	Descrição
image	file	Sim	Arquivo de imagem (máx. 10 MB)
format	string	Não	Formato de saída: png (padrão), webp

Gestão de conta

GETPUTDELETE/api/user/ai-key

Gerenciar configuração modelo BYOK salva (criptografada AES-256-GCM).

GET — Obter config salva (chave mascarada, ex. sk-12****abcd)
PUT — Salvar/atualizar config (body: baseUrl, model, apiKey). Retorna chave mascarada.
DELETE — Excluir config salva (irreversível)

Respostas de erro

Todos os erros retornam JSON com { "statusCode": 4xx, "statusMessage": "..." }

Código	Erro	Descrição
400	`missing_form_data`	Body deve ser multipart/form-data
400	`missing_image_file`	Nenhum arquivo de imagem encontrado (campo: "image")
400	`file_too_large`	Arquivo excede limite de 15 MB
400	`invalid_image_type`	Arquivo não é imagem válida
400	`invalid_image`	Imagem corrompida ou ilegível
400	`image_too_large`	Imagem excede 80 megapixels
400	`invalid_params`	Valores de parâmetros inválidos (ver campo issues)
401	`missing_or_invalid_api_key`	Header Authorization ausente ou malformado
401	`invalid_or_revoked_api_key`	Chave API não encontrada ou revogada
401	`api_access_not_available`	Seu plano não inclui acesso API (somente Team/Enterprise)
429	`rate_limited`	Muitas requisições (limite: 30/minuto)
429	`monthly_limit_exceeded`	Cota API mensal esgotada
500	`conversion_failed`	Erro de processamento de imagem no servidor
Erros de recursos IA
403	`ai_access_denied`	Plano Pro/Team necessário (ou modo BYOK: login necessário)
429	`ai_daily_limit_exceeded`	Cota IA diária esgotada (somente modo plataforma; BYOK ilimitado)
503	`ai_service_unavailable`	Serviço IA não configurado no servidor
403	`no_saved_ai_key`	BYOK: useAccountKey=true mas nenhuma chave salva
503	`ai_key_encryption_disabled`	AI_KEY_ENCRYPTION_SECRET não configurado no servidor

Exemplos 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 (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: Use seu próprio 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"
    }
  }'

Experimente

Registro de alterações da 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

Precisa de uma chave API? Ir para o painel

Sem assinatura? Compre pré-pago Créditos API