Auto-tag images in n8n with Uploadcare object recognition
Trust Jamin OkpukoroInย this guide, youโll learn how toย auto-tag every image upload inย n8n with the Uploadcare
Object Recognition add-on. Byย the end, youโll have aย workflow where each file.uploaded event runs
the add-on and writes high-confidence labels toย your database orย CMS.
The Object Recognition add-on isย an
Uploadcare REST API feature that runs anย uploaded image through
AWS Rekognition and stores the detected labels onย the file. Each label carries a Name and a
Confidence score, soย you can keep only the tags the model isย sure about.
For the basics onย connecting n8n toย Uploadcare, see the main n8n + Uploadcare integration guide.
Ifย you want aย fully ready-to-import workflow.json version ofย this tutorial,
you can find itย inย the image-tagging folder ofย the repo.
Prerequisites
Toย follow along with this tutorial, youโll need the following:
- Aย free Uploadcare account
- The Object Recognition add-on enabled onย your Uploadcare project.
- Access toย anย n8n instance (self-hosted orย n8n.cloud)
- Aย database, CMS, orย HTTP endpoint toย receive the tags.
What weโre building
- Anย Uploadcare webhook fires on
file.uploadedand hits anย n8n Webhook node. - n8n triggers the
aws_rekognition_detect_labelsadd-on for that file UUID. - The workflow polls the add-on status until itย reports
done. - n8n reads the labels from the fileโs
appdataand keeps only high-confidence tags. - The tags are written toย yourย DB orย CMS for organization and search.
The n8n workflow for auto-tagging images with Uploadcareโs Object Recognition add-onStepย 1: Receive the upload event
The workflow starts when Uploadcare tells n8n aย file landed. Aย Webhook node gives you aย URL to register, andย a Set node pulls the file UUID out ofย the payload soย the rest ofย the workflow can reference itย cleanly.
Add the Webhook node
- Click the + button toย add aย new node and search for the Webhook node.
- Set the HTTP Method to
POST. - Copy the nodeโs Production URL.
- Inย the Uploadcare Dashboard, goย toย API โ Webhooks, paste the URL, and subscribe
toย the
file.uploadedevent.
Uploadcare then POSTs aย JSON payload toย that URL onย every new upload. The JSON isย shaped like this:
{
"event": "file.uploaded",
"data": {
"uuid": "..."
}
}
n8n Webhook node configured for the Uploadcare file.uploaded eventExtract the UUID
- Add aย Set node after the Webhook node and rename it
Extract UUID. - Add aย field, set its Name to
uuid, and set its Type toString. - For the value, enter the expression
{{ $json.body.data.uuid }}.
This reads body.data.uuid from the incoming webhook payload, which isย where
Uploadcare puts the file identifier, and stores itย asย aย clean uuid field. Every downstream node can
then reference {{ $json.uuid }} without digging back into the raw event body.
n8n Set node extracting the file UUID from the webhook payloadStepย 2: Trigger the Object Recognition add-on
The add-on runs server-side and asynchronously, soย you start itย withย an HTTP Request node.
The execute call (Add-Ons REST API reference) doesnโt return labels right away.
Instead, itย returns a request_id that you poll in the next step.
Configure the execute request
- Add anย HTTP Request node after the Set node and rename it
Execute Rekognition. - Set the Method to
POST. - Set the URL to
https://api.uploadcare.com/addons/aws_rekognition_detect_labels/execute/.
n8n HTTP Request node set toย POST the Object Recognition execute endpointAdd the authentication headers
Every Uploadcare REST API call needs the Authorization and Accept headers, and because this auth
isย server-side only, never ship itย toย aย browser.
- Toggle Send Headers onย and set the Specify Headers field to
Using Fields Below. - Add aย header with Name
Authorizationand ValueUploadcare.Simple YOUR_PUBLIC_KEY:YOUR_SECRET_KEY. - Add aย second header with Name
Acceptand Valueapplication/vnd.uploadcare-v0.7+json.
Send the target UUID
-
Toggle Send Body onย and set the Body Content Type to
JSON. -
Set Specify Body to
Using JSON. -
Enter this JSON body, where
targetisย the file the add-on should analyze:{ "target": "{{ $json.uuid }}" } -
Open Options โ Response and set Response Format to
JSON.
Note: Uploadcareโs REST API responds with the content type application/vnd.uploadcare-v0.7+json.
n8n doesnโt auto-detect that vendor +json type asย JSON, soย without Response Format set to JSON
itย hands you the body asย aย raw string under a data field, and expressions like {{ $json.request_id }}
come back empty. Set Response Format to JSON here and onย every Uploadcare REST call inย this
workflow soย n8n parses the body and you can read its fields directly.
The response includes a request_id youโll use toย poll for completion inย the next step.
Stepย 3: Wait and poll for completion
Now that the add-on isย running, give itย aย moment and then check onย it.
Add aย Wait node
- Addย a Wait node after the execute request.
- Set itย toย wait for around
8seconds, giving Rekognition time toย process the image.
n8n Wait node set toย pause for 8ย secondsCheck the add-on status
-
Add anย HTTP Request node after the Wait node and rename it
Check Add-on Status. -
Set the Method to
GET. -
Set the URL toย the status endpoint, passing the
request_idfrom the execute response:https://api.uploadcare.com/addons/aws_rekognition_detect_labels/execute/status/?request_id={{ $json.request_id }} -
Toggle Send Headers onย and add the same
AuthorizationandAcceptheaders from Stepย 2. -
Open Options โ Response and set Response Format to
JSON, just asย inย Stepย 2, so{{ $json.status }}parses instead ofย arriving asย aย string underdata.
n8n HTTP Request node polling the Object Recognition status endpointBranch onย the result
- Addย an If node after the status check.
- Add aย condition comparing
{{ $json.status }}todone.
When status equals done (the true output), the labels are ready, soย the workflow continues.
Otherwise, route the false output back toย aย short Wait &ย Retry node that loops toย the status check.
Tip: Ifย aย file occasionally takes longer, this loop keeps polling instead ofย failing the moment a result isnโt ready.
n8n Ifย node branching onย the done statusStepย 4: Where doย the recognition results live?
The add-on stores its results onย the file itself, not inย the poll response, which only reports
{"status": "done"}. The labels land in appdata.aws_rekognition_detect_labels.data.Labels, where
each entry has a Name and a Confidence score, soย once the status reports done, you fetch the file
toย read them.
Note: Two things toย watch out for:
-
The
appdatafield isย only returned when you ask for itย with?include=appdata; aย plainGET /files/<UUID>/comes back withappdata: null. -
The labels array is
Labelswith aย capitalL, because itย mirrors the raw AWS Rekognition response.
Fetch the file info
-
Onย theย If nodeโs true output, add anย HTTP Request node and rename it
Get File Info. -
Set the Method to
GET. -
Set the URL toย the file endpoint, using the UUID captured back inย Stepย 1, with the
?include=appdataquery parameter soย the response carries the add-on results:https://api.uploadcare.com/files/{{ $(โExtract UUIDโ).item.json.uuid }}/?include=appdata -
Toggle Send Headers onย and add the same
AuthorizationandAcceptheaders from Stepย 2. -
Open Options โ Response and set Response Format to
JSON, just asย inย Stepย 2, soย n8n parses the body andappdataarrives asย anย object instead ofย aย string underdata.
This reads the same file the add-on analyzed and returns the full file object (File REST API reference). The ?include=appdata
parameter isย what makes Uploadcare attach the appdata.aws_rekognition_detect_labels.data.Labels
array that the Object Recognition add-on wrote; withoutย it, appdata comes back null.
n8n HTTP Request node fetching the Uploadcare file info with appdataStepย 5: Filter tags byย confidence
Aย Code node turns the raw labels into aย tidy tag list, dropping anything below your threshold. Add aย Code node after the file fetch, set its language toย JavaScript, and enter the following:
const CONFIDENCE_THRESHOLD = 80;
const file = $input.first().json;
const labels = file?.appdata?.aws_rekognition_detect_labels?.data?.Labels || [];
const tags = labels
.filter((label) => label.Confidence >= CONFIDENCE_THRESHOLD)
.map((label) => label.Name);
return [
{
json: {
uuid: file.uuid,
cdnUrl: `https://2ta6v1zvst.ucarecd.net/${file.uuid}/`,
tags,
tagCount: tags.length,
},
},
];The code above:
- Sets a
CONFIDENCE_THRESHOLDofย 80ย so only labels the model isย reasonably sure about make the cut. - Reads the labels from
appdata.aws_rekognition_detect_labels.data.Labels(capitalL), defaulting toย anย empty array ifย the add-on returned nothing. - Keeps each labelโs
Nameand discards its score, then returns aย single record with theuuid, aย ready-to-usecdnUrl, the filteredtags, and atagCount.
Note: 2ta6v1zvst.ucarecd.net isย this projectโs CDN domain.
Find yours inย the Uploadcare Dashboard under Delivery โ CDN Domain names,
and use itย inย place ofย the shared ucarecdn.com host inย the URLs throughout this guide.
What the tags look like
Run aย real photo through this and you can watch the threshold doย its job. Aย car photo returns these
high-confidence labels, while aย borderline Sports Car guess atย 58% confidence gets filtered out:
{
"uuid": "<file-uuid>",
"cdnUrl": "https://2ta6v1zvst.ucarecd.net/<file-uuid>/",
"tags": ["Machine", "Wheel", "Tire", "Alloy Wheel", "Car", "Car Wheel", "Spoke", "Vehicle", "Person"],
"tagCount": 9
}That single dropped label isย the difference between aย clean tag set and aย noisy one, which isย exactly
what the CONFIDENCE_THRESHOLD controls.
Stepย 6: Store the tags
With aย clean tag list ready, aย Set node assembles the final record andย a Data Table node stores itย inย n8nโs built-in, lightweight datastore, noย external database toย run.
Assemble the record
- Add aย Set node after the Code node and rename it
Build Tag Record. - Add fields for
uuid,cdnUrl, andtags, mapping each from the Code nodeโs output.
n8n Set node assembling the uuid, cdnUrl, and tags recordStore the tags inย aย Data Table
n8nโs built-in Data Tables give you aย local, lightweight store with noย extra service toย run, aย good fit for this workflow. First create the table:
- From the n8n Overview, open the Data tables tab and select Create data table.
- Name it
image_tags, then add three string columns:uuid,cdnUrl, andtags.
Then write each tagged image intoย it:
- Add aย Data Table node after the Set node and rename it
Store Tags (Data Table). - Set the Operation toย Insert row and choose your
image_tagstable. - With Map Each Column Manually, map each column toย the record:
uuidโ{{ $json.uuid }}cdnUrlโ{{ $json.cdnUrl }}tagsโ{{ $json.tags.join(", ") }}โ the column isย text, soย join the array into aย string.
Each new upload now appends aย row you can browse right inย the n8n UI.
n8n Data Table node inserting the uuid, cdnUrl, and tags rowNote: Data Tables ship with recent n8n versions. Onย anย older release, orย ifย you want aย store shared
across systems, swap this node for anย HTTP Request (orย the Postgres node) that writes the same
uuid, cdnUrl, and tags toย your database, CMS, orย API. From here you can power faceted search,
auto-foldering, orย alerting whenever aย specific label appears.
Conclusion
Inย this guide, youโve learned how toย turn aย new upload into high-confidence tags automatically: triggering the Object Recognition add-on, filtering its labels byย confidence, and storing the result for later use.
Feel free toย import the workflow from the image-tagging folder ofย the repo and adapt itย toย your own database, CMS, orย API.
Some possible next steps:
- Faceted search: Index the
tagsarray soย users can filter the media library byย label. - Auto-foldering: Route files into collections based onย their top label.
- Label alerts: Notify aย channel whenever aย specific label, such asย aย brand orย aย person, appears.
For more workflows built onย the same execute-then-poll REST API pattern, see how toย convert documents toย PDF automatically inย n8n.
FAQs
Doย Iย need toย poll instead ofย relying onย the webhook alone?
Yes. The file.uploaded webhook tells you aย file exists, but the Object Recognition add-on runs
asynchronously and finishes aย little later. The execute call returns a request_id, and polling the
status endpoint with that request_id confirms the labels are ready before you read them.
How doย I tune which tags Iย keep?
Adjust the CONFIDENCE_THRESHOLD inย the Code node, which compares against each labelโs Confidence
score. For aย clean, low-noise tag set, use aย higher value such asย 90ย toย keep only the most certain
labels; for broader coverage, use aย lower value toย capture more tags atย the cost ofย some noise.
Where does the Object Recognition add-on store its results?
Onย the fileโs appdata, not inย the poll response. After the add-on completes,
GET /files/<UUID>/?include=appdata returns appdata.aws_rekognition_detect_labels.data.Labels
(capital L), where each entry has a Name and a Confidence value. Without the ?include=appdata
parameter, appdata comes back null.
Why are myย tags empty even though the add-on ran?
Three things cause anย empty tag list, and any one ofย them isย enough:
- Response Format isnโt set toย JSON. Uploadcare replies with
application/vnd.uploadcare-v0.7+json, which n8n leaves asย aย raw string under adatakey unless the HTTP Request nodeโs Response Format isJSON. While itโs aย string,appdataisย unreachable. ?include=appdataisย missing from theGet File InfoURL, soย the response hasappdata: null.- The labels key is
Labels, notlabels(capitalL, mirroring the AWS Rekognition response).
Fix all three and the same image returns its labels, for example Person, Man, and Portrait at
high confidence.