zpan/docs/tool-integrations.md

Tool Integrations

ZPan Image Hosting integrates with popular screenshot and upload tools. All configuration is generated client-side from your API key — the server never stores or transmits plaintext keys.

Prerequisites

1. Enable Image Hosting in your ZPan workspace.
2. Create an API key under Settings → Image Hosting → API Keys.
3. Save the key immediately — it is only shown once at creation time.
4. Navigate to Settings → Image Hosting → Tool Integration and paste the key you saved.

---

PicGo / PicList

PicGo is a cross-platform image uploader with a plugin ecosystem.

Installation

# Install the web-uploader plugin (CLI)
picgo install picgo-plugin-web-uploader

# Or use the GUI Plugin Manager: search for "web-uploader" and install

Configuration

1. Open PicGo → Settings → Uploader → Custom Web.
2. Generate the JSON in the Tool Integration panel and paste it into the Custom Web configuration.
3. Set Custom Web as the default uploader.
4. Click Test to verify the upload works.

The generated JSON looks like:

{
  "url": "https://<your-zpan-host>/api/ihost/images",
  "paramName": "file",
  "jsonPath": "data.url",
  "customHeader": "{\"Authorization\":\"Bearer <your-key>\"}",
  "customBody": "{\"path\":\"{year}/{month}/{fileName}\"}"
}

---

uPic (macOS)

uPic is a macOS image uploader that supports custom HTTP hosts.

Configuration

1. Open uPic → Preferences → Host → click + → choose Custom.
2. Generate the JSON in the Tool Integration panel.
3. In uPic, use File → Import Config and select the generated JSON file (save it first).

Alternatively, fill in the fields manually:

Field	Value
API URL	https://<host>/api/ihost/images
File Form Key	file
Authorization Header	Bearer <your-key>
Response Field	data.url

---

ShareX (Windows)

ShareX supports custom upload targets via .sxcu configuration files.

Installation

1. Generate and download the zpan-ihost.sxcu file from the Tool Integration panel.
2. Double-click the file — ShareX will automatically import it as a custom uploader.
3. In ShareX go to Destinations → Custom Uploader Settings → verify "ZPan Image Host" is listed.
4. Set the active destination to ZPan Image Host under Destinations → Image Uploader.

The .sxcu file contains:

{
  "Version": "15.0.0",
  "Name": "ZPan Image Host",
  "DestinationType": "ImageUploader, FileUploader",
  "RequestMethod": "POST",
  "RequestURL": "https://<host>/api/ihost/images",
  "Headers": { "Authorization": "Bearer <your-key>" },
  "Body": "MultipartFormData",
  "FileFormName": "file",
  "Arguments": { "path": "%y/%mo/$filename$" },
  "URL": "{json:data.url}",
  "ErrorMessage": "{json:error}"
}

---

Flameshot (Linux)

Flameshot is an open-source screenshot tool with scripting support.

Requirements

• curl
• jq
• xclip (X11) or wl-clipboard (wl-copy) for Wayland

Usage

1. Copy the generated script from the Tool Integration panel.
2. Save it as ~/bin/zpan-upload.sh and make it executable:

chmod +x ~/bin/zpan-upload.sh

3. Run after capture:

flameshot gui --raw | ~/bin/zpan-upload.sh

Or bind it as a keyboard shortcut in your desktop environment.

The script:

IHOST_KEY="<your-key>"
flameshot gui --raw | curl \
  -H "Authorization: Bearer $IHOST_KEY" \
  -F "file=@-" \
  -F "path=screenshots/$(date +%Y/%m)/$(date +%s).png" \
  https://<host>/api/ihost/images \
  | jq -r '.data.url' | xclip -selection clipboard

For Wayland, replace xclip -selection clipboard with wl-copy.

See Flameshot scripting docs for more configuration options.

---

Security Notes

• API keys are hashed on the server. Never share your key or commit it to version control.
• Keys can be revoked any time under Settings → Image Hosting → API Keys.
• The pasted key in the Tool Integration panel is ephemeral — it is never persisted to localStorage or sent to the server.