Using PicsTag

A short reference for the two things people get stuck on — the shape of the CSV going in, and the shape of the file coming out. If you have never tagged a library before, theguides cover the judgement calls; this page covers the mechanics.

Adding images

There are two ways in, and they behave differently.

Files from your disk. Drag them into the drop zone. They are read into memory and go straight to the model — nothing is uploaded, and nothing is written back to your disk. A hundred at a time is comfortable; several hundred will make the tab work hard.
A CSV of image URLs. For images already live on your site or in a bucket. PicsTag fetches each one and processes it like a local file.

The CSV format

Two columns matter. Every other column in your file is ignored, so you can export straight from your CMS without cleaning it up first.

Column	Required	What it is
`image_url`	Yes	A publicly reachable http(s) URL. If it needs a login or a signed token, it will fail.
`asset_id`	Yes	Your own identifier. It is passed through untouched to the export, so you can join the results back onto your database.

Header names are matched loosely — underscores, spaces and capitalisation are stripped before matching, so Image URL,image_url andimageurl all work.

asset_id,image_url
SKU-1041,https://cdn.example.com/products/1041.jpg
SKU-1042,https://cdn.example.com/products/1042.jpg

Running the analysis

Nothing runs until you press Start analysis, andStop takes effect between images rather than at the end of the batch. The first run downloads about 250 MB of model files, which your browser then caches — the first image is slow, everything after it is fast, and your next visit skips the download entirely.

Two providers are available in Settings:

Local (default). An image classifier and a captioning model run in a Web Worker in your tab, on WebGPU where your browser supports it and WebAssembly where it does not. Free, unlimited, and nothing leaves the machine.
OpenRouter. Your own API key calls a cloud vision model — noticeably better output, and you pay that provider directly. The key is stored in your browser and the request goes from your browser to them; it never passes through us. With this provider, remote CSV images are fetched by the model server-side, which sidesteps the CORS failures that block some URLs in local mode.

Reviewing

Every suggested tag carries a confidence score and starts as pending. Nothing reaches your export until you accept it — the model never puts a keyword in your catalogue behind your back. You can work through the queue, or open the focus review to take one image at a time on its own page.

For a large batch, the fast path is to auto-accept everything above a confidence threshold and then read only what is left. That is the whole efficiency argument for AI tagging: it is not that the model is right about everything, it is that it is confidently right about the boring 80% —how accurate AI image tagging actually is goes into what it gets wrong.

The export format

CSV or JSON, same fields either way. Only accepted predicted tags and your own custom tags are written — pending and rejected tags are dropped.

Field	Contents
`asset_id`	Your CSV identifier, or the filename for local files.
`filename`	The original file name.
`file_size`	Bytes.
`width`,`height`	Pixel dimensions.
`description`	The caption, as you left it after editing. This is your alt text draft.
`validated_tags`	Accepted tags plus your custom ones, comma-separated.
`source_url`	The original URL for CSV rows; empty for local files.

PicsTag does not write metadata back into your image files. It produces a sidecar you import — seeIPTC and XMP metadata explained for how those fields map onto the embedded standards.

When something goes wrong

The models never finish downloading. A strict corporate proxy or an ad blocker is usually blocking the Hugging Face CDN. Try another network, or switch to the OpenRouter provider, which downloads nothing.
CSV rows fail with a network error. The image URL is not publicly reachable, or the host refuses cross-origin requests. The OpenRouter provider avoids this entirely, because the model fetches the URL itself.
It is slower than you expected. Your browser fell back to WebAssembly because WebGPU was unavailable. It still works; it is roughly an order of magnitude slower. Enabling hardware acceleration in your browser settings usually fixes it.
You lost your queue. The queue lives in memory, on purpose — nothing about your images is persisted anywhere. Reloading the tab clears it. Export before you close.

Still stuck? Tell us what happened — a real person reads it.