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”).
A Product Marketing Manager at Filestack with four years of dedicated experience. As a true technology enthusiast, they pair marketing expertise with a deep technical background. This allows them to effectively translate complex product capabilities into clear value for a developer-focused audience.
Read More →