endpoints

token and generator
schema
2026-10-23 01:59:31 -04:00 · 2026-06-15 11:08:24 -04:00 · 2026-06-15 09:12:07 -04:00 · 2026-06-15 08:55:47 -04:00 · 2026-06-14 22:20:29 -04:00 · 2026-06-14 18:09:42 -04:00
462 changed files with 18518 additions and 6848 deletions
@@ -38,6 +38,7 @@ script/socat_dev_database_connect.sh
 venv/

 # LLM Testing
+/external/
 /prompts/
 /reports/
 /requests/
@@ -102,3 +103,4 @@ windows/sqlite/sqlite3.lib
 # ArtCraft Windows DLLs
 crates/desktop/src-tauri/*.dll
 windows_dlls/
+
@@ -120,7 +120,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 3
+          "max_size": 11
        }
      },
      {
@@ -60,7 +60,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -70,7 +70,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -0,0 +1,124 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `token: ApiKeyToken`,\n  LEFT(api_key, 20) as `api_key_prefix!`,\n  name,\n  maybe_description,\n  owner_user_token as `owner_user_token: UserToken`,\n  ip_address_creation,\n  ip_address_update,\n  created_at,\n  updated_at,\n  maybe_deleted_at\nFROM api_keys\nWHERE owner_user_token = ?\nORDER BY id DESC\nLIMIT ? OFFSET ?\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token: ApiKeyToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "api_key_prefix!",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_description",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 2048
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "owner_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "ip_address_creation",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "ip_address_update",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "maybe_deleted_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": [
+      false,
+      true,
+      false,
+      true,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true
+    ]
+  },
+  "hash": "097b8a8d02734c8c8e31dbb8a3bf4ace970693a2a0df2f05a31caf86b4d3d0ab"
+}
@@ -210,7 +210,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -220,7 +220,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -30,7 +30,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 3
+          "max_size": 11
        }
      },
      {
@@ -180,7 +180,7 @@
          "type": "LongLong",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 20
        }
      },
      {
@@ -40,7 +40,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -50,7 +50,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -50,7 +50,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -60,7 +60,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -210,7 +210,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -220,7 +220,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -40,7 +40,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -50,7 +50,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -180,7 +180,7 @@
          "type": "LongLong",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 20
        }
      },
      {
@@ -30,7 +30,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 3
+          "max_size": 11
        }
      },
      {
@@ -190,7 +190,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -30,7 +30,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 3
+          "max_size": 11
        }
      }
    ],
@@ -1,12 +1,12 @@
 {
  "db_name": "MySQL",
-  "query": "\nINSERT INTO generic_inference_jobs\nSET\n  token = ?,\n  uuid_idempotency_token = ?,\n\n  job_type = ?,\n\n  maybe_external_third_party = ?,\n  maybe_external_third_party_id = ?,\n\n  product_category = ?,\n  inference_category = ?,\n\n  maybe_model_type = ?,\n  maybe_model_token = ?,\n\n  maybe_input_source_token = ?,\n  maybe_input_source_token_type = ?,\n\n  maybe_download_url = ?,\n  maybe_cover_image_media_file_token = ?,\n\n  maybe_prompt_token = ?,\n  maybe_wallet_ledger_entry_token = ?,\n\n  maybe_raw_inference_text = ?,\n\n  maybe_inference_args = ?,\n\n  maybe_creator_user_token = ?,\n  maybe_creator_anonymous_visitor_token = ?,\n  creator_ip_address = ?,\n  creator_set_visibility = ?,\n\n  platform_type = ?,\n\n  priority_level = ?,\n  is_keepalive_required = ?,\n  max_duration_seconds = ?,\n  is_debug_request = ?,\n\n  maybe_routing_tag = ?,\n\n  maybe_debug_log_event_token = ?,\n\n  frontend_failure_category = ?,\n  failure_reason = ?,\n\n  status = ?\n        ",
+  "query": "\nINSERT INTO generic_inference_jobs\nSET\n  token = ?,\n  uuid_idempotency_token = ?,\n\n  job_type = ?,\n\n  maybe_external_third_party = ?,\n  maybe_external_third_party_id = ?,\n\n  product_category = ?,\n  inference_category = ?,\n\n  maybe_model_type = ?,\n  maybe_model_token = ?,\n\n  maybe_input_source_token = ?,\n  maybe_input_source_token_type = ?,\n\n  maybe_download_url = ?,\n  maybe_cover_image_media_file_token = ?,\n\n  maybe_prompt_token = ?,\n  maybe_wallet_ledger_entry_token = ?,\n\n  maybe_raw_inference_text = ?,\n\n  maybe_inference_args = ?,\n\n  maybe_creator_user_token = ?,\n  maybe_creator_anonymous_visitor_token = ?,\n  creator_ip_address = ?,\n  creator_set_visibility = ?,\n\n  platform_type = ?,\n\n  maybe_external_third_party_cost_credits = ?,\n  maybe_external_third_party_cost_usd_cents = ?,\n  maybe_system_cost_credits = ?,\n  maybe_system_cost_usd_cents = ?,\n\n  priority_level = ?,\n  is_keepalive_required = ?,\n  max_duration_seconds = ?,\n  is_debug_request = ?,\n\n  maybe_routing_tag = ?,\n\n  maybe_debug_log_event_token = ?,\n\n  frontend_failure_category = ?,\n  failure_reason = ?,\n\n  status = ?\n        ",
  "describe": {
    "columns": [],
    "parameters": {
-      "Right": 31
+      "Right": 35
    },
    "nullable": []
  },
-  "hash": "108731dc51d915ebb8b6ed391c5bae4c41ae6f2c813be92c07d8a10ca401db53"
+  "hash": "5c67c3dd7f8bb6771c6b058a8cf6ffcc66b2be2bea41bd988070713173982dab"
 }
@@ -160,7 +160,7 @@
          "type": "LongLong",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 20
        }
      },
      {
@@ -60,7 +60,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -70,7 +70,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -150,7 +150,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 3
+          "max_size": 11
        }
      },
      {
@@ -160,7 +160,7 @@
          "type": "LongLong",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 20
        }
      },
      {
@@ -1,14 +1,14 @@
 {
  "db_name": "MySQL",
-  "query": "\nSELECT\n  fmf.id as `membership_id: u64`,\n  fmf.created_at as `added_to_folder_at: DateTime<Utc>`,\n\n  mf.token as `media_file_token: MediaFileToken`,\n  mf.media_class as `media_class: MediaFileClass`,\n  mf.media_type as `media_type: MediaFileType`,\n\n  mf.maybe_batch_token as `maybe_batch_token: BatchGenerationToken`,\n\n  mf.public_bucket_directory_hash,\n  mf.maybe_public_bucket_prefix,\n  mf.maybe_public_bucket_extension,\n\n  cover.public_bucket_directory_hash as `maybe_cover_public_bucket_directory_hash?`,\n  cover.maybe_public_bucket_prefix as `maybe_cover_public_bucket_prefix?`,\n  cover.maybe_public_bucket_extension as `maybe_cover_public_bucket_extension?`,\n\n  mf.creator_set_visibility as `creator_set_visibility: Visibility`,\n  mf.is_user_upload as `is_user_upload: bool`,\n  mf.is_intermediate_system_file as `is_intermediate_system_file: bool`,\n\n  mf.maybe_title,\n  mf.maybe_prompt_token as `maybe_prompt_token: PromptToken`,\n  mf.maybe_origin_filename,\n\n  mf.maybe_duration_millis,\n  mf.maybe_frame_width,\n  mf.maybe_frame_height,\n\n  mf.created_at,\n  mf.updated_at\nFROM folder_media_files fmf\nJOIN media_files mf\n  ON mf.token = fmf.media_file_token\nLEFT JOIN media_files cover\n  ON cover.token = mf.maybe_cover_image_media_file_token\nWHERE fmf.folder_token = ?\n  AND mf.user_deleted_at IS NULL\n  AND mf.mod_deleted_at IS NULL\nORDER BY fmf.id DESC\nLIMIT ?\n        ",
+  "query": "\nSELECT\n  mf.id as `media_file_id: u64`,\n  fmf.created_at as `added_to_folder_at: DateTime<Utc>`,\n\n  mf.token as `media_file_token: MediaFileToken`,\n  mf.media_class as `media_class: MediaFileClass`,\n  mf.media_type as `media_type: MediaFileType`,\n\n  mf.maybe_batch_token as `maybe_batch_token: BatchGenerationToken`,\n\n  mf.public_bucket_directory_hash,\n  mf.maybe_public_bucket_prefix,\n  mf.maybe_public_bucket_extension,\n\n  cover.public_bucket_directory_hash as `maybe_cover_public_bucket_directory_hash?`,\n  cover.maybe_public_bucket_prefix as `maybe_cover_public_bucket_prefix?`,\n  cover.maybe_public_bucket_extension as `maybe_cover_public_bucket_extension?`,\n\n  mf.creator_set_visibility as `creator_set_visibility: Visibility`,\n  mf.is_user_upload as `is_user_upload: bool`,\n  mf.is_intermediate_system_file as `is_intermediate_system_file: bool`,\n\n  mf.maybe_title,\n  mf.maybe_prompt_token as `maybe_prompt_token: PromptToken`,\n  mf.maybe_origin_filename,\n\n  mf.maybe_duration_millis,\n  mf.maybe_frame_width,\n  mf.maybe_frame_height,\n\n  mf.created_at,\n  mf.updated_at\nFROM folder_media_files fmf\nJOIN media_files mf\n  ON mf.token = fmf.media_file_token\nLEFT JOIN media_files cover\n  ON cover.token = mf.maybe_cover_image_media_file_token\nWHERE fmf.folder_token = ?\n  AND mf.user_deleted_at IS NULL\n  AND mf.mod_deleted_at IS NULL\nORDER BY mf.id DESC\nLIMIT ?\n        ",
  "describe": {
    "columns": [
      {
        "ordinal": 0,
-        "name": "membership_id: u64",
+        "name": "media_file_id: u64",
        "type_info": {
          "type": "LongLong",
-          "flags": "NOT_NULL | UNIQUE_KEY | UNSIGNED | AUTO_INCREMENT",
+          "flags": "NOT_NULL | PRIMARY_KEY | AUTO_INCREMENT",
          "char_set": 63,
          "max_size": 20
        }
@@ -190,7 +190,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -200,7 +200,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 5
+          "max_size": 11
        }
      },
      {
@@ -210,7 +210,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 5
+          "max_size": 11
        }
      },
      {
@@ -263,5 +263,5 @@
      false
    ]
  },
-  "hash": "88673127b54626dc38d28693e709dfaeced9a05300a26b3f3c52a17f28171c9a"
+  "hash": "8aca9bc976b980ea1a3b3052bc8a45dd4d8db55c20fd1aede2a4415cc1395cf3"
 }
@@ -160,7 +160,7 @@
          "type": "LongLong",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 20
        }
      },
      {
@@ -50,7 +50,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -60,7 +60,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -140,7 +140,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -0,0 +1,124 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `token: ApiKeyToken`,\n  LEFT(api_key, 20) as `api_key_prefix!`,\n  name,\n  maybe_description,\n  owner_user_token as `owner_user_token: UserToken`,\n  ip_address_creation,\n  ip_address_update,\n  created_at,\n  updated_at,\n  maybe_deleted_at\nFROM api_keys\nWHERE api_key = ?\n  AND maybe_deleted_at IS NULL\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token: ApiKeyToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "api_key_prefix!",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_description",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 2048
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "owner_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "ip_address_creation",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "ip_address_update",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "maybe_deleted_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      true,
+      false,
+      true,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true
+    ]
+  },
+  "hash": "9b30c67842e4c408c9002fc116dc86705484268efcadb3100ef13244bcd8f922"
+}
@@ -150,7 +150,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 3
+          "max_size": 11
        }
      },
      {
@@ -30,7 +30,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 3
+          "max_size": 11
        }
      },
      {
@@ -160,7 +160,7 @@
          "type": "LongLong",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 20
        }
      },
      {
@@ -270,7 +270,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE api_keys\nSET\n  maybe_description = ?,\n  ip_address_update = ?\nWHERE token = ?\n  AND maybe_deleted_at IS NULL\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "b72d951fc8b60e3622bb981dd5cd66ce86c6c2d788c5606d2df80a3d07e588fe"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO api_keys\nSET\n  token = ?,\n  api_key = ?,\n  name = ?,\n  maybe_description = ?,\n  owner_user_token = ?,\n  ip_address_creation = ?,\n  ip_address_update = ?,\n  created_at = NOW()\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 7
+    },
+    "nullable": []
+  },
+  "hash": "bb39045ffcc9d3a9e150b32e7ff884dccbae60101deeaaad23ccd430b25bb5a4"
+}
@@ -0,0 +1,124 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `token: ApiKeyToken`,\n  LEFT(api_key, 20) as `api_key_prefix!`,\n  name,\n  maybe_description,\n  owner_user_token as `owner_user_token: UserToken`,\n  ip_address_creation,\n  ip_address_update,\n  created_at,\n  updated_at,\n  maybe_deleted_at\nFROM api_keys\nWHERE token = ?\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token: ApiKeyToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "api_key_prefix!",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_description",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 2048
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "owner_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "ip_address_creation",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "ip_address_update",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "maybe_deleted_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      true,
+      false,
+      true,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true
+    ]
+  },
+  "hash": "bb542b8a86cf2bf770daf29e09a92be981b307810241dd3cc1a7225a83f6824c"
+}
@@ -160,7 +160,7 @@
          "type": "LongLong",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 20
        }
      },
      {
@@ -1,14 +1,14 @@
 {
  "db_name": "MySQL",
-  "query": "\nSELECT\n  fmf.id as `membership_id: u64`,\n  fmf.created_at as `added_to_folder_at: DateTime<Utc>`,\n\n  mf.token as `media_file_token: MediaFileToken`,\n  mf.media_class as `media_class: MediaFileClass`,\n  mf.media_type as `media_type: MediaFileType`,\n\n  mf.maybe_batch_token as `maybe_batch_token: BatchGenerationToken`,\n\n  mf.public_bucket_directory_hash,\n  mf.maybe_public_bucket_prefix,\n  mf.maybe_public_bucket_extension,\n\n  cover.public_bucket_directory_hash as `maybe_cover_public_bucket_directory_hash?`,\n  cover.maybe_public_bucket_prefix as `maybe_cover_public_bucket_prefix?`,\n  cover.maybe_public_bucket_extension as `maybe_cover_public_bucket_extension?`,\n\n  mf.creator_set_visibility as `creator_set_visibility: Visibility`,\n  mf.is_user_upload as `is_user_upload: bool`,\n  mf.is_intermediate_system_file as `is_intermediate_system_file: bool`,\n\n  mf.maybe_title,\n  mf.maybe_prompt_token as `maybe_prompt_token: PromptToken`,\n  mf.maybe_origin_filename,\n\n  mf.maybe_duration_millis,\n  mf.maybe_frame_width,\n  mf.maybe_frame_height,\n\n  mf.created_at,\n  mf.updated_at\nFROM folder_media_files fmf\nJOIN media_files mf\n  ON mf.token = fmf.media_file_token\nLEFT JOIN media_files cover\n  ON cover.token = mf.maybe_cover_image_media_file_token\nWHERE fmf.folder_token = ?\n  AND mf.user_deleted_at IS NULL\n  AND mf.mod_deleted_at IS NULL\n  AND fmf.id < ?\nORDER BY fmf.id DESC\nLIMIT ?\n        ",
+  "query": "\nSELECT\n  mf.id as `media_file_id: u64`,\n  fmf.created_at as `added_to_folder_at: DateTime<Utc>`,\n\n  mf.token as `media_file_token: MediaFileToken`,\n  mf.media_class as `media_class: MediaFileClass`,\n  mf.media_type as `media_type: MediaFileType`,\n\n  mf.maybe_batch_token as `maybe_batch_token: BatchGenerationToken`,\n\n  mf.public_bucket_directory_hash,\n  mf.maybe_public_bucket_prefix,\n  mf.maybe_public_bucket_extension,\n\n  cover.public_bucket_directory_hash as `maybe_cover_public_bucket_directory_hash?`,\n  cover.maybe_public_bucket_prefix as `maybe_cover_public_bucket_prefix?`,\n  cover.maybe_public_bucket_extension as `maybe_cover_public_bucket_extension?`,\n\n  mf.creator_set_visibility as `creator_set_visibility: Visibility`,\n  mf.is_user_upload as `is_user_upload: bool`,\n  mf.is_intermediate_system_file as `is_intermediate_system_file: bool`,\n\n  mf.maybe_title,\n  mf.maybe_prompt_token as `maybe_prompt_token: PromptToken`,\n  mf.maybe_origin_filename,\n\n  mf.maybe_duration_millis,\n  mf.maybe_frame_width,\n  mf.maybe_frame_height,\n\n  mf.created_at,\n  mf.updated_at\nFROM folder_media_files fmf\nJOIN media_files mf\n  ON mf.token = fmf.media_file_token\nLEFT JOIN media_files cover\n  ON cover.token = mf.maybe_cover_image_media_file_token\nWHERE fmf.folder_token = ?\n  AND mf.user_deleted_at IS NULL\n  AND mf.mod_deleted_at IS NULL\n  AND mf.id < ?\nORDER BY mf.id DESC\nLIMIT ?\n        ",
  "describe": {
    "columns": [
      {
        "ordinal": 0,
-        "name": "membership_id: u64",
+        "name": "media_file_id: u64",
        "type_info": {
          "type": "LongLong",
-          "flags": "NOT_NULL | UNIQUE_KEY | UNSIGNED | AUTO_INCREMENT",
+          "flags": "NOT_NULL | PRIMARY_KEY | AUTO_INCREMENT",
          "char_set": 63,
          "max_size": 20
        }
@@ -190,7 +190,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -200,7 +200,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 5
+          "max_size": 11
        }
      },
      {
@@ -210,7 +210,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 5
+          "max_size": 11
        }
      },
      {
@@ -263,5 +263,5 @@
      false
    ]
  },
-  "hash": "d2a406bcf08f656fd602aa6ba1124a77d04ad874b15abafca300e8b381c7b211"
+  "hash": "c0ba9f9aa3184b1cb3d714173b31e530e201a6c24afd29ad534cf7f3954c7316"
 }
@@ -150,7 +150,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 3
+          "max_size": 11
        }
      },
      {
@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE api_keys\nSET maybe_deleted_at = NOW()\nWHERE token = ?\n  AND maybe_deleted_at IS NULL\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "c28c716aa08601b208c727102680bfa91025f0e3958390ed9e27e521d38b5805"
+}
@@ -180,7 +180,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -190,7 +190,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -140,7 +140,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -180,7 +180,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -190,7 +190,7 @@
          "type": "Long",
          "flags": "NOT_NULL",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -190,7 +190,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -140,7 +140,7 @@
          "type": "Long",
          "flags": "",
          "char_set": 63,
-          "max_size": 10
+          "max_size": 11
        }
      },
      {
@@ -10,6 +10,7 @@ members = [
  "crates/api_clients/artcraft/artcraft_client",
  "crates/api_clients/artcraft/artcraft_router",
  "crates/api_clients/cloud_storage",
+  "crates/api_clients/comet_api_client",
  "crates/api_clients/datadog_client",
  "crates/api_clients/fal_client",
  "crates/api_clients/google_drive_downloader",
@@ -294,16 +295,14 @@ worldlabs_consumer_client = { path = "crates/api_clients/worldlabs_consumer_clie
 # External libs
 # Centrally pinned versions so that we can uniformly upgrade/downgrade versions across the workspace
 # If a crate needs to use an older/newer version, the dependency should be managed in that crate's own Cargo.toml
-actix = "0.13.5"
-actix-cors = "0.6.4" # TODO(bt): Carefully upgrade this. CORS broke last time.
-actix-http = "3.7.0"
-actix-multipart = "0.6.2"
-actix-rt = "2.10.0"
+actix-cors = "0.7.1"
+actix-http = "3.12.1"
+actix-multipart = "0.7.2"
+actix-rt = "2.11.0"
 actix-service = "2.0.3"
 actix-utils = "3.0.1"
-actix-web = "4.7.0" # TODO(bt): We're behind and need to bump versions.
-actix-web-actors = "4.3.1+deprecated"
-actix-web-lab = "0.20.2"
+actix-web = "4.13.0"
+actix-web-lab = "0.26.0"
 anyhow = "1.0.102"
 assertor = "0.0.3"
 base64 = "0.22.1"
@@ -343,11 +342,11 @@ sha2 = "0.11.0-rc.5"
 sha3 = "0.10.8"
 speculoos = "0.11.0"
 strum = { version = "0.28.0", features = ["derive"] }
-tauri = { version = "2.8.3", features = ["unstable", "devtools", "protocol-asset"] } # NB: "devtools" prevents App Store distribution; "ubstable" is needed for window access
-tauri-plugin-dialog = "2.3.3"
-tauri-plugin-fs = "2.4.2"
-tauri-plugin-log = "2.6.0"
-tauri-plugin-upload = "2.3.1"
+tauri = { version = "2.11.2", features = ["unstable", "devtools", "protocol-asset"] } # NB: "devtools" prevents App Store distribution; "ubstable" is needed for window access
+tauri-plugin-dialog = "2.7.1"
+tauri-plugin-fs = "2.5.1"
+tauri-plugin-log = "2.8.0"
+tauri-plugin-upload = "2.4.0"
 tempdir = "0.3.7"
 tempfile = "3.27.0"
 thiserror = "2.0.18"
@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE generic_inference_jobs
+  DROP COLUMN maybe_external_third_party_cost_credits;
@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE generic_inference_jobs
+  ADD COLUMN maybe_external_third_party_cost_credits INT(10) UNSIGNED DEFAULT NULL;
@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE generic_inference_jobs
+  DROP COLUMN maybe_external_third_party_cost_usd_cents;
@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE generic_inference_jobs
+  ADD COLUMN maybe_external_third_party_cost_usd_cents INT(10) UNSIGNED DEFAULT NULL;
@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE generic_inference_jobs
+  DROP COLUMN maybe_system_cost_credits;
@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE generic_inference_jobs
+  ADD COLUMN maybe_system_cost_credits INT(10) UNSIGNED DEFAULT NULL;
@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE generic_inference_jobs
+  DROP COLUMN maybe_system_cost_usd_cents;
@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE generic_inference_jobs
+  ADD COLUMN maybe_system_cost_usd_cents INT(10) UNSIGNED DEFAULT NULL;
@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS api_keys;
@@ -0,0 +1,50 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE api_keys (
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Effective "primary key" (used internally for lookups and as a foreign key).
+  token VARCHAR(32) NOT NULL,
+
+  -- The actual API key value presented by clients to authenticate.
+  api_key VARCHAR(255) NOT NULL,
+
+  -- ========== KEY INFO ==========
+
+  -- User-supplied display name for the key.
+  name VARCHAR(255) NOT NULL,
+
+  -- Optional user-supplied description.
+  maybe_description VARCHAR(512) DEFAULT NULL,
+
+  -- ========== OWNER ==========
+
+  -- The user that owns this API key.
+  owner_user_token VARCHAR(32) NOT NULL,
+
+  -- ========== IP ADDRESSES ==========
+
+  -- IP address that created the key. Wide enough for IPv4/IPv6.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address that last updated the key. Wide enough for IPv4/IPv6.
+  ip_address_update VARCHAR(40) NOT NULL,
+
+  -- ========== TIMESTAMPS ==========
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- Soft-delete timestamp. NULL means the key is live.
+  maybe_deleted_at TIMESTAMP NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (api_key),
+  KEY fk_owner_user_token (owner_user_token),
+  KEY index_maybe_deleted_at (maybe_deleted_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,50 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE api_keys (
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Effective "primary key" (used internally for lookups and as a foreign key).
+  token VARCHAR(32) NOT NULL,
+
+  -- The actual API key value presented by clients to authenticate.
+  api_key VARCHAR(255) NOT NULL,
+
+  -- ========== KEY INFO ==========
+
+  -- User-supplied display name for the key.
+  name VARCHAR(255) NOT NULL,
+
+  -- Optional user-supplied description.
+  maybe_description VARCHAR(512) DEFAULT NULL,
+
+  -- ========== OWNER ==========
+
+  -- The user that owns this API key.
+  owner_user_token VARCHAR(32) NOT NULL,
+
+  -- ========== IP ADDRESSES ==========
+
+  -- IP address that created the key. Wide enough for IPv4/IPv6.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address that last updated the key. Wide enough for IPv4/IPv6.
+  ip_address_update VARCHAR(40) NOT NULL,
+
+  -- ========== TIMESTAMPS ==========
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- Soft-delete timestamp. NULL means the key is live.
+  maybe_deleted_at TIMESTAMP NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (api_key),
+  KEY fk_owner_user_token (owner_user_token),
+  KEY index_maybe_deleted_at (maybe_deleted_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -56,6 +56,19 @@ CREATE TABLE generic_inference_jobs (
  -- service uses.
  maybe_external_third_party_id VARCHAR(64) DEFAULT NULL,

+  -- What the third-party service charges us for the job, in the service's
+  -- own credit denomination (if it bills in credits).
+  maybe_external_third_party_cost_credits INT(10) UNSIGNED DEFAULT NULL,
+
+  -- What the third-party service charges us for the job, in USD cents.
+  maybe_external_third_party_cost_usd_cents INT(10) UNSIGNED DEFAULT NULL,
+
+  -- What we charge the user for the job, in our own credits.
+  maybe_system_cost_credits INT(10) UNSIGNED DEFAULT NULL,
+
+  -- What we charge the user for the job, in USD cents.
+  maybe_system_cost_usd_cents INT(10) UNSIGNED DEFAULT NULL,
+
  -- There is an index on this column.
  -- NB: See notes on inference_category. This is becoming a problematic field. We're using
  -- this to load the container spin-up arguments and dependencies, but the former is being
@@ -0,0 +1,42 @@
+use chrono::{DateTime, Utc};
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use tokens::tokens::api_keys::ApiKeyToken;
+use tokens::tokens::users::UserToken;
+
+/// Canonical wire shape for an API key, used by the list rows and the
+/// single-key GET.
+///
+/// NB: the full secret `api_key` is NEVER included here — only
+/// `truncated_api_key` (its first 20 characters), enough to disambiguate keys
+/// in a UI. The full value is returned exactly once, at creation time.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct ApiKeyInfo {
+  pub token: ApiKeyToken,
+
+  /// First 20 characters of the API key. The full secret is never returned
+  /// after creation.
+  pub truncated_api_key: String,
+
+  pub name: String,
+  pub maybe_description: Option<String>,
+
+  pub owner_user_token: UserToken,
+
+  pub ip_address_creation: String,
+  pub ip_address_update: String,
+
+  pub created_at: DateTime<Utc>,
+  pub updated_at: DateTime<Utc>,
+
+  /// Soft-delete timestamp. `None` for live keys.
+  pub maybe_deleted_at: Option<DateTime<Utc>>,
+}
+
+/// Path info for endpoints addressed by the API key's `token` (NOT the secret
+/// `api_key` value): `GET` / `DELETE` / `PUT` `/v1/api_keys/{api_key_token}`.
+#[derive(Deserialize, ToSchema)]
+pub struct ApiKeyPathInfo {
+  pub api_key_token: ApiKeyToken,
+}
@@ -0,0 +1,28 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use tokens::tokens::api_keys::ApiKeyToken;
+
+// ── POST /v1/api_keys/create ──
+
+#[derive(Deserialize, ToSchema)]
+pub struct CreateApiKeyRequest {
+  /// Display name (title) for the key.
+  pub name: String,
+
+  /// Optional description.
+  pub maybe_description: Option<String>,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct CreateApiKeySuccessResponse {
+  pub success: bool,
+
+  /// The key's `token` — used for all subsequent management
+  /// (get / update / delete). Safe to store and display.
+  pub api_key_token: ApiKeyToken,
+
+  /// The full secret API key value. This is the ONLY time it is ever
+  /// returned — the caller must store it now, as it cannot be retrieved again.
+  pub api_key: String,
+}
@@ -0,0 +1,9 @@
+use serde_derive::Serialize;
+use utoipa::ToSchema;
+
+// ── DELETE /v1/api_keys/{api_key_token} ──
+
+#[derive(Serialize, ToSchema)]
+pub struct DeleteApiKeySuccessResponse {
+  pub success: bool,
+}
@@ -0,0 +1,12 @@
+use serde_derive::Serialize;
+use utoipa::ToSchema;
+
+use crate::api_keys::common::ApiKeyInfo;
+
+// ── GET /v1/api_keys/{api_key_token} ──
+
+#[derive(Serialize, ToSchema)]
+pub struct GetApiKeySuccessResponse {
+  pub success: bool,
+  pub api_key: ApiKeyInfo,
+}
@@ -0,0 +1,24 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::{IntoParams, ToSchema};
+
+use crate::api_keys::common::ApiKeyInfo;
+
+// ── GET /v1/api_keys/list ──
+
+#[derive(Deserialize, ToSchema, IntoParams)]
+pub struct ListApiKeysQueryParams {
+  /// Page size. Defaults server-side if omitted.
+  pub limit: Option<u32>,
+
+  /// Number of rows to skip. Defaults to 0.
+  pub offset: Option<u32>,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct ListApiKeysSuccessResponse {
+  pub success: bool,
+
+  /// The user's API keys (including soft-deleted ones), newest first. Each
+  /// entry's key value is truncated — the full secret is never listed.
+  pub api_keys: Vec<ApiKeyInfo>,
+}
@@ -0,0 +1,6 @@
+pub mod common;
+pub mod create_api_key;
+pub mod delete_api_key;
+pub mod get_api_key;
+pub mod list_api_keys;
+pub mod update_api_key;
@@ -0,0 +1,15 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+// ── PUT /v1/api_keys/{api_key_token} ──
+
+#[derive(Deserialize, ToSchema)]
+pub struct UpdateApiKeyRequest {
+  /// New description for the key. `None` clears it.
+  pub maybe_description: Option<String>,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct UpdateApiKeySuccessResponse {
+  pub success: bool,
+}
@@ -64,6 +64,31 @@ pub struct FolderThumbnail {

  /// Resizing template URL (with `{{width}}` / `{{height}}` placeholders)
  /// when the media class supports it. `None` for media classes without
-  /// a thumbnail variant.
+  /// a thumbnail variant. (Video media files instead have video previews,
+  /// which, in turn, have their own thumbnail templates.)
  pub maybe_thumbnail_template: Option<String>,
+
+  /// Video preview images (still and animated gif) for mp4 video files.
+  /// These are only set for video media files.
+  pub maybe_video_previews: Option<FolderThumbnailVideoPreviews>,
+}
+
+/// Video preview images for a video media file referenced by a folder.
+/// Mirrors the shape of `MediaLinks`' video previews, but is its own type
+/// so the folder wire shape can evolve independently.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct FolderThumbnailVideoPreviews {
+  /// A static single frame preview image of the video.
+  pub still: Url,
+
+  /// An animated gif preview of the video.
+  pub animated: Url,
+
+  /// A template used to construct the still thumbnail URL.
+  /// Replace the string `{WIDTH}` with the desired width.
+  pub still_thumbnail_template: String,
+
+  /// A template used to construct the animated thumbnail URL.
+  /// Replace the string `{WIDTH}` with the desired width.
+  pub animated_thumbnail_template: String,
 }
@@ -1,4 +1,5 @@
 pub mod analytics;
+pub mod api_keys;
 pub mod characters;
 pub mod common;
 pub mod credits;
@@ -11,9 +11,11 @@ use crate::generate::generate_image::providers::artcraft::midjourney_7::request:
 /// |   3   |   19    |   19¢     |  (interpolated; Kinovi doesn't expose 3)
 /// |   4   |   25    |   25¢     |
 ///
-/// Kinovi-side math: 12 Kinovi credits per Midjourney task; 193 Kinovi
-/// credits per USD. Kinovi rounds to nearest cent, so batches 1/2/4 land
-/// on 6/12/25. Batch 3 is `ceil((12 × 3 / 193) × 100) = 19`.
+/// Kinovi-side math (historical, 22,000-credit package at 193 credits/$1):
+/// 12 Kinovi credits per Midjourney task → batches 1/2/4 land on 6/12/25¢;
+/// batch 3 is `ceil((12 × 3 / 193) × 100) = 19`. Under the current
+/// 525,000-credit package (243 credits/$1) Kinovi costs only 5/10/20¢ —
+/// user pricing is intentionally kept at the 193-derived values.
 #[derive(Clone, Debug)]
 pub struct ArtcraftMidjourney7CostState {
  pub num_images: u16,
@@ -127,38 +129,6 @@ mod tests {
    }
  }

-  // ── 1:1 cost parity with Kinovi for batches 1/2/4 ──
-  //
-  // Kinovi midjourney_7 returns 6/12/25¢ for batches 1/2/4. The artcraft
-  // provider must match those values byte-for-byte so users pay the same.
-
-  mod kinovi_parity {
-    use super::*;
-    use crate::generate::generate_image::providers::kinovi::midjourney_7::cost::KinoviMidjourney7CostState;
-    use seedance2pro_client::generate::image::generate_midjourney_v7::KinoviMidjourneyBatchCount;
-
-    #[test]
-    fn batch_1_matches_kinovi() {
-      let kinovi = KinoviMidjourney7CostState { batch_count: KinoviMidjourneyBatchCount::One }
-        .estimate_cost();
-      assert_eq!(cost_cents(1), kinovi.cost_in_usd_cents.unwrap());
-    }
-
-    #[test]
-    fn batch_2_matches_kinovi() {
-      let kinovi = KinoviMidjourney7CostState { batch_count: KinoviMidjourneyBatchCount::Two }
-        .estimate_cost();
-      assert_eq!(cost_cents(2), kinovi.cost_in_usd_cents.unwrap());
-    }
-
-    #[test]
-    fn batch_4_matches_kinovi() {
-      let kinovi = KinoviMidjourney7CostState { batch_count: KinoviMidjourneyBatchCount::Four }
-        .estimate_cost();
-      assert_eq!(cost_cents(4), kinovi.cost_in_usd_cents.unwrap());
-    }
-  }
-
  // ── Monotonicity ──

  #[test]
@@ -82,32 +82,4 @@ mod tests {
    }
  }

-  // ── 1:1 cost parity with Kinovi 7-niji ──
-
-  mod kinovi_parity {
-    use super::*;
-    use crate::generate::generate_image::providers::kinovi::midjourney_7_niji::cost::KinoviMidjourney7NijiCostState;
-    use seedance2pro_client::generate::image::generate_midjourney_v7_niji::KinoviMidjourneyBatchCount;
-
-    #[test]
-    fn batch_1_matches_kinovi() {
-      let kinovi = KinoviMidjourney7NijiCostState { batch_count: KinoviMidjourneyBatchCount::One }
-        .estimate_cost();
-      assert_eq!(cost_cents(1), kinovi.cost_in_usd_cents.unwrap());
-    }
-
-    #[test]
-    fn batch_2_matches_kinovi() {
-      let kinovi = KinoviMidjourney7NijiCostState { batch_count: KinoviMidjourneyBatchCount::Two }
-        .estimate_cost();
-      assert_eq!(cost_cents(2), kinovi.cost_in_usd_cents.unwrap());
-    }
-
-    #[test]
-    fn batch_4_matches_kinovi() {
-      let kinovi = KinoviMidjourney7NijiCostState { batch_count: KinoviMidjourneyBatchCount::Four }
-        .estimate_cost();
-      assert_eq!(cost_cents(4), kinovi.cost_in_usd_cents.unwrap());
-    }
-  }
 }
@@ -82,32 +82,4 @@ mod tests {
    }
  }

-  // ── 1:1 cost parity with Kinovi v8 ──
-
-  mod kinovi_parity {
-    use super::*;
-    use crate::generate::generate_image::providers::kinovi::midjourney_8::cost::KinoviMidjourney8CostState;
-    use seedance2pro_client::generate::image::generate_midjourney_v8::KinoviMidjourneyBatchCount;
-
-    #[test]
-    fn batch_1_matches_kinovi() {
-      let kinovi = KinoviMidjourney8CostState { batch_count: KinoviMidjourneyBatchCount::One }
-        .estimate_cost();
-      assert_eq!(cost_cents(1), kinovi.cost_in_usd_cents.unwrap());
-    }
-
-    #[test]
-    fn batch_2_matches_kinovi() {
-      let kinovi = KinoviMidjourney8CostState { batch_count: KinoviMidjourneyBatchCount::Two }
-        .estimate_cost();
-      assert_eq!(cost_cents(2), kinovi.cost_in_usd_cents.unwrap());
-    }
-
-    #[test]
-    fn batch_4_matches_kinovi() {
-      let kinovi = KinoviMidjourney8CostState { batch_count: KinoviMidjourneyBatchCount::Four }
-        .estimate_cost();
-      assert_eq!(cost_cents(4), kinovi.cost_in_usd_cents.unwrap());
-    }
-  }
 }
@@ -37,8 +37,9 @@ impl KinoviMidjourney7CostState {
      reference_image_urls: None,
    };

-    let cost_in_credits = pricing_request.estimate_credits() as u64;
-    let cost_in_usd_cents = pricing_request.estimate_cost_in_usd_cents();
+    let costs = pricing_request.calculate_costs();
+    let cost_in_credits = costs.kinovi_credits;
+    let cost_in_usd_cents = costs.usd_cents_rounded_up;

    ImageGenerationCostEstimate {
      cost_in_credits: Some(cost_in_credits),
@@ -85,27 +86,27 @@ mod tests {
    }
  }

-  // ── USD pricing (193 credits per dollar; rounded) ──
+  // ── USD pricing (243 credits per dollar; rounded up) ──

  mod usd {
    use super::*;

    #[test]
-    fn batch_one_is_six_cents() {
-      // 12 / 193 × 100 = 6.21 → 6¢
-      assert_eq!(usd_cents_for(KinoviMidjourneyBatchCount::One), 6);
+    fn batch_one_is_five_cents() {
+      // 12/243 × 100 = 4.94 → 5¢
+      assert_eq!(usd_cents_for(KinoviMidjourneyBatchCount::One), 5); // rounds UP
    }

    #[test]
-    fn batch_two_is_twelve_cents() {
-      // 24 / 193 × 100 = 12.44 → 12¢
-      assert_eq!(usd_cents_for(KinoviMidjourneyBatchCount::Two), 12);
+    fn batch_two_is_ten_cents() {
+      // 24/243 × 100 = 9.88 → 10¢
+      assert_eq!(usd_cents_for(KinoviMidjourneyBatchCount::Two), 10); // rounds UP
    }

    #[test]
-    fn batch_four_is_twentyfive_cents() {
-      // 48 / 193 × 100 = 24.87 → 25¢
-      assert_eq!(usd_cents_for(KinoviMidjourneyBatchCount::Four), 25);
+    fn batch_four_is_twenty_cents() {
+      // 48/243 × 100 = 19.75 → 20¢
+      assert_eq!(usd_cents_for(KinoviMidjourneyBatchCount::Four), 20);
    }
  }

@@ -35,8 +35,9 @@ impl KinoviMidjourney7NijiCostState {
      reference_image_urls: None,
    };

-    let cost_in_credits = pricing_request.estimate_credits() as u64;
-    let cost_in_usd_cents = pricing_request.estimate_cost_in_usd_cents();
+    let costs = pricing_request.calculate_costs();
+    let cost_in_credits = costs.kinovi_credits;
+    let cost_in_usd_cents = costs.usd_cents_rounded_up;

    ImageGenerationCostEstimate {
      cost_in_credits: Some(cost_in_credits),
@@ -55,11 +56,11 @@ mod tests {
  use super::*;

  #[test]
-  fn batch_one_is_twelve_credits_and_six_cents() {
+  fn batch_one_is_twelve_credits_and_five_cents() {
    let cost = KinoviMidjourney7NijiCostState { batch_count: KinoviMidjourneyBatchCount::One }
      .estimate_cost();
    assert_eq!(cost.cost_in_credits, Some(12));
-    assert_eq!(cost.cost_in_usd_cents, Some(6));
+    assert_eq!(cost.cost_in_usd_cents, Some(5)); // 1200/243 = 4.94 -> rounds UP
  }

  #[test]
@@ -67,7 +68,7 @@ mod tests {
    let cost = KinoviMidjourney7NijiCostState { batch_count: KinoviMidjourneyBatchCount::Two }
      .estimate_cost();
    assert_eq!(cost.cost_in_credits, Some(24));
-    assert_eq!(cost.cost_in_usd_cents, Some(12));
+    assert_eq!(cost.cost_in_usd_cents, Some(10)); // 2400/243 = 9.88 -> rounds UP
  }

  #[test]
@@ -75,7 +76,7 @@ mod tests {
    let cost = KinoviMidjourney7NijiCostState { batch_count: KinoviMidjourneyBatchCount::Four }
      .estimate_cost();
    assert_eq!(cost.cost_in_credits, Some(48));
-    assert_eq!(cost.cost_in_usd_cents, Some(25));
+    assert_eq!(cost.cost_in_usd_cents, Some(20));
  }

  #[test]
@@ -35,8 +35,9 @@ impl KinoviMidjourney8CostState {
      reference_image_urls: None,
    };

-    let cost_in_credits = pricing_request.estimate_credits() as u64;
-    let cost_in_usd_cents = pricing_request.estimate_cost_in_usd_cents();
+    let costs = pricing_request.calculate_costs();
+    let cost_in_credits = costs.kinovi_credits;
+    let cost_in_usd_cents = costs.usd_cents_rounded_up;

    ImageGenerationCostEstimate {
      cost_in_credits: Some(cost_in_credits),
@@ -55,11 +56,11 @@ mod tests {
  use super::*;

  #[test]
-  fn batch_one_is_twelve_credits_and_six_cents() {
+  fn batch_one_is_twelve_credits_and_five_cents() {
    let cost = KinoviMidjourney8CostState { batch_count: KinoviMidjourneyBatchCount::One }
      .estimate_cost();
    assert_eq!(cost.cost_in_credits, Some(12));
-    assert_eq!(cost.cost_in_usd_cents, Some(6));
+    assert_eq!(cost.cost_in_usd_cents, Some(5)); // 1200/243 = 4.94 -> rounds UP
  }

  #[test]
@@ -67,7 +68,7 @@ mod tests {
    let cost = KinoviMidjourney8CostState { batch_count: KinoviMidjourneyBatchCount::Two }
      .estimate_cost();
    assert_eq!(cost.cost_in_credits, Some(24));
-    assert_eq!(cost.cost_in_usd_cents, Some(12));
+    assert_eq!(cost.cost_in_usd_cents, Some(10)); // 2400/243 = 9.88 -> rounds UP
  }

  #[test]
@@ -75,6 +76,6 @@ mod tests {
    let cost = KinoviMidjourney8CostState { batch_count: KinoviMidjourneyBatchCount::Four }
      .estimate_cost();
    assert_eq!(cost.cost_in_credits, Some(48));
-    assert_eq!(cost.cost_in_usd_cents, Some(25));
+    assert_eq!(cost.cost_in_usd_cents, Some(20));
  }
 }
@@ -231,176 +231,6 @@ mod tests {
    }
  }

-  // ── Cross-provider margin: ArtCraft is consistently ~30% above GrokApi ──
-
-  mod small_margin {
-    use super::*;
-    use crate::api::router_aspect_ratio::RouterAspectRatio;
-
-    #[test]
-    fn small_margin() {
-      let resolutions = [
-        None,
-        Some(RouterResolution::FourEightyP),
-        Some(RouterResolution::SevenTwentyP),
-        Some(RouterResolution::TenEightyP), // clamps to 720p on both sides
-      ];
-      let durations: &[u16] = &[1, 4, 5, 8, 10, 12, 15];
-      let aspect_ratios = [
-        None,
-        Some(RouterAspectRatio::Auto),
-        Some(RouterAspectRatio::Square),
-        Some(RouterAspectRatio::WideSixteenByNine),
-        Some(RouterAspectRatio::TallNineBySixteen),
-        Some(RouterAspectRatio::WideFourByThree),
-        Some(RouterAspectRatio::TallThreeByFour),
-        Some(RouterAspectRatio::WideThreeByTwo),
-        Some(RouterAspectRatio::TallTwoByThree),
-      ];
-      // (has_start_frame, num_reference_images). At most one of the two is
-      // non-default — start_frame and reference_images are mutually exclusive
-      // on the GrokApi wire (image-to-video vs reference-to-video), so we
-      // don't mix them here to keep the comparison apples-to-apples.
-      let image_combos: &[(bool, usize)] = &[
-        (false, 0),  // text-to-video
-        (true,  0),  // image-to-video, 1 source image
-        (false, 1),  // reference-to-video, 1 ref image
-        (false, 2),
-        (false, 3),
-      ];
-
-      let mut total_cases = 0;
-      let mut failures = Vec::new();
-
-      for &res in &resolutions {
-        for &dur in durations {
-          for &ar in &aspect_ratios {
-            for &(has_start, num_refs) in image_combos {
-              total_cases += 1;
-              let artcraft = artcraft_cents(res, dur, ar, has_start, num_refs);
-              let grokapi  = grokapi_cents(res, dur, ar, has_start, num_refs);
-
-              // Margin requirement: artcraft / max(grokapi - 1, 1) >= 1.29.
-              // The (-1, 1) floor accounts for one cent of GrokApi-side
-              // ceiling-rounding noise (see test doc comment above).
-              let grokapi_compare = grokapi.saturating_sub(1).max(1);
-              let lhs = artcraft.saturating_mul(100);
-              let rhs = grokapi_compare.saturating_mul(129);
-
-              if lhs < rhs {
-                let pct = if grokapi == 0 { 0.0 }
-                  else { (artcraft as f64 / grokapi as f64 - 1.0) * 100.0 };
-                failures.push(format!(
-                  "res={:?} dur={}s ar={:?} start={} refs={} → \
-                   artcraft={}¢ vs grokapi={}¢ (margin {:.1}%, want ≥ 29% after 1¢ tolerance)",
-                  res, dur, ar, has_start, num_refs, artcraft, grokapi, pct,
-                ));
-              }
-
-              // Defense in depth: ArtCraft must always cost at least as
-              // much as GrokApi, regardless of rounding noise.
-              assert!(
-                artcraft >= grokapi,
-                "ArtCraft ({artcraft}¢) cheaper than GrokApi ({grokapi}¢) for \
-                 res={res:?} dur={dur}s ar={ar:?} start={has_start} refs={num_refs}",
-              );
-            }
-          }
-        }
-      }
-
-      if !failures.is_empty() {
-        let summary = failures.iter().take(10).cloned().collect::<Vec<_>>().join("\n  ");
-        panic!(
-          "{} / {} (res × duration × aspect × image_combo) tuples failed \
-           the ≥29% (with 1¢ tolerance) margin check.\nFirst 10:\n  {}",
-          failures.len(), total_cases, summary,
-        );
-      }
-    }
-
-    // ── Cross-provider helpers ──
-
-    fn artcraft_cents(
-      resolution: Option<RouterResolution>,
-      duration_seconds: u16,
-      aspect_ratio: Option<RouterAspectRatio>,
-      has_start_frame: bool,
-      num_reference_images: usize,
-    ) -> u64 {
-      let start_frame = if has_start_frame {
-        // ArtCraft's omni endpoint takes MediaFileTokens for image refs.
-        Some(ImageRef::MediaFileToken(MediaFileToken::new("mf_start".to_string())))
-      } else { None };
-      let reference_images = if num_reference_images > 0 {
-        Some(ImageListRef::MediaFileTokens(
-          (0..num_reference_images)
-            .map(|i| MediaFileToken::new(format!("mf_ref_{i}")))
-            .collect(),
-        ))
-      } else { None };
-
-      let builder = GenerateVideoRequestBuilder {
-        model: RouterVideoModel::GrokImagineVideo,
-        provider: RouterProvider::Artcraft,
-        resolution,
-        aspect_ratio,
-        duration_seconds: Some(duration_seconds),
-        // Batch is fixed at 1 because GrokApi's per-request cost calculator
-        // doesn't multiply by batch (Grok returns one video per call); the
-        // markup test would compare apples to oranges otherwise.
-        video_batch_count: Some(1),
-        start_frame,
-        reference_images,
-        ..Default::default()
-      };
-      builder.build2()
-        .expect("build2 (artcraft) should succeed")
-        .estimate_cost()
-        .expect("estimate_cost (artcraft) should succeed")
-        .cost_in_usd_cents
-        .unwrap()
-    }
-
-    fn grokapi_cents(
-      resolution: Option<RouterResolution>,
-      duration_seconds: u16,
-      aspect_ratio: Option<RouterAspectRatio>,
-      has_start_frame: bool,
-      num_reference_images: usize,
-    ) -> u64 {
-      let start_frame = if has_start_frame {
-        // GrokApi (direct xAI) takes URLs for image refs.
-        Some(ImageRef::Url("https://example.com/start.png".to_string()))
-      } else { None };
-      let reference_images = if num_reference_images > 0 {
-        Some(ImageListRef::Urls(
-          (0..num_reference_images)
-            .map(|i| format!("https://example.com/ref_{i}.png"))
-            .collect(),
-        ))
-      } else { None };
-
-      let builder = GenerateVideoRequestBuilder {
-        model: RouterVideoModel::GrokImagineVideo,
-        provider: RouterProvider::GrokApi,
-        resolution,
-        aspect_ratio,
-        duration_seconds: Some(duration_seconds),
-        video_batch_count: Some(1),
-        start_frame,
-        reference_images,
-        ..Default::default()
-      };
-      builder.build2()
-        .expect("build2 (grokapi) should succeed")
-        .estimate_cost()
-        .expect("estimate_cost (grokapi) should succeed")
-        .cost_in_usd_cents
-        .unwrap()
-    }
-  }
-
  // ── Helpers ──

  fn build_cost(
@@ -144,113 +144,6 @@ mod tests {
  use crate::generate::generate_video::generate_video_request_builder::GenerateVideoRequestBuilder;
  use crate::generate::generate_video::video_generation_cost_estimate::VideoGenerationCostEstimate;

-  // ── Base cost parity with grok_api_client ─────────────────────────────
-  //
-  // The base cost (before ArtCraft markup, batch=1) must equal exactly what
-  // grok_api_client's calculator returns for an equivalent direct-Grok
-  // request. This protects against the artcraft and grok-api implementations
-  // silently drifting apart.
-
-  mod grok_api_parity {
-    use super::*;
-
-    // (resolution, duration, image_count)
-    //
-    // Durations are confined to [4, 15] because the ArtCraft pipeline clamps
-    // outside that range (see `plan_duration` in artcraft/build_common.rs).
-    // Every case carries exactly one image. v1.5 rejects text-to-video, AND
-    // the GrokApi build step collapses multi-image reference-to-video
-    // requests down to one `image` (promote-first; see grok_api side
-    // build.rs). So the only request shape where both sides agree on the
-    // input image count is the single-image case.
-    const PARITY_CASES: &[(Option<RouterResolution>, u16, u64)] = &[
-      // 480p variations
-      (Some(RouterResolution::FourEightyP),  4, 1),
-      (Some(RouterResolution::FourEightyP),  5, 1),
-      (Some(RouterResolution::FourEightyP),  8, 1),
-      (Some(RouterResolution::FourEightyP), 15, 1),
-      // 720p variations
-      (Some(RouterResolution::SevenTwentyP),  4, 1),
-      (Some(RouterResolution::SevenTwentyP),  5, 1),
-      (Some(RouterResolution::SevenTwentyP),  8, 1),
-      (Some(RouterResolution::SevenTwentyP), 15, 1),
-      // None defaults to 720p in our `from_request`, which matches the
-      // assumption Grok's calculator makes when fed a 720p request.
-      (None,                                  5, 1),
-    ];
-
-    #[test]
-    fn base_cost_for_one_video_matches_grok_api_client() {
-      for &(router_res, duration, image_count) in PARITY_CASES {
-        let artcraft = artcraft_state(router_res, duration, image_count, 1);
-        let grok_cents = grok_cents(router_res, duration, image_count);
-
-        assert_eq!(
-          artcraft.base_cost_in_cents_for_one_video(),
-          grok_cents,
-          "parity mismatch at res={router_res:?} dur={duration} images={image_count}: \
-           artcraft_base={} grok={}",
-          artcraft.base_cost_in_cents_for_one_video(),
-          grok_cents,
-        );
-      }
-    }
-
-    #[test]
-    fn batch_one_base_total_equals_one_video_base() {
-      let s = artcraft_state(Some(RouterResolution::SevenTwentyP), 5, 1, 1);
-      assert_eq!(s.base_cost_in_cents_for_batch(), s.base_cost_in_cents_for_one_video());
-    }
-
-    #[test]
-    fn batch_scales_base_linearly() {
-      // The ArtCraft pipeline only accepts batch counts of 1, 2, or 4 (see
-      // `plan_batch_count` in artcraft/build_common.rs); anything else gets
-      // clamped, so we can only meaningfully test those values.
-      let per_one = artcraft_state(Some(RouterResolution::SevenTwentyP), 5, 1, 1)
-        .base_cost_in_cents_for_one_video();
-      for batch in [1u16, 2, 4] {
-        let s = artcraft_state(Some(RouterResolution::SevenTwentyP), 5, 1, batch);
-        assert_eq!(
-          s.base_cost_in_cents_for_batch(),
-          per_one * batch as u64,
-          "batch={batch}",
-        );
-      }
-    }
-
-    /// Builder-driven parity — exercises the full pipeline (build2 →
-    /// estimate_cost) on both providers and compares ArtCraft's base cost
-    /// (final / 1.05, accounting for ceiling) against GrokApi's direct
-    /// cost.
-    ///
-    /// We verify the markup rather than the base here because the public
-    /// `estimate_cost()` returns the marked-up number; the explicit
-    /// `base_cost_in_cents_*` API is tested above.
-    #[test]
-    fn end_to_end_markup_is_at_least_five_percent_over_grok() {
-      // Single-image cases only — see PARITY_CASES comment above for why
-      // multi-image rows can't be apples-to-apples between the two sides.
-      let cases: &[(Option<RouterResolution>, u16, bool, usize)] = &[
-        (Some(RouterResolution::FourEightyP),  5, true,  0),
-        (Some(RouterResolution::FourEightyP), 10, true,  0),
-        (Some(RouterResolution::SevenTwentyP), 5, true,  0),
-        (Some(RouterResolution::SevenTwentyP), 8, true,  0),
-        (Some(RouterResolution::SevenTwentyP),15, true,  0),
-      ];
-      for &(res, duration, has_start, refs) in cases {
-        let artcraft_cents = artcraft_end_to_end_cents(res, duration, 1, has_start, refs);
-        let grok_cents = grok_cents(res, duration, has_start as u64 + refs as u64);
-        let want_minimum = grok_cents.saturating_mul(MARKUP_NUMERATOR).div_ceil(MARKUP_DENOMINATOR);
-        assert_eq!(
-          artcraft_cents, want_minimum,
-          "res={res:?} dur={duration} start={has_start} refs={refs}: \
-           artcraft={artcraft_cents}¢ vs ceil(grok({grok_cents})×1.05)={want_minimum}¢",
-        );
-      }
-    }
-  }
-
  // ── Markup correctness ─────────────────────────────────────────────────

  mod markup {
@@ -484,42 +377,6 @@ mod tests {
    }
  }

-  fn artcraft_end_to_end_cents(
-    resolution: Option<RouterResolution>,
-    duration_seconds: u16,
-    batch_count: u16,
-    has_start_frame: bool,
-    num_reference_images: usize,
-  ) -> u64 {
-    let start_frame = if has_start_frame {
-      Some(ImageRef::MediaFileToken(MediaFileToken::new("mf_start".to_string())))
-    } else { None };
-    let reference_images = if num_reference_images > 0 {
-      Some(ImageListRef::MediaFileTokens(
-        (0..num_reference_images)
-          .map(|i| MediaFileToken::new(format!("mf_ref_{i}")))
-          .collect(),
-      ))
-    } else { None };
-
-    let builder = GenerateVideoRequestBuilder {
-      model: RouterVideoModel::GrokImagineVideo1p5,
-      provider: RouterProvider::Artcraft,
-      resolution,
-      duration_seconds: Some(duration_seconds),
-      video_batch_count: Some(batch_count),
-      start_frame,
-      reference_images,
-      ..Default::default()
-    };
-    builder.build2()
-      .expect("build2 should succeed")
-      .estimate_cost()
-      .expect("estimate_cost should succeed")
-      .cost_in_usd_cents
-      .unwrap()
-  }
-
  fn build_cost_via_builder(
    resolution: Option<RouterResolution>,
    duration_seconds: u16,
@@ -542,40 +399,4 @@ mod tests {
      .expect("estimate_cost should succeed")
  }

-  /// Reference value: what GrokApi's own pipeline would charge for one
-  /// equivalent video. Used by parity tests.
-  ///
-  /// The Grok build step prefers `start_frame` over `reference_images` when
-  /// both are supplied and drops the latter (see grok_api/grok_imagine_video_1p5/build.rs).
-  /// To keep parity with the ArtCraft input-image *count*, we put all source
-  /// images in `reference_images` only — the cost calculator counts the total
-  /// either way.
-  fn grok_cents(
-    resolution: Option<RouterResolution>,
-    duration_seconds: u16,
-    image_count: u64,
-  ) -> u64 {
-    let reference_images = if image_count >= 1 {
-      Some(ImageListRef::Urls(
-        (0..image_count).map(|i| format!("https://example.com/ref_{i}.png")).collect(),
-      ))
-    } else { None };
-
-    let builder = GenerateVideoRequestBuilder {
-      model: RouterVideoModel::GrokImagineVideo1p5,
-      provider: RouterProvider::GrokApi,
-      resolution,
-      duration_seconds: Some(duration_seconds),
-      video_batch_count: Some(1),
-      start_frame: None,
-      reference_images,
-      ..Default::default()
-    };
-    builder.build2()
-      .expect("build2 (grokapi) should succeed")
-      .estimate_cost()
-      .expect("estimate_cost (grokapi) should succeed")
-      .cost_in_usd_cents
-      .unwrap()
-  }
 }
@@ -14,13 +14,16 @@ use crate::generate::generate_video::providers::artcraft::happy_horse_1p0::reque
 //
 // Default resolution (None) is 720p.
 // Batch count multiplies the total cost.
-// Credit package: 22,000 credits for $114 (~192.98 credits/$1, rounded to 193).
+// Credit package (historical): 22,000 credits for $114 (~193 credits/$1).
+// The upstream package is now 525,000 credits for $2,159.0909 (~243 credits/$1),
+// but user pricing is intentionally kept at the 193-derived rates.
 //
 // ArtCraft credits: 100 credits = $1.00, so ArtCraft credits = USD cents.
 // We compute USD cents from upstream credits ÷ credits_per_dollar × 100.

 const UPSTREAM_CREDITS_PER_SECOND_720P: u32 = 33;
 const UPSTREAM_CREDITS_PER_SECOND_1080P: u32 = 66;
+// Frozen at the historical rate so user pricing doesn't shift with the package deal.
 const UPSTREAM_CREDITS_PER_DOLLAR: f64 = 193.0;

 pub struct ArtcraftHappyHorse1p0CostState {
@@ -201,50 +204,6 @@ mod tests {
    }
  }

-  // ── Cross-check with Kinovi ──
-
-  mod cross_check_with_kinovi {
-    use super::*;
-
-    #[test]
-    fn artcraft_matches_kinovi_all_combos() {
-      let resolutions = [
-        Some(RouterResolution::SevenTwentyP),
-        None,
-        Some(RouterResolution::TenEightyP),
-      ];
-      let durations: [u16; 4] = [4, 5, 10, 15];
-      let batches: [u16; 3] = [1, 2, 4];
-
-      for res in &resolutions {
-        for dur in &durations {
-          for batch in &batches {
-            let artcraft_cost = build_cost(*res, *dur, *batch);
-
-            let kinovi = GenerateVideoRequestBuilder {
-              model: RouterVideoModel::HappyHorse1p0,
-              provider: RouterProvider::Seedance2Pro,
-              resolution: *res,
-              duration_seconds: Some(*dur),
-              video_batch_count: Some(*batch),
-              ..Default::default()
-            };
-            let kinovi_cost = kinovi.build2()
-              .expect("kinovi build2")
-              .estimate_cost()
-              .expect("kinovi estimate_cost");
-
-            assert_eq!(
-              artcraft_cost.cost_in_usd_cents, kinovi_cost.cost_in_usd_cents,
-              "USD cents mismatch: res={:?} dur={}s batch={}",
-              res, dur, batch,
-            );
-          }
-        }
-      }
-    }
-  }
-
  // ── Helpers ──

  fn build_cost(
@@ -18,6 +18,10 @@ use crate::generate::generate_video::providers::artcraft::seedance_2p0::request:
 ///
 /// We keep these as f64 because per-second rates are fractional; rounding
 /// happens once at the end after multiplying by duration × batch.
+///
+/// NB: Derivation is historical (193 credits/$1 package). The upstream
+/// package is now 525,000 credits for $2,159.0909 (~243 credits/$1), but
+/// user pricing is intentionally kept at these 193-derived rates.
 const CENTS_PER_SECOND_480P: f64 = 7.772;
 const CENTS_PER_SECOND_720P: f64 = 16.0;
 const CENTS_PER_SECOND_1080P: f64 = 46.632;
@@ -214,51 +218,6 @@ mod tests {
    }
  }

-  // -- Cross-check with Kinovi via builder --
-
-  mod cross_check_with_kinovi {
-    use super::*;
-
-    #[test]
-    fn artcraft_matches_kinovi_all_combos() {
-      let resolutions = [
-        Some(RouterResolution::FourEightyP),
-        Some(RouterResolution::TenEightyP),
-        // NB: These are underpriced (for now)
-        //Some(RouterResolution::SevenTwentyP),
-        //None,
-      ];
-      let durations: [u16; 4] = [4, 5, 10, 15];
-      let batches: [u16; 3] = [1, 2, 4];
-
-      for res in &resolutions {
-        for dur in &durations {
-          for batch in &batches {
-            let artcraft_cost = build_cost(*res, *dur, *batch);
-
-            let kinovi = GenerateVideoRequestBuilder {
-              provider: RouterProvider::Seedance2Pro,
-              resolution: *res,
-              duration_seconds: Some(*dur),
-              video_batch_count: Some(*batch),
-              ..Default::default()
-            };
-            let kinovi_cost = kinovi.build2()
-              .expect("kinovi build2")
-              .estimate_cost()
-              .expect("kinovi estimate_cost");
-
-            assert_eq!(
-              artcraft_cost.cost_in_usd_cents, kinovi_cost.cost_in_usd_cents,
-              "USD cents mismatch: res={:?} dur={}s batch={}",
-              res, dur, batch,
-            );
-          }
-        }
-      }
-    }
-  }
-
  // -- Helpers --

  /// Build a cost estimate end-to-end: GenerateVideoRequestBuilder → build2 → estimate_cost.
@@ -154,6 +154,8 @@ mod tests {
    }
  }

+  // -- Helpers --
+
  fn build_cost(
    resolution: Option<RouterResolution>,
    duration_seconds: u16,
@@ -125,6 +125,8 @@ mod tests {
    }
  }

+  // -- Helpers --
+
  fn build_cost(
    resolution: Option<RouterResolution>,
    duration_seconds: u16,
@@ -154,6 +154,8 @@ mod tests {
    }
  }

+  // -- Helpers --
+
  fn build_cost(
    resolution: Option<RouterResolution>,
    duration_seconds: u16,
@@ -125,6 +125,8 @@ mod tests {
    }
  }

+  // -- Helpers --
+
  fn build_cost(
    resolution: Option<RouterResolution>,
    duration_seconds: u16,
@@ -13,6 +13,8 @@ use crate::generate::generate_video::providers::artcraft::seedance_2p0_fast::req

 /// USD cents per second by resolution, derived from upstream Fast rates:
 ///   480p:  10 upstream-credits/sec / 193 upstream-credits/$1 * 100 ~= 5.181 c/s
+///   (historical 193 credits/$1 derivation; the upstream package is now
+///   ~243 credits/$1 but user pricing is intentionally unchanged)
 ///   720p:  28 upstream-credits/sec / 220 upstream-credits/$1 * 100 ~= 12.727 c/s
 ///
 /// We keep these as f64 because per-second rates are fractional; rounding
@@ -184,50 +186,6 @@ mod tests {
    }
  }

-  // -- Cross-check with Kinovi Fast via builder --
-
-  //mod cross_check_with_kinovi {
-  //  use super::*;
-  //
-  //  #[test]
-  //  fn artcraft_fast_matches_kinovi_fast_all_combos() {
-  //    let resolutions = [
-  //      Some(RouterResolution::FourEightyP),
-  //      Some(RouterResolution::SevenTwentyP),
-  //      None,
-  //    ];
-  //    let durations: [u16; 4] = [4, 5, 10, 15];
-  //    let batches: [u16; 3] = [1, 2, 4];
-  //
-  //    for res in &resolutions {
-  //      for dur in &durations {
-  //        for batch in &batches {
-  //          let artcraft_cost = build_cost(*res, *dur, *batch);
-  //
-  //          let kinovi = GenerateVideoRequestBuilder {
-  //            model: RouterVideoModel::Seedance2p0Fast,
-  //            provider: RouterProvider::Seedance2Pro,
-  //            resolution: *res,
-  //            duration_seconds: Some(*dur),
-  //            video_batch_count: Some(*batch),
-  //            ..Default::default()
-  //          };
-  //          let kinovi_cost = kinovi.build2()
-  //            .expect("kinovi build2")
-  //            .estimate_cost()
-  //            .expect("kinovi estimate_cost");
-  //
-  //          assert_eq!(
-  //            artcraft_cost.cost_in_usd_cents, kinovi_cost.cost_in_usd_cents,
-  //            "USD cents mismatch: res={:?} dur={}s batch={}",
-  //            res, dur, batch,
-  //          );
-  //        }
-  //      }
-  //    }
-  //  }
-  //}
-
  // -- Helpers --

  fn build_cost(
@@ -159,6 +159,8 @@ mod tests {
    }
  }

+  // -- Helpers --
+
  fn build_cost(
    resolution: Option<RouterResolution>,
    duration_seconds: u16,
@@ -144,6 +144,8 @@ mod tests {
    }
  }

+  // -- Helpers --
+
  fn build_cost(
    resolution: Option<RouterResolution>,
    duration_seconds: u16,
@@ -42,11 +42,12 @@ impl KinoviHappyHorse1p0CostState {
      start_frame_url: None,
    };

-    let cost_in_credits = pricing_request.estimate_credits();
-    let cost_in_usd_cents = pricing_request.estimate_cost_in_usd_cents();
+    let costs = pricing_request.calculate_costs();
+    let cost_in_credits = costs.kinovi_credits;
+    let cost_in_usd_cents = costs.usd_cents_rounded_up;

    VideoGenerationCostEstimate {
-      cost_in_credits: Some(cost_in_credits as u64),
+      cost_in_credits: Some(cost_in_credits),
      cost_in_usd_cents: Some(cost_in_usd_cents),
      is_free: false,
      is_unlimited: false,
@@ -97,10 +98,8 @@ mod tests {

    #[test]
    fn usd_cents_720p() {
-      // 165 credits / 193 * 100 = 85.49 → 85¢
-      assert_eq!(usd_cents(None, 5, None), 85);
-      // 495 credits / 193 * 100 = 256.48 → 256¢
-      assert_eq!(usd_cents(None, 15, None), 256);
+      assert_eq!(usd_cents(None, 5, None), 68); // 16500/243 = 67.90 -> rounds UP
+      assert_eq!(usd_cents(None, 15, None), 204); // 49500/243 = 203.70 -> rounds UP
    }
  }

@@ -130,10 +129,10 @@ mod tests {
    #[test]
    fn usd_cents_1080p() {
      let r = Some(KinoviHappyHorse1p0OutputResolution::TenEightyP);
-      // 330 credits / 193 * 100 = 170.98 → 171¢
-      assert_eq!(usd_cents(r, 5, None), 171);
-      // 990 credits / 193 * 100 = 512.95 → 513¢
-      assert_eq!(usd_cents(r, 15, None), 513);
+      // 330 credits; 33000/243 = 135.80 → rounds UP to 136¢
+      assert_eq!(usd_cents(r, 5, None), 136);
+      // 990 credits; 99000/243 = 407.41 → rounds UP to 408¢
+      assert_eq!(usd_cents(r, 15, None), 408);
    }
  }

@@ -237,7 +236,7 @@ mod tests {
      );
      let cost = KinoviHappyHorse1p0CostState::from_request(&req);
      assert_eq!(cost.estimate_cost().cost_in_credits, Some(330));
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(171));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(136));
    }
  }

@@ -46,23 +46,31 @@ impl KinoviSeedance2p0CostState {
      duration_seconds: self.duration_seconds,
      batch_count: self.batch_count,

+      // PRESENCE of reference videos changes the price (per-second
+      // surcharge); the URL contents don't.
+      reference_video_urls: if self.has_video_reference {
+        Some(vec!["pricing-placeholder".to_string()])
+      } else {
+        None
+      },
+
      // No impact on price
      prompt: String::new(),
      aspect_ratio: None,
      start_frame_url: None,
      end_frame_url: None,
      reference_image_urls: None,
-      reference_video_urls: None,
      reference_audio_urls: None,
      character_ids: None,
      use_face_blur_hack: None,
    };

-    let cost_in_credits = pricing_request.estimate_credits();
-    let cost_in_usd_cents = pricing_request.estimate_cost_in_usd_cents();
+    let costs = pricing_request.calculate_costs();
+    let cost_in_credits = costs.total_cost.kinovi_credits;
+    let cost_in_usd_cents = costs.total_cost.usd_cents_rounded_up;

    VideoGenerationCostEstimate {
-      cost_in_credits: Some(cost_in_credits as u64),
+      cost_in_credits: Some(cost_in_credits),
      cost_in_usd_cents: Some(cost_in_usd_cents),
      is_free: false,
      is_unlimited: false,
@@ -95,26 +103,26 @@ mod tests {

    #[test]
    fn cost_720p_batch_1() {
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 4, KinoviBatchCount::One), 83);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::One), 104);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 6, KinoviBatchCount::One), 124);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 7, KinoviBatchCount::One), 145);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 10, KinoviBatchCount::One), 207);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 15, KinoviBatchCount::One), 311);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 4, KinoviBatchCount::One), 66);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::One), 83);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 6, KinoviBatchCount::One), 99);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 7, KinoviBatchCount::One), 116);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 10, KinoviBatchCount::One), 165);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 15, KinoviBatchCount::One), 247);
    }

    #[test]
    fn cost_720p_batch_2() {
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 4, KinoviBatchCount::Two), 166);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::Two), 207);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 15, KinoviBatchCount::Two), 622);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 4, KinoviBatchCount::Two), 132);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::Two), 165);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 15, KinoviBatchCount::Two), 494);
    }

    #[test]
    fn cost_720p_batch_4() {
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 4, KinoviBatchCount::Four), 332);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::Four), 415);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 15, KinoviBatchCount::Four), 1244);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 4, KinoviBatchCount::Four), 264);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::Four), 330);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 15, KinoviBatchCount::Four), 988);
    }
  }

@@ -125,20 +133,20 @@ mod tests {

    #[test]
    fn cost_480p_batch_1() {
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 4, KinoviBatchCount::One), 31);
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::One), 39);
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 10, KinoviBatchCount::One), 78);
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 15, KinoviBatchCount::One), 117);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 4, KinoviBatchCount::One), 25);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::One), 31);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 10, KinoviBatchCount::One), 62);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 15, KinoviBatchCount::One), 93);
    }

    #[test]
    fn cost_480p_batch_2() {
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::Two), 78);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::Two), 62);
    }

    #[test]
    fn cost_480p_batch_4() {
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::Four), 155);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::Four), 124);
    }
  }

@@ -149,20 +157,20 @@ mod tests {

    #[test]
    fn cost_1080p_batch_1() {
-      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 4, KinoviBatchCount::One), 187);
-      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 5, KinoviBatchCount::One), 233);
-      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 10, KinoviBatchCount::One), 466);
-      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 15, KinoviBatchCount::One), 699);
+      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 4, KinoviBatchCount::One), 149);
+      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 5, KinoviBatchCount::One), 186);
+      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 10, KinoviBatchCount::One), 371);
+      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 15, KinoviBatchCount::One), 556);
    }

    #[test]
    fn cost_1080p_batch_2() {
-      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 5, KinoviBatchCount::Two), 466);
+      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 5, KinoviBatchCount::Two), 371);
    }

    #[test]
    fn cost_1080p_batch_4() {
-      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 5, KinoviBatchCount::Four), 933);
+      assert_eq!(usd_cents(KinoviOutputResolution::TenEightyP, 5, KinoviBatchCount::Four), 741);
    }
  }

@@ -202,7 +210,7 @@ mod tests {
  // -- Video reference does NOT affect cost (yet) --

  #[test]
-  fn video_reference_does_not_affect_cost() {
+  fn video_reference_adds_surcharge() {
    let base = KinoviSeedance2p0CostState {
      resolution: Some(KinoviOutputResolution::SevenTwentyP),
      duration_seconds: 5,
@@ -211,8 +219,10 @@ mod tests {
    };
    let without = base.estimate_cost();
    let with = KinoviSeedance2p0CostState { has_video_reference: true, ..base }.estimate_cost();
-    assert_eq!(without.cost_in_usd_cents, with.cost_in_usd_cents);
-    assert_eq!(without.cost_in_credits, with.cost_in_credits);
+    // 720p surcharge is +8 credits/s: 200 -> 240 credits (24000/243 = 98.77 -> 99 cents).
+    assert_eq!(without.cost_in_credits, Some(200));
+    assert_eq!(with.cost_in_credits, Some(240));
+    assert_eq!(with.cost_in_usd_cents, Some(99));
  }

  // ── from_request() tests ──
@@ -228,7 +238,7 @@ mod tests {
      assert_eq!(cost.duration_seconds, 5);
      assert!(matches!(cost.batch_count, Some(KinoviBatchCount::One)));
      assert!(!cost.has_video_reference);
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(104));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(83));
    }

    #[test]
@@ -236,21 +246,21 @@ mod tests {
      let req = make_request_state(None, 5, KinoviBatchCount::One, false);
      let cost = KinoviSeedance2p0CostState::from_request(&req);
      assert!(cost.resolution.is_none()); // None defaults to 720p pricing
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(104));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(83));
    }

    #[test]
    fn from_request_480p() {
      let req = make_request_state(Some(KinoviOutputResolution::FourEightyP), 5, KinoviBatchCount::One, false);
      let cost = KinoviSeedance2p0CostState::from_request(&req);
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(39));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(31));
    }

    #[test]
    fn from_request_1080p_batch_2() {
      let req = make_request_state(Some(KinoviOutputResolution::TenEightyP), 5, KinoviBatchCount::Two, false);
      let cost = KinoviSeedance2p0CostState::from_request(&req);
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(466));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(371));
    }

    #[test]
@@ -258,8 +268,9 @@ mod tests {
      let req = make_request_state(Some(KinoviOutputResolution::SevenTwentyP), 5, KinoviBatchCount::One, true);
      let cost = KinoviSeedance2p0CostState::from_request(&req);
      assert!(cost.has_video_reference);
-      // Video refs don't affect cost yet
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(104));
+      // Video refs add a +8 credits/s surcharge at 720p: 240 credits -> 125 cents.
+      assert_eq!(cost.estimate_cost().cost_in_credits, Some(240));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(99));
    }

    #[test]
@@ -283,7 +294,7 @@ mod tests {
      assert_eq!(cost.duration_seconds, 5);
      assert!(matches!(cost.batch_count, Some(KinoviBatchCount::One)));
      assert!(!cost.has_video_reference);
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(104));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(83));
    }

    #[test]
@@ -291,7 +302,7 @@ mod tests {
      let draft = make_draft(5, 1, Some(RouterResolution::FourEightyP), false);
      let cost = KinoviSeedance2p0CostState::from_draft(&draft);
      assert!(matches!(cost.resolution, Some(KinoviOutputResolution::FourEightyP)));
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(39));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(31));
    }

    #[test]
@@ -300,7 +311,7 @@ mod tests {
      let cost = KinoviSeedance2p0CostState::from_draft(&draft);
      assert!(matches!(cost.resolution, Some(KinoviOutputResolution::TenEightyP)));
      assert!(matches!(cost.batch_count, Some(KinoviBatchCount::Four)));
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(933));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(741));
    }

    #[test]
@@ -308,8 +319,9 @@ mod tests {
      let draft = make_draft(5, 1, None, true);
      let cost = KinoviSeedance2p0CostState::from_draft(&draft);
      assert!(cost.has_video_reference);
-      // Video refs don't affect cost yet
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(104));
+      // Video refs add a +8 credits/s surcharge at 720p: 240 credits -> 125 cents.
+      assert_eq!(cost.estimate_cost().cost_in_credits, Some(240));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(99));
    }

    #[test]
@@ -325,7 +337,7 @@ mod tests {
      let cost = KinoviSeedance2p0CostState::from_draft(&draft);
      assert_eq!(cost.duration_seconds, 15);
      assert!(matches!(cost.batch_count, Some(KinoviBatchCount::Two)));
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(622));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(494));
    }
  }

@@ -46,23 +46,31 @@ impl KinoviSeedance2p0FastCostState {
      duration_seconds: self.duration_seconds,
      batch_count: self.batch_count,

+      // PRESENCE of reference videos changes the price (per-second
+      // surcharge); the URL contents don't.
+      reference_video_urls: if self.has_video_reference {
+        Some(vec!["pricing-placeholder".to_string()])
+      } else {
+        None
+      },
+
      // No impact on price
      prompt: String::new(),
      aspect_ratio: None,
      start_frame_url: None,
      end_frame_url: None,
      reference_image_urls: None,
-      reference_video_urls: None,
      reference_audio_urls: None,
      character_ids: None,
      use_face_blur_hack: None,
    };

-    let cost_in_credits = pricing_request.estimate_credits();
-    let cost_in_usd_cents = pricing_request.estimate_cost_in_usd_cents();
+    let costs = pricing_request.calculate_costs();
+    let cost_in_credits = costs.total_cost.kinovi_credits;
+    let cost_in_usd_cents = costs.total_cost.usd_cents_rounded_up;

    VideoGenerationCostEstimate {
-      cost_in_credits: Some(cost_in_credits as u64),
+      cost_in_credits: Some(cost_in_credits),
      cost_in_usd_cents: Some(cost_in_usd_cents),
      is_free: false,
      is_unlimited: false,
@@ -92,51 +100,51 @@ mod tests {
  // ── Direct estimate_cost() tests ──
  // These must match the reference implementation values exactly.

-  // -- 720p (28 credits/sec, 193 credits/$1) --
+  // -- 720p (28 credits/sec, 243 credits/$1) --

  mod pricing_720p {
    use super::*;

    #[test]
    fn cost_720p_batch_1() {
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 4, KinoviBatchCount::One), 58);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::One), 73);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 10, KinoviBatchCount::One), 145);
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 15, KinoviBatchCount::One), 218);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 4, KinoviBatchCount::One), 47);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::One), 58);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 10, KinoviBatchCount::One), 116);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 15, KinoviBatchCount::One), 173);
    }

    #[test]
    fn cost_720p_batch_2() {
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::Two), 145);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::Two), 116);
    }

    #[test]
    fn cost_720p_batch_4() {
-      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::Four), 290);
+      assert_eq!(usd_cents(KinoviOutputResolution::SevenTwentyP, 5, KinoviBatchCount::Four), 231);
    }
  }

-  // -- 480p (14 credits/sec, 193 credits/$1) --
+  // -- 480p (14 credits/sec, 243 credits/$1) --

  mod pricing_480p {
    use super::*;

    #[test]
    fn cost_480p_batch_1() {
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 4, KinoviBatchCount::One), 29);
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::One), 36);
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 10, KinoviBatchCount::One), 73);
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 15, KinoviBatchCount::One), 109);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 4, KinoviBatchCount::One), 24);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::One), 29);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 10, KinoviBatchCount::One), 58);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 15, KinoviBatchCount::One), 87);
    }

    #[test]
    fn cost_480p_batch_2() {
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::Two), 73);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::Two), 58);
    }

    #[test]
    fn cost_480p_batch_4() {
-      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::Four), 145);
+      assert_eq!(usd_cents(KinoviOutputResolution::FourEightyP, 5, KinoviBatchCount::Four), 116);
    }
  }

@@ -174,7 +182,7 @@ mod tests {
  // -- Video reference does NOT affect cost (yet) --

  #[test]
-  fn video_reference_does_not_affect_cost() {
+  fn video_reference_adds_surcharge() {
    let base = KinoviSeedance2p0FastCostState {
      resolution: Some(KinoviOutputResolution::SevenTwentyP),
      duration_seconds: 5,
@@ -183,8 +191,10 @@ mod tests {
    };
    let without = base.estimate_cost();
    let with = KinoviSeedance2p0FastCostState { has_video_reference: true, ..base }.estimate_cost();
-    assert_eq!(without.cost_in_usd_cents, with.cost_in_usd_cents);
-    assert_eq!(without.cost_in_credits, with.cost_in_credits);
+    // Fast 720p surcharge is +6 credits/s: 140 -> 170 credits (17000/243 = 69.96 -> 70 cents).
+    assert_eq!(without.cost_in_credits, Some(140));
+    assert_eq!(with.cost_in_credits, Some(170));
+    assert_eq!(with.cost_in_usd_cents, Some(70));
  }

  // ── from_request() tests ──
@@ -200,7 +210,7 @@ mod tests {
      assert_eq!(cost.duration_seconds, 5);
      assert!(matches!(cost.batch_count, Some(KinoviBatchCount::One)));
      assert!(!cost.has_video_reference);
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(73));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(58));
    }

    #[test]
@@ -208,14 +218,14 @@ mod tests {
      let req = make_request_state(None, 5, KinoviBatchCount::One, false);
      let cost = KinoviSeedance2p0FastCostState::from_request(&req);
      assert!(cost.resolution.is_none());
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(73));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(58));
    }

    #[test]
    fn from_request_480p() {
      let req = make_request_state(Some(KinoviOutputResolution::FourEightyP), 5, KinoviBatchCount::One, false);
      let cost = KinoviSeedance2p0FastCostState::from_request(&req);
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(36));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(29));
    }

    #[test]
@@ -223,8 +233,9 @@ mod tests {
      let req = make_request_state(Some(KinoviOutputResolution::SevenTwentyP), 5, KinoviBatchCount::One, true);
      let cost = KinoviSeedance2p0FastCostState::from_request(&req);
      assert!(cost.has_video_reference);
-      // Video refs don't affect cost yet
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(73));
+      // Video refs add a +6 credits/s surcharge at 720p: 170 credits -> 89 cents.
+      assert_eq!(cost.estimate_cost().cost_in_credits, Some(170));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(70));
    }

    #[test]
@@ -248,7 +259,7 @@ mod tests {
      assert_eq!(cost.duration_seconds, 5);
      assert!(matches!(cost.batch_count, Some(KinoviBatchCount::One)));
      assert!(!cost.has_video_reference);
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(73));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(58));
    }

    #[test]
@@ -256,7 +267,7 @@ mod tests {
      let draft = make_draft(5, 1, Some(RouterResolution::FourEightyP), false);
      let cost = KinoviSeedance2p0FastCostState::from_draft(&draft);
      assert!(matches!(cost.resolution, Some(KinoviOutputResolution::FourEightyP)));
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(36));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(29));
    }

    #[test]
@@ -264,8 +275,9 @@ mod tests {
      let draft = make_draft(5, 1, None, true);
      let cost = KinoviSeedance2p0FastCostState::from_draft(&draft);
      assert!(cost.has_video_reference);
-      // Video refs don't affect cost yet
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(73));
+      // Video refs add a +6 credits/s surcharge at 720p: 170 credits -> 89 cents.
+      assert_eq!(cost.estimate_cost().cost_in_credits, Some(170));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(70));
    }

    #[test]
@@ -281,7 +293,7 @@ mod tests {
      let cost = KinoviSeedance2p0FastCostState::from_draft(&draft);
      assert_eq!(cost.duration_seconds, 15);
      assert!(matches!(cost.batch_count, Some(KinoviBatchCount::Two)));
-      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(435));
+      assert_eq!(cost.estimate_cost().cost_in_usd_cents, Some(346));
    }
  }

@@ -0,0 +1,30 @@
+[package]
+name = "comet_api_client"
+edition = "2024"
+version = "0.0.1"
+publish = false
+
+[package.metadata.cargo-udeps.ignore]
+normal = ["workspace-build-acceleration"]
+
+[lib]
+name = "comet_api_client"
+path = "src/lib.rs"
+
+[dependencies]
+# Workspace hack (faster compile times)
+workspace-build-acceleration.workspace = true
+
+# External
+log.workspace = true
+# `multipart` is enabled on top of the workspace feature set because the
+# CometAPI video creation endpoint takes `multipart/form-data` (the
+# `input_reference` image fields are binary parts).
+reqwest = { workspace = true, features = ["multipart"] }
+serde.workspace = true
+serde_derive.workspace = true
+serde_json.workspace = true
+
+[dev-dependencies]
+test_data = { path = "../../testing/test_data" }
+tokio = { version = "1", features = ["full"] }
@@ -0,0 +1,17 @@
+/// A CometAPI key used for Bearer token authentication.
+#[derive(Clone)]
+pub struct CometApiKey(pub String);
+
+impl CometApiKey {
+  pub fn new(api_key: String) -> Self {
+    Self(api_key.trim().to_string())
+  }
+
+  pub fn from_str(api_key: &str) -> Self {
+    Self(api_key.trim().to_string())
+  }
+
+  pub fn as_str(&self) -> &str {
+    &self.0
+  }
+}
@@ -0,0 +1 @@
+pub mod comet_api_key;
@@ -0,0 +1,157 @@
+use reqwest::StatusCode;
+
+use crate::error::comet_bad_request_api_error::CometBadRequestApiError;
+use crate::error::comet_error::CometError;
+use crate::error::comet_generic_api_error::CometGenericApiError;
+use crate::error::comet_specific_api_error::CometSpecificApiError;
+
+/// Marker CometAPI returns from `GET /v1/videos/{id}` for unknown task ids.
+const TASK_NOT_EXIST_MARKER: &str = "task_not_exist";
+
+/// Categorize a non-success response from the video creation endpoint
+/// (`POST /v1/videos`).
+///
+/// Per the docs, 400s from this endpoint mean the request itself was invalid
+/// (missing prompt, out-of-range duration, image input on an unsupported
+/// model) — the caller's fault, surfaced as [`CometBadRequestApiError`].
+pub fn categorize_create_video_error(
+  status_code: StatusCode,
+  body: String,
+) -> CometError {
+  if status_code == StatusCode::UNAUTHORIZED {
+    return CometSpecificApiError::UnauthorizedInvalidApiKey { raw_body: body }.into();
+  }
+
+  if status_code == StatusCode::BAD_REQUEST {
+    return CometBadRequestApiError::InvalidRequestParameters { raw_body: body }.into();
+  }
+
+  CometGenericApiError::UncategorizedBadResponseWithStatusAndBody {
+    status_code,
+    body,
+  }.into()
+}
+
+/// Categorize a non-success response from the poll endpoint
+/// (`GET /v1/videos/{id}`).
+///
+/// Unlike the creation endpoint, a 400 here means the task id is unknown
+/// ("task_not_exist") — a specific, well-known cause rather than a
+/// user-facing bad request.
+pub fn categorize_get_video_task_error(
+  status_code: StatusCode,
+  body: String,
+  task_id: &str,
+) -> CometError {
+  if status_code == StatusCode::UNAUTHORIZED {
+    return CometSpecificApiError::UnauthorizedInvalidApiKey { raw_body: body }.into();
+  }
+
+  if status_code == StatusCode::BAD_REQUEST && body.contains(TASK_NOT_EXIST_MARKER) {
+    return CometSpecificApiError::TaskNotFound {
+      task_id: task_id.to_string(),
+      raw_body: body,
+    }.into();
+  }
+
+  CometGenericApiError::UncategorizedBadResponseWithStatusAndBody {
+    status_code,
+    body,
+  }.into()
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  mod create_video_tests {
+    use super::*;
+
+    #[test]
+    fn bad_request_is_caller_fault() {
+      let body = r#"{"error":{"message":"seconds must be between 4 and 15","type":"invalid_request_error"}}"#.to_string();
+
+      let error = categorize_create_video_error(StatusCode::BAD_REQUEST, body.clone());
+
+      match error {
+        CometError::ApiBadRequest(CometBadRequestApiError::InvalidRequestParameters { raw_body }) => {
+          assert_eq!(raw_body, body);
+        }
+        other => panic!("Expected InvalidRequestParameters, got: {:?}", other),
+      }
+    }
+
+    #[test]
+    fn unauthorized_is_specific() {
+      let body = r#"{"error":{"message":"invalid token","type":"cometapi_error"}}"#.to_string();
+
+      let error = categorize_create_video_error(StatusCode::UNAUTHORIZED, body);
+
+      match error {
+        CometError::ApiSpecific(CometSpecificApiError::UnauthorizedInvalidApiKey { raw_body }) => {
+          assert!(raw_body.contains("invalid token"));
+        }
+        other => panic!("Expected UnauthorizedInvalidApiKey, got: {:?}", other),
+      }
+    }
+
+    #[test]
+    fn server_errors_fall_back_to_uncategorized() {
+      let error = categorize_create_video_error(
+        StatusCode::BAD_GATEWAY,
+        "upstream timeout".to_string(),
+      );
+
+      match &error {
+        CometError::ApiGeneric(CometGenericApiError::UncategorizedBadResponseWithStatusAndBody { status_code, .. }) => {
+          assert_eq!(*status_code, StatusCode::BAD_GATEWAY);
+        }
+        other => panic!("Expected UncategorizedBadResponseWithStatusAndBody, got: {:?}", other),
+      }
+      assert!(error.is_having_downtime_issues());
+    }
+  }
+
+  mod get_video_task_tests {
+    use super::*;
+
+    #[test]
+    fn task_not_exist_is_task_not_found() {
+      let body = r#"{"error":{"message":"task_not_exist","type":"cometapi_error"}}"#.to_string();
+
+      let error = categorize_get_video_task_error(StatusCode::BAD_REQUEST, body, "task_abc123");
+
+      match error {
+        CometError::ApiSpecific(CometSpecificApiError::TaskNotFound { task_id, raw_body }) => {
+          assert_eq!(task_id, "task_abc123");
+          assert!(raw_body.contains("task_not_exist"));
+        }
+        other => panic!("Expected TaskNotFound, got: {:?}", other),
+      }
+    }
+
+    #[test]
+    fn other_bad_requests_fall_back_to_uncategorized() {
+      let body = r#"{"error":{"message":"something else"}}"#.to_string();
+
+      let error = categorize_get_video_task_error(StatusCode::BAD_REQUEST, body, "task_abc123");
+
+      match error {
+        CometError::ApiGeneric(CometGenericApiError::UncategorizedBadResponseWithStatusAndBody { .. }) => {}
+        other => panic!("Expected UncategorizedBadResponseWithStatusAndBody, got: {:?}", other),
+      }
+    }
+
+    #[test]
+    fn unauthorized_is_specific() {
+      let body = r#"{"error":{"message":"invalid token"}}"#.to_string();
+
+      let error = categorize_get_video_task_error(StatusCode::UNAUTHORIZED, body, "task_abc123");
+
+      match error {
+        CometError::ApiSpecific(CometSpecificApiError::UnauthorizedInvalidApiKey { .. }) => {}
+        other => panic!("Expected UnauthorizedInvalidApiKey, got: {:?}", other),
+      }
+    }
+  }
+}
@@ -0,0 +1,22 @@
+use std::error::Error;
+use std::fmt::{Display, Formatter};
+
+/// These represent known "400s" that are the fault of the client sending a
+/// bad request. They should surface to the end user as 400s.
+#[derive(Debug)]
+pub enum CometBadRequestApiError {
+  /// The video creation request was rejected for invalid parameters (eg.
+  /// missing prompt, out-of-range duration, an `input_reference` image on a
+  /// model that doesn't support image input).
+  InvalidRequestParameters { raw_body: String },
+}
+
+impl Error for CometBadRequestApiError {}
+
+impl Display for CometBadRequestApiError {
+  fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+    match self {
+      Self::InvalidRequestParameters { raw_body } => write!(f, "Invalid request parameters: {}", raw_body),
+    }
+  }
+}
@@ -0,0 +1,26 @@
+use std::error::Error;
+use std::fmt::{Display, Formatter};
+
+#[derive(Debug)]
+pub enum CometClientError {
+  /// An error was encountered building the reqwest client or the request.
+  ReqwestClientError(reqwest::Error),
+
+  /// A request field couldn't be validated or converted to the value
+  /// expected on the wire. Carries the field name and the raw input the
+  /// caller supplied.
+  InvalidRequestField { field: &'static str, raw_value: String, reason: String },
+}
+
+impl Error for CometClientError {}
+
+impl Display for CometClientError {
+  fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+    match self {
+      Self::ReqwestClientError(err) => write!(f, "Reqwest client error: {}", err),
+      Self::InvalidRequestField { field, raw_value, reason } => {
+        write!(f, "Invalid value for request field `{}`: {:?} ({})", field, raw_value, reason)
+      }
+    }
+  }
+}
@@ -0,0 +1,71 @@
+use std::error::Error;
+use std::fmt::{Display, Formatter};
+
+use crate::error::comet_bad_request_api_error::CometBadRequestApiError;
+use crate::error::comet_client_error::CometClientError;
+use crate::error::comet_generic_api_error::CometGenericApiError;
+use crate::error::comet_specific_api_error::CometSpecificApiError;
+
+#[derive(Debug)]
+pub enum CometError {
+  /// An error that happened client-side (before or while making the request).
+  Client(CometClientError),
+
+  /// Known "400s" that are the fault of the client sending a bad request.
+  /// These should surface to the end user as 400s.
+  ApiBadRequest(CometBadRequestApiError),
+
+  /// Server-side errors with specific, well-known causes.
+  ApiSpecific(CometSpecificApiError),
+
+  /// Server-side errors with unknown / grab-bag causes.
+  ApiGeneric(CometGenericApiError),
+}
+
+impl CometError {
+  pub fn is_having_downtime_issues(&self) -> bool {
+    match self {
+      Self::ApiGeneric(CometGenericApiError::UncategorizedBadResponseWithStatusAndBody { status_code, body: _ }) => {
+        matches!(status_code.as_u16(), 502 | 503 | 504 | 524)
+      },
+      _ => false,
+    }
+  }
+}
+
+impl Error for CometError {}
+
+impl Display for CometError {
+  fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+    match self {
+      Self::Client(e) => write!(f, "CometClientError: {:?}", e),
+      Self::ApiBadRequest(e) => write!(f, "CometBadRequestApiError: {:?}", e),
+      Self::ApiSpecific(e) => write!(f, "CometSpecificApiError: {:?}", e),
+      Self::ApiGeneric(e) => write!(f, "CometGenericApiError: {:?}", e),
+    }
+  }
+}
+
+impl From<CometClientError> for CometError {
+  fn from(error: CometClientError) -> Self {
+    Self::Client(error)
+  }
+}
+
+impl From<CometBadRequestApiError> for CometError {
+  fn from(error: CometBadRequestApiError) -> Self {
+    Self::ApiBadRequest(error)
+  }
+}
+
+impl From<CometSpecificApiError> for CometError {
+  fn from(error: CometSpecificApiError) -> Self {
+    Self::ApiSpecific(error)
+  }
+}
+
+impl From<CometGenericApiError> for CometError {
+  fn from(error: CometGenericApiError) -> Self {
+    Self::ApiGeneric(error)
+  }
+}
@@ -0,0 +1,33 @@
+use std::error::Error;
+use std::fmt::{Display, Formatter};
+
+use reqwest::StatusCode;
+
+/// Server-side errors with unknown / grab-bag causes.
+#[derive(Debug)]
+pub enum CometGenericApiError {
+  /// serde_json::Error, likely from a JSON deserialization schema mismatch.
+  /// Includes the original body.
+  SerdeResponseParseErrorWithBody(serde_json::Error, String),
+
+  /// An uncategorized bad HTTP response with status code and body.
+  UncategorizedBadResponseWithStatusAndBody {
+    status_code: StatusCode,
+    body: String,
+  },
+
+  /// An uncaught error from the HTTP client (network failures, timeouts, etc.)
+  ReqwestError(reqwest::Error),
+}
+
+impl Error for CometGenericApiError {}
+
+impl Display for CometGenericApiError {
+  fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+    match self {
+      Self::SerdeResponseParseErrorWithBody(err, body) => write!(f, "Failed to parse response body: {:?}. Body: {}", err, body),
+      Self::UncategorizedBadResponseWithStatusAndBody { status_code, body } => write!(f, "Uncategorized bad response: status code {}, body: {}", status_code, body),
+      Self::ReqwestError(err) => write!(f, "Reqwest error: {}", err),
+    }
+  }
+}
@@ -0,0 +1,23 @@
+use std::error::Error;
+use std::fmt::{Display, Formatter};
+
+/// Server-side errors with specific, well-known causes.
+#[derive(Debug)]
+pub enum CometSpecificApiError {
+  /// 401: the API key is missing or invalid.
+  UnauthorizedInvalidApiKey { raw_body: String },
+
+  /// The poll endpoint responded "task_not_exist" for the given task id.
+  TaskNotFound { task_id: String, raw_body: String },
+}
+
+impl Error for CometSpecificApiError {}
+
+impl Display for CometSpecificApiError {
+  fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+    match self {
+      Self::UnauthorizedInvalidApiKey { raw_body } => write!(f, "Unauthorized: invalid or missing API key: {}", raw_body),
+      Self::TaskNotFound { task_id, raw_body } => write!(f, "Task not found: {} ({})", task_id, raw_body),
+    }
+  }
+}
@@ -0,0 +1,6 @@
+pub mod categorize_comet_error;
+pub mod comet_bad_request_api_error;
+pub mod comet_client_error;
+pub mod comet_error;
+pub mod comet_generic_api_error;
+pub mod comet_specific_api_error;
@@ -0,0 +1 @@
+pub mod video;
@@ -0,0 +1,146 @@
+use crate::creds::comet_api_key::CometApiKey;
+use crate::error::comet_client_error::CometClientError;
+use crate::error::comet_error::CometError;
+use crate::requests::create_video::create_video::{
+  create_video, CometVideoModelRaw, CometVideoSize, CreateVideoArgs, CreateVideoRequest,
+};
+use crate::requests::video_task_status::CometVideoTaskStatus;
+
+/// Seedance 1.0 Pro supports 2-10 second durations.
+const MIN_DURATION_SECONDS: u8 = 2;
+const MAX_DURATION_SECONDS: u8 = 10;
+
+// ── Args ──
+
+pub struct GenerateDoubaoSeedance1p0ProArgs<'a> {
+  pub request: GenerateDoubaoSeedance1p0ProRequest,
+  pub api_key: &'a CometApiKey,
+}
+
+// ── Request ──
+
+/// NB: Seedance 1.0 Pro is text-only — `input_reference` images are not
+/// supported, so this request deliberately has no image field.
+#[derive(Clone, Debug)]
+pub struct GenerateDoubaoSeedance1p0ProRequest {
+  pub prompt: String,
+
+  /// 2-10 seconds. `None` uses the API default (5).
+  pub duration_seconds: Option<u8>,
+
+  pub size: Option<DoubaoSeedance1p0ProSize>,
+}
+
+// ── Enums ──
+
+#[derive(Debug, Clone, Copy)]
+pub enum DoubaoSeedance1p0ProSize {
+  Landscape16x9,
+  Standard4x3,
+  Square1x1,
+  Portrait3x4,
+  Portrait9x16,
+  UltraWide21x9,
+  Exact { width: u32, height: u32 },
+}
+
+// ── Response ──
+
+pub struct GenerateDoubaoSeedance1p0ProResponse {
+  /// Poll `GET /v1/videos/{task_id}` until terminal.
+  pub task_id: String,
+  pub status: CometVideoTaskStatus,
+}
+
+// ── Entry point ──
+
+pub async fn generate_doubao_seedance_1p0_pro(
+  args: GenerateDoubaoSeedance1p0ProArgs<'_>,
+) -> Result<GenerateDoubaoSeedance1p0ProResponse, CometError> {
+  let raw_request = args.request.to_create_video_request()?;
+
+  let result = create_video(CreateVideoArgs {
+    api_key: args.api_key,
+    request: raw_request,
+  }).await?;
+
+  Ok(GenerateDoubaoSeedance1p0ProResponse {
+    task_id: result.task_id,
+    status: result.status,
+  })
+}
+
+impl GenerateDoubaoSeedance1p0ProRequest {
+  /// Validate and lower to the generic wire request.
+  pub fn to_create_video_request(&self) -> Result<CreateVideoRequest, CometClientError> {
+    if let Some(seconds) = self.duration_seconds {
+      if !(MIN_DURATION_SECONDS..=MAX_DURATION_SECONDS).contains(&seconds) {
+        return Err(CometClientError::InvalidRequestField {
+          field: "duration_seconds",
+          raw_value: seconds.to_string(),
+          reason: format!("Seedance 1.0 Pro supports {MIN_DURATION_SECONDS}-{MAX_DURATION_SECONDS} second durations"),
+        });
+      }
+    }
+
+    Ok(CreateVideoRequest {
+      model: CometVideoModelRaw::DoubaoSeedance1p0Pro,
+      prompt: self.prompt.clone(),
+      maybe_seconds: self.duration_seconds,
+      maybe_size: self.size.map(map_size),
+      input_reference_images: vec![],
+    })
+  }
+}
+
+fn map_size(size: DoubaoSeedance1p0ProSize) -> CometVideoSize {
+  match size {
+    DoubaoSeedance1p0ProSize::Landscape16x9 => CometVideoSize::Landscape16x9,
+    DoubaoSeedance1p0ProSize::Standard4x3 => CometVideoSize::Standard4x3,
+    DoubaoSeedance1p0ProSize::Square1x1 => CometVideoSize::Square,
+    DoubaoSeedance1p0ProSize::Portrait3x4 => CometVideoSize::Portrait3x4,
+    DoubaoSeedance1p0ProSize::Portrait9x16 => CometVideoSize::Portrait9x16,
+    DoubaoSeedance1p0ProSize::UltraWide21x9 => CometVideoSize::UltraWide21x9,
+    DoubaoSeedance1p0ProSize::Exact { width, height } => CometVideoSize::Exact { width, height },
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn maps_to_wire_request() {
+    let request = GenerateDoubaoSeedance1p0ProRequest {
+      prompt: "time lapse of a city at dusk".to_string(),
+      duration_seconds: Some(2),
+      size: Some(DoubaoSeedance1p0ProSize::Square1x1),
+    };
+
+    let raw = request.to_create_video_request().expect("should validate");
+    assert_eq!(raw.text_form_fields(), vec![
+      ("model", "doubao-seedance-1-0-pro".to_string()),
+      ("prompt", "time lapse of a city at dusk".to_string()),
+      ("seconds", "2".to_string()),
+      ("size", "1:1".to_string()),
+    ]);
+    assert!(raw.input_reference_images.is_empty());
+  }
+
+  #[test]
+  fn duration_bounds() {
+    assert!(request_with_seconds(Some(1)).to_create_video_request().is_err());
+    assert!(request_with_seconds(Some(2)).to_create_video_request().is_ok());
+    assert!(request_with_seconds(Some(10)).to_create_video_request().is_ok());
+    assert!(request_with_seconds(Some(11)).to_create_video_request().is_err());
+    assert!(request_with_seconds(None).to_create_video_request().is_ok());
+  }
+
+  fn request_with_seconds(duration_seconds: Option<u8>) -> GenerateDoubaoSeedance1p0ProRequest {
+    GenerateDoubaoSeedance1p0ProRequest {
+      prompt: "ok".to_string(),
+      duration_seconds,
+      size: None,
+    }
+  }
+}
@@ -0,0 +1,146 @@
+use crate::creds::comet_api_key::CometApiKey;
+use crate::error::comet_client_error::CometClientError;
+use crate::error::comet_error::CometError;
+use crate::requests::create_video::create_video::{
+  create_video, CometVideoModelRaw, CometVideoSize, CreateVideoArgs, CreateVideoRequest,
+};
+use crate::requests::video_task_status::CometVideoTaskStatus;
+
+/// Seedance 1.5 Pro supports 4-12 second durations.
+const MIN_DURATION_SECONDS: u8 = 4;
+const MAX_DURATION_SECONDS: u8 = 12;
+
+// ── Args ──
+
+pub struct GenerateDoubaoSeedance1p5ProArgs<'a> {
+  pub request: GenerateDoubaoSeedance1p5ProRequest,
+  pub api_key: &'a CometApiKey,
+}
+
+// ── Request ──
+
+/// NB: Seedance 1.5 Pro is text-only — `input_reference` images are not
+/// supported, so this request deliberately has no image field.
+#[derive(Clone, Debug)]
+pub struct GenerateDoubaoSeedance1p5ProRequest {
+  pub prompt: String,
+
+  /// 4-12 seconds. `None` uses the API default (5).
+  pub duration_seconds: Option<u8>,
+
+  pub size: Option<DoubaoSeedance1p5ProSize>,
+}
+
+// ── Enums ──
+
+#[derive(Debug, Clone, Copy)]
+pub enum DoubaoSeedance1p5ProSize {
+  Landscape16x9,
+  Standard4x3,
+  Square1x1,
+  Portrait3x4,
+  Portrait9x16,
+  UltraWide21x9,
+  Exact { width: u32, height: u32 },
+}
+
+// ── Response ──
+
+pub struct GenerateDoubaoSeedance1p5ProResponse {
+  /// Poll `GET /v1/videos/{task_id}` until terminal.
+  pub task_id: String,
+  pub status: CometVideoTaskStatus,
+}
+
+// ── Entry point ──
+
+pub async fn generate_doubao_seedance_1p5_pro(
+  args: GenerateDoubaoSeedance1p5ProArgs<'_>,
+) -> Result<GenerateDoubaoSeedance1p5ProResponse, CometError> {
+  let raw_request = args.request.to_create_video_request()?;
+
+  let result = create_video(CreateVideoArgs {
+    api_key: args.api_key,
+    request: raw_request,
+  }).await?;
+
+  Ok(GenerateDoubaoSeedance1p5ProResponse {
+    task_id: result.task_id,
+    status: result.status,
+  })
+}
+
+impl GenerateDoubaoSeedance1p5ProRequest {
+  /// Validate and lower to the generic wire request.
+  pub fn to_create_video_request(&self) -> Result<CreateVideoRequest, CometClientError> {
+    if let Some(seconds) = self.duration_seconds {
+      if !(MIN_DURATION_SECONDS..=MAX_DURATION_SECONDS).contains(&seconds) {
+        return Err(CometClientError::InvalidRequestField {
+          field: "duration_seconds",
+          raw_value: seconds.to_string(),
+          reason: format!("Seedance 1.5 Pro supports {MIN_DURATION_SECONDS}-{MAX_DURATION_SECONDS} second durations"),
+        });
+      }
+    }
+
+    Ok(CreateVideoRequest {
+      model: CometVideoModelRaw::DoubaoSeedance1p5Pro,
+      prompt: self.prompt.clone(),
+      maybe_seconds: self.duration_seconds,
+      maybe_size: self.size.map(map_size),
+      input_reference_images: vec![],
+    })
+  }
+}
+
+fn map_size(size: DoubaoSeedance1p5ProSize) -> CometVideoSize {
+  match size {
+    DoubaoSeedance1p5ProSize::Landscape16x9 => CometVideoSize::Landscape16x9,
+    DoubaoSeedance1p5ProSize::Standard4x3 => CometVideoSize::Standard4x3,
+    DoubaoSeedance1p5ProSize::Square1x1 => CometVideoSize::Square,
+    DoubaoSeedance1p5ProSize::Portrait3x4 => CometVideoSize::Portrait3x4,
+    DoubaoSeedance1p5ProSize::Portrait9x16 => CometVideoSize::Portrait9x16,
+    DoubaoSeedance1p5ProSize::UltraWide21x9 => CometVideoSize::UltraWide21x9,
+    DoubaoSeedance1p5ProSize::Exact { width, height } => CometVideoSize::Exact { width, height },
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn maps_to_wire_request() {
+    let request = GenerateDoubaoSeedance1p5ProRequest {
+      prompt: "a paper boat in a storm drain".to_string(),
+      duration_seconds: Some(12),
+      size: Some(DoubaoSeedance1p5ProSize::Portrait9x16),
+    };
+
+    let raw = request.to_create_video_request().expect("should validate");
+    assert_eq!(raw.text_form_fields(), vec![
+      ("model", "doubao-seedance-1-5-pro".to_string()),
+      ("prompt", "a paper boat in a storm drain".to_string()),
+      ("seconds", "12".to_string()),
+      ("size", "9:16".to_string()),
+    ]);
+    assert!(raw.input_reference_images.is_empty());
+  }
+
+  #[test]
+  fn duration_bounds() {
+    assert!(request_with_seconds(Some(3)).to_create_video_request().is_err());
+    assert!(request_with_seconds(Some(4)).to_create_video_request().is_ok());
+    assert!(request_with_seconds(Some(12)).to_create_video_request().is_ok());
+    assert!(request_with_seconds(Some(13)).to_create_video_request().is_err());
+    assert!(request_with_seconds(None).to_create_video_request().is_ok());
+  }
+
+  fn request_with_seconds(duration_seconds: Option<u8>) -> GenerateDoubaoSeedance1p5ProRequest {
+    GenerateDoubaoSeedance1p5ProRequest {
+      prompt: "ok".to_string(),
+      duration_seconds,
+      size: None,
+    }
+  }
+}
@@ -0,0 +1,471 @@
+use crate::creds::comet_api_key::CometApiKey;
+use crate::error::comet_client_error::CometClientError;
+use crate::error::comet_error::CometError;
+use crate::requests::create_video::create_video::{
+  create_video, CometInputReferenceImage, CometVideoModelRaw, CometVideoSize,
+  CreateVideoArgs, CreateVideoRequest,
+};
+use crate::requests::video_task_status::CometVideoTaskStatus;
+
+/// Seedance 2.0 supports 4-15 second durations.
+const MIN_DURATION_SECONDS: u8 = 4;
+const MAX_DURATION_SECONDS: u8 = 15;
+
+/// The API default duration when `seconds` is omitted.
+const DEFAULT_DURATION_SECONDS: u8 = 5;
+
+// ── Args ──
+
+pub struct GenerateDoubaoSeedance2p0Args<'a> {
+  pub request: GenerateDoubaoSeedance2p0Request,
+  pub api_key: &'a CometApiKey,
+}
+
+// ── Request ──
+
+#[derive(Clone, Debug)]
+pub struct GenerateDoubaoSeedance2p0Request {
+  /// Reference attached images in the prompt as `[Image 1]`, `[Image 2]`, etc.
+  pub prompt: String,
+
+  /// 4-15 seconds. `None` uses the API default (5).
+  pub duration_seconds: Option<u8>,
+
+  /// `None` defaults to 16:9 (when a resolution is set).
+  pub aspect_ratio: Option<DoubaoSeedance2p0AspectRatio>,
+
+  /// `None` defaults to 720p (when an aspect ratio is set).
+  pub resolution: Option<DoubaoSeedance2p0Resolution>,
+
+  /// Reference images (JPEG, PNG, WebP) for image-to-video.
+  pub input_reference_images: Vec<CometInputReferenceImage>,
+}
+
+// ── Enums ──
+
+#[derive(Debug, Clone, Copy)]
+pub enum DoubaoSeedance2p0AspectRatio {
+  Landscape16x9,
+  Standard4x3,
+  Square1x1,
+  Portrait3x4,
+  Portrait9x16,
+  UltraWide21x9,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub enum DoubaoSeedance2p0Resolution {
+  FourEightyP,
+  SevenTwentyP,
+  TenEightyP,
+}
+
+// ── Pricing ──
+//
+// Seedance 2.0 per-second USD pricing (via CometAPI):
+//
+// | Resolution | $/sec  |
+// |------------|--------|
+// | 480p       | 0.063  |
+// | 720p       | 0.1368 |
+// | 1080p      | 0.3366 |
+//
+// Total cost = price per second × video duration (seconds).
+
+impl GenerateDoubaoSeedance2p0Request {
+  /// Estimate the USD cost in cents for this generation request.
+  pub fn estimate_cost_in_usd_cents(&self) -> u64 {
+    let dollars_per_second: f64 = match self.resolution {
+      Some(DoubaoSeedance2p0Resolution::FourEightyP) => 0.063,
+      // Default resolution (None) is 720p.
+      Some(DoubaoSeedance2p0Resolution::SevenTwentyP) | None => 0.1368,
+      Some(DoubaoSeedance2p0Resolution::TenEightyP) => 0.3366,
+    };
+    let seconds = self.duration_seconds.unwrap_or(DEFAULT_DURATION_SECONDS);
+    (f64::from(seconds) * dollars_per_second * 100.0).round() as u64
+  }
+}
+
+// ── Response ──
+
+pub struct GenerateDoubaoSeedance2p0Response {
+  /// Poll `GET /v1/videos/{task_id}` until terminal.
+  pub task_id: String,
+  pub status: CometVideoTaskStatus,
+}
+
+// ── Entry point ──
+
+pub async fn generate_doubao_seedance_2p0(
+  args: GenerateDoubaoSeedance2p0Args<'_>,
+) -> Result<GenerateDoubaoSeedance2p0Response, CometError> {
+  let raw_request = args.request.to_create_video_request()?;
+
+  let result = create_video(CreateVideoArgs {
+    api_key: args.api_key,
+    request: raw_request,
+  }).await?;
+
+  Ok(GenerateDoubaoSeedance2p0Response {
+    task_id: result.task_id,
+    status: result.status,
+  })
+}
+
+impl GenerateDoubaoSeedance2p0Request {
+  /// Validate and lower to the generic wire request.
+  pub fn to_create_video_request(&self) -> Result<CreateVideoRequest, CometClientError> {
+    if let Some(seconds) = self.duration_seconds {
+      if !(MIN_DURATION_SECONDS..=MAX_DURATION_SECONDS).contains(&seconds) {
+        return Err(CometClientError::InvalidRequestField {
+          field: "duration_seconds",
+          raw_value: seconds.to_string(),
+          reason: format!("Seedance 2.0 supports {MIN_DURATION_SECONDS}-{MAX_DURATION_SECONDS} second durations"),
+        });
+      }
+    }
+
+    Ok(CreateVideoRequest {
+      model: CometVideoModelRaw::DoubaoSeedance2p0,
+      prompt: self.prompt.clone(),
+      maybe_seconds: self.duration_seconds,
+      maybe_size: self.resolve_size(),
+      input_reference_images: self.input_reference_images.clone(),
+    })
+  }
+
+  /// The wire `size` is a single exact-dimensions field determined by the
+  /// (aspect ratio, resolution) pair. Dimensions mirror CometAPI's own
+  /// playground options for `doubao-seedance-2-0`. When neither knob is
+  /// set, `size` is omitted and the API picks its default.
+  fn resolve_size(&self) -> Option<CometVideoSize> {
+    if self.aspect_ratio.is_none() && self.resolution.is_none() {
+      return None;
+    }
+
+    let aspect_ratio = self.aspect_ratio.unwrap_or(DoubaoSeedance2p0AspectRatio::Landscape16x9);
+    let resolution = self.resolution.unwrap_or(DoubaoSeedance2p0Resolution::SevenTwentyP);
+
+    use DoubaoSeedance2p0AspectRatio as Ratio;
+    use DoubaoSeedance2p0Resolution as Res;
+
+    let (width, height) = match (resolution, aspect_ratio) {
+      (Res::FourEightyP, Ratio::Landscape16x9) => (864, 496),
+      (Res::FourEightyP, Ratio::Standard4x3) => (752, 560),
+      (Res::FourEightyP, Ratio::Square1x1) => (640, 640),
+      (Res::FourEightyP, Ratio::Portrait3x4) => (560, 752),
+      (Res::FourEightyP, Ratio::Portrait9x16) => (496, 864),
+      (Res::FourEightyP, Ratio::UltraWide21x9) => (992, 432),
+
+      (Res::SevenTwentyP, Ratio::Landscape16x9) => (1280, 720),
+      (Res::SevenTwentyP, Ratio::Standard4x3) => (1112, 834),
+      (Res::SevenTwentyP, Ratio::Square1x1) => (960, 960),
+      (Res::SevenTwentyP, Ratio::Portrait3x4) => (834, 1112),
+      (Res::SevenTwentyP, Ratio::Portrait9x16) => (720, 1280),
+      (Res::SevenTwentyP, Ratio::UltraWide21x9) => (1470, 630),
+
+      (Res::TenEightyP, Ratio::Landscape16x9) => (1920, 1080),
+      (Res::TenEightyP, Ratio::Standard4x3) => (1664, 1248),
+      (Res::TenEightyP, Ratio::Square1x1) => (1440, 1440),
+      (Res::TenEightyP, Ratio::Portrait3x4) => (1248, 1664),
+      (Res::TenEightyP, Ratio::Portrait9x16) => (1080, 1920),
+      (Res::TenEightyP, Ratio::UltraWide21x9) => (2206, 946),
+    };
+
+    Some(CometVideoSize::Exact { width, height })
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  use DoubaoSeedance2p0AspectRatio as Ratio;
+  use DoubaoSeedance2p0Resolution as Res;
+
+  #[test]
+  fn maps_to_wire_request() {
+    let request = GenerateDoubaoSeedance2p0Request {
+      prompt: "animate [Image 1]".to_string(),
+      duration_seconds: Some(8),
+      aspect_ratio: Some(Ratio::UltraWide21x9),
+      resolution: Some(Res::TenEightyP),
+      input_reference_images: vec![],
+    };
+
+    let raw = request.to_create_video_request().expect("should validate");
+    assert_eq!(raw.text_form_fields(), vec![
+      ("model", "doubao-seedance-2-0".to_string()),
+      ("prompt", "animate [Image 1]".to_string()),
+      ("seconds", "8".to_string()),
+      ("size", "2206x946".to_string()),
+    ]);
+  }
+
+  #[test]
+  fn size_matrix_matches_cometapi_playground() {
+    // (resolution, ratio) -> exact size, as offered by CometAPI's own
+    // playground dropdown for doubao-seedance-2-0.
+    let cases = [
+      (Res::FourEightyP, Ratio::Landscape16x9, "864x496"),
+      (Res::FourEightyP, Ratio::Standard4x3, "752x560"),
+      (Res::FourEightyP, Ratio::Square1x1, "640x640"),
+      (Res::FourEightyP, Ratio::Portrait3x4, "560x752"),
+      (Res::FourEightyP, Ratio::Portrait9x16, "496x864"),
+      (Res::FourEightyP, Ratio::UltraWide21x9, "992x432"),
+      (Res::SevenTwentyP, Ratio::Landscape16x9, "1280x720"),
+      (Res::SevenTwentyP, Ratio::Standard4x3, "1112x834"),
+      (Res::SevenTwentyP, Ratio::Square1x1, "960x960"),
+      (Res::SevenTwentyP, Ratio::Portrait3x4, "834x1112"),
+      (Res::SevenTwentyP, Ratio::Portrait9x16, "720x1280"),
+      (Res::SevenTwentyP, Ratio::UltraWide21x9, "1470x630"),
+      (Res::TenEightyP, Ratio::Landscape16x9, "1920x1080"),
+      (Res::TenEightyP, Ratio::Standard4x3, "1664x1248"),
+      (Res::TenEightyP, Ratio::Square1x1, "1440x1440"),
+      (Res::TenEightyP, Ratio::Portrait3x4, "1248x1664"),
+      (Res::TenEightyP, Ratio::Portrait9x16, "1080x1920"),
+      (Res::TenEightyP, Ratio::UltraWide21x9, "2206x946"),
+    ];
+
+    for (resolution, aspect_ratio, expected) in cases {
+      let request = base_request(Some(aspect_ratio), Some(resolution));
+      let size = request.resolve_size().expect("should resolve");
+      assert_eq!(size.as_api_string(), expected,
+        "({resolution:?}, {aspect_ratio:?}) should map to {expected}");
+    }
+  }
+
+  #[test]
+  fn size_defaults() {
+    // Neither knob set: omit size, let the API default.
+    assert!(base_request(None, None).resolve_size().is_none());
+
+    // Only ratio set: resolution defaults to 720p.
+    let size = base_request(Some(Ratio::Portrait9x16), None).resolve_size().expect("should resolve");
+    assert_eq!(size.as_api_string(), "720x1280");
+
+    // Only resolution set: ratio defaults to 16:9.
+    let size = base_request(None, Some(Res::TenEightyP)).resolve_size().expect("should resolve");
+    assert_eq!(size.as_api_string(), "1920x1080");
+  }
+
+  #[test]
+  fn duration_bounds() {
+    let mut request = base_request(None, None);
+    for (seconds, ok) in [(Some(3), false), (Some(4), true), (Some(15), true), (Some(16), false), (None, true)] {
+      request.duration_seconds = seconds;
+      assert_eq!(request.to_create_video_request().is_ok(), ok, "seconds: {seconds:?}");
+    }
+  }
+
+  #[test]
+  fn cost_estimates() {
+    // 5 seconds at 480p: 5 × $0.063 = $0.315 -> 32¢
+    let mut request = base_request(None, Some(Res::FourEightyP));
+    request.duration_seconds = Some(5);
+    assert_eq!(request.estimate_cost_in_usd_cents(), 32);
+
+    // 10 seconds at 1080p: 10 × $0.3366 = $3.366 -> 337¢
+    request.resolution = Some(Res::TenEightyP);
+    request.duration_seconds = Some(10);
+    assert_eq!(request.estimate_cost_in_usd_cents(), 337);
+
+    // Defaults (5 seconds, 720p): 5 × $0.1368 = $0.684 -> 68¢
+    request.resolution = None;
+    request.duration_seconds = None;
+    assert_eq!(request.estimate_cost_in_usd_cents(), 68);
+  }
+
+  fn base_request(
+    aspect_ratio: Option<DoubaoSeedance2p0AspectRatio>,
+    resolution: Option<DoubaoSeedance2p0Resolution>,
+  ) -> GenerateDoubaoSeedance2p0Request {
+    GenerateDoubaoSeedance2p0Request {
+      prompt: "ok".to_string(),
+      duration_seconds: None,
+      aspect_ratio,
+      resolution,
+      input_reference_images: vec![],
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────
+  // ⚠️  EXPENSIVE LIVE TESTS  ⚠️
+  //
+  // Each test below enqueues a REAL 10-second Seedance 2.0 generation with
+  // four reference images and polls it to completion. These INCUR REAL
+  // COSTS (per CometAPI's per-second pricing):
+  //
+  //   480p:  10s × $0.063  ≈ $0.63
+  //   720p:  10s × $0.1368 ≈ $1.37
+  //   1080p: 10s × $0.3366 ≈ $3.37
+  //
+  // They also take a while — generations have been observed to run well
+  // past 10 minutes. Run one at a time, manually:
+  //
+  //   cargo test -p comet_api_client live_generate_480p -- --ignored --nocapture
+  // ─────────────────────────────────────────────────────────────────────
+  mod live_tests {
+    use std::time::Duration;
+
+    use test_data::web::image_urls::{
+      ERNEST_GHOST_TREX_IMAGE_URL,
+      FOREST_BACKDROP_IMAGE_URL,
+      GHOST_IMAGE_URL,
+      GRASSY_HILL_TRANSPARENT_IMAGE_URL,
+      JUNO_AT_LAKE_IMAGE_URL,
+      MOUNTAIN_TREE_IMAGE_URL,
+      SUPER_WIDE_FALL_MOUNTAINS_IMAGE_URL,
+      TALL_CORGI_SHIBA_TREASURE_OCEAN_URL,
+      TALL_MOCHI_WITH_GLASSES_IMAGE_URL,
+      TREX_SKELETON_IMAGE_URL,
+      WHITE_HOUSE_SUNSET_IMAGE_URL,
+      WIDE_CORGI_SHIBA_TREASURE_OCEAN_URL,
+    };
+
+    use super::*;
+    use crate::requests::get_video_task::get_video_task::{get_video_task, GetVideoTaskArgs};
+    use crate::test_utils::load_api_key;
+
+    /// ⚠️ EXPENSIVE: real 10s 480p generation (~$0.63) + a long poll.
+    #[ignore]
+    #[tokio::test]
+    async fn live_generate_480p_with_references() {
+      let input_reference_images = download_reference_images(&[
+        ERNEST_GHOST_TREX_IMAGE_URL,
+        GHOST_IMAGE_URL,
+        TREX_SKELETON_IMAGE_URL,
+        FOREST_BACKDROP_IMAGE_URL,
+      ]).await;
+
+      run_generation_to_completion(GenerateDoubaoSeedance2p0Request {
+        prompt: "The frightened man from [Image 1] runs through the dark forest \
+          from [Image 4], chased by the glowing ghost from [Image 2]. The t-rex \
+          skeleton from [Image 3] rises out of the leaves behind them. Spooky, \
+          comedic 90s horror movie tone."
+          .to_string(),
+        duration_seconds: Some(10),
+        aspect_ratio: Some(DoubaoSeedance2p0AspectRatio::Landscape16x9),
+        resolution: Some(DoubaoSeedance2p0Resolution::FourEightyP),
+        input_reference_images,
+      }).await;
+    }
+
+    /// ⚠️ EXPENSIVE: real 10s 720p generation (~$1.37) + a long poll.
+    #[ignore]
+    #[tokio::test]
+    async fn live_generate_720p_with_references() {
+      let input_reference_images = download_reference_images(&[
+        JUNO_AT_LAKE_IMAGE_URL,
+        TALL_MOCHI_WITH_GLASSES_IMAGE_URL,
+        TALL_CORGI_SHIBA_TREASURE_OCEAN_URL,
+        WIDE_CORGI_SHIBA_TREASURE_OCEAN_URL,
+      ]).await;
+
+      run_generation_to_completion(GenerateDoubaoSeedance2p0Request {
+        prompt: "The dog from [Image 1] and the bespectacled dog from [Image 2] \
+          join the corgi and shiba from [Image 3] on the beach, digging up the \
+          treasure chest from [Image 4] as waves roll in. Joyful, sunny \
+          adventure-film tone."
+          .to_string(),
+        duration_seconds: Some(10),
+        aspect_ratio: Some(DoubaoSeedance2p0AspectRatio::Landscape16x9),
+        resolution: Some(DoubaoSeedance2p0Resolution::SevenTwentyP),
+        input_reference_images,
+      }).await;
+    }
+
+    /// ⚠️ EXPENSIVE: real 10s 1080p generation (~$3.37) + a long poll.
+    #[ignore]
+    #[tokio::test]
+    async fn live_generate_1080p_with_references() {
+      let input_reference_images = download_reference_images(&[
+        GRASSY_HILL_TRANSPARENT_IMAGE_URL,
+        MOUNTAIN_TREE_IMAGE_URL,
+        SUPER_WIDE_FALL_MOUNTAINS_IMAGE_URL,
+        WHITE_HOUSE_SUNSET_IMAGE_URL,
+      ]).await;
+
+      run_generation_to_completion(GenerateDoubaoSeedance2p0Request {
+        prompt: "A cinematic drone shot glides over the grassy hill from \
+          [Image 1], past the lone tree on the mountainside from [Image 2], \
+          across the sweeping autumn mountain range from [Image 3], and settles \
+          on the white house at sunset from [Image 4]. Golden hour, slow and \
+          steady camera movement."
+          .to_string(),
+        duration_seconds: Some(10),
+        aspect_ratio: Some(DoubaoSeedance2p0AspectRatio::Landscape16x9),
+        resolution: Some(DoubaoSeedance2p0Resolution::TenEightyP),
+        input_reference_images,
+      }).await;
+    }
+
+    // ── Helpers ──
+
+    async fn download_reference_images(urls: &[&str]) -> Vec<CometInputReferenceImage> {
+      let mut images = Vec::with_capacity(urls.len());
+      for url in urls {
+        images.push(download_reference_image(url).await);
+      }
+      images
+    }
+
+    async fn download_reference_image(url: &str) -> CometInputReferenceImage {
+      let response = reqwest::get(url).await.expect("image download should succeed");
+      assert!(response.status().is_success(), "image download failed: {} ({})", url, response.status());
+
+      let filename = url.rsplit('/').next().expect("url should have a path").to_string();
+      let maybe_content_type = if filename.ends_with(".png") {
+        Some("image/png".to_string())
+      } else {
+        Some("image/jpeg".to_string())
+      };
+      let file_bytes = response.bytes().await.expect("image body should download").to_vec();
+
+      println!("Downloaded reference: {} ({} bytes)", filename, file_bytes.len());
+
+      CometInputReferenceImage {
+        file_bytes,
+        filename,
+        maybe_content_type,
+      }
+    }
+
+    /// Enqueue the generation, poll until terminal, and assert success.
+    async fn run_generation_to_completion(request: GenerateDoubaoSeedance2p0Request) {
+      // NB: Generations have been observed to run well past 10 minutes.
+      const POLL_INTERVAL: Duration = Duration::from_secs(15);
+      const MAX_POLLS: u32 = 120; // ~30 minutes
+
+      let api_key = load_api_key();
+      println!("Estimated cost: {}¢", request.estimate_cost_in_usd_cents());
+
+      let created = generate_doubao_seedance_2p0(GenerateDoubaoSeedance2p0Args {
+        request,
+        api_key: &api_key,
+      }).await.expect("generate_doubao_seedance_2p0 should succeed");
+
+      println!("Enqueued task: {} (status: {})", created.task_id, created.status);
+
+      for poll in 1..=MAX_POLLS {
+        tokio::time::sleep(POLL_INTERVAL).await;
+
+        let task = get_video_task(GetVideoTaskArgs {
+          api_key: &api_key,
+          task_id: &created.task_id,
+        }).await.expect("get_video_task should succeed");
+
+        println!("Poll {}: status {} (progress: {:?})", poll, task.status, task.maybe_progress);
+
+        if task.status.is_terminal() {
+          assert!(task.status.is_success(), "task should complete successfully: {:?}", task);
+          let video_url = task.maybe_video_url.expect("completed task should have a video url");
+          println!("Video URL: {}", video_url);
+          return;
+        }
+      }
+
+      panic!("Task {} did not reach a terminal state in time", created.task_id);
+    }
+  }
+}
@@ -0,0 +1,278 @@
+use crate::creds::comet_api_key::CometApiKey;
+use crate::error::comet_client_error::CometClientError;
+use crate::error::comet_error::CometError;
+use crate::requests::create_video::create_video::{
+  create_video, CometInputReferenceImage, CometVideoModelRaw, CometVideoSize,
+  CreateVideoArgs, CreateVideoRequest,
+};
+use crate::requests::video_task_status::CometVideoTaskStatus;
+
+/// Seedance 2.0 Fast supports 4-15 second durations.
+const MIN_DURATION_SECONDS: u8 = 4;
+const MAX_DURATION_SECONDS: u8 = 15;
+
+/// The API default duration when `seconds` is omitted.
+const DEFAULT_DURATION_SECONDS: u8 = 5;
+
+// ── Args ──
+
+pub struct GenerateDoubaoSeedance2p0FastArgs<'a> {
+  pub request: GenerateDoubaoSeedance2p0FastRequest,
+  pub api_key: &'a CometApiKey,
+}
+
+// ── Request ──
+
+#[derive(Clone, Debug)]
+pub struct GenerateDoubaoSeedance2p0FastRequest {
+  /// Reference attached images in the prompt as `[Image 1]`, `[Image 2]`, etc.
+  pub prompt: String,
+
+  /// 4-15 seconds. `None` uses the API default (5).
+  pub duration_seconds: Option<u8>,
+
+  /// `None` defaults to 16:9 (when a resolution is set).
+  pub aspect_ratio: Option<DoubaoSeedance2p0FastAspectRatio>,
+
+  /// `None` defaults to 720p (when an aspect ratio is set).
+  pub resolution: Option<DoubaoSeedance2p0FastResolution>,
+
+  /// Reference images (JPEG, PNG, WebP) for image-to-video.
+  pub input_reference_images: Vec<CometInputReferenceImage>,
+}
+
+// ── Enums ──
+
+#[derive(Debug, Clone, Copy)]
+pub enum DoubaoSeedance2p0FastAspectRatio {
+  Landscape16x9,
+  Standard4x3,
+  Square1x1,
+  Portrait3x4,
+  Portrait9x16,
+  UltraWide21x9,
+}
+
+/// NB: 1080p is available for all Seedance models EXCEPT 2.0 Fast, so this
+/// enum deliberately has no 1080p variant.
+#[derive(Debug, Clone, Copy)]
+pub enum DoubaoSeedance2p0FastResolution {
+  FourEightyP,
+  SevenTwentyP,
+}
+
+// ── Pricing ──
+//
+// Seedance 2.0 Fast per-second USD pricing (via CometAPI):
+//
+// | Resolution | $/sec  |
+// |------------|--------|
+// | 480p       | 0.0504 |
+// | 720p       | 0.108  |
+//
+// Total cost = price per second × video duration (seconds).
+
+impl GenerateDoubaoSeedance2p0FastRequest {
+  /// Estimate the USD cost in cents for this generation request.
+  pub fn estimate_cost_in_usd_cents(&self) -> u64 {
+    let dollars_per_second: f64 = match self.resolution {
+      Some(DoubaoSeedance2p0FastResolution::FourEightyP) => 0.0504,
+      // Default resolution (None) is 720p.
+      Some(DoubaoSeedance2p0FastResolution::SevenTwentyP) | None => 0.108,
+    };
+    let seconds = self.duration_seconds.unwrap_or(DEFAULT_DURATION_SECONDS);
+    (f64::from(seconds) * dollars_per_second * 100.0).round() as u64
+  }
+}
+
+// ── Response ──
+
+pub struct GenerateDoubaoSeedance2p0FastResponse {
+  /// Poll `GET /v1/videos/{task_id}` until terminal.
+  pub task_id: String,
+  pub status: CometVideoTaskStatus,
+}
+
+// ── Entry point ──
+
+pub async fn generate_doubao_seedance_2p0_fast(
+  args: GenerateDoubaoSeedance2p0FastArgs<'_>,
+) -> Result<GenerateDoubaoSeedance2p0FastResponse, CometError> {
+  let raw_request = args.request.to_create_video_request()?;
+
+  let result = create_video(CreateVideoArgs {
+    api_key: args.api_key,
+    request: raw_request,
+  }).await?;
+
+  Ok(GenerateDoubaoSeedance2p0FastResponse {
+    task_id: result.task_id,
+    status: result.status,
+  })
+}
+
+impl GenerateDoubaoSeedance2p0FastRequest {
+  /// Validate and lower to the generic wire request.
+  pub fn to_create_video_request(&self) -> Result<CreateVideoRequest, CometClientError> {
+    if let Some(seconds) = self.duration_seconds {
+      if !(MIN_DURATION_SECONDS..=MAX_DURATION_SECONDS).contains(&seconds) {
+        return Err(CometClientError::InvalidRequestField {
+          field: "duration_seconds",
+          raw_value: seconds.to_string(),
+          reason: format!("Seedance 2.0 Fast supports {MIN_DURATION_SECONDS}-{MAX_DURATION_SECONDS} second durations"),
+        });
+      }
+    }
+
+    Ok(CreateVideoRequest {
+      model: CometVideoModelRaw::DoubaoSeedance2p0Fast,
+      prompt: self.prompt.clone(),
+      maybe_seconds: self.duration_seconds,
+      maybe_size: self.resolve_size(),
+      input_reference_images: self.input_reference_images.clone(),
+    })
+  }
+
+  /// The wire `size` is a single exact-dimensions field determined by the
+  /// (aspect ratio, resolution) pair. Dimensions mirror CometAPI's own
+  /// playground options for the Seedance 2.0 family. When neither knob is
+  /// set, `size` is omitted and the API picks its default.
+  fn resolve_size(&self) -> Option<CometVideoSize> {
+    if self.aspect_ratio.is_none() && self.resolution.is_none() {
+      return None;
+    }
+
+    let aspect_ratio = self.aspect_ratio.unwrap_or(DoubaoSeedance2p0FastAspectRatio::Landscape16x9);
+    let resolution = self.resolution.unwrap_or(DoubaoSeedance2p0FastResolution::SevenTwentyP);
+
+    use DoubaoSeedance2p0FastAspectRatio as Ratio;
+    use DoubaoSeedance2p0FastResolution as Res;
+
+    let (width, height) = match (resolution, aspect_ratio) {
+      (Res::FourEightyP, Ratio::Landscape16x9) => (864, 496),
+      (Res::FourEightyP, Ratio::Standard4x3) => (752, 560),
+      (Res::FourEightyP, Ratio::Square1x1) => (640, 640),
+      (Res::FourEightyP, Ratio::Portrait3x4) => (560, 752),
+      (Res::FourEightyP, Ratio::Portrait9x16) => (496, 864),
+      (Res::FourEightyP, Ratio::UltraWide21x9) => (992, 432),
+
+      (Res::SevenTwentyP, Ratio::Landscape16x9) => (1280, 720),
+      (Res::SevenTwentyP, Ratio::Standard4x3) => (1112, 834),
+      (Res::SevenTwentyP, Ratio::Square1x1) => (960, 960),
+      (Res::SevenTwentyP, Ratio::Portrait3x4) => (834, 1112),
+      (Res::SevenTwentyP, Ratio::Portrait9x16) => (720, 1280),
+      (Res::SevenTwentyP, Ratio::UltraWide21x9) => (1470, 630),
+    };
+
+    Some(CometVideoSize::Exact { width, height })
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  use DoubaoSeedance2p0FastAspectRatio as Ratio;
+  use DoubaoSeedance2p0FastResolution as Res;
+
+  #[test]
+  fn maps_to_wire_request() {
+    let request = GenerateDoubaoSeedance2p0FastRequest {
+      prompt: "a corgi surfing".to_string(),
+      duration_seconds: Some(4),
+      aspect_ratio: Some(Ratio::Landscape16x9),
+      resolution: Some(Res::FourEightyP),
+      input_reference_images: vec![],
+    };
+
+    let raw = request.to_create_video_request().expect("should validate");
+    assert_eq!(raw.text_form_fields(), vec![
+      ("model", "doubao-seedance-2-0-fast".to_string()),
+      ("prompt", "a corgi surfing".to_string()),
+      ("seconds", "4".to_string()),
+      ("size", "864x496".to_string()),
+    ]);
+  }
+
+  #[test]
+  fn size_matrix_matches_cometapi_playground() {
+    // (resolution, ratio) -> exact size, as offered by CometAPI's own
+    // playground dropdown for the Seedance 2.0 family. No 1080p row: Fast
+    // doesn't support it (enforced by the resolution enum).
+    let cases = [
+      (Res::FourEightyP, Ratio::Landscape16x9, "864x496"),
+      (Res::FourEightyP, Ratio::Standard4x3, "752x560"),
+      (Res::FourEightyP, Ratio::Square1x1, "640x640"),
+      (Res::FourEightyP, Ratio::Portrait3x4, "560x752"),
+      (Res::FourEightyP, Ratio::Portrait9x16, "496x864"),
+      (Res::FourEightyP, Ratio::UltraWide21x9, "992x432"),
+      (Res::SevenTwentyP, Ratio::Landscape16x9, "1280x720"),
+      (Res::SevenTwentyP, Ratio::Standard4x3, "1112x834"),
+      (Res::SevenTwentyP, Ratio::Square1x1, "960x960"),
+      (Res::SevenTwentyP, Ratio::Portrait3x4, "834x1112"),
+      (Res::SevenTwentyP, Ratio::Portrait9x16, "720x1280"),
+      (Res::SevenTwentyP, Ratio::UltraWide21x9, "1470x630"),
+    ];
+
+    for (resolution, aspect_ratio, expected) in cases {
+      let request = base_request(Some(aspect_ratio), Some(resolution));
+      let size = request.resolve_size().expect("should resolve");
+      assert_eq!(size.as_api_string(), expected,
+        "({resolution:?}, {aspect_ratio:?}) should map to {expected}");
+    }
+  }
+
+  #[test]
+  fn size_defaults() {
+    // Neither knob set: omit size, let the API default.
+    assert!(base_request(None, None).resolve_size().is_none());
+
+    // Only ratio set: resolution defaults to 720p.
+    let size = base_request(Some(Ratio::Square1x1), None).resolve_size().expect("should resolve");
+    assert_eq!(size.as_api_string(), "960x960");
+
+    // Only resolution set: ratio defaults to 16:9.
+    let size = base_request(None, Some(Res::FourEightyP)).resolve_size().expect("should resolve");
+    assert_eq!(size.as_api_string(), "864x496");
+  }
+
+  #[test]
+  fn duration_bounds() {
+    let mut request = base_request(None, None);
+    for (seconds, ok) in [(Some(3), false), (Some(4), true), (Some(15), true), (Some(16), false), (None, true)] {
+      request.duration_seconds = seconds;
+      assert_eq!(request.to_create_video_request().is_ok(), ok, "seconds: {seconds:?}");
+    }
+  }
+
+  #[test]
+  fn cost_estimates() {
+    // 5 seconds at 480p: 5 × $0.0504 = $0.252 -> 25¢
+    let mut request = base_request(None, Some(Res::FourEightyP));
+    request.duration_seconds = Some(5);
+    assert_eq!(request.estimate_cost_in_usd_cents(), 25);
+
+    // 15 seconds at 720p: 15 × $0.108 = $1.62 -> 162¢
+    request.resolution = Some(Res::SevenTwentyP);
+    request.duration_seconds = Some(15);
+    assert_eq!(request.estimate_cost_in_usd_cents(), 162);
+
+    // Defaults (5 seconds, 720p): 5 × $0.108 = $0.54 -> 54¢
+    request.resolution = None;
+    request.duration_seconds = None;
+    assert_eq!(request.estimate_cost_in_usd_cents(), 54);
+  }
+
+  fn base_request(
+    aspect_ratio: Option<DoubaoSeedance2p0FastAspectRatio>,
+    resolution: Option<DoubaoSeedance2p0FastResolution>,
+  ) -> GenerateDoubaoSeedance2p0FastRequest {
+    GenerateDoubaoSeedance2p0FastRequest {
+      prompt: "ok".to_string(),
+      duration_seconds: None,
+      aspect_ratio,
+      resolution,
+      input_reference_images: vec![],
+    }
+  }
+}
@@ -0,0 +1,162 @@
+use crate::creds::comet_api_key::CometApiKey;
+use crate::error::comet_client_error::CometClientError;
+use crate::error::comet_error::CometError;
+use crate::requests::create_video::create_video::{
+  create_video, CometInputReferenceImage, CometVideoModelRaw, CometVideoSize,
+  CreateVideoArgs, CreateVideoRequest,
+};
+use crate::requests::video_task_status::CometVideoTaskStatus;
+
+/// Vidu Q3 supports 1-16 second durations.
+const MIN_DURATION_SECONDS: u8 = 1;
+const MAX_DURATION_SECONDS: u8 = 16;
+
+// ── Args ──
+
+pub struct GenerateViduQ3Args<'a> {
+  pub request: GenerateViduQ3Request,
+  pub api_key: &'a CometApiKey,
+}
+
+// ── Request ──
+
+#[derive(Clone, Debug)]
+pub struct GenerateViduQ3Request {
+  pub prompt: String,
+
+  /// 1-16 seconds. `None` uses the API default (5).
+  pub duration_seconds: Option<u8>,
+
+  pub size: Option<ViduQ3Size>,
+
+  /// Reference images for image-to-video / start-end-to-video workflows.
+  pub input_reference_images: Vec<CometInputReferenceImage>,
+}
+
+// ── Enums ──
+
+/// Vidu Q3 renders at 540p/720p/1080p (24 FPS). The API's `size` field takes
+/// an aspect ratio preset or exact dimensions (eg. 960x528).
+#[derive(Debug, Clone, Copy)]
+pub enum ViduQ3Size {
+  Landscape16x9,
+  Standard4x3,
+  Square1x1,
+  Portrait3x4,
+  Portrait9x16,
+  Exact { width: u32, height: u32 },
+}
+
+// ── Pricing ──
+//
+// Vidu Q3 per-second USD pricing (via CometAPI):
+//
+// | Resolution  | $/sec   |
+// |-------------|---------|
+// | 360p/540p   | 0.056   |
+// | 720p/1080p  | 0.1232  |
+//
+// Total cost = price per second × video duration (seconds).
+// NB: Not modeled as an estimator because the `size` field is an aspect
+// ratio in the common case, which doesn't determine the billed resolution.
+
+// ── Response ──
+
+pub struct GenerateViduQ3Response {
+  /// Poll `GET /v1/videos/{task_id}` until terminal.
+  pub task_id: String,
+  pub status: CometVideoTaskStatus,
+}
+
+// ── Entry point ──
+
+pub async fn generate_vidu_q3(
+  args: GenerateViduQ3Args<'_>,
+) -> Result<GenerateViduQ3Response, CometError> {
+  let raw_request = args.request.to_create_video_request()?;
+
+  let result = create_video(CreateVideoArgs {
+    api_key: args.api_key,
+    request: raw_request,
+  }).await?;
+
+  Ok(GenerateViduQ3Response {
+    task_id: result.task_id,
+    status: result.status,
+  })
+}
+
+impl GenerateViduQ3Request {
+  /// Validate and lower to the generic wire request.
+  pub fn to_create_video_request(&self) -> Result<CreateVideoRequest, CometClientError> {
+    if let Some(seconds) = self.duration_seconds {
+      if !(MIN_DURATION_SECONDS..=MAX_DURATION_SECONDS).contains(&seconds) {
+        return Err(CometClientError::InvalidRequestField {
+          field: "duration_seconds",
+          raw_value: seconds.to_string(),
+          reason: format!("Vidu Q3 supports {MIN_DURATION_SECONDS}-{MAX_DURATION_SECONDS} second durations"),
+        });
+      }
+    }
+
+    Ok(CreateVideoRequest {
+      model: CometVideoModelRaw::ViduQ3,
+      prompt: self.prompt.clone(),
+      maybe_seconds: self.duration_seconds,
+      maybe_size: self.size.map(map_size),
+      input_reference_images: self.input_reference_images.clone(),
+    })
+  }
+}
+
+fn map_size(size: ViduQ3Size) -> CometVideoSize {
+  match size {
+    ViduQ3Size::Landscape16x9 => CometVideoSize::Landscape16x9,
+    ViduQ3Size::Standard4x3 => CometVideoSize::Standard4x3,
+    ViduQ3Size::Square1x1 => CometVideoSize::Square,
+    ViduQ3Size::Portrait3x4 => CometVideoSize::Portrait3x4,
+    ViduQ3Size::Portrait9x16 => CometVideoSize::Portrait9x16,
+    ViduQ3Size::Exact { width, height } => CometVideoSize::Exact { width, height },
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn maps_to_wire_request() {
+    let request = GenerateViduQ3Request {
+      prompt: "a lighthouse in fog".to_string(),
+      duration_seconds: Some(16),
+      size: Some(ViduQ3Size::Exact { width: 960, height: 528 }),
+      input_reference_images: vec![],
+    };
+
+    let raw = request.to_create_video_request().expect("should validate");
+    assert_eq!(raw.text_form_fields(), vec![
+      ("model", "viduq3".to_string()),
+      ("prompt", "a lighthouse in fog".to_string()),
+      ("seconds", "16".to_string()),
+      ("size", "960x528".to_string()),
+    ]);
+  }
+
+  #[test]
+  fn duration_bounds() {
+    assert!(request_with_seconds(Some(0)).to_create_video_request().is_err());
+    assert!(request_with_seconds(Some(1)).to_create_video_request().is_ok());
+    assert!(request_with_seconds(Some(16)).to_create_video_request().is_ok());
+    assert!(request_with_seconds(Some(17)).to_create_video_request().is_err());
+    assert!(request_with_seconds(None).to_create_video_request().is_ok());
+  }
+
+  fn request_with_seconds(duration_seconds: Option<u8>) -> GenerateViduQ3Request {
+    GenerateViduQ3Request {
+      prompt: "ok".to_string(),
+      duration_seconds,
+      size: None,
+      input_reference_images: vec![],
+    }
+  }
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Brandon Thomas	6e95be9bdb	endpoints	2026-06-15 11:08:24 -04:00
Brandon Thomas	b7667976df	token and generator	2026-06-15 09:12:07 -04:00
Brandon Thomas	e07d302df1	schema	2026-06-15 08:55:47 -04:00
Brandon Thomas	0de867ad13	upgrade tauri 2.8 -> 2.11 (#1645 )	2026-06-14 22:20:29 -04:00
Brandon Thomas	a1cb1b2629	enhance database connection pooling (#1644 )	2026-06-14 18:09:42 -04:00
BFlat	8da68b009c	Desktop create pages redesign: shared generation feed, embedded model selector, gallery folders sidebar (#1635 ) ## Summary Reworks the desktop (Tauri) app's Create Image / Create Video pages to match the webapp, extracts the webapp's generation gallery into a shared library used by both apps, embeds the model selector into every prompt box, adds a folders sidebar + marquee selection to the gallery modal, restyles the login/pricing/credits modals to the webapp look, and turns the Apps page into the default landing tab. ### Shared generation-list lib - Extracted the webapp's generation feed into `@storyteller/ui-generation-list`: list + masonry grid views, pending/failed/completed rows and cards, thumbnail handling, gallery/prompt data hooks, and the shared grid/list view store + toggle. Host-specific actions (recreate, make-video, share, download, toasts) inject via render props — webapp markup unchanged, its old files are now thin wrappers. ### Desktop create pages - Prompt box fixed at the bottom, `max-w-5xl` like the webapp; pages renamed to "Create Image" / "Create Video". - Generation feed: in-progress/failed from the Tauri task queue, history from the library API, rendered as grid or list (toggle in the TopBar next to credits). Typed Tauri completion events push finished media in instantly; the poll reconciles and dedupes. - Row/card quick actions (recreate, make video, copy link, download) backed by a shared `desktopMediaActions` module extracted from the TopBar gallery wiring. - Hero + background act as a splash that fades when the feed loads; bottom gradient behind the prompt box. Batch generations show "Generating N images" on the single pending chip. - Video prompt box now expands vertically as far as the image prompt box (viewport-relative). ### Embedded model selector - `ClassyModelSelector` gained `variant="embedded"`: a compact pill that opens the webapp-style rich-list popover while keeping the desktop's provider selection. Embedded on all five prompt-input pages; floating selectors removed; legacy "10 sec." badges dropped. ### Gallery modal - Left sidebar lists the user's folders (drag-and-drop, right-click management, new-folder button) and shows on the Folders tab too, highlighting the active folder's root branch. - Marquee (drag-rectangle) selection in view mode, with edge auto-scroll; starts only on blank background so it doesn't interfere with drag-to-folder/canvas. ### Restyled modals (desktop) - Login/signup: webapp 2-column layout (form left, Vimeo showcase right), no Google button (Google auth isn't wired for Tauri), `artcraft-icon` logo, eye toggles. The dismiss button is removed so login is required; the post-auth Discord + Success onboarding steps are kept, as is the existing Tauri auth flow. - Pricing + credits: match the webapp visually (unified monochrome plan cards with Most Popular / Best Value highlight frames; `#161618` credit-pack cards with Popular badge). All billing stays on the existing Tauri `invoke` calls — no billing logic changed. ### Apps page / navigation - The Apps page is now the first tab and the default landing tab, with a Home icon. Restyled to the webapp home: "What will you craft today?" hero, Create / Edit sections, gradient-hover cards sized to their content, full-width scrollbar. The TopBar quick-menu header reads "Create" instead of "Generate". ### Fixes - Video Editor no longer crashes on the desktop app (`Tooltip must be used within TooltipProvider`): the editor shell now mounts its own Radix `TooltipProvider`. The webapp got one app-wide via `SidebarProvider`; the Tauri app had none, so panel tooltips threw. ### Misc - `getCreatorIconPathForModelId()` added to `@storyteller/model-list` (model id → creator icon path, desktop/webapp aware).	2026-06-13 17:25:40 -04:00
Brandon Thomas	e4bc031fbb	modernize require_user_session_extended() (#1643 )	2026-06-13 17:03:21 -04:00
Brandon Thomas	d937a7f78f	cleanup require_user_session (#1642 )	2026-06-13 05:54:01 -04:00
Brandon Thomas	fef96c3835	cleanup usage of require_moderator further (#1641 )	2026-06-13 05:26:36 -04:00
Brandon Thomas	b9e793098c	cleanup session and require_moderator (#1640 )	2026-06-13 04:52:35 -04:00
Brandon Thomas	222f3e958d	actix crates upgrades (#1638 )	2026-06-12 21:47:36 -04:00
Brandon Thomas	4ab06030dc	fix cors with PUT methods (#1637 )	2026-06-12 20:02:44 -04:00
Brandon Thomas	189c5afc80	updating pricing tests (#1636 )	2026-06-12 19:52:58 -04:00
BFlat	2818831a66	Webapp: seed new folders with selection + marquee selection fixes (#1634 ) - New folder keeps selection: "Add to folder > Create new folder" now drops the selected items into the folder on create instead of leaving it empty (webapp library + desktop gallery modal) - Marquee dead below the fold (main bug): flex-column scroll parent shrank the page root to one viewport; presses lower down missed the handler. Fixed with `shrink-0` so the root spans the full scroll height - Edge auto-scroll: holding a drag near the top/bottom edge scrolls the list so you can keep selecting past the viewport in one drag (anchor compensated for scroll; virtualized tiles stay selected) - No blue highlight: `select-none` on the page (inputs opted back in) blocks accidental text/image highlighting and stops it competing with the drag - Rectangle no longer covers the top bar: visible marquee box clamped to the gallery viewport; selection hit-testing stays unclamped	2026-06-12 10:48:25 +07:00
Brandon Thomas	8497a8c83a	artcraft 0.33 (#1633 )	2026-06-11 23:02:35 -04:00
Brandon Thomas	5fff16ee22	cost accounting; credits updates (#1632 )	2026-06-11 23:01:30 -04:00
bflatastic	1c3810e5a5	webapp: rounder corners and styling updates for mobile	2026-06-12 05:50:58 +07:00
bflatastic	5206a1d3e5	webapp: less blurry bg more visible promptbox	2026-06-12 05:19:15 +07:00
Tanish Manku	10f8297c1f	Fix desktop video generation ignoring selected resolution (#1631 ) The desktop video promptbox built the GenerateVideoRequest without ever setting `resolution`, so generation always omitted it and the backend fell back to the model's default (720p) — and billed for it. The cost preview reads the same store value and sends it, so the preview was correct (e.g. 117 for 480p) while the charge stayed at the 720p price (240). Populate request.resolution in buildRequest, mapping the store's legacy display string ("480p"/"720p"/"1080p") to CommonResolution, guarded on the model exposing resolutionOptions. Also fix useImageCostEstimate (webapp) omitting `quality` from its effect deps, which meant the image cost preview didn't refresh when only the quality option changed.	2026-06-11 14:48:48 -07:00
Brandon Thomas	edb771ccfb	uncommitted comet api module	2026-06-11 16:47:38 -04:00
Brandon Thomas	5979002f7e	new cost tracking fields (#1630 )	2026-06-11 16:37:43 -04:00
Brandon Thomas	74e30c4ffb	comet api (#1629 )	2026-06-11 10:43:32 -04:00
bflatastic	4061f00874	webapp: tailwind config colors update	2026-06-11 21:19:07 +07:00
bflatastic	633003c43b	webapp: styling updates and package versions	2026-06-11 21:18:49 +07:00
Brandon Thomas	957db2d07f	folders - add video previews / thumbnails (#1628 )	2026-06-11 08:50:23 -04:00
Brandon Thomas	b82a4e1599	change sorting for media files in folders (#1627 )	2026-06-10 23:32:52 -04:00
BFlat	bee790b952	feat(library): marquee selection, multi-select UX, mobile polish and … (#1626 ) …perf - Add desktop-style marquee drag selection on the webapp library: drag on blank space to select covered tiles, click blank space to deselect all - Multi-select: clicking anywhere on a tile toggles it (fixes a double-fire that cancelled the toggle so only the checkbox worked); selection persists across tabs and folder navigation - Gallery item menus show "View image" / "View video" / "View 3D" above Add to Folder; menu panels size to content so labels no longer wrap - Mobile/touch: no tile dragging or marquee (finger drags scroll), checkbox and menu buttons always visible (no hover on touch), and the Add to Folder submenu expands inline as an accordion instead of overflowing the screen - Select-mode gallery modal: folder cards hide the options menu and ignore right-click (picker is browse-only) - Perf: bulk selection moved to a module store with per-tile subscriptions so selection changes re-render only flipped tiles, never the page; marquee rectangle is positioned imperatively with cached tile rects and commits only when coverage changes; webapp date groups virtualized via the shared LazyDateGroup for smooth scrolling on large libraries - Bulk selection bar extracted to its own component, fixed to the viewport bottom and centered within the content area	2026-06-11 00:47:42 +07:00
BFlat	a2d57e3685	Folders for the library modal (#1309 ) - Redesigned the gallery modal with a sidebar replacing the old filter dropdown - filters now show as a list with item counts - Added a Folders system - create, rename, and delete folders to organize assets - Users can drag items onto folders in the sidebar, including multi-selected items - Added "Add to Folder" option in the item right-click menu with a folder picker submenu - Added "Add to folder" button in the bulk selection bar with a folder picker popup - Clicking a folder in the sidebar opens a folder view with its own content area and empty state - Folder names are editable - click the title in the header or right-click a folder in the sidebar to rename - Videos are now draggable - previously only images and 3D objects could be dragged - Folder data is mocked locally for now - ready for API integration	2026-06-10 22:04:26 +07:00
Brandon Thomas	9104faf806	fix frontend dev scripts (#1625 )	2026-06-10 09:28:25 -04:00