Overview
This guide demonstrates how to turn a single uploaded photo into a structured mood entry using Filestack’s image sentiment transform. The reference implementation uses the Filestack Picker to upload an image, extracts the file handle, then calls image_sentiment on the handle. The UI displays a preview, emotion bars, a dominant “journal mood,” and the raw JSON for debugging.
The solution highlights production-oriented patterns:
-
Handle-first pipeline: Picker → Handle → Transform
-
Security segment placement compatible with protected files
-
403-safe URL construction with a fallback shape
Why mood journaling for image sentiment
Image sentiment is most useful when it becomes a small, reliable unit of data—mood, confidence, timestamp. A journaling UI provides that structure and makes the transform’s output directly actionable for wellness features, timeline summaries, or personalized check-ins.
Of course. Here is the content formatted with h2 headings and code blocks.
API Call (Handle-Based)
Two URL shapes are commonly used, depending on security and transform routing. The demo attempts them in order and treats a 401/403 status as a signal to try the next.
Transform-first with explicit security segment
https://cdn.filestackcontent.com/image_sentiment/security=policy:<POLICY>,signature:<SIGNATURE>/<HANDLE>
API key path with shorthand security
https://cdn.filestackcontent.com/<APIKEY>/security=p:<POLICY>,s:<SIGNATURE>/image_sentiment/<HANDLE>Response Examples
Successful Response
If emotional content is detected, the API returns an object with confidence scores for each emotion.
{
"emotions": {
"HAPPY": 99.7474517822,
"FEAR": 0.0966,
"SAD": 0.0441,
"ANGRY": 0.0396,
"SURPRISED": 0.0332,
"DISGUSTED": 0.0135,
"CONFUSED": 0.0131,
"CALM": 0.0125
}
}Empty Response
If no emotional content is detected, the emotions object will be empty.
{ "emotions": {} }Mood selection rule
-
Pick the highest-scoring emotion ≥ MinConfidence (default 10%).
-
If nothing qualifies or
emotionsis empty → “No detectable mood.”
This yields a consistent label while avoiding noise from extremely low confidence scores.
Production notes
-
Policy & signature: Generate on the server; set short expiries; include the required permissions (typically
readandconvert). -
Storage: Persist
{ handle, mood, score, timestamp }with optional notes or tags. -
Privacy: Provide visibility and deletion/export paths for end users.
-
Bias & model limits: Treat emotion scores as a heuristic signal; lighting, pose, and culture can affect results.
-
Latency: Show progress during uploads; the transform is fast but asynchronous.
Working Demo
This app and image sentiment should fit well in our text sentiment analysis tutorial.
Full reference implementation (index.html)
Single-file, light mode, no frameworks. Uses Filestack v4 picker and a fallback-aware request helper for image_sentiment.
Extensions for the future
-
Calendar & trends: show a monthly heatmap or weekly bar of mood counts.
-
Notes & tags: pair each entry with free-text journaling or activities.
-
Batch import: create entries from an album; filter by confidence thresholds.
-
Custom mapping: collapse multiple emotions into broader categories (e.g., “Positive,” “Neutral,” “Tense”).
Carl is a Product Marketing Manager at Filestack with four years of hands-on experience in React, JavaScript, Django, and Python. He bridges the gap between product and developer, translating how Filestack’s APIs and SDKs actually work into content that’s useful for the engineers building with them. His writing covers file handling workflows, upload integrations, and real-world implementation patterns, written from the perspective of someone who has built with these tools firsthand.
Read More →