Integrating Zipic

Zipic supports URL Scheme, enabling both scripts and other apps to leverage Zipic’s full image compression capabilities.

URL Scheme

Zipic’s URL Scheme is: zipic://compress.

URL parameters can specify the objects to be compressed and compression options.

Specifying Compression Targets

zipic://compress?
  url=/Users/5km/Downloads/demo_jpeg.jpeg&
  url=/Users/5km/Downloads/demo_png.png&
  url=/Users/5km/Downloads/demo_folder

You can specify multiple targets, including both image paths and directory paths.

Specifying Compression Options Pro Only

zipic://compress?
  url=PATH_TO_IMAGE_OR_FOLDER&
  level=3.0&
  format=webp&
  directory=PATH_TO_SAVE_COMPRESSED_IMAGES&
  width=0&
  height=0&
  location=custom&
  addSuffix=false&
  suffix=-compressed&
  addSubfolder=false&
  specified=false

Compression Level

The higher the level, the greater the compression and the lower the quality. Generally, levels 2 or 3 provide a good balance between quality and size, but results may vary depending on the format.

Parameter: level, double precision

Range: 1~6, step: 1.0

zipic://compress?
  url=/Users/5km/Downloads/demo_jpeg.jpeg&
  level=3.0

Save Directory

Parameter: directory, path to save the files, string

To specify a save directory, use the location option set to custom.

Parameter: location, string, options:

• original
• custom

zipic://compress?
  url=/Users/5km/Downloads/demo_jpeg.jpeg&
  location=custom&
  directory=/Users/5km/Desktop

To save files to the default directory, you must enable the specified option and set it to true.

Parameter: specified, boolean, default value: false

• true
• false

zipic://compress?
  url=/Users/5km/Downloads/demo_jpeg.jpeg&
  location=custom&
  specified=true

Format Conversion

Parameter: format, string

Specifies the desired output format.

Options:

• original
• jpeg
• webp
• heic
• avif
• png

zipic://compress?
  url=/Users/5km/Downloads/demo_jpeg.jpeg&
  format=webp

Resize Image

Parameter: width, double

Sets the desired width, default is 0, which auto-adjusts.

Parameter: height, double

Sets the desired height, default is 0, which auto-adjusts.

Resize the image to 1920 pixels wide, maintaining the original aspect ratio.

// Resize the image to 1920 pixels wide, maintaining the original aspect ratio
zipic://compress?
  url=/Users/5km/Downloads/demo_jpeg.jpeg&
  width=1920

Example Usage

Using Terminal

To compress the image /Users/5km/Downloads/CleanshotX/demo.png, convert it to webp format, and save it to the Downloads directory, use the following URL Scheme:

zipic://compress?
  url=/Users/5km/Downloads/CleanshotX/demo.png&
  format=webp&
  directory=/Users/5km/Downloads&
  location=custom

You can execute this URL Scheme in the terminal using the macOS open command:

open "zipic://compress?url=/Users/5km/Downloads/CleanshotX/demo.png&format=webp&directory=/Users/5km/Downloads&location=custom"

The video below demonstrates the process in iTerm2, where the image is successfully compressed and saved in webp format in the Downloads directory.

Tip

You can automate image compression by scripting and using the URL Scheme.

Shortcuts

Using macOS Shortcuts and the Zipic URL Scheme, you can quickly compress selected images or directories in Finder. Below is the complete configuration for the Zipic shortcut:

Here’s a step-by-step explanation:

1. Obtain the list of selected files in Finder.
2. Parse the selected files into a list of file paths and store them in the paths variable.
3. Encode each item in paths as url=ITEM and save it to the urls list.
4. Concatenate each url in the urls list with & to form the URL parameters.
5. Combine zipic://compress? with the URL params to create the final URL.
6. Open the final URL to trigger Zipic’s image compression.

Download Zipic Shortcut

Tip

This is a basic shortcut. You can add options for compression settings to customize it further.

After downloading the shortcut, import it into Shortcuts and enable it for Finder with a custom keyboard shortcut to quickly compress selected images and directories.

Note

As shown in the video, there are two ways to quickly compress selected files and directories.

Method 1: Use the shortcut key ^+⌥+C (customizable)

Method 2: Right-click the selected files → Quick Actions → Zipic

Programmatic Access

You can invoke Zipic’s compression capabilities from any programming language that supports URL handling. Here are examples in different languages, based on the target used in the Terminal:

Swift

import AppKit

let urlString = "zipic://compress?url=/Users/5km/Downloads/CleanshotX/demo.png&format=webp&directory=/Users/5km/Downloads&location=custom"

if let url = URL(string: urlString) {
    if NSWorkspace.shared.open(url) {
        print("URL successfully opened")
    } else {
        print("Failed to open URL")
    }
} else {
    print("Invalid URL")
}

Python

import webbrowser

url = "zipic://compress?url=/Users/5km/Downloads/CleanshotX/demo.png&format=webp&directory=/Users/5km/Downloads&location=custom"
webbrowser.open(url)

Golang

package main

import (
    "os/exec"
    "log"
)

func main() {
    url := "zipic://compress?url=/Users/5km/Downloads/CleanshotX/demo.png&format=webp&directory=/Users/5km/Downloads&location=custom"
    err := exec.Command("open", url).Start()
    if err != nil {
        log.Fatal(err)
    }
}

Javascript

const url = "zipic://compress?url=/Users/5km/Downloads/CleanshotX/demo.png&format=webp&directory=/Users/5km/Downloads&location=custom";
window.location.href = url;

Typescript

const url = "zipic://compress?url=/Users/5km/Downloads/CleanshotX/demo.png&format=webp&directory=/Users/5km/Downloads&location=custom";
window.location.href = url;

We’ve implemented a Raycast extension using this URL Scheme, allowing Raycast users to quickly compress images directly from Finder. Check out the Raycast Extension Guide for more details.

For developers, we’re planning to release a VS Code extension for in-project image compression—stay tuned.