Referência da API

Cada endpoint, cada parâmetro, cada campo de resposta. URL base: https://cleverutils.com/api/v1

Conversor universal

POST/api/v1/convert

Converte um único arquivo para um formato de destino. Usado por mais de 143 pares de formatos (imagem, áudio, vídeo, documento, arquivo compactado, 3D, fonte).

Request (multipart/form-data)

CampoTipoNotas
file OBRIGATÓRIOarquivoO arquivo de origem. Até 200 MB.
to_format OBRIGATÓRIOstringExtensão do formato de destino, por exemplo png, mp3, pdf, webp. 2–5 caracteres alfanuméricos.
img_quality opcionalintQualidade da imagem 0–100. Padrão 80. Usado para compressão JPG, WebP, PDF.
img_resize_w, img_resize_h opcionalintRedimensionar para dimensões exatas (16–7680 px). Use uma ou ambas.
img_rotate opcionalstringRotacionar: 90, 180, 270, flip-h, flip-v.
img_crop_x, img_crop_y, img_crop_w, img_crop_h opcionalintRegião de recorte em pixels.
mp3_mode, mp3_quality, mp3_bitrate opcionalváriosOpções do codificador MP3. Veja a referência de áudio.
wav_rate, wav_depth, wav_channels opcionalintOpções de saída WAV.
ocr_lang opcionalstringIdioma Tesseract para OCR de PDF/imagem. Padrão eng.

Response (sucesso, 200)

JSON
{ "data": {
    "job_id": "5f8c1a2e9d4b7c0e3f6a8b2d1e4c5f78",
    "status": "done",
    "output": { "filename": "photo_cleverutils.com.jpg", "size_bytes": 184523, "size_human": "180 KB", "url": "https://cleverutils.com/api/v1/jobs/5f8c.../output" },
    "links": { "self": "...", "output": "..." },
    "expires_at": "2026-04-10T14:32:11Z"
} }

Processamento em batch

POST/api/v1/batch

Converte até 20 arquivos em uma única request. Cada arquivo conta individualmente contra a sua cota diária.

CampoTipoNotas
files[] OBRIGATÓRIOarquivo[]Até 20 arquivos em uma única request multipart.
to_format OBRIGATÓRIOstringFormato de destino aplicado a todos os arquivos.

Estrutura da response

Retorna um batch_id mais um array de jobs por arquivo. Use GET /api/v1/batches/{batch_id} para consultar o status agregado depois.

Ciclo de vida do job

GET/api/v1/jobs/{job_id}

Consulta o status de um job de conversão. job_id tem 32 caracteres hexadecimais retornados por /api/v1/convert.

Estados da response

  • data.status: "processing" — conversão em andamento, progress opcional 0–99
  • data.status: "done" — conversão concluída, bloco output preenchido
  • HTTP 404 com error.code: JOB_NOT_FOUND — ID inválido ou expirado
  • HTTP 500 com error.code: CONVERSION_FAILED — conversão falhou
GET/api/v1/jobs/{job_id}/output

Faz streaming do arquivo convertido como anexo binário. Retorna Content-Type correspondente ao MIME de saída e Content-Disposition: attachment; filename=.... Os arquivos expiram 2 horas após a conversão.

GET/api/v1/batches/{batch_id}

Status agregado de todos os jobs em um batch. Formato de batch_id: bat_ seguido de 16 caracteres hexadecimais. Inclui overall_status (done / processing / failed) mais o array por job.

Ferramentas de IA

POST/api/v1/tools/{slug}

Ferramentas especializadas que não se encaixam em uma simples conversão de formato. Cada ferramenta tem seu próprio conjunto de parâmetros.

SlugDescriçãoLimite diário
upscale-imageAmpliação por IA 2x/3x/4x (Real-ESRGAN). Opcional: scale, model.50
enhance-photoMelhoria automática de foto (atualmente aliasado para colorize).50
vocal-removerSeparar vocais do instrumental (Demucs).50
speech-to-textTranscrever áudio/vídeo. Opções: format (txt/srt/vtt), quality, language.100
remove-backgroundRemover fundo de imagem (rembg).100
colorize-photoColorir fotos em preto e branco (siggraph17).50
restore-old-photoRestaurar e colorir fotos antigas.50
noise-reductionRedução de ruído de áudio (DeepFilterNet3).50
change-backgroundSubstituir fundo de imagem.100
remove-objectRemover objeto via inpainting (LaMa).50
passport-photoGerar foto de passaporte.100
image-to-textOCR (Tesseract). Retorna text em JSON, sem download_url.100

Ferramentas de edição de imagem

POST/api/v1/tools/{slug}
SlugDescrição
resize-imageRedimensionar. Passe img_resize_w e/ou img_resize_h.
compress-image, compress-jpg, compress-png, compress-webp, compress-gifComprimir com img_quality.
crop-imageRecortar região com img_crop_x/y/w/h.
rotate-imageRotacionar via img_rotate.
grayscale-imageConverter para escala de cinza.
blur-imageAplicar desfoque gaussiano.
watermark-imageAdicionar marca d'água de texto.
og-image-resizerRedimensionar para dimensões OG padrão (1200x630).

Ferramentas de edição de áudio e vídeo

POST/api/v1/tools/{slug}
SlugDescrição
audio-cutterCortar áudio. Passe start_time, end_time.
trim-videoCortar vídeo para um intervalo de tempo.
compress-videoComprimir com bitrate alvo ou preset de qualidade.
extract-audio-from-videoExtrair faixa de áudio como MP3.
remove-audio-from-videoRemover áudio do vídeo.
merge-videosMesclar vários arquivos de vídeo. Envie files[].
reverse-videoReproduzir vídeo ao contrário.
gif-makerCriar GIF animado a partir de quadros ou vídeo.

Ferramentas PDF

POST/api/v1/tools/{slug}
SlugDescrição
compress-pdfComprimir com qualidade 0–100 (mapeada para Ghostscript /screen, /ebook, /printer, /prepress).
merge-pdfMesclar vários PDFs. Envie files[].
split-pdfDividir PDF em páginas individuais.
pdf-page-removerRemover páginas específicas. Passe pages como lista separada por vírgulas.
protect-pdfAdicionar senha. Passe password.
unlock-pdfRemover senha. Passe password.
webpage-to-pdfConverter URL para PDF. Passe url em vez de file.

Saúde e limites

GET/api/v1/health

Sonda de liveness. Retorna status do serviço e versões detectadas dos binários (ImageMagick, FFmpeg, Ghostscript, LibreOffice, Tesseract). NÃO conta contra os rate limits.

GET/api/v1/limits

Inspeção somente leitura do seu uso atual do rate-limit. Retorna contadores diários e horários, cotas restantes e status de banimento. NÃO conta contra os rate limits.

Veja também

Solicitar um recurso

0 / 2000