Serve direct thumbnail URLs to reduce load on main app server

ami/main/admin.py

@@ -28,6 +28,7 @@
     Site,
     SourceImage,
     SourceImageCollection,
+    SourceImageThumbnail,
     Tag,
     TaxaList,
     Taxon,
@@ -327,6 +328,10 @@ class SourceImageAdmin(AdminBase):
         "path",
     )
 
+    # Populated from the source file during sync/upload; read-only here so
+    # operators don't clobber them. The API stays writable for fixups.
+    readonly_fields = ("size", "last_modified", "checksum", "checksum_algorithm")
+
     def get_queryset(self, request: HttpRequest) -> QuerySet[Any]:
         return (
             super()
@@ -336,6 +341,17 @@ def get_queryset(self, request: HttpRequest) -> QuerySet[Any]:
         )
 
 
+@admin.register(SourceImageThumbnail)
+class SourceImageThumbnailAdmin(AdminBase):
+    """Admin panel for ``SourceImageThumbnail`` model."""
+
+    list_display = ("source_image", "path", "label", "width", "height", "size")
+    list_filter = ("source_image__deployment__project", "source_image__deployment__data_source", "label")
+
+    def get_queryset(self, request: HttpRequest) -> QuerySet[Any]:
+        return super().get_queryset(request).select_related("source_image", "source_image__deployment")
+
+
 class ClassificationInline(admin.TabularInline):
     model = Classification
     extra = 0

ami/main/api/serializers.py

@@ -72,6 +72,19 @@ class Meta:
         ]
 
 
+class SourceImageThumbnailSerializer(DefaultSerializer):
+    """Adds a ``thumbnails`` field via :meth:`SourceImage.thumbnail_urls`.
+    Viewsets must apply :meth:`SourceImageQuerySet.with_thumbnails`.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.fields["thumbnails"] = serializers.SerializerMethodField()
+
+    def get_thumbnails(self, obj: SourceImage) -> dict[str, str]:
+        return obj.thumbnail_urls(request=self.context.get("request"))
+
+
 class SourceImageNestedSerializer(DefaultSerializer):
     event_id = serializers.PrimaryKeyRelatedField(source="event", read_only=True)
 
@@ -90,7 +103,7 @@ class Meta:
         ]
 
 
-class ExampleSourceImageNestedSerializer(DefaultSerializer):
+class ExampleSourceImageNestedSerializer(SourceImageThumbnailSerializer):
     class Meta:
         model = SourceImage
         fields = [
@@ -1092,7 +1105,7 @@ class Meta:
         ]
 
 
-class SourceImageListSerializer(DefaultSerializer):
+class SourceImageListSerializer(SourceImageThumbnailSerializer):
     detections_count = serializers.IntegerField(read_only=True)
     detections = CaptureDetectionsSerializer(many=True, read_only=True, source="filtered_detections")
     deployment = DeploymentNestedSerializer(read_only=True)
@@ -1111,7 +1124,6 @@ class Meta:
             "event",
             "url",
             "path",
-            # "thumbnail",
             "timestamp",
             "width",
             "height",
@@ -1459,7 +1471,7 @@ class Meta:
         ]
 
 
-class EventCaptureNestedSerializer(DefaultSerializer):
+class EventCaptureNestedSerializer(SourceImageThumbnailSerializer):
     """
     Load the first capture for an event. Or @TODO a single capture from the URL params.
     """

ami/main/api/views.py

@@ -2,13 +2,15 @@
 import logging
 from statistics import mode
 
+from django.conf import settings
 from django.contrib.postgres.search import TrigramSimilarity
 from django.core import exceptions
+from django.core.files.storage import default_storage
 from django.db import models
 from django.db.models import OuterRef, Prefetch, Q, Subquery
 from django.db.models.query import QuerySet
 from django.forms import BooleanField, CharField, IntegerField
-from django.shortcuts import get_object_or_404
+from django.shortcuts import get_object_or_404, redirect
 from django.utils import timezone
 from django_filters.rest_framework import DjangoFilterBackend
 from drf_spectacular.types import OpenApiTypes
@@ -449,9 +451,10 @@ def get_queryset(self) -> QuerySet:
                 Prefetch(
                     "captures",
                     queryset=SourceImage.objects.order_by("-size").select_related(
-                        "deployment",
-                        "deployment__data_source",
-                    )[:num_example_captures],
+                        "deployment", "deployment__data_source"
+                    )
+                    # Required by SourceImage.thumbnail_urls in the nested serializer.
+                    .with_thumbnails()[:num_example_captures],
                     to_attr="example_captures",
                 )
             )
@@ -630,11 +633,11 @@ def get_queryset(self) -> QuerySet:
             self.require_project = True
         project = self.get_active_project()
 
-        queryset = queryset.select_related(
-            "event",
-            "deployment",
-            "deployment__data_source",
-        ).order_by("timestamp")
+        queryset = (
+            queryset.select_related("event", "deployment", "deployment__data_source")
+            # Required by SourceImage.thumbnail_urls in SourceImageThumbnailSerializer.
+            .with_thumbnails().order_by("timestamp")
+        )
 
         if self.action == "list":
             # It's cumbersome to override the default list view, so customize the queryset here
@@ -851,6 +854,47 @@ def unstar(self, _request, pk=None) -> Response:
             raise api_exceptions.ValidationError(detail="Source image must be associated with a project")
 
 
+class SourceImageThumbnailViewSet(DefaultReadOnlyViewSet, ProjectMixin):
+    """
+    Endpoint for capture thumbnails
+    """
+
+    queryset = SourceImage.objects.all()
+
+    permission_classes = [ObjectPermission]
+
+    def list(self, request):
+        # Only ``/captures/thumbnails/<pk>/?label=...`` is defined; listing has no
+        # meaning here (which capture's thumbnails?), so 405 rather than a fake 404.
+        raise api_exceptions.MethodNotAllowed(
+            method="GET", detail="Listing thumbnails is not supported; request a single capture's thumbnail by pk."
+        )
+
+    def retrieve(self, request, pk=None):
+        _sizes = settings.THUMBNAILS["SIZES"]
+        if not _sizes:
+            # Empty THUMBNAILS['SIZES'] is a misconfiguration — clear API error, not a 500.
+            raise api_exceptions.NotFound(detail="No thumbnail sizes are configured (settings.THUMBNAILS['SIZES']).")
+
+        label = self.request.query_params.get("label") or next(iter(_sizes))
+        size = _sizes.get(label, None)
+        if size is None:
+            raise api_exceptions.ValidationError(
+                detail=f"Invalid thumbnail size label provided: {label} not in {', '.join(_sizes.keys())}"
+            )
+        obj: SourceImage = self.get_object()
+        try:
+            thumb = obj.find_or_generate_thumbnail_for_label(label)
+        except exceptions.ObjectDoesNotExist as e:
+            raise api_exceptions.NotFound(detail=f"{e}")
+        response = redirect(default_storage.url(thumb.path))
+        # Redirects aren't browser-cached by default. max-age stays well below the
+        # presigned-URL lifetime (AWS_QUERYSTRING_EXPIRE default 3600s) so a cached
+        # redirect never points at an expired signature.
+        response["Cache-Control"] = "private, max-age=300"
+        return response
+
+
 class SourceImageCollectionViewSet(DefaultViewSet, ProjectMixin):
     """
     Endpoint for viewing capture sets or samples of captures.

ami/main/migrations/0091_sourceimagethumbnail_and_more.py

@@ -0,0 +1,44 @@
+# Generated by Django 4.2.10 on 2026-06-03 10:16
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("main", "0090_session_time_gap_seconds_help_text"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="SourceImageThumbnail",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("path", models.CharField(blank=True, max_length=255)),
+                ("label", models.CharField(max_length=255)),
+                ("width", models.IntegerField(blank=True, null=True)),
+                ("height", models.IntegerField(blank=True, null=True)),
+                ("size", models.BigIntegerField(blank=True, null=True)),
+                ("last_modified", models.DateTimeField(auto_now_add=True, null=True)),
+                (
+                    "source_image",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="thumbnails",
+                        to="main.sourceimage",
+                    ),
+                ),
+            ],
+            options={
+                "indexes": [models.Index(fields=["source_image", "label"], name="main_source_source__b0d4cd_idx")],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name="sourceimagethumbnail",
+            constraint=models.UniqueConstraint(
+                fields=("source_image", "label"), name="unique_source_image_thumbnail_label"
+            ),
+        ),
+    ]

ami/main/migrations/0092_alter_sourceimage_checksum_and_more.py

@@ -0,0 +1,47 @@
+# Generated by Django 4.2.10 on 2026-06-04 19:24
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("main", "0091_sourceimagethumbnail_and_more"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="sourceimage",
+            name="checksum",
+            field=models.CharField(
+                blank=True,
+                help_text="Checksum of the image file, read from the source file in image storage.",
+                max_length=255,
+                null=True,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="sourceimage",
+            name="checksum_algorithm",
+            field=models.CharField(
+                blank=True, help_text="Algorithm used for the checksum (e.g. MD5, SHA256).", max_length=255, null=True
+            ),
+        ),
+        migrations.AlterField(
+            model_name="sourceimage",
+            name="last_modified",
+            field=models.DateTimeField(
+                blank=True,
+                help_text="When the image file was last modified, read from the source file in image storage.",
+                null=True,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="sourceimage",
+            name="size",
+            field=models.BigIntegerField(
+                blank=True,
+                help_text="Size of the image file in bytes, read from the source file in image storage.",
+                null=True,
+            ),
+        ),
+    ]