DEV Community

visiohex
visiohex

Posted on

I built CompressGIF: local GIF compression, plus REST and MCP APIs

#showdev #webdev #api #mcp

A GIF can be useful in a README, bug report, or product demo—and still be too large to attach. Getting it below an upload limit often means trying compression settings, checking the animation, and trying again.

I’m sharing CompressGIF, a tool I built for that workflow. It has a browser compressor for local files and a separate cloud API for automation.

Start with the browser tool

The free browser tool processes your GIF on your device without uploading the file for compression. It keeps the output as an animated GIF and adds no watermark.

There are three modes:

  • Quality first: start with conservative compression and inspect the result.
  • Size first: try stronger palette and lossy settings when a smaller file matters more than fine detail.
  • Target size: try to get under a specific limit, with free presets for 100KB, 512KB, and 1MB.

Free usage supports three files per batch, up to 10MB per file. Pro adds larger batches, custom target sizes, and ZIP downloads.

A target is a goal, not a guarantee

CompressGIF uses Gifsicle. The useful tradeoff depends on the content: small UI text, flat illustrations, and video-like animations do not respond to compression in the same way.

By default, the tool preserves dimensions, animation duration, and loop behavior rather than silently dropping motion frames or resizing. Resizing is an explicit choice.

If a target cannot be reached, the tool says so. It keeps the smallest valid candidate, including the original when compression cannot improve it. I’d rather show a missed target than imply that every GIF can become 100KB without a visible tradeoff.

When checking a result, look beyond the byte count: inspect text, gradients, transparent edges, and playback timing.

Automate it with REST

For scripts and integrations, there is an asynchronous compression API. Unlike the browser tool, this is cloud processing: you upload a file or provide a public HTTPS GIF URL.

Here is an upload request targeting 1MB (1,000,000 bytes):

curl -X POST https://compressgif.net/api/v1/compressions \
  -H "Authorization: Bearer $COMPRESSGIF_API_KEY" \
  -H "Idempotency-Key: demo-upload-001" \
  -F "file=@animation.gif" \
  -F 'options={"mode":"target","targetBytes":1000000}'
Enter fullscreen mode Exit fullscreen mode

Keep the API key in a protected environment variable, not client-side code. Use a new idempotency key for each new file-and-options request, and reuse that key when retrying the same request after an uncertain response.

The response includes a top-level job id. Poll GET /api/v1/compressions/{id} every few seconds. Once the status is succeeded, read result.downloadUrl and check targetMet. A completed job can still miss the requested size. Stop polling on failed or canceled and inspect the error.

Or connect an MCP client

The Streamable HTTP endpoint at https://compressgif.net/api/mcp exposes three tools:

  • compress_gif
  • get_compression
  • get_usage

It uses the same API key and credit pool as REST. MCP accepts public HTTPS GIF URLs; local files should be uploaded through REST. A successful tool call starts a job—it does not mean compression has finished.

Free API access currently provides 500 credits per UTC calendar month after activation with a verified Gmail-based Google sign-in and a security check. It is subject to shared monthly compute capacity; target-size jobs cost more credits than quality/size jobs. The API documentation covers activation, limits, retention, and examples.

Privacy distinction: local browser compression keeps the GIF on your device. REST and MCP process it in the cloud, where file access expires after 24 hours. Importing a URL in the browser also contacts the image’s host.

If you work with GIFs in documentation or developer workflows, I’d appreciate feedback: which matters most to you—readable UI text, predictable file size, or batch automation?

Try CompressGIF · REST and MCP docs

Top comments (0)