How It Works
Metadata Studio turns a folder of stock images into editable metadata in six steps: add a provider key, choose a model, upload images, generate a batch, edit the results, and export a CSV. This page explains each step and the controls that keep a large batch moving.
Before you start
Metadata Studio is bring-your-own-key, so the only setup is a key from one of the three supported providers: Gemini, OpenRouter or Groq. There is no account and no pricing. Paste a key into the API Keys dialog, click Test, and you are ready to generate. Keys are stored in your browser localStorage, forwarded with each request through a stateless relay, and never stored on the server or written to logs. If you publish the app for a team, an optional auth token can protect the API.
The six steps
- Add an API key. Click API Keys, pick a provider tab and add one or more keys. Metadata Studio supports Gemini (the default), OpenRouter and Groq. Use Test to check a key; the badge shows the real reason as Good, Quota, Invalid or Model unavailable.
- Choose a model. Pick a model for that provider, or click Refresh models to pull the live list your key can use. Vision-capable models are labelled, which matters because the generator needs a model that can actually see the image.
- Upload images. Drop JPG, JPEG, PNG, WEBP or GIF files, up to 25 MB each, into the dropzone. Every upload is checked by MIME type and magic bytes and gets a downscaled preview.
- Generate the batch. Set title length, description length, keyword count, content type and concurrency, then click Generate Batch. Items cycle through the available providers and keys top to bottom.
- Edit the results. Titles, descriptions, keywords and Shutterstock categories are all editable inline, and each item shows the provider and model that produced it. Use Regenerate for a fresh result on one image.
-
Export a CSV. Switch the topbar tabs to Adobe Stock or Shutterstock and export.
The download is named
Adobe_Stock_CSV_<DD-MM-YYYY>.csvorShutterstock_CSV_<DD-MM-YYYY>.csv, up to 2,000 rows.
Key rotation and cooldown
If you add multiple keys, the queue rotates through them while it works. When a key hits a quota or transient error, it is cooled down with a jittered delay and the next available key is tried, so one rate-limited key does not stall the whole batch. An invalid key is treated differently: it is marked Invalid instead of being recycled. You can lower concurrency if a provider is throttling you.
Concurrency and batch controls
Concurrency is how many images are processed at once; the choices are two or three. Higher concurrency finishes small batches faster, while lower concurrency is gentler on free tiers. The queue stays in your control throughout:
- Stop aborts the running batch immediately.
- Cancel drops a single in-flight item.
- Retry failed re-runs only the items that errored, leaving good results alone.
- Regenerate asks for a fresh result for one image.
- Clear empties the queue when you are finished.
Failed items stay visible with their error reason, so a provider hiccup or a bad model choice never costs you the rest of the batch. This is what makes the difference between a retry being a single click and starting over.
Text-only retry
Sometimes a model rejects image input. When that happens the relay retries that item once in text-only mode using the filename, and the item is flagged text-only. The result is still editable, but it is a hint that the model could not read the picture. Click Refresh models and choose a model labelled as vision capable for better results.
Working with larger folders
Each upload becomes a downscaled 512-pixel JPEG preview before it is sent, which keeps requests small and predictable. Concurrency of two is a safe default on free tiers; three clears a small batch faster when your provider allows it. For a folder of a few hundred images, generate in batches and use Clear between runs so the workspace stays readable. Remember that a single CSV export is capped at 2,000 rows, so larger libraries should be exported in slices.
Common errors and what they mean
Errors are surfaced per item with a short reason, and the ones you are most likely to meet are handled without losing your place in the queue.
| Error or badge | What to do |
|---|---|
| invalid_model | The provider retired or renamed the model. Click Refresh models and pick an available id. |
| invalid_key | The key is wrong or lacks permission. Re-check it; the key is marked Invalid. |
| quota | The key hit a rate limit or ran out of credits. Wait for the cooldown, add another key, or lower concurrency. |
| truncated | The model ran out of output budget. Lower the keyword count and try again. |
| content_blocked | A provider safety filter stopped the request. Try another image or provider. |
| text-only | The model could not read the image. Pick a model labelled as vision capable. |
A note on exports
The Adobe export writes Filename,Title,Keywords,Category,Releases and leaves Category
blank unless you set it. The Shutterstock export classifies categories from the image, and at least
one valid category per row is required; a row without one is rejected and the error names the files
rather than producing a CSV the marketplace will refuse. The client also warns, without blocking,
when a row has fewer than 20 keywords or is marked Editorial.
For field-by-field detail, see the templates and column references or the marketplace guides for Adobe Stock and Shutterstock.
Run the six steps yourself
Add a key, upload a few images, and watch the batch fill in editable metadata.