From 555ac2dcfa39d31d76d14163221b549299d479dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mike=20F=C3=A4hrmann?= <mike_faehrmann@web.de>
Date: Fri, 17 Oct 2025 20:29:10 +0200
Subject: [PATCH] [civitai] add 'sort' & 'period' options (#8426)

---
 docs/configuration.rst          | 39 ++++++++++++++++++++++++++++
 docs/gallery-dl.conf            |  2 ++
 gallery_dl/extractor/civitai.py | 45 ++++++++++++++++++++++-----------
 3 files changed, 71 insertions(+), 15 deletions(-)

diff --git a/docs/configuration.rst b/docs/configuration.rst
index fc63870f..8496dc1d 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -2098,6 +2098,45 @@ Description
       ``None`` and ``Soft`` rated images,
 
 
+extractor.civitai.period
+------------------------
+Type
+    ``string``
+Default
+    ``"AllTime"``
+Description
+    Sets the ``period`` parameter
+    when paginating over results.
+Supported Values
+    * ``"AllTime"``
+    * ``"Year"``
+    * ``"Month"``
+    * ``"Week"``
+    * ``"Day"``
+
+
+extractor.civitai.sort
+----------------------
+Type
+    ``string``
+Default
+    ``"Newest"``
+Description
+    Sets the ``sort`` parameter
+    when paginating over results.
+Supported Values
+    * ``"Newest"``
+    * ``"Oldest"``
+    * ``"Most Reactions"``
+    * ``"Most Comments"``
+    * ``"Most Collected"``
+Special Values
+    ``"asc"``
+        Ascending order (``"Oldest"``)
+    ``"desc"`` | ``"reverse"``
+        Descending order (``"Newest"``)
+
+
 extractor.civitai.quality
 -------------------------
 Type
diff --git a/docs/gallery-dl.conf b/docs/gallery-dl.conf
index e2256b96..db367a9a 100644
--- a/docs/gallery-dl.conf
+++ b/docs/gallery-dl.conf
@@ -215,6 +215,8 @@
             "include" : ["user-images", "user-videos"],
             "metadata": false,
             "nsfw"    : true,
+            "period"  : "AllTime",
+            "sort"    : "Newest",
             "quality" : "original=true",
             "quality-videos": "quality=100"
         },
diff --git a/gallery_dl/extractor/civitai.py b/gallery_dl/extractor/civitai.py
index c546e5d2..36a12d74 100644
--- a/gallery_dl/extractor/civitai.py
+++ b/gallery_dl/extractor/civitai.py
@@ -342,9 +342,9 @@ class CivitaiModelExtractor(CivitaiExtractor):
             params = {
                 "modelVersionId": version["id"],
                 "prioritizedUserIds": (user["id"],),
-                "period": "AllTime",
-                "sort": "Most Reactions",
-                "limit": 20,
+                "period" : self.api._param_period(),
+                "sort"   : self.api._param_sort(),
+                "limit"  : 20,
                 "pending": True,
             }
             images = self.api.images(params, defaults=False)
@@ -391,8 +391,8 @@ class CivitaiCollectionExtractor(CivitaiExtractor):
 
         params = {
             "collectionId"  : cid,
-            "period"        : "AllTime",
-            "sort"          : "Newest",
+            "period"        : self.api._param_period(),
+            "sort"          : self.api._param_sort(),
             "browsingLevel" : self.api.nsfw,
             "include"       : ("cosmetics",),
         }
@@ -719,8 +719,8 @@ class CivitaiTrpcAPI():
         if defaults:
             params = self._merge_params(params, {
                 "useIndex"     : True,
-                "period"       : "AllTime",
-                "sort"         : "Newest",
+                "period"       : self._param_period(),
+                "sort"         : self._param_sort(),
                 "withMeta"     : False,  # Metadata Only
                 "fromPlatform" : False,  # Made On-Site
                 "browsingLevel": self.nsfw,
@@ -733,8 +733,8 @@ class CivitaiTrpcAPI():
     def images_gallery(self, model, version, user):
         endpoint = "image.getImagesAsPostsInfinite"
         params = {
-            "period"        : "AllTime",
-            "sort"          : "Newest",
+            "period"        : self._param_period(),
+            "sort"          : self._param_sort(),
             "modelVersionId": version["id"],
             "modelId"       : model["id"],
             "hidden"        : False,
@@ -768,9 +768,9 @@ class CivitaiTrpcAPI():
 
         if defaults:
             params = self._merge_params(params, {
-                "period"       : "AllTime",
+                "period"       : self._param_period(),
                 "periodMode"   : "published",
-                "sort"         : "Newest",
+                "sort"         : self._param_sort(),
                 "pending"      : False,
                 "hidden"       : False,
                 "followed"     : False,
@@ -797,9 +797,9 @@ class CivitaiTrpcAPI():
         if defaults:
             params = self._merge_params(params, {
                 "browsingLevel": self.nsfw,
-                "period"       : "AllTime",
+                "period"       : self._param_period(),
                 "periodMode"   : "published",
-                "sort"         : "Newest",
+                "sort"         : self._param_sort(),
                 "followed"     : False,
                 "draftOnly"    : False,
                 "pending"      : True,
@@ -821,7 +821,7 @@ class CivitaiTrpcAPI():
         if defaults:
             params = self._merge_params(params, {
                 "browsingLevel": self.nsfw,
-                "sort"         : "Newest",
+                "sort"         : self._param_sort(),
             })
 
         params = self._type_params(params)
@@ -835,7 +835,7 @@ class CivitaiTrpcAPI():
     def orchestrator_queryGeneratedImages(self):
         endpoint = "orchestrator.queryGeneratedImages"
         params = {
-            "ascending": False,
+            "ascending": True if self._param_sort() == "Oldest" else False,
             "tags"     : ("gen",),
             "authed"   : True,
         }
@@ -908,6 +908,21 @@ class CivitaiTrpcAPI():
                 params[name] = [type(item) for item in value]
         return params
 
+    def _param_period(self):
+        if period := self.extractor.config("period"):
+            return period
+        return "AllTime"
+
+    def _param_sort(self):
+        if sort := self.extractor.config("sort"):
+            s = sort[0].lower()
+            if s in "drn":
+                return "Newest"
+            if s in "ao":
+                return "Oldest"
+            return sort
+        return "Newest"
+
 
 def _bool(value):
     return value == "true"