Audio: consolidate sound system into SoundManager, fix bootstrap + master toggle

- Move sound catalog registration off PageScene mount and into a single
  SoundManager.install() call in GlobalSettingsManager so sounds exist at
  app boot (previously silent until PageScene mounted).
- Honor the play_sounds master toggle in all five event playback sites
  via SoundManager.playEvent helpers. Settings preview keeps firing
  regardless (handled by SoundManager.playPreview).
- Replace per-callsite GetAppPreferences + SoundRegistry boilerplate in
  the four generation event hooks and the file-deleted handler with
  one-line SoundManager.* calls.
- Dedupe SOUND_OPTIONS: AudioSettingsPane now reads SoundManager.OPTIONS,
  derived from a single declarative SOUNDS array (label-bearing entries
  are user-selectable; others are still registered for code-driven use).
- Narrow the soundboard public barrel to SoundManager + SoundOption only;
  SoundRegistry and SoundEffect are now lib-internal.

.claude/rules/code-style.md

@@ -6,7 +6,11 @@
 - No minimum supported Rust version; use latest stable features freely
 - `#[macro_use] extern crate serde_derive;` is used in binary crates; library crates use `use serde_derive::{Serialize, Deserialize};`
 - Never use `println!` or `eprintln!` outside of tests; use `log` crate macros (`info!`, `warn!`, `error!`, `debug!`, `trace!`) instead
-- Use `anyhow::Result` / `AnyhowResult` for fallible functions in application code
+- Use `anyhow::Result` / `AnyhowResult` for fallible functions in application code; new database queries should use `Result<T, sqlx::Error>` instead
+- SQLx queries: prefer `sqlx::query!` and `sqlx::query_as!` compile-time checked macros over 
+  runtime `sqlx::query()` / `sqlx::query_as()`. The macros catch SQL typos, column mismatches, 
+  and type errors at build time. Use runtime queries only when assembling complicated 
+  dynamic/branching queries that cannot be expressed as a compile-time macro.
 - Enum Display/Debug: use `impl_enum_display_and_debug_using_to_str!` macro, not `derive_more::Display` (CLion doesn't understand it)
 - Fields that are optional use the `maybe_` prefix: `maybe_creator_user_token`, `maybe_prompt_token`
 - When implementing `fmt::Display` for error types, use the pattern: `write!(f, "{:?}", self)`
@@ -38,6 +42,21 @@ then the story, then the fine print.
    - A method that calls another method in the same file should appear *above* the method
      it calls. This lets readers follow the call chain downward.
 
+### Ordering within test modules
+
+Put test cases first, helpers last. A reader opening a test file should immediately see
+*what* is being tested before *how* the test machinery works.
+
+1. **Imports**
+2. **Constants** (test IDs, URLs, fixture data) — small context that tests reference
+3. **Test functions** or **sub-modules** grouped by category
+4. **Helper functions** (builders, pipeline runners, assertions)
+
+Group related tests into sub-modules (`mod pricing_tests { ... }`) when a category has 2+
+tests. Don't create a sub-module for a single test. Keep nesting to two levels max
+(`mod tests { mod category { ... } }`). Shared helpers go in the parent module so
+sub-modules can reach them via `use super::*`.
+
 ## Naming
 
 - Handler functions: `{verb}_{noun}_handler` (e.g. `get_health_check_handler`, `login_handler`)
@@ -49,15 +68,24 @@ then the story, then the fine print.
 ## Imports
 
 - Group imports: std, external crates, internal workspace crates, `crate::` imports
-- Use fully qualified paths for one-off references; `use` for repeated references
+- Prefer `use` imports over inline fully-qualified paths. Inline qualification is acceptable
+  only for genuine one-off references where adding an import would be noise, or for types
+  that collide with std prelude names (`Result`, `Option`, `Error`). If you reference a symbol
+  more than once, always import it.
 - Prefer specific imports over wildcards, except in `api_doc.rs` and test modules
 - When two crates export a type with the same name, alias with a suffix describing the source crate:
   `use enums::...::CommonResolution as CommonResolutionEnum;`
   `use artcraft_router::...::CommonResolution as CommonResolutionRouter;`
   This avoids long fully-qualified paths in function signatures and bodies.
 
+## MySQL 
+
+- MySQL tables: primary key `id` columns must be `BIGINT(20) UNSIGNED`. Do not use signed IDs. 
+- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`.
+
 ## TypeScript / Frontend
 
 - TypeScript with React, Vite, Zustand, Three.js
 - Nx monorepo under `crates/frontend/`
 - Two spaces for indentation
+

.claude/rules/testing.md

@@ -10,10 +10,28 @@
 ## Test Patterns
 
 - Tests live in `#[cfg(test)] mod tests { ... }` at the bottom of each file
-- Group related tests in sub-modules: `mod explicit_checks`, `mod mechanical_checks`
+- Group related tests into sub-modules by category (e.g. `mod pricing_tests`, `mod resolution_tests`)
+- Only create a sub-module when it has 2+ tests — don't wrap a single test in its own module
+- Keep nesting shallow: `mod tests { mod category { ... } }` is fine; a third level is rarely needed
+- Shared helpers used by multiple sub-modules belong in the parent `mod tests`, not duplicated in each sub-module
 - Enum tests should cover: serialization, deserialization, `to_str`/`from_str` round-trip, variant count
 - Password/crypto tests: be mindful of computation cost, don't add too many bcrypt test cases
 
+## Test File Layout
+
+Put test cases first, helpers last. Engineers should see the actual tests before scrolling
+to understand helper plumbing.
+
+Within a `mod tests { ... }` block:
+
+1. **Imports** at the top
+2. **Constants** (test data IDs, URLs, etc.) — small context that tests reference
+3. **Test functions** (`#[test]` / `#[tokio::test]`) grouped by category
+4. **Helper functions** (builders, pipeline runners, etc.) at the very bottom
+
+If tests are grouped into sub-modules, the same rule applies within each sub-module:
+constants first, then tests, then helpers at the end of that sub-module.
+
 ## What to Test
 
 - New error types and their mappings
@@ -21,6 +39,14 @@
 - Hash/deduplication functions with known inputs
 - Edge cases in parsers (empty input, missing fields, malformed data)
 
+## Imports in Tests
+
+- Import test fixtures and constants with `use`, not inline fully-qualified paths.
+  Write `use test_data::web::image_urls::JUNO_AT_LAKE_IMAGE_URL;` at the top,
+  then reference `JUNO_AT_LAKE_IMAGE_URL` in test bodies.
+- Same rule applies to enum variants used in match arms — import them, don't write
+  `crate::some::deep::module::MyEnum::Variant` inline.
+
 ## What Not to Test
 
 - Don't add integration tests that require a running database unless explicitly asked

.sqlx/query-27cebaa36f0ec873f86cdf8fa994d499db1a5cc84d2c6fceb3587145eb2f9bec.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  uir.id,\n  uir.impersonator_user_token as `impersonator_user_token: UserToken`,\n  impersonator.username as impersonator_username,\n  impersonator.display_name as impersonator_display_name,\n  uir.impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonated.username as impersonated_username,\n  impersonated.display_name as impersonated_display_name,\n  uir.is_redeemed as `is_redeemed: bool`,\n  (uir.expires_at < NOW()) as `is_expired: bool`,\n  uir.expires_at,\n  uir.created_at,\n  uir.updated_at\nFROM user_impersonation_requests uir\nJOIN users impersonator ON impersonator.token = uir.impersonator_user_token\nJOIN users impersonated ON impersonated.token = uir.impersonated_user_token\nWHERE uir.impersonated_user_token = ?\n  AND uir.id < ?\nORDER BY uir.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "impersonator_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "impersonated_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": "impersonated_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "impersonated_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "is_expired: bool",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "27cebaa36f0ec873f86cdf8fa994d499db1a5cc84d2c6fceb3587145eb2f9bec"
+}

.sqlx/query-381e13ab37a2f4ce39bd6db9d90202c301091376108f645a9bb5264a9cd113d7.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  uir.id,\n  uir.impersonator_user_token as `impersonator_user_token: UserToken`,\n  impersonator.username as impersonator_username,\n  impersonator.display_name as impersonator_display_name,\n  uir.impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonated.username as impersonated_username,\n  impersonated.display_name as impersonated_display_name,\n  uir.is_redeemed as `is_redeemed: bool`,\n  (uir.expires_at < NOW()) as `is_expired: bool`,\n  uir.expires_at,\n  uir.created_at,\n  uir.updated_at\nFROM user_impersonation_requests uir\nJOIN users impersonator ON impersonator.token = uir.impersonator_user_token\nJOIN users impersonated ON impersonated.token = uir.impersonated_user_token\nWHERE uir.impersonated_user_token = ?\nORDER BY uir.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "impersonator_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "impersonated_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": "impersonated_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "impersonated_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "is_expired: bool",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "381e13ab37a2f4ce39bd6db9d90202c301091376108f645a9bb5264a9cd113d7"
+}

.sqlx/query-3846628765bd34ea2ce01e15a0db732121ce473c5c542d0e971ad29b2b421193.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  sal.id,\n  sal.token as `token: StaffAuditLogToken`,\n  sal.audit_action,\n  sal.maybe_entity_type,\n  sal.maybe_entity_token,\n  target_user.username as maybe_target_username,\n  target_user.display_name as maybe_target_display_name,\n  sal.staff_user_token as `staff_user_token: UserToken`,\n  staff_user.username as staff_username,\n  staff_user.display_name as staff_display_name,\n  sal.staff_ip_address,\n  sal.created_at\nFROM staff_audit_logs sal\nLEFT JOIN users target_user ON target_user.token = sal.maybe_entity_token\nLEFT JOIN users staff_user ON staff_user.token = sal.staff_user_token\nORDER BY sal.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "token: StaffAuditLogToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "audit_action",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_entity_type",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "maybe_entity_token",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "maybe_target_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "maybe_target_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "staff_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "staff_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "staff_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "staff_ip_address",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      true,
+      false,
+      true,
+      true,
+      true,
+      true,
+      true,
+      false,
+      false
+    ]
+  },
+  "hash": "3846628765bd34ea2ce01e15a0db732121ce473c5c542d0e971ad29b2b421193"
+}

.sqlx/query-3d746dcb479005f1f4ae5e157a5ace7626eda4849d44c6c2d7079fd346eb4edc.json

@@ -1,6 +1,6 @@
 {
   "db_name": "MySQL",
-  "query": "\nUPDATE users\nSET\n    is_banned = ?,\n    maybe_mod_comments = ?,\n    maybe_mod_user_token  = ?,\n    version = version + 1\n\nWHERE users.token = ?\nLIMIT 1\n        ",
+  "query": "\nUPDATE users\nSET\n    is_banned = ?,\n    maybe_mod_comments = ?,\n    maybe_mod_user_token  = ?,\n    version = version + 1\n\nWHERE users.token = ?\nLIMIT 1\n    ",
   "describe": {
     "columns": [],
     "parameters": {
@@ -8,5 +8,5 @@
     },
     "nullable": []
   },
-  "hash": "eab69a8d679b2dcfb06a9ccc79851f6c693d0c372142ff0e7ded89c95e4bcf44"
+  "hash": "3d746dcb479005f1f4ae5e157a5ace7626eda4849d44c6c2d7079fd346eb4edc"
 }

.sqlx/query-5d45897a5d4c326c8d17f105cae81db7f5878c197b55e8ea61c225e739d11234.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  uir.id,\n  uir.impersonator_user_token as `impersonator_user_token: UserToken`,\n  impersonator.username as impersonator_username,\n  impersonator.display_name as impersonator_display_name,\n  uir.impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonated.username as impersonated_username,\n  impersonated.display_name as impersonated_display_name,\n  uir.is_redeemed as `is_redeemed: bool`,\n  (uir.expires_at < NOW()) as `is_expired: bool`,\n  uir.expires_at,\n  uir.created_at,\n  uir.updated_at\nFROM user_impersonation_requests uir\nJOIN users impersonator ON impersonator.token = uir.impersonator_user_token\nJOIN users impersonated ON impersonated.token = uir.impersonated_user_token\nWHERE uir.id < ?\nORDER BY uir.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "impersonator_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "impersonated_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": "impersonated_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "impersonated_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "is_expired: bool",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "5d45897a5d4c326c8d17f105cae81db7f5878c197b55e8ea61c225e739d11234"
+}

.sqlx/query-9132f832752ea40736bedf4729c76af7fe019cc69ed5cc280fce87e68c3f4846.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  sal.id,\n  sal.token as `token: StaffAuditLogToken`,\n  sal.audit_action,\n  sal.maybe_entity_type,\n  sal.maybe_entity_token,\n  target_user.username as maybe_target_username,\n  target_user.display_name as maybe_target_display_name,\n  sal.staff_user_token as `staff_user_token: UserToken`,\n  staff_user.username as staff_username,\n  staff_user.display_name as staff_display_name,\n  sal.staff_ip_address,\n  sal.created_at\nFROM staff_audit_logs sal\nLEFT JOIN users target_user ON target_user.token = sal.maybe_entity_token\nLEFT JOIN users staff_user ON staff_user.token = sal.staff_user_token\nWHERE sal.id < ?\nORDER BY sal.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "token: StaffAuditLogToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "audit_action",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_entity_type",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "maybe_entity_token",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "maybe_target_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "maybe_target_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "staff_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "staff_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "staff_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "staff_ip_address",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      true,
+      false,
+      true,
+      true,
+      true,
+      true,
+      true,
+      false,
+      false
+    ]
+  },
+  "hash": "9132f832752ea40736bedf4729c76af7fe019cc69ed5cc280fce87e68c3f4846"
+}

.sqlx/query-9dc83df0b7f1cf2716352e947b6b7fcb6c455fb0c12d72e584612f35366831f4.json

@@ -0,0 +1,80 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token,\n  impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonator_user_token as `impersonator_user_token: UserToken`,\n  user_impersonation_token,\n  is_redeemed as `is_redeemed: bool`,\n  expires_at\nFROM user_impersonation_requests\nWHERE user_impersonation_token = ?\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonated_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "user_impersonation_token",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "9dc83df0b7f1cf2716352e947b6b7fcb6c455fb0c12d72e584612f35366831f4"
+}

.sqlx/query-ba5b0a542d4b95b781077b8895529d222dd682eb28c9d00031a820ec6f37e095.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO user_sessions (\n  token,\n  user_token,\n  maybe_impersonation_user_token,\n  ip_address_creation,\n  expires_at\n)\nVALUES (?, ?, ?, ?, ?)\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 5
+    },
+    "nullable": []
+  },
+  "hash": "ba5b0a542d4b95b781077b8895529d222dd682eb28c9d00031a820ec6f37e095"
+}

.sqlx/query-c39800423a5fe0aa324e117e624015f85d039c3ca6833cf6865471345ab0768e.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO staff_audit_logs\nSET\n  token = ?,\n  audit_action = ?,\n  maybe_entity_type = ?,\n  maybe_entity_token = ?,\n  staff_user_token = ?,\n  staff_ip_address = ?\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 6
+    },
+    "nullable": []
+  },
+  "hash": "c39800423a5fe0aa324e117e624015f85d039c3ca6833cf6865471345ab0768e"
+}

.sqlx/query-cc782c807dadcaaaad08f469935f61dc2e9f3217aa01532d6602b8e37cedf92d.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO user_impersonation_requests\nSET\n  token = ?,\n  impersonated_user_token = ?,\n  impersonator_user_token = ?,\n  user_impersonation_token = ?,\n  ip_address_creation = ?,\n  expires_at = ?\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 6
+    },
+    "nullable": []
+  },
+  "hash": "cc782c807dadcaaaad08f469935f61dc2e9f3217aa01532d6602b8e37cedf92d"
+}

.sqlx/query-cf4be26ce3a48c7108640faa6c9fc68a48136327a9d374c52c16848c006f0984.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE user_impersonation_requests\nSET\n  is_redeemed = TRUE,\n  ip_address_redemption = ?\nWHERE user_impersonation_token = ?\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": []
+  },
+  "hash": "cf4be26ce3a48c7108640faa6c9fc68a48136327a9d374c52c16848c006f0984"
+}

.sqlx/query-e72b3dfdd9df4ee10a696faa4dfc3fb8addc9d2b88017f503c339fb616bef6f1.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  uir.id,\n  uir.impersonator_user_token as `impersonator_user_token: UserToken`,\n  impersonator.username as impersonator_username,\n  impersonator.display_name as impersonator_display_name,\n  uir.impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonated.username as impersonated_username,\n  impersonated.display_name as impersonated_display_name,\n  uir.is_redeemed as `is_redeemed: bool`,\n  (uir.expires_at < NOW()) as `is_expired: bool`,\n  uir.expires_at,\n  uir.created_at,\n  uir.updated_at\nFROM user_impersonation_requests uir\nJOIN users impersonator ON impersonator.token = uir.impersonator_user_token\nJOIN users impersonated ON impersonated.token = uir.impersonated_user_token\nORDER BY uir.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "impersonator_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "impersonated_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": "impersonated_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "impersonated_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "is_expired: bool",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "e72b3dfdd9df4ee10a696faa4dfc3fb8addc9d2b88017f503c339fb616bef6f1"
+}

CLAUDE.md

@@ -58,10 +58,11 @@ artcraft/
 
 - Rust with no minimum supported version
 - Actix-web for HTTP services
-- SQLx for MySQL and SQLite
+- SQLx for MySQL and SQLite; prefer `sqlx::query!` / `sqlx::query_as!` compile-time checked macros over runtime `sqlx::query()` whenever possible
 - A mix of wreq and reqwest for Rust HTTP clients
 - Never use `println!` or `eprintln!` outside of tests; use `log` crate macros instead
 - When two crates export the same type name, alias imports with a suffix: `use foo::Bar as BarFoo;`
+- Prefer `use` imports over inline fully-qualified paths; only qualify inline for true one-offs or std collisions
 - TypeScript with Nx, React, Vite, Zustand, and Three.js
 - Use two spaces for indentation
 
@@ -75,3 +76,4 @@ Organize for top-to-bottom reading. Important things first, details later.
 - **In impl blocks**: constructors first, then public methods, then private helpers
 - Private helpers go *below* the methods that call them
 - Among helpers: meatier logic above leaf-level formatters
+- **In test modules**: constants first, then test cases (grouped into sub-modules when 2+), then helper functions last

Cargo.lock

@@ -770,6 +770,7 @@ dependencies = [
  "anyhow",
  "artcraft_api_defs",
  "artcraft_client",
+ "enums",
  "fal_client",
  "log",
  "muapi_client",
@@ -3876,6 +3877,13 @@ dependencies = [
  "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "error_utils"
+version = "0.0.1"
+dependencies = [
+ "regex",
+]
+
 [[package]]
 name = "errors"
 version = "0.0.1"
@@ -6089,7 +6097,6 @@ dependencies = [
 name = "jwt_signer"
 version = "0.0.1"
 dependencies = [
- "errors",
  "hmac 0.10.1",
  "jwt",
  "sha2 0.9.9",
@@ -7744,6 +7751,17 @@ version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "624a8340c38c1b80fd549087862da4ba43e08858af025b236e509b6649fc13d5"
 
+[[package]]
+name = "opaque_cursors"
+version = "0.0.1"
+dependencies = [
+ "base64 0.22.1",
+ "magic-crypt",
+ "serde",
+ "serde_derive",
+ "serde_json",
+]
+
 [[package]]
 name = "open"
 version = "5.3.3"
@@ -10173,6 +10191,7 @@ dependencies = [
  "anyhow",
  "bootstrap",
  "bucket_paths",
+ "chrono",
  "cloud_storage",
  "concurrency",
  "easyenv",
@@ -11234,6 +11253,7 @@ dependencies = [
  "elasticsearch",
  "elasticsearch_schema",
  "enums",
+ "error_utils",
  "errors",
  "fal_client",
  "ffmpeg_utils",
@@ -11261,6 +11281,7 @@ dependencies = [
  "mimetypes",
  "mysql_queries",
  "once_cell",
+ "opaque_cursors",
  "pager",
  "password",
  "primitives",
@@ -14772,6 +14793,7 @@ dependencies = [
  "serde",
  "serde_json",
  "strum",
+ "test_data",
  "tokio",
  "uuid 1.22.0",
  "workspace-build-acceleration",

Cargo.toml

@@ -59,6 +59,7 @@ members = [
   "crates/lib/data/primitives",
   "crates/lib/data/web_base64",
   "crates/lib/easyenv", # NB: Vendored version of https://github.com/echelon/easyenv.rs that we'll improve.
+  "crates/lib/error_utils",
   "crates/lib/errors",
   "crates/lib/ffmpeg_utils",
   "crates/lib/files/file_to_base64_url",
@@ -72,6 +73,7 @@ members = [
   "crates/lib/http_headers",
   "crates/lib/jobs_common",
   "crates/lib/jwt_light",
+  "crates/lib/opaque_cursors",
   "crates/lib/jwt_signer",
   "crates/lib/logging",
   "crates/lib/markdown",
@@ -236,6 +238,7 @@ cookie_store = { path = "crates/lib/cookie_store" }
 crockford = { path = "crates/lib/data/crockford" }
 easyenv = { path = "crates/lib/easyenv" }
 enums = { path = "crates/schema/public/enums" }
+error_utils = { path = "crates/lib/error_utils" }
 errors = { path = "crates/lib/errors" }
 fal_client = { path = "crates/api_clients/fal_client" }
 ffmpeg_utils = { path = "crates/lib/ffmpeg_utils" }
@@ -250,6 +253,7 @@ images = { path = "crates/lib/files/images" }
 jobs_common = { path = "crates/lib/jobs_common" }
 jwt_light = { path = "crates/lib/jwt_light" }
 jwt_signer = { path = "crates/lib/jwt_signer" }
+opaque_cursors = { path = "crates/lib/opaque_cursors" }
 memory_caching = { path = "crates/lib/caching/memory_caching" }
 memory_store = { path = "crates/lib/caching/memory_store" }
 midjourney_client = { path = "crates/api_clients/midjourney_client" }

_database/sql/migrations/2026-04-13-224821-0000_staff_audit_logs/down.sql

@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS staff_audit_logs;

_database/sql/migrations/2026-04-13-224821-0000_staff_audit_logs/up.sql

@@ -0,0 +1,39 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE staff_audit_logs (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- Effective "primary key" of the audit log item (in case we add a UI or notes)
+  token VARCHAR(32) NOT NULL,
+
+  -- The type of action taken
+  audit_action VARCHAR(32) NOT NULL,
+
+  -- The type of entity acted upon (if any)
+  maybe_entity_type VARCHAR(16) DEFAULT NULL,
+
+  -- The token of the entity mutated (if any)
+  maybe_entity_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who performed the action.
+  staff_user_token VARCHAR(32) DEFAULT NULL,
+
+  -- For abuse tracking.
+  -- Wide enough for IPv4/6
+  staff_ip_address VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY index_maybe_entity_type (maybe_entity_type),
+  KEY index_maybe_entity_token (maybe_entity_token),
+  KEY index_staff_user_token (staff_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations/2026-04-13-230305-0000_alter_user_sessions_impersonation/down.sql

@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE user_sessions
+  DROP COLUMN maybe_impersonation_user_token;

_database/sql/migrations/2026-04-13-230305-0000_alter_user_sessions_impersonation/up.sql

@@ -0,0 +1,7 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE user_sessions
+  ADD COLUMN maybe_impersonation_user_token VARCHAR(32) DEFAULT NULL
+  AFTER user_token;

_database/sql/migrations/2026-04-13-231638-0000_user_impersonation_requests/down.sql

@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS user_impersonation_requests;

_database/sql/migrations/2026-04-13-231638-0000_user_impersonation_requests/up.sql

@@ -0,0 +1,44 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_impersonation_requests (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- Internal "primary key"
+  token VARCHAR(32) NOT NULL,
+
+  -- The user being impersonated.
+  impersonated_user_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who initiated the impersonation.
+  impersonator_user_token VARCHAR(32) NOT NULL,
+
+  -- The actual secret that must be presented to redeem the impersonation.
+  user_impersonation_token VARCHAR(32) NOT NULL,
+
+  -- Whether this request has been redeemed (used to create a session).
+  is_redeemed BOOLEAN NOT NULL DEFAULT FALSE,
+
+  -- IP address of the staff user who created the request.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address from which the request was redeemed, if redeemed.
+  ip_address_redemption VARCHAR(40) DEFAULT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- The request expires after this time if not redeemed.
+  expires_at TIMESTAMP NOT NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (user_impersonation_token),
+  KEY index_impersonated_user_token (impersonated_user_token),
+  KEY index_impersonator_user_token (impersonator_user_token)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations/2026-04-14-054849-0000_drop_user_impersonation_requests/down.sql

@@ -0,0 +1,35 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- Recreate with the original signed BIGINT id.
+CREATE TABLE user_impersonation_requests (
+
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  token VARCHAR(32) NOT NULL,
+
+  impersonated_user_token VARCHAR(32) NOT NULL,
+
+  impersonator_user_token VARCHAR(32) NOT NULL,
+
+  user_impersonation_token VARCHAR(32) NOT NULL,
+
+  is_redeemed BOOLEAN NOT NULL DEFAULT FALSE,
+
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  ip_address_redemption VARCHAR(40) DEFAULT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  expires_at TIMESTAMP NOT NULL,
+
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (user_impersonation_token),
+  KEY index_impersonated_user_token (impersonated_user_token),
+  KEY index_impersonator_user_token (impersonator_user_token)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations/2026-04-14-054849-0000_drop_user_impersonation_requests/up.sql

@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS user_impersonation_requests;

_database/sql/migrations/2026-04-14-054856-0000_recreate_user_impersonation_requests/down.sql

@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS user_impersonation_requests;

_database/sql/migrations/2026-04-14-054856-0000_recreate_user_impersonation_requests/up.sql

@@ -0,0 +1,44 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_impersonation_requests (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Internal "primary key"
+  token VARCHAR(32) NOT NULL,
+
+  -- The user being impersonated.
+  impersonated_user_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who initiated the impersonation.
+  impersonator_user_token VARCHAR(32) NOT NULL,
+
+  -- The actual secret that must be presented to redeem the impersonation.
+  user_impersonation_token VARCHAR(32) NOT NULL,
+
+  -- Whether this request has been redeemed (used to create a session).
+  is_redeemed BOOLEAN NOT NULL DEFAULT FALSE,
+
+  -- IP address of the staff user who created the request.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address from which the request was redeemed, if redeemed.
+  ip_address_redemption VARCHAR(40) DEFAULT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- The request expires after this time if not redeemed.
+  expires_at TIMESTAMP NOT NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (user_impersonation_token),
+  KEY index_impersonated_user_token (impersonated_user_token),
+  KEY index_impersonator_user_token (impersonator_user_token)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/down.sql

@@ -0,0 +1,31 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- Recreate with the original signed BIGINT id.
+CREATE TABLE staff_audit_logs (
+
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  token VARCHAR(32) NOT NULL,
+
+  audit_action VARCHAR(32) NOT NULL,
+
+  maybe_entity_type VARCHAR(16) DEFAULT NULL,
+
+  maybe_entity_token VARCHAR(32) NOT NULL,
+
+  staff_user_token VARCHAR(32) DEFAULT NULL,
+
+  staff_ip_address VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY index_maybe_entity_type (maybe_entity_type),
+  KEY index_maybe_entity_token (maybe_entity_token),
+  KEY index_staff_user_token (staff_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations/2026-04-14-062939-0000_drop_staff_audit_logs/up.sql

@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS staff_audit_logs;

_database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/down.sql

@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS staff_audit_logs;

_database/sql/migrations/2026-04-14-062950-0000_recreate_staff_audit_logs/up.sql

@@ -0,0 +1,39 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE staff_audit_logs (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Effective "primary key" of the audit log item (in case we add a UI or notes)
+  token VARCHAR(32) NOT NULL,
+
+  -- The type of action taken
+  audit_action VARCHAR(32) NOT NULL,
+
+  -- The type of entity acted upon (if any)
+  maybe_entity_type VARCHAR(16) DEFAULT NULL,
+
+  -- The token of the entity mutated (if any)
+  maybe_entity_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who performed the action.
+  staff_user_token VARCHAR(32) DEFAULT NULL,
+
+  -- For abuse tracking.
+  -- Wide enough for IPv4/6
+  staff_ip_address VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY index_maybe_entity_type (maybe_entity_type),
+  KEY index_maybe_entity_token (maybe_entity_token),
+  KEY index_staff_user_token (staff_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations/CLAUDE.md

@@ -0,0 +1,38 @@
+# SQL Migrations
+
+Incremental schema changes applied in order by timestamp prefix.
+
+## Naming Convention
+
+Migration directories follow the format:
+
+```
+YYYY-MM-DD-HHMMSS-NNNN_description_goes_here/
+  up.sql
+  down.sql
+```
+
+These are created with the `diesel` tool, and in particular:
+
+> `diesel migration generate description_goes_here`
+
+- `NNNN` is a zero-padded sequence number for ordering multiple migrations on the same timestamp.
+- `up.sql` applies the migration forward.
+- `down.sql` reverses it.
+
+## Table Conventions
+
+- Primary key `id` columns must be `BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT`. Do not use signed IDs.
+- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`.
+- All SQL files should start with the standard IntelliJ noinspection comments:
+  ```sql
+  -- noinspection SqlDialectInspectionForFile
+  -- noinspection SqlNoDataSourceInspectionForFile
+  -- noinspection SqlResolveForFile
+  ```
+
+## Rules
+
+- Every `up.sql` must have a corresponding `down.sql` that cleanly reverses the migration.
+- For `CREATE TABLE` migrations, the `down.sql` is typically `DROP TABLE IF EXISTS table_name;`.
+- For `ALTER TABLE` migrations, the `down.sql` reverses the alteration (e.g. `DROP COLUMN`).

_database/sql/migrations_squashed/CLAUDE.md

@@ -0,0 +1,26 @@
+# Squashed / Materialized Schemas
+
+Fully materialized table definitions representing the current state of each table
+after all migrations have been applied. These are not executed — they exist as
+human-readable documentation of the current schema.
+
+## When to Update
+
+Update the corresponding squashed file whenever a migration changes a table's schema
+(adding columns, changing types, dropping and recreating, etc.).
+
+## Table Conventions
+
+- Primary key `id` columns must be `BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT`. Do not use signed IDs.
+- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`.
+- All SQL files should start with the standard IntelliJ noinspection comments:
+  ```sql
+  -- noinspection SqlDialectInspectionForFile
+  -- noinspection SqlNoDataSourceInspectionForFile
+  -- noinspection SqlResolveForFile
+  ```
+
+## File Organization
+
+Files are named after their table (e.g. `users.sql`, `media_files.sql`).
+Some tables are grouped into subdirectories (e.g. `user_tables/`).

_database/sql/migrations_squashed/staff_audit_logs.sql

@@ -0,0 +1,39 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE staff_audit_logs (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Effective "primary key" of the audit log item (in case we add a UI or notes)
+  token VARCHAR(32) NOT NULL,
+
+  -- The type of action taken
+  audit_action VARCHAR(32) NOT NULL,
+
+  -- The type of entity acted upon (if any)
+  maybe_entity_type VARCHAR(16) DEFAULT NULL,
+
+  -- The token of the entity mutated (if any)
+  maybe_entity_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who performed the action.
+  staff_user_token VARCHAR(32) DEFAULT NULL,
+
+  -- For abuse tracking.
+  -- Wide enough for IPv4/6
+  staff_ip_address VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY index_maybe_entity_type (maybe_entity_type),
+  KEY index_maybe_entity_token (maybe_entity_token),
+  KEY index_staff_user_token (staff_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations_squashed/user_tables/user_impersonation_requests.sql

@@ -0,0 +1,44 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_impersonation_requests (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Internal "primary key"
+  token VARCHAR(32) NOT NULL,
+
+  -- The user being impersonated.
+  impersonated_user_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who initiated the impersonation.
+  impersonator_user_token VARCHAR(32) NOT NULL,
+
+  -- The actual secret that must be presented to redeem the impersonation.
+  user_impersonation_token VARCHAR(32) NOT NULL,
+
+  -- Whether this request has been redeemed (used to create a session).
+  is_redeemed BOOLEAN NOT NULL DEFAULT FALSE,
+
+  -- IP address of the staff user who created the request.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address from which the request was redeemed, if redeemed.
+  ip_address_redemption VARCHAR(40) DEFAULT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- The request expires after this time if not redeemed.
+  expires_at TIMESTAMP NOT NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (user_impersonation_token),
+  KEY index_impersonated_user_token (impersonated_user_token),
+  KEY index_impersonator_user_token (impersonator_user_token)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations_squashed/user_tables/user_sessions.sql

@@ -0,0 +1,50 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_sessions (
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- Session primary key
+  token VARCHAR(32) NOT NULL,
+
+  -- The user that the session belongs to.
+  user_token VARCHAR(32) NOT NULL,
+
+  -- NEVER IMPERSONATE A USER'S ACCOUNT WITHOUT THEIR CONSENT!
+  --
+  -- For support requests and inquiries, we can have staff log into user accounts
+  -- to verify and debug possible broken states. The user is always told about
+  -- this if we are to use this for support cases.
+  --
+  -- Every action performed by impersonated sessions is logged for auditing.
+  --
+  -- If this session is impersonating another user, this is the token of
+  -- the staff user who initiated the impersonation.
+  maybe_impersonation_user_token VARCHAR(32) DEFAULT NULL,
+
+  -- Track each session's creation IP.
+  -- Wide enough for IPv4/6
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- Session termination time.
+  -- This must be set by the server code, or the session is invalid
+  expires_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- deletion = session termination
+  -- Typically these are destroyed by users, but if in the future we allow mods to
+  -- delete them, it doesn't really matter who did the deletion: sessions are not
+  -- designed to be recoverable.
+  deleted_at TIMESTAMP NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY fk_user_token (user_token),
+  KEY index_ip_address_creation (ip_address_creation)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_tools/postman/collections/ArtCraft API/generate/cost/Estimate Image Cost.request.yaml

@@ -15,11 +15,12 @@ body:
   type: json
   content: |
     {
-        "model": "seedream_5_lite",
+        "model": "gpt_image_2",
         "provider": "artcraft",
         "generation_mode": {"type": "text_to_image" },
         "aspect_ratio": "wide_sixteen_by_nine",
         "resolution": "two_k",
+        "quality": "low",
         "image_batch_count": 1
     }
 order: 2000

_tools/postman/collections/ArtCraft API/moderation/Create Wallet for User.request.yaml

@@ -15,7 +15,7 @@ body:
   type: json
   content: |
     {
-        "user_token": "user_jg7ng4kdt2x5y", // newuser946
+        "user_token": "user_rtdhen9kz73kx", // 
         "payments_namespace": "artcraft"
     }
 order: 4100053395280358

_tools/postman/collections/ArtCraft API/moderation/Impersonate User Request.request.yaml

@@ -0,0 +1,11 @@
+$kind: http-request
+name: Impersonate User Request
+url: "{{api_host}}/v1/moderation/user_sessions/impersonate"
+method: POST
+body:
+  type: json
+  content: |-
+    {
+        "username": "newuser3"
+    }
+order: 4318829221021218

crates/CLAUDE.md

@@ -0,0 +1,59 @@
+# Rust Workspace
+
+All Rust code lives under `crates/`. The workspace is defined in `Cargo.toml` at the repo root.
+
+## Code Style
+
+- Two spaces for indentation (not four)
+- No minimum supported Rust version; use latest stable features freely
+- Never use `println!` or `eprintln!` outside of tests; use `log` crate macros instead
+- Use `anyhow::Result` / `AnyhowResult` for fallible functions in application code
+- Fields that are optional use the `maybe_` prefix: `maybe_creator_user_token`
+- When two crates export the same type name, alias with a suffix: `use foo::Bar as BarFoo;`
+- Prefer `use` imports over inline fully-qualified paths; only qualify inline for true one-offs or std prelude collisions (`Result`, `Option`, `Error`)
+
+## File Layout
+
+Organize for top-to-bottom reading. Important things first, details later.
+
+1. **Constants** at the top (after imports)
+2. **Primary public type** (the main struct/enum the file defines)
+3. **Supporting types** below the primary type
+4. **API types** in order: Request, Response, Error
+5. **`impl` blocks** after their type definitions
+   - Constructors first, then public methods, then private helpers
+   - Callers above callees — follow the call chain downward
+
+## Test Layout
+
+Within `#[cfg(test)] mod tests { ... }`:
+
+1. **Imports**
+2. **Constants** (test IDs, URLs, fixture data) — small context that tests reference
+3. **Test functions or sub-modules** grouped by category
+4. **Helper functions** (builders, pipeline runners, assertions)
+
+Constants provide small context up front. Test cases come next so engineers see *what* is
+tested before *how* the helpers work.
+
+Group related tests into sub-modules (`mod pricing_tests { ... }`) when a category has 2+
+tests. Don't wrap a single test in its own module. Keep nesting to two levels max. Shared
+helpers go in the parent `mod tests` so sub-modules can `use super::*`.
+
+## Building
+
+- Most crates: `cargo check -p {crate_name}` or `cargo test -p {crate_name}`
+- Crates using SQLx: `SQLX_OFFLINE=true cargo check -p {crate_name}`
+- `storyteller-web` and `mysql_queries` require `SQLX_OFFLINE=true`
+- `storyteller-web` has ~370 pre-existing warnings — check the last few lines for actual errors
+
+## Key Crates
+
+- `storyteller_web` — main HTTP API monolith (actix-web)
+- `artcraft` (desktop) — Tauri desktop app
+- `artcraft_router` — provider routing for image/video generation (Artcraft, Fal, Seedance2Pro, Muapi)
+- `artcraft_api_defs` — shared HTTP API type definitions
+- `seedance2pro_client` — HTTP client for the Kinovi/Seedance2Pro video generation service
+- `enums` — database-backed enums stored as VARCHAR fields
+- `tokens` — primary key identifiers with Stripe-like prefixes (e.g. `user_`, `mf_`)
+- `mysql_queries` — SQLx MySQL queries for the backend

crates/api_clients/artcraft/artcraft_api_defs/src/generate/cost_estimate/estimate_image_cost.rs

@@ -3,13 +3,14 @@ use utoipa::ToSchema;
 
 use enums::common::generation::common_aspect_ratio::CommonAspectRatio;
 use enums::common::generation::common_image_model::CommonImageModel;
+use enums::common::generation::common_quality::CommonQuality;
 use enums::common::generation::common_resolution::CommonResolution;
 use enums::common::generation_provider::GenerationProvider;
 
 pub const ESTIMATE_IMAGE_COST_PATH: &str = "/v1/generate/cost_estimate/image";
 
 /// Request body for the image cost estimate endpoint.
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Serialize, Deserialize, ToSchema, Debug)]
 pub struct EstimateImageCostRequest {
   /// The image model to estimate costs for.
   pub model: CommonImageModel,
@@ -29,12 +30,15 @@ pub struct EstimateImageCostRequest {
   /// Optional resolution.
   pub resolution: Option<CommonResolution>,
 
+  // Optional quality.
+  pub quality: Option<CommonQuality>,
+
   /// Number of images to generate in parallel.
   pub image_batch_count: Option<u16>,
 }
 
 /// Describes the type of image generation being requested.
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Serialize, Deserialize, ToSchema, Debug)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum GenerationMode {
   /// No input images — generate from prompt only.
@@ -94,6 +98,7 @@ mod tests {
       generation_mode: GenerationMode::TextToImage,
       aspect_ratio: None,
       resolution: None,
+      quality: None,
       image_batch_count: None,
     };
     let serialized = serde_json::to_string(&request).unwrap();
@@ -108,6 +113,7 @@ mod tests {
       generation_mode: GenerationMode::ImageEdit { count: 2 },
       aspect_ratio: None,
       resolution: None,
+      quality: None,
       image_batch_count: None,
     };
     let serialized = serde_json::to_string(&request).unwrap();

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/generate_kling_1_6_pro_image_to_video.rs

@@ -28,7 +28,7 @@ pub struct GenerateKling16ProImageToVideoRequest {
   pub duration: Option<GenerateKling16ProDuration>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateKling16ProAspectRatio {
   /// 16:9 aspect ratio
@@ -39,7 +39,7 @@ pub enum GenerateKling16ProAspectRatio {
   Square,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateKling16ProDuration {
   FiveSeconds,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/generate_kling_2_1_master_image_to_video.rs

@@ -24,7 +24,7 @@ pub struct GenerateKling21MasterImageToVideoRequest {
   pub duration: Option<GenerateKling21MasterDuration>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateKling21MasterAspectRatio {
   /// 16:9 aspect ratio
@@ -35,7 +35,7 @@ pub enum GenerateKling21MasterAspectRatio {
   Square,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateKling21MasterDuration {
   FiveSeconds,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/generate_kling_2_1_pro_image_to_video.rs

@@ -28,7 +28,7 @@ pub struct GenerateKling21ProImageToVideoRequest {
   pub duration: Option<GenerateKling21ProDuration>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateKling21ProAspectRatio {
   /// 16:9 aspect ratio
@@ -39,7 +39,7 @@ pub enum GenerateKling21ProAspectRatio {
   Square,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateKling21ProDuration {
   FiveSeconds,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/generate_seedance_1_0_lite_image_to_video.rs

@@ -31,14 +31,14 @@ pub struct GenerateSeedance10LiteImageToVideoRequest {
   pub aspect_ratio: Option<GenerateSeedance10LiteAspectRatio>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateSeedance10LiteResolution {
   FourEightyP,
   SevenTwentyP,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateSeedance10LiteDuration {
   FiveSeconds,
@@ -46,7 +46,7 @@ pub enum GenerateSeedance10LiteDuration {
 }
 
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateSeedance10LiteAspectRatio {
   Auto,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/generate_veo_2_image_to_video.rs

@@ -16,7 +16,8 @@ pub struct GenerateVeo2ImageToVideoRequest {
   
   /// Optional text prompt.
   pub prompt: Option<String>,
-  
+
+  /// **NB(bt): ASPECT RATIO IS ACTUALLY NOT USED IN VEO 2 IMAGE-TO-VIDEO**
   /// Optional: aspect ratio of the generated video.
   pub aspect_ratio: Option<GenerateVeo2AspectRatio>,
 
@@ -24,7 +25,7 @@ pub struct GenerateVeo2ImageToVideoRequest {
   pub duration: Option<GenerateVeo2Duration>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateVeo2AspectRatio {
   Auto,
@@ -33,7 +34,7 @@ pub enum GenerateVeo2AspectRatio {
   TallNineSixteen, // 9:16
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateVeo2Duration {
   FiveSeconds,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/generate_veo_3_fast_image_to_video.rs

@@ -21,20 +21,31 @@ pub struct GenerateVeo3FastImageToVideoRequest {
   pub resolution: Option<GenerateVeo3FastResolution>,
 
   /// Optional: aspect ratio of the generated video.
+  pub aspect_ratio: Option<GenerateVeo3FastAspectRatio>,
+
+  /// Optional: duration of the generated video.
   pub duration: Option<GenerateVeo3FastDuration>,
 
   /// Optional: Generate an audio track along with the video
   pub generate_audio: Option<bool>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateVeo3FastResolution {
   SevenTwentyP, // 720p
   TenEightyP, // 1080p
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum GenerateVeo3FastAspectRatio {
+  Auto,
+  SixteenByNine,
+  NineBySixteen,
+}
+
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateVeo3FastDuration {
   EightSeconds,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/generate_veo_3_image_to_video.rs

@@ -37,22 +37,26 @@ pub struct GenerateVeo3ImageToVideoRequest {
   // pub auto_fix: Option<bool>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateVeo3AspectRatio {
   WideSixteenNine, // 16:9
   TallNineSixteen, // 9:16
+  
+  /// NB: DO NOT REMOVE. This is an unsupported resolution for Veo 3, but we can't 
+  /// impact existing callers by removing it. The handler will convert this to a 
+  /// supported resolution or 400 the request instead.
   Square, // 1:1
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateVeo3Resolution {
   SevenTwentyP, // 720p
   TenEightyP, // 1080p
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateVeo3Duration {
   EightSeconds,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/multi_function/kling_2_5_turbo_multi_function_video_gen.rs

@@ -41,14 +41,14 @@ pub struct Kling2p5TurboProMultiFunctionVideoGenRequest {
   pub aspect_ratio: Option<Kling2p5TurboProMultiFunctionVideoGenAspectRatio>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Kling2p5TurboProMultiFunctionVideoGenDuration {
   FiveSeconds,
   TenSeconds,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Kling2p5TurboProMultiFunctionVideoGenAspectRatio {
   Square,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/multi_function/kling_2_6_multi_function_video_gen.rs

@@ -45,14 +45,14 @@ pub struct Kling2p6ProMultiFunctionVideoGenRequest {
   pub aspect_ratio: Option<Kling2p6ProMultiFunctionVideoGenAspectRatio>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Kling2p6ProMultiFunctionVideoGenDuration {
   FiveSeconds,
   TenSeconds,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Kling2p6ProMultiFunctionVideoGenAspectRatio {
   Square,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/multi_function/seedance_2p0_multi_function_video_gen.rs

@@ -7,7 +7,7 @@ use utoipa::ToSchema;
 pub const SEEDANCE_2P0_MULTI_FUNCTION_VIDEO_GEN_PATH: &str = "/v1/generate/video/multi_function/seedance_2p0";
 
 /// Seedance 2.0 multi-function video generation (text-to-video, image-to-video, and reference-based).
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
 pub struct Seedance2p0MultiFunctionVideoGenRequest {
   /// Idempotency token to prevent duplicate requests.
   pub uuid_idempotency_token: String,
@@ -37,6 +37,9 @@ pub struct Seedance2p0MultiFunctionVideoGenRequest {
   /// Video aspect ratio / resolution.
   pub aspect_ratio: Option<Seedance2p0AspectRatio>,
 
+  /// Output resolution quality tier (480p, 720p, 1080p).
+  pub output_resolution: Option<Seedance2p0OutputResolution>,
+
   /// Duration in seconds (4–15).
   pub duration_seconds: Option<u8>,
 
@@ -67,6 +70,17 @@ pub enum Seedance2p0BatchCount {
   Four,
 }
 
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum Seedance2p0OutputResolution {
+  /// 480p
+  FourEightyP,
+  /// 720p (default)
+  SevenTwentyP,
+  /// 1080p
+  TenEightyP,
+}
+
 #[derive(Serialize, Deserialize, ToSchema)]
 pub struct Seedance2p0MultiFunctionVideoGenResponse {
   pub success: bool,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/multi_function/sora_2_multi_function_video_gen.rs

@@ -35,14 +35,14 @@ pub struct Sora2MultiFunctionVideoGenRequest {
   pub aspect_ratio: Option<Sora2MultiFunctionVideoGenAspectRatio>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Sora2MultiFunctionVideoGenResolution {
   Auto,
   SevenTwentyP,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Sora2MultiFunctionVideoGenDuration {
   FourSeconds,
@@ -50,7 +50,7 @@ pub enum Sora2MultiFunctionVideoGenDuration {
   TwelveSeconds,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Sora2MultiFunctionVideoGenAspectRatio {
   Auto,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/multi_function/sora_2_pro_multi_function_video_gen.rs

@@ -35,7 +35,7 @@ pub struct Sora2ProMultiFunctionVideoGenRequest {
   pub aspect_ratio: Option<Sora2ProMultiFunctionVideoGenAspectRatio>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Sora2ProMultiFunctionVideoGenResolution {
   Auto,
@@ -43,7 +43,7 @@ pub enum Sora2ProMultiFunctionVideoGenResolution {
   TenEightyP,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Sora2ProMultiFunctionVideoGenDuration {
   FourSeconds,
@@ -51,7 +51,7 @@ pub enum Sora2ProMultiFunctionVideoGenDuration {
   TwelveSeconds,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Sora2ProMultiFunctionVideoGenAspectRatio {
   Auto,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/multi_function/veo_3p1_fast_multi_function_video_gen.rs

@@ -60,7 +60,7 @@ pub struct Veo3p1FastMultiFunctionVideoGenRequest {
   pub auto_fix: Option<bool>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Veo3p1FastMultiFunctionVideoGenDuration {
   FourSeconds,
@@ -68,7 +68,7 @@ pub enum Veo3p1FastMultiFunctionVideoGenDuration {
   EightSeconds,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Veo3p1FastMultiFunctionVideoGenAspectRatio {
   Auto,
@@ -76,7 +76,7 @@ pub enum Veo3p1FastMultiFunctionVideoGenAspectRatio {
   NineBySixteen,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Veo3p1FastMultiFunctionVideoGenResolution {
   SevenTwentyP,

crates/api_clients/artcraft/artcraft_api_defs/src/generate/video/multi_function/veo_3p1_multi_function_video_gen.rs

@@ -60,7 +60,7 @@ pub struct Veo3p1MultiFunctionVideoGenRequest {
   pub auto_fix: Option<bool>,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Veo3p1MultiFunctionVideoGenDuration {
   FourSeconds,
@@ -68,7 +68,7 @@ pub enum Veo3p1MultiFunctionVideoGenDuration {
   EightSeconds,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Veo3p1MultiFunctionVideoGenAspectRatio {
   Auto,
@@ -76,7 +76,7 @@ pub enum Veo3p1MultiFunctionVideoGenAspectRatio {
   NineBySixteen,
 }
 
-#[derive(Serialize, Deserialize, ToSchema)]
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum Veo3p1MultiFunctionVideoGenResolution {
   SevenTwentyP,

crates/api_clients/artcraft/artcraft_api_defs/src/omni_gen/cost_and_generate_requests/omni_gen_image_cost_and_generate_request.rs

@@ -40,11 +40,11 @@ pub struct OmniGenImageCostAndGenerateRequest {
   pub image_batch_count: Option<u16>,
 
   /// Only for angle manipulation models.
-  pub horizontal_angle: Option<f64>,
+  pub adjust_horizontal_angle: Option<f64>,
 
   /// Only for angle manipulation models.
-  pub vertical_angle: Option<f64>,
+  pub adjust_vertical_angle: Option<f64>,
 
   /// Only for angle manipulation models.
-  pub zoom: Option<f64>,
+  pub adjust_zoom: Option<f64>,
 }

crates/api_clients/artcraft/artcraft_api_defs/src/omni_gen/cost_and_generate_requests/omni_gen_video_cost_and_generate_request.rs

@@ -5,10 +5,11 @@ use enums::common::generation::common_aspect_ratio::CommonAspectRatio;
 use enums::common::generation::common_quality::CommonQuality;
 use enums::common::generation::common_resolution::CommonResolution;
 use enums::common::generation::common_video_model::CommonVideoModel;
+use tokens::tokens::characters::CharacterToken;
 use tokens::tokens::media_files::MediaFileToken;
 
 /// Shared request body for both the video cost estimate and video generation endpoints.
-#[derive(Serialize, Deserialize, ToSchema, Debug)]
+#[derive(Clone, Serialize, Deserialize, ToSchema, Debug)]
 pub struct OmniGenVideoCostAndGenerateRequest {
   /// REQUIRED (even if marked optional)
   /// Idempotency token to prevent duplicate requests.
@@ -39,6 +40,10 @@ pub struct OmniGenVideoCostAndGenerateRequest {
   /// Reference audio (optional).
   pub reference_audio_media_tokens: Option<Vec<MediaFileToken>>,
 
+  /// Optional character tokens to reference in the prompt.
+  /// Characters are referenced in prompts as @CharacterName.
+  pub reference_character_tokens: Option<Vec<CharacterToken>>,
+
   /// The resolution to use.
   pub resolution: Option<CommonResolution>,
 

crates/api_clients/artcraft/artcraft_api_defs/src/omni_gen/models/omni_gen_image_models.rs

@@ -2,6 +2,7 @@ use enums::common::generation::common_aspect_ratio::CommonAspectRatio;
 use enums::common::generation::common_image_model::CommonImageModel;
 use enums::common::generation::common_quality::CommonQuality;
 use enums::common::generation::common_resolution::CommonResolution;
+use enums::common::generation::model_creator::ModelCreator;
 use enums::common::generation_provider::GenerationProvider;
 use serde_derive::{Deserialize, Serialize};
 use utoipa::{IntoParams, ToSchema};
@@ -56,6 +57,9 @@ pub struct OmniGenImageProviderModelDetails {
 pub struct OmniGenImageModelDetails {
   pub model: CommonImageModel,
 
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub model_creator: Option<ModelCreator>,
+
   #[serde(skip_serializing_if = "Option::is_none")]
   pub full_name: Option<String>,
 
@@ -103,6 +107,7 @@ pub struct OmniGenImageModelDetails {
   #[serde(skip_serializing_if = "Option::is_none")]
   pub resolution_default: Option<CommonResolution>,
 
+  #[serde(skip_serializing_if = "Option::is_none")]
   pub quality_options: Option<Vec<CommonQuality>>,
 
   #[serde(skip_serializing_if = "Option::is_none")]
@@ -119,12 +124,16 @@ pub struct OmniGenImageModelDetails {
 
   #[serde(skip_serializing_if = "Option::is_none")]
   pub batch_size_default: Option<u16>,
+
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub is_disabled: Option<bool>,
 }
 
 impl Default for OmniGenImageModelDetails {
   fn default() -> Self {
     Self {
       model: CommonImageModel::NanoBananaPro,
+      model_creator: None,
       full_name: None,
       text_prompt_supported: None,
       text_prompt_max_length: None,
@@ -144,6 +153,7 @@ impl Default for OmniGenImageModelDetails {
       batch_size_max: None,
       batch_size_options: None,
       batch_size_default: None,
+      is_disabled: None,
     }
   }
 }

crates/api_clients/artcraft/artcraft_api_defs/src/omni_gen/models/omni_gen_video_models.rs

@@ -1,10 +1,14 @@
-use serde_derive::{Deserialize, Serialize};
-use utoipa::{IntoParams, ToSchema};
 use enums::common::generation::common_aspect_ratio::CommonAspectRatio;
 use enums::common::generation::common_quality::CommonQuality;
 use enums::common::generation::common_resolution::CommonResolution;
 use enums::common::generation::common_video_model::CommonVideoModel;
+use enums::common::generation::model_creator::ModelCreator;
 use enums::common::generation_provider::GenerationProvider;
+use serde_derive::{Deserialize, Serialize};
+use utoipa::{IntoParams, ToSchema};
+
+/// Video model to default to if none is specified
+const DEFAULT_VIDEO_MODEL : CommonVideoModel = CommonVideoModel::Seedance2p0;
 
 /// Query string parameters for the video models endpoint.
 #[derive(Deserialize, IntoParams, ToSchema)]
@@ -62,6 +66,9 @@ pub struct OmniGenVideoModelDetails {
 
   pub model: CommonVideoModel,
   
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub model_creator: Option<ModelCreator>,
+  
   #[serde(skip_serializing_if = "Option::is_none")]
   pub full_name: Option<String>,
   
@@ -110,6 +117,12 @@ pub struct OmniGenVideoModelDetails {
   #[serde(skip_serializing_if = "Option::is_none")]
   pub audio_references_max_total_duration_seconds: Option<u16>,
 
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub character_references_supported: Option<bool>,
+
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub character_references_max: Option<u16>,
+
   #[serde(skip_serializing_if = "Option::is_none")]
   pub show_generate_with_sound_toggle: Option<bool>,
 
@@ -154,12 +167,16 @@ pub struct OmniGenVideoModelDetails {
   
   #[serde(skip_serializing_if = "Option::is_none")]
   pub batch_size_default: Option<u16>,
+
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub is_disabled: Option<bool>,
 }
 
 impl Default for OmniGenVideoModelDetails {
   fn default() -> Self {
     Self {
-      model: CommonVideoModel::Seedance2p0,
+      model: DEFAULT_VIDEO_MODEL,
+      model_creator: None,
       full_name: None,
       text_prompt_supported: None,
       text_prompt_max_length: None,
@@ -176,6 +193,8 @@ impl Default for OmniGenVideoModelDetails {
       audio_references_supported: None,
       audio_references_max: None,
       audio_references_max_total_duration_seconds: None,
+      character_references_supported: None,
+      character_references_max: None,
       show_generate_with_sound_toggle: None,
       aspect_ratio_options: None,
       aspect_ratio_default: None,
@@ -191,6 +210,7 @@ impl Default for OmniGenVideoModelDetails {
       batch_size_max: None,
       batch_size_options: None,
       batch_size_default: None,
+      is_disabled: None,
     }
   }
 }

crates/api_clients/artcraft/artcraft_client/src/endpoints/mod.rs

@@ -2,6 +2,7 @@ pub mod analytics;
 pub mod credits;
 pub mod generate;
 pub mod jobs;
+pub mod omni_gen;
 pub mod media_files;
 pub mod prompts;
 pub mod stripe_artcraft;

crates/api_clients/artcraft/artcraft_client/src/endpoints/omni_gen/generate/image/mod.rs

@@ -0,0 +1 @@
+pub mod omni_gen_image;

crates/api_clients/artcraft/artcraft_client/src/endpoints/omni_gen/generate/image/omni_gen_image.rs

@@ -0,0 +1,21 @@
+use crate::credentials::storyteller_credential_set::StorytellerCredentialSet;
+use crate::error::storyteller_error::StorytellerError;
+use crate::utils::api_host::ApiHost;
+use crate::utils::basic_json_post_request::basic_json_post_request;
+use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_image_cost_and_generate_request::OmniGenImageCostAndGenerateRequest;
+use artcraft_api_defs::omni_gen::generate_response::omni_gen_image_generate_response::OmniGenImageGenerateResponse;
+
+pub const OMNI_GEN_IMAGE_GENERATE_PATH: &str = "/v1/omni_gen/generate/image";
+
+pub async fn omni_gen_image_generate(
+  api_host: &ApiHost,
+  maybe_creds: Option<&StorytellerCredentialSet>,
+  request: OmniGenImageCostAndGenerateRequest,
+) -> Result<OmniGenImageGenerateResponse, StorytellerError> {
+  Ok(basic_json_post_request(
+    api_host,
+    OMNI_GEN_IMAGE_GENERATE_PATH,
+    maybe_creds,
+    request,
+  ).await?)
+}

crates/api_clients/artcraft/artcraft_client/src/endpoints/omni_gen/generate/mod.rs

@@ -0,0 +1,2 @@
+pub mod image;
+pub mod video;

crates/api_clients/artcraft/artcraft_client/src/endpoints/omni_gen/generate/video/mod.rs

@@ -0,0 +1 @@
+pub mod omni_gen_video;

crates/api_clients/artcraft/artcraft_client/src/endpoints/omni_gen/generate/video/omni_gen_video.rs

@@ -0,0 +1,21 @@
+use crate::credentials::storyteller_credential_set::StorytellerCredentialSet;
+use crate::error::storyteller_error::StorytellerError;
+use crate::utils::api_host::ApiHost;
+use crate::utils::basic_json_post_request::basic_json_post_request;
+use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_video_cost_and_generate_request::OmniGenVideoCostAndGenerateRequest;
+use artcraft_api_defs::omni_gen::generate_response::omni_gen_video_generate_response::OmniGenVideoGenerateResponse;
+
+pub const OMNI_GEN_VIDEO_GENERATE_PATH: &str = "/v1/omni_gen/generate/video";
+
+pub async fn omni_gen_video_generate(
+  api_host: &ApiHost,
+  maybe_creds: Option<&StorytellerCredentialSet>,
+  request: OmniGenVideoCostAndGenerateRequest,
+) -> Result<OmniGenVideoGenerateResponse, StorytellerError> {
+  Ok(basic_json_post_request(
+    api_host,
+    OMNI_GEN_VIDEO_GENERATE_PATH,
+    maybe_creds,
+    request,
+  ).await?)
+}

crates/api_clients/artcraft/artcraft_client/src/endpoints/omni_gen/mod.rs

@@ -0,0 +1 @@
+pub mod generate;

crates/api_clients/artcraft/artcraft_router/Cargo.toml

@@ -17,6 +17,7 @@ workspace-build-acceleration.workspace = true
 
 # Internal
 artcraft_api_defs.workspace = true
+enums.workspace = true
 artcraft_client.workspace = true
 fal_client.workspace = true
 muapi_client.workspace = true

crates/api_clients/artcraft/artcraft_router/src/api/audio_list_ref.rs

@@ -1,7 +1,7 @@
 use tokens::tokens::media_files::MediaFileToken;
 
-#[derive(Copy, Clone, Debug)]
-pub enum AudioListRef<'a> {
-  MediaFileTokens(&'a Vec<MediaFileToken>),
-  Urls(&'a Vec<String>),
+#[derive(Clone, Debug)]
+pub enum AudioListRef {
+  MediaFileTokens(Vec<MediaFileToken>),
+  Urls(Vec<String>),
 }

crates/api_clients/artcraft/artcraft_router/src/api/character_list_ref.rs

@@ -1,9 +1,9 @@
 use tokens::tokens::characters::CharacterToken;
 
 /// Forward-compatible character reference list.
-#[derive(Copy, Clone, Debug)]
-pub enum CharacterListRef<'a> {
-  CharacterTokens(&'a Vec<CharacterToken>),
-  
+#[derive(Clone, Debug)]
+pub enum CharacterListRef {
+  CharacterTokens(Vec<CharacterToken>),
+
   // In the future, we may have other identifiers for characters.
 }

crates/api_clients/artcraft/artcraft_router/src/api/common_aspect_ratio.rs

@@ -36,7 +36,11 @@ pub enum CommonAspectRatio {
 
   // Auto values that bake in resolution
   // These are from the Seedream models
+  #[serde(rename = "auto_2k")]
   Auto2k,
+  #[serde(rename = "auto_3k")]
+  Auto3k,
+  #[serde(rename = "auto_4k")]
   Auto4k,
 
   // Defined aspect ratios that bake in resolution

crates/api_clients/artcraft/artcraft_router/src/api/common_image_model.rs

@@ -13,8 +13,12 @@ pub enum CommonImageModel {
   FluxPro11,
   #[serde(rename = "flux_pro_1p1_ultra")]
   FluxPro11Ultra,
+  #[serde(rename = "gpt_image_1")]
+  GptImage1,
   #[serde(rename = "gpt_image_1p5")]
   GptImage1p5,
+  #[serde(rename = "gpt_image_2")]
+  GptImage2,
   #[serde(rename = "nano_banana")]
   NanoBanana,
   #[serde(rename = "nano_banana_2")]

crates/api_clients/artcraft/artcraft_router/src/api/common_quality.rs

@@ -0,0 +1,11 @@
+use serde_derive::{Deserialize, Serialize};
+
+/// Common quality levels you can specify when enqueuing a generation.
+/// Not every model will use this; models that don't simply ignore it.
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum CommonQuality {
+  High,
+  Medium,
+  Low,
+}

crates/api_clients/artcraft/artcraft_router/src/api/common_video_model.rs

@@ -38,6 +38,12 @@ pub enum CommonVideoModel {
   #[serde(rename = "seedance_2p0")]
   Seedance2p0,
 
+  #[serde(rename = "seedance_2p0_fast")]
+  Seedance2p0Fast,
+
+  #[serde(rename = "happy_horse_1p0")]
+  HappyHorse1p0,
+
   #[serde(rename = "sora_2")]
   Sora2,
 

crates/api_clients/artcraft/artcraft_router/src/api/image_list_ref.rs

@@ -1,7 +1,7 @@
 use tokens::tokens::media_files::MediaFileToken;
 
-#[derive(Copy, Clone, Debug)]
-pub enum ImageListRef<'a> {
-  MediaFileTokens(&'a Vec<MediaFileToken>),
-  Urls(&'a Vec<String>),
+#[derive(Clone, Debug)]
+pub enum ImageListRef {
+  MediaFileTokens(Vec<MediaFileToken>),
+  Urls(Vec<String>),
 }

crates/api_clients/artcraft/artcraft_router/src/api/image_ref.rs

@@ -1,7 +1,7 @@
 use tokens::tokens::media_files::MediaFileToken;
 
-#[derive(Copy, Clone, Debug)]
-pub enum ImageRef<'a> {
-  MediaFileToken(&'a MediaFileToken),
-  Url(&'a str),
+#[derive(Clone, Debug)]
+pub enum ImageRef {
+  MediaFileToken(MediaFileToken),
+  Url(String),
 }

crates/api_clients/artcraft/artcraft_router/src/api/mod.rs

@@ -2,6 +2,7 @@ pub mod audio_list_ref;
 pub mod character_list_ref;
 pub mod common_aspect_ratio;
 pub mod common_image_model;
+pub mod common_quality;
 pub mod common_resolution;
 pub mod common_splat_model;
 pub mod common_video_model;

crates/api_clients/artcraft/artcraft_router/src/api/video_list_ref.rs

@@ -1,7 +1,7 @@
 use tokens::tokens::media_files::MediaFileToken;
 
-#[derive(Copy, Clone, Debug)]
-pub enum VideoListRef<'a> {
-  MediaFileTokens(&'a Vec<MediaFileToken>),
-  Urls(&'a Vec<String>),
+#[derive(Clone, Debug)]
+pub enum VideoListRef {
+  MediaFileTokens(Vec<MediaFileToken>),
+  Urls(Vec<String>),
 }

crates/api_clients/artcraft/artcraft_router/src/errors/artcraft_router_error.rs

@@ -15,6 +15,9 @@ pub enum ArtcraftRouterError {
   /// The requested model is not yet supported by the router.
   UnsupportedModel(String),
 
+  /// [Temporary during migration] The requested model/provider is not yet supported by the router.
+  UnsupportedProviderAndModelForNewApi(String),
+
   /// Invalid or missing input arguments.
   InvalidInput(String),
 
@@ -30,6 +33,7 @@ impl Display for ArtcraftRouterError {
       Self::Client(e) => write!(f, "Client error: {}", e),
       Self::Download(e) => write!(f, "Download error: {}", e),
       Self::UnsupportedModel(model) => write!(f, "Unsupported model: {}", model),
+      Self::UnsupportedProviderAndModelForNewApi(msg) => write!(f, "Unsupported provider/model (for new API during migration): {}", msg),
       Self::InvalidInput(msg) => write!(f, "Invalid input: {}", msg),
       Self::Provider(e) => write!(f, "Provider error: {}", e),
     }

crates/api_clients/artcraft/artcraft_router/src/errors/client_error.rs

@@ -1,5 +1,7 @@
 use std::error::Error;
 use std::fmt::{Display, Formatter};
+use tokens::tokens::characters::CharacterToken;
+use tokens::tokens::media_files::MediaFileToken;
 
 #[derive(Debug, Clone, Copy)]
 pub enum ClientType {
@@ -22,6 +24,9 @@ impl Display for ClientType {
 
 #[derive(Debug)]
 pub enum ClientError {
+  /// A RouterClient was required but not provided on the draft context.
+  RouterClientNotProvided,
+
   /// The requested client is not configured on the RouterClient.
   ClientNotConfigured(ClientType),
 
@@ -43,6 +48,18 @@ pub enum ClientError {
 
   /// Seedance2Pro only accepts URLs for media inputs, not media tokens.
   Seedance2ProOnlySupportsUrls,
+  
+  /// The pre-dispatch context of media file token to URL map was not supplied.
+  MediaFileToUrlMapNotProvided,
+
+  /// A media file token was not found in the provided media-file-to-URL map.
+  MediaFileTokenNotFoundInMap { token: MediaFileToken },
+
+  /// The pre-dispatch context of character token to ID map was not supplied.
+  CharacterTokenToKinoviCharacterIdNotProvided,
+
+  /// A character token was not found in the provided character-token-to-id map
+  CharacterTokenNotFoundInMap { token: CharacterToken },
 }
 
 impl Error for ClientError {}
@@ -50,6 +67,9 @@ impl Error for ClientError {}
 impl Display for ClientError {
   fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
     match self {
+      Self::RouterClientNotProvided => {
+        write!(f, "A RouterClient is required but was not provided on the draft context")
+      }
       Self::ClientNotConfigured(client_type) => {
         write!(f, "{} client is not configured on the RouterClient", client_type)
       }
@@ -71,6 +91,18 @@ impl Display for ClientError {
       Self::Seedance2ProOnlySupportsUrls => {
         write!(f, "Seedance2Pro only supports URLs for media inputs; resolve media tokens to URLs before calling this provider")
       }
+      Self::MediaFileToUrlMapNotProvided => {
+        write!(f, "Media file to URL map was not provided")
+      }
+      Self::MediaFileTokenNotFoundInMap { token } => {
+        write!(f, "Media file token '{}' was not found in the provided URL map", token.as_str())
+      }
+      Self::CharacterTokenToKinoviCharacterIdNotProvided => {
+        write!(f, "Character token to Kinovi character ID map was not provided")
+      }
+      Self::CharacterTokenNotFoundInMap { token } => {
+        write!(f, "Character token '{}' was not found in the provided character-token-to-id map", token.as_str())
+      }
     }
   }
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_flux_1_dev.rs

@@ -4,7 +4,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_flux_1_dev::PlanArtcraftFlux1Dev;
 
 pub(crate) fn estimate_image_cost_artcraft_flux_1_dev(
-  plan: &PlanArtcraftFlux1Dev<'_>,
+  plan: &PlanArtcraftFlux1Dev,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.02/image (2 cents). 1 credit = 1 USD cent.
   let cost_per_image: u64 = 2;
@@ -43,6 +43,7 @@ mod tests {
       image_inputs: None,
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_flux_1_schnell.rs

@@ -2,7 +2,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_flux_1_schnell::PlanArtcraftFlux1Schnell;
 
 pub(crate) fn estimate_image_cost_artcraft_flux_1_schnell(
-  _plan: &PlanArtcraftFlux1Schnell<'_>,
+  _plan: &PlanArtcraftFlux1Schnell,
 ) -> ImageGenerationCostEstimate {
   // Pricing: not available
   ImageGenerationCostEstimate {
@@ -31,6 +31,7 @@ mod tests {
       image_inputs: None,
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(1),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_flux_2_lora_angles.rs

@@ -4,7 +4,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_flux_2_lora_angles::PlanArtcraftFlux2LoraAngles;
 
 pub(crate) fn estimate_image_cost_artcraft_flux_2_lora_angles(
-  plan: &PlanArtcraftFlux2LoraAngles<'_>,
+  plan: &PlanArtcraftFlux2LoraAngles,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.04/image (4 cents). 1 credit = 1 USD cent.
   let cost_per_image: u64 = 4;
@@ -43,9 +43,10 @@ mod tests {
       model: CommonImageModel::Flux2LoraAngles,
       provider: Provider::Artcraft,
       prompt: None,
-      image_inputs: Some(ImageListRef::MediaFileTokens(&tokens)),
+      image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       horizontal_angle: None,
       vertical_angle: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_flux_pro_1p1.rs

@@ -4,10 +4,13 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_flux_pro_1p1::PlanArtcraftFluxPro11;
 
 pub(crate) fn estimate_image_cost_artcraft_flux_pro_1p1(
-  plan: &PlanArtcraftFluxPro11<'_>,
+  plan: &PlanArtcraftFluxPro11,
 ) -> ImageGenerationCostEstimate {
-  // NB(bt): Slightly more than 3 cents, weird megapixel maths. We can eat that cost for now.
-  let cost_per_image: u64 = 3;
+  // Fal pricing: $0.04 per megapixel, billed by rounding up to the nearest
+  // megapixel. The default image_size values are ~1MP, so 4 cents per image.
+  // (The legacy `generate_flux_pro_11_text_to_image_handler` charges this same
+  // amount via `FluxPro11Args::calculate_cost_in_cents`.)
+  let cost_per_image: u64 = 4;
 
   let num_images: u64 = match plan.num_images {
     GenerateFluxPro11TextToImageNumImages::One => 1,
@@ -43,6 +46,7 @@ mod tests {
       image_inputs: None,
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,
@@ -60,10 +64,10 @@ mod tests {
 
   #[test]
   fn test_estimate_cost_usd_cents() {
-    // ~$0.03/image = 3 cents each (slightly more than 3¢ actual, rounded up)
-    assert_eq!(estimate_usd_cents(1), 3);
-    assert_eq!(estimate_usd_cents(2), 6);
-    assert_eq!(estimate_usd_cents(3), 9);
-    assert_eq!(estimate_usd_cents(4), 12);
+    // $0.04/image = 4 cents each (Fal's $0.04/MP at the default ~1MP).
+    assert_eq!(estimate_usd_cents(1), 4);
+    assert_eq!(estimate_usd_cents(2), 8);
+    assert_eq!(estimate_usd_cents(3), 12);
+    assert_eq!(estimate_usd_cents(4), 16);
   }
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_flux_pro_1p1_ultra.rs

@@ -4,7 +4,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_flux_pro_1p1_ultra::PlanArtcraftFluxPro11Ultra;
 
 pub(crate) fn estimate_image_cost_artcraft_flux_pro_1p1_ultra(
-  plan: &PlanArtcraftFluxPro11Ultra<'_>,
+  plan: &PlanArtcraftFluxPro11Ultra,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.06/image (6 cents). 1 credit = 1 USD cent.
   let cost_per_image: u64 = 6;
@@ -43,6 +43,7 @@ mod tests {
       image_inputs: None,
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_gpt_image_1.rs

@@ -0,0 +1,239 @@
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_gpt_image_1::{
+  ArtcraftGptImage1Quality, ArtcraftGptImage1Size, PlanArtcraftGptImage1,
+};
+
+pub(crate) fn estimate_image_cost_artcraft_gpt_image_1(
+  plan: &PlanArtcraftGptImage1,
+) -> ImageGenerationCostEstimate {
+  // Pricing per the fal-ai GPT Image 1 docs, adapted for our artcraft billing:
+  //
+  //   Output image cost (per output image):
+  //     Low    – $0.011 (1024×1024) / $0.016 (other)  →  2¢ / 2¢
+  //     Medium – $0.042 (1024×1024) / $0.063 (other)  →  5¢ / 7¢
+  //     High   – $0.167 (1024×1024) / $0.250 (other)  → 17¢ / 25¢
+  //
+  //   Input image cost (edit mode only, per input image, high-fidelity assumed):
+  //     3,050 tokens × $0.005/1K tokens ≈ $0.01525 → 2¢ per input image
+  //
+  //   Input text tokens: free (we don't charge for these).
+  //
+  let is_square = matches!(
+    plan.image_size,
+    None | Some(ArtcraftGptImage1Size::Square)
+  );
+
+  let output_cost_per_image: u64 = match (plan.quality, is_square) {
+    (ArtcraftGptImage1Quality::Auto, _) => 17, // Auto treated as High square
+    (ArtcraftGptImage1Quality::Low, true) => 2,
+    (ArtcraftGptImage1Quality::Low, false) => 2,
+    (ArtcraftGptImage1Quality::Medium, true) => 5,
+    (ArtcraftGptImage1Quality::Medium, false) => 7,
+    (ArtcraftGptImage1Quality::High, true) => 17,
+    (ArtcraftGptImage1Quality::High, false) => 25,
+  };
+
+  let num_output_images = plan.num_images.as_u64();
+  let output_cost = output_cost_per_image * num_output_images;
+
+  // Input image token cost: 2¢ per input image (high-fidelity estimate).
+  let input_image_cost: u64 = 2 * plan.num_input_images;
+
+  let cost_in_usd_cents = output_cost + input_image_cost;
+
+  ImageGenerationCostEstimate {
+    cost_in_credits: Some(cost_in_usd_cents),
+    cost_in_usd_cents: Some(cost_in_usd_cents),
+    is_free: false,
+    is_unlimited: false,
+    is_rate_limited: false,
+    has_watermark: false,
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use crate::api::common_aspect_ratio::CommonAspectRatio;
+  use crate::api::common_image_model::CommonImageModel;
+  use crate::api::common_quality::CommonQuality;
+  use crate::api::image_list_ref::ImageListRef;
+  use crate::api::provider::Provider;
+  use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use tokens::tokens::media_files::MediaFileToken;
+
+  fn base() -> GenerateImageRequest {
+    GenerateImageRequest {
+      model: CommonImageModel::GptImage1,
+      provider: Provider::Artcraft,
+      prompt: None,
+      image_inputs: None,
+      resolution: None,
+      aspect_ratio: None,
+      quality: None,
+      image_batch_count: Some(1),
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+    }
+  }
+
+  fn estimate_text(
+    quality: Option<CommonQuality>,
+    aspect_ratio: Option<CommonAspectRatio>,
+    batch: u16,
+  ) -> u64 {
+    let request = GenerateImageRequest {
+      quality,
+      aspect_ratio,
+      image_batch_count: Some(batch),
+      ..base()
+    };
+    request.build().unwrap().estimate_costs()
+      .cost_in_usd_cents.unwrap()
+  }
+
+  fn estimate_edit(
+    quality: Option<CommonQuality>,
+    aspect_ratio: Option<CommonAspectRatio>,
+    batch: u16,
+    num_input_images: usize,
+  ) -> u64 {
+    let tokens: Vec<MediaFileToken> = (0..num_input_images)
+      .map(|i| MediaFileToken::new_from_str(&format!("mf_test{:028}", i)))
+      .collect();
+    let request = GenerateImageRequest {
+      quality,
+      aspect_ratio,
+      image_batch_count: Some(batch),
+      image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
+      ..base()
+    };
+    request.build().unwrap().estimate_costs()
+      .cost_in_usd_cents.unwrap()
+  }
+
+  // ── Default quality (None → High) ───────────────────────────────────────
+
+  #[test]
+  fn default_quality_square_one_image_costs_17_cents() {
+    assert_eq!(estimate_text(None, None, 1), 17);
+  }
+
+  #[test]
+  fn default_quality_square_four_images_costs_68_cents() {
+    assert_eq!(estimate_text(None, None, 4), 68);
+  }
+
+  // ── Low quality (2¢/image regardless of size) ───────────────────────────
+
+  #[test]
+  fn low_square_one_image() {
+    assert_eq!(estimate_text(Some(CommonQuality::Low), Some(CommonAspectRatio::Square), 1), 2);
+  }
+
+  #[test]
+  fn low_wide_one_image() {
+    assert_eq!(estimate_text(Some(CommonQuality::Low), Some(CommonAspectRatio::WideSixteenByNine), 1), 2);
+  }
+
+  #[test]
+  fn low_tall_one_image() {
+    assert_eq!(estimate_text(Some(CommonQuality::Low), Some(CommonAspectRatio::TallNineBySixteen), 1), 2);
+  }
+
+  #[test]
+  fn low_four_images() {
+    assert_eq!(estimate_text(Some(CommonQuality::Low), None, 4), 8);
+  }
+
+  // ── Medium quality (5¢ square, 7¢ wide/tall) ───────────────────────────
+
+  #[test]
+  fn medium_square_one_image() {
+    assert_eq!(estimate_text(Some(CommonQuality::Medium), Some(CommonAspectRatio::Square), 1), 5);
+  }
+
+  #[test]
+  fn medium_wide_one_image() {
+    assert_eq!(estimate_text(Some(CommonQuality::Medium), Some(CommonAspectRatio::WideSixteenByNine), 1), 7);
+  }
+
+  #[test]
+  fn medium_tall_one_image() {
+    assert_eq!(estimate_text(Some(CommonQuality::Medium), Some(CommonAspectRatio::TallNineBySixteen), 1), 7);
+  }
+
+  #[test]
+  fn medium_square_four_images() {
+    assert_eq!(estimate_text(Some(CommonQuality::Medium), Some(CommonAspectRatio::Square), 4), 20);
+  }
+
+  #[test]
+  fn medium_wide_four_images() {
+    assert_eq!(estimate_text(Some(CommonQuality::Medium), Some(CommonAspectRatio::WideSixteenByNine), 4), 28);
+  }
+
+  // ── High quality (17¢ square, 25¢ wide/tall) ───────────────────────────
+
+  #[test]
+  fn high_square_one_image() {
+    assert_eq!(estimate_text(Some(CommonQuality::High), Some(CommonAspectRatio::Square), 1), 17);
+  }
+
+  #[test]
+  fn high_wide_one_image() {
+    assert_eq!(estimate_text(Some(CommonQuality::High), Some(CommonAspectRatio::WideSixteenByNine), 1), 25);
+  }
+
+  #[test]
+  fn high_tall_one_image() {
+    assert_eq!(estimate_text(Some(CommonQuality::High), Some(CommonAspectRatio::TallNineBySixteen), 1), 25);
+  }
+
+  #[test]
+  fn high_square_four_images() {
+    assert_eq!(estimate_text(Some(CommonQuality::High), Some(CommonAspectRatio::Square), 4), 68);
+  }
+
+  #[test]
+  fn high_wide_four_images() {
+    assert_eq!(estimate_text(Some(CommonQuality::High), Some(CommonAspectRatio::WideSixteenByNine), 4), 100);
+  }
+
+  // ── Edit mode: adds 2¢ per input image ─────────────────────────────────
+
+  #[test]
+  fn edit_one_input_adds_2_cents() {
+    // High square 1 output = 17¢, plus 1 input × 2¢ = 19¢
+    assert_eq!(estimate_edit(Some(CommonQuality::High), Some(CommonAspectRatio::Square), 1, 1), 19);
+  }
+
+  #[test]
+  fn edit_three_inputs_adds_6_cents() {
+    // High square 1 output = 17¢, plus 3 inputs × 2¢ = 23¢
+    assert_eq!(estimate_edit(Some(CommonQuality::High), Some(CommonAspectRatio::Square), 1, 3), 23);
+  }
+
+  #[test]
+  fn edit_five_inputs_adds_10_cents() {
+    // Medium wide 2 outputs = 7×2 = 14¢, plus 5 inputs × 2¢ = 24¢
+    assert_eq!(estimate_edit(Some(CommonQuality::Medium), Some(CommonAspectRatio::WideSixteenByNine), 2, 5), 24);
+  }
+
+  #[test]
+  fn edit_low_quality_with_inputs() {
+    // Low square 1 output = 2¢, plus 2 inputs × 2¢ = 6¢
+    assert_eq!(estimate_edit(Some(CommonQuality::Low), None, 1, 2), 6);
+  }
+
+  // ── Text mode (no input images) has no input cost ──────────────────────
+
+  #[test]
+  fn text_mode_no_input_cost() {
+    assert_eq!(estimate_text(Some(CommonQuality::High), Some(CommonAspectRatio::Square), 1), 17);
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_gpt_image_1p5.rs

@@ -7,44 +7,35 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_gpt_image_1p5::PlanArtcraftGptImage1p5;
 
 pub(crate) fn estimate_image_cost_artcraft_gpt_image_1p5(
-  plan: &PlanArtcraftGptImage1p5<'_>,
+  plan: &PlanArtcraftGptImage1p5,
 ) -> ImageGenerationCostEstimate {
-  // Pricing varies by quality and image size. 1 credit = 1 USD cent.
-  // Low:    $0.01/image (any size)
-  // Medium: $0.03/image (square/unset), $0.05/image (wide or tall)
-  // High:   $0.13/image (square/unset), $0.20/image (wide or tall)
+  // Per fal docs (fal-ai/gpt-image-1.5 and fal-ai/gpt-image-1.5/edit):
   //
-  // From Fal (text to image) -
+  //   Output image cost (per output image), rounded up to whole cents:
+  //     Low:    $0.009 (1024×1024) / $0.013 (other)  →  1¢ / 2¢
+  //     Medium: $0.034 (1024×1024) / $0.050 (1536×1024) / $0.051 (1024×1536)  →  4¢ / 5¢ / 6¢
+  //     High:   $0.133 (1024×1024) / $0.199 (1536×1024) / $0.200 (1024×1536)  → 14¢ / 20¢ / 20¢
   //
-  // Your request will cost different amounts based on the number of images, quality, and size.
+  //   Input text tokens: free (we don't charge for these).
   //
-  //     You will be charged $0.005 per 1,000 input text tokens. One word is roughly 4 tokens.
-  //     You will be charged $0.010 per 1,000 output text tokens. The model will consume tokens reasoning about your prompt based on it's complexity.
-  //     For low quality, you will be charged $0.009 for 1024x1024 or $0.013 for any other size per image.
-  //     For medium quality, you will be charged $0.034 for 1024x1024, $0.051 for 1024x1536 and $0.050 for 1536x1024 per image.
-  //     For high quality, you will be charged $0.133 for 1024x1024, $0.200 for 1024x1536 or $0.199 for 1536x1024 per image.
+  //   Default quality: High (when request.quality is None).
   //
-  // From Fal (image to image) -
-  //
-  // Your request will cost different amounts based on the number of images, quality, and size.
-  //
-  //     You will be charged $0.005 per 1,000 input text tokens. One word is roughly 4 tokens.
-  //     You will be charged $0.008 per 1,000 input image tokens. One 1024x1024 image is roughly 135 tokens in low fidelity mode, or 3,050 tokens in high fidelity mode.
-  //     You will be charged $0.010 per 1,000 output text tokens. The model will consume tokens reasoning about your prompt based on it's complexity.
-  //     For low quality, you will be charged $0.009 for 1024x1024 or $0.013 for any other size per image.
-  //     For medium quality, you will be charged $0.034 for 1024x1024, $0.051 for 1024x1536 and $0.050 for 1536x1024 per image.
-  //     For high quality, you will be charged $0.133 for 1024x1024, $0.200 for 1024x1536 or $0.199 for 1536x1024 per image.
-  //
-  let cost_per_image: u64 = match plan.quality {
-    GptImage1p5MultiFunctionImageGenQuality::Low => 1,
-    GptImage1p5MultiFunctionImageGenQuality::Medium => match plan.image_size {
-      Some(GptImage1p5MultiFunctionImageGenSize::Square) | None => 3,
-      Some(GptImage1p5MultiFunctionImageGenSize::Wide) | Some(GptImage1p5MultiFunctionImageGenSize::Tall) => 5,
-    },
-    GptImage1p5MultiFunctionImageGenQuality::High => match plan.image_size {
-      Some(GptImage1p5MultiFunctionImageGenSize::Square) | None => 13,
-      Some(GptImage1p5MultiFunctionImageGenSize::Wide) | Some(GptImage1p5MultiFunctionImageGenSize::Tall) => 20,
-    },
+  use GptImage1p5MultiFunctionImageGenQuality as Q;
+  use GptImage1p5MultiFunctionImageGenSize as S;
+
+  let cost_per_image: u64 = match (plan.quality, plan.image_size) {
+    // Low quality
+    (Q::Low, None | Some(S::Square)) => 1,
+    (Q::Low, Some(S::Wide) | Some(S::Tall)) => 2,
+
+    // Medium quality
+    (Q::Medium, None | Some(S::Square)) => 4,
+    (Q::Medium, Some(S::Wide)) => 5,
+    (Q::Medium, Some(S::Tall)) => 6,
+
+    // High quality
+    (Q::High, None | Some(S::Square)) => 14,
+    (Q::High, Some(S::Wide) | Some(S::Tall)) => 20,
   };
 
   let num_images: u64 = match plan.num_images {
@@ -70,11 +61,16 @@ pub(crate) fn estimate_image_cost_artcraft_gpt_image_1p5(
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::common_image_model::CommonImageModel;
+  use crate::api::common_quality::CommonQuality;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
   use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
 
-  fn estimate_usd_cents(image_batch_count: u16, aspect_ratio: Option<CommonAspectRatio>) -> u64 {
+  fn estimate(
+    quality: Option<CommonQuality>,
+    aspect_ratio: Option<CommonAspectRatio>,
+    batch: u16,
+  ) -> u64 {
     let request = GenerateImageRequest {
       model: CommonImageModel::GptImage1p5,
       provider: Provider::Artcraft,
@@ -82,7 +78,8 @@ mod tests {
       image_inputs: None,
       resolution: None,
       aspect_ratio,
-      image_batch_count: Some(image_batch_count),
+      quality,
+      image_batch_count: Some(batch),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,
       idempotency_token: None,
@@ -90,34 +87,140 @@ mod tests {
       vertical_angle: None,
       zoom: None,
     };
-    request.build()
-      .expect("build should succeed")
-      .estimate_costs()
-      .cost_in_usd_cents
-      .expect("cost_in_usd_cents should be present")
+    request.build().unwrap().estimate_costs()
+      .cost_in_usd_cents.unwrap()
+  }
+
+  // ── Default quality (None → High) ─────────────────────────────────────
+
+  #[test]
+  fn default_quality_square_one_image() {
+    assert_eq!(estimate(None, Some(CommonAspectRatio::Square), 1), 14);
   }
 
   #[test]
-  fn test_estimate_cost_medium_square() {
-    // Default quality (Medium) + square/unset size = 3 cents each
-    assert_eq!(estimate_usd_cents(1, None), 3);
-    assert_eq!(estimate_usd_cents(1, Some(CommonAspectRatio::Square)), 3);
-    assert_eq!(estimate_usd_cents(2, Some(CommonAspectRatio::Square)), 6);
-    assert_eq!(estimate_usd_cents(3, Some(CommonAspectRatio::Square)), 9);
-    assert_eq!(estimate_usd_cents(4, Some(CommonAspectRatio::Square)), 12);
+  fn default_quality_unset_one_image() {
+    assert_eq!(estimate(None, None, 1), 14);
   }
 
   #[test]
-  fn test_estimate_cost_medium_wide() {
-    // Medium + wide = 5 cents each
-    assert_eq!(estimate_usd_cents(1, Some(CommonAspectRatio::WideSixteenByNine)), 5);
-    assert_eq!(estimate_usd_cents(4, Some(CommonAspectRatio::WideSixteenByNine)), 20);
+  fn default_quality_wide_one_image() {
+    assert_eq!(estimate(None, Some(CommonAspectRatio::WideSixteenByNine), 1), 20);
   }
 
   #[test]
-  fn test_estimate_cost_medium_tall() {
-    // Medium + tall = 5 cents each
-    assert_eq!(estimate_usd_cents(1, Some(CommonAspectRatio::TallNineBySixteen)), 5);
-    assert_eq!(estimate_usd_cents(4, Some(CommonAspectRatio::TallNineBySixteen)), 20);
+  fn default_quality_tall_one_image() {
+    assert_eq!(estimate(None, Some(CommonAspectRatio::TallNineBySixteen), 1), 20);
+  }
+
+  #[test]
+  fn default_quality_square_four_images() {
+    assert_eq!(estimate(None, Some(CommonAspectRatio::Square), 4), 56);
+  }
+
+  // ── Low quality (1¢ square, 2¢ wide/tall) ─────────────────────────────
+
+  #[test]
+  fn low_square_one() {
+    assert_eq!(estimate(Some(CommonQuality::Low), Some(CommonAspectRatio::Square), 1), 1);
+  }
+
+  #[test]
+  fn low_unset_one() {
+    assert_eq!(estimate(Some(CommonQuality::Low), None, 1), 1);
+  }
+
+  #[test]
+  fn low_wide_one() {
+    assert_eq!(estimate(Some(CommonQuality::Low), Some(CommonAspectRatio::WideSixteenByNine), 1), 2);
+  }
+
+  #[test]
+  fn low_tall_one() {
+    assert_eq!(estimate(Some(CommonQuality::Low), Some(CommonAspectRatio::TallNineBySixteen), 1), 2);
+  }
+
+  #[test]
+  fn low_square_four() {
+    assert_eq!(estimate(Some(CommonQuality::Low), None, 4), 4);
+  }
+
+  #[test]
+  fn low_wide_four() {
+    assert_eq!(estimate(Some(CommonQuality::Low), Some(CommonAspectRatio::WideSixteenByNine), 4), 8);
+  }
+
+  // ── Medium quality (4¢ square, 5¢ wide, 6¢ tall) ─────────────────────
+
+  #[test]
+  fn medium_square_one() {
+    assert_eq!(estimate(Some(CommonQuality::Medium), Some(CommonAspectRatio::Square), 1), 4);
+  }
+
+  #[test]
+  fn medium_unset_one() {
+    assert_eq!(estimate(Some(CommonQuality::Medium), None, 1), 4);
+  }
+
+  #[test]
+  fn medium_wide_one() {
+    assert_eq!(estimate(Some(CommonQuality::Medium), Some(CommonAspectRatio::WideSixteenByNine), 1), 5);
+  }
+
+  #[test]
+  fn medium_tall_one() {
+    assert_eq!(estimate(Some(CommonQuality::Medium), Some(CommonAspectRatio::TallNineBySixteen), 1), 6);
+  }
+
+  #[test]
+  fn medium_square_four() {
+    assert_eq!(estimate(Some(CommonQuality::Medium), Some(CommonAspectRatio::Square), 4), 16);
+  }
+
+  #[test]
+  fn medium_wide_four() {
+    assert_eq!(estimate(Some(CommonQuality::Medium), Some(CommonAspectRatio::WideSixteenByNine), 4), 20);
+  }
+
+  #[test]
+  fn medium_tall_four() {
+    assert_eq!(estimate(Some(CommonQuality::Medium), Some(CommonAspectRatio::TallNineBySixteen), 4), 24);
+  }
+
+  // ── High quality (14¢ square, 20¢ wide/tall) ─────────────────────────
+
+  #[test]
+  fn high_square_one() {
+    assert_eq!(estimate(Some(CommonQuality::High), Some(CommonAspectRatio::Square), 1), 14);
+  }
+
+  #[test]
+  fn high_unset_one() {
+    assert_eq!(estimate(Some(CommonQuality::High), None, 1), 14);
+  }
+
+  #[test]
+  fn high_wide_one() {
+    assert_eq!(estimate(Some(CommonQuality::High), Some(CommonAspectRatio::WideSixteenByNine), 1), 20);
+  }
+
+  #[test]
+  fn high_tall_one() {
+    assert_eq!(estimate(Some(CommonQuality::High), Some(CommonAspectRatio::TallNineBySixteen), 1), 20);
+  }
+
+  #[test]
+  fn high_square_four() {
+    assert_eq!(estimate(Some(CommonQuality::High), Some(CommonAspectRatio::Square), 4), 56);
+  }
+
+  #[test]
+  fn high_wide_four() {
+    assert_eq!(estimate(Some(CommonQuality::High), Some(CommonAspectRatio::WideSixteenByNine), 4), 80);
+  }
+
+  #[test]
+  fn high_tall_four() {
+    assert_eq!(estimate(Some(CommonQuality::High), Some(CommonAspectRatio::TallNineBySixteen), 4), 80);
   }
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_gpt_image_2.rs

@@ -0,0 +1,210 @@
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_gpt_image_2::{
+  ArtcraftGptImage2ImageSize, ArtcraftGptImage2Quality, PlanArtcraftGptImage2,
+};
+
+pub(crate) fn estimate_image_cost_artcraft_gpt_image_2(
+  plan: &PlanArtcraftGptImage2,
+) -> ImageGenerationCostEstimate {
+  // Same cost table as the Fal GPT Image 2 estimator.
+  //
+  //   Output image cost (per output image), rounded up to whole cents:
+  //     Low:    all sizes                        →  1¢
+  //     Medium: landscape_4_3/portrait_4_3       →  4¢
+  //             landscape_16_9/portrait_16_9     →  4¢
+  //             square                           →  6¢
+  //             square_hd                        →  6¢
+  //     High:   landscape_4_3/portrait_4_3       → 15¢
+  //             landscape_16_9/portrait_16_9     → 16¢
+  //             square                           → 22¢
+  //             square_hd                        → 23¢
+  //
+  use ArtcraftGptImage2ImageSize as S;
+
+  let cost_per_image: u64 = match (plan.quality, plan.image_size) {
+    // Low quality
+    (ArtcraftGptImage2Quality::Low, _) => 1,
+
+    // Medium quality
+    (ArtcraftGptImage2Quality::Medium, None | Some(S::Square) | Some(S::SquareHd)) => 6,
+    (ArtcraftGptImage2Quality::Medium, Some(S::Landscape4x3) | Some(S::Portrait4x3)) => 4,
+    (ArtcraftGptImage2Quality::Medium, Some(S::Landscape16x9) | Some(S::Portrait16x9)) => 4,
+    (ArtcraftGptImage2Quality::Medium, Some(S::Auto)) => 6,
+
+    // High quality
+    (ArtcraftGptImage2Quality::High, None | Some(S::Square)) => 22,
+    (ArtcraftGptImage2Quality::High, Some(S::SquareHd)) => 23,
+    (ArtcraftGptImage2Quality::High, Some(S::Landscape4x3) | Some(S::Portrait4x3)) => 15,
+    (ArtcraftGptImage2Quality::High, Some(S::Landscape16x9) | Some(S::Portrait16x9)) => 16,
+    (ArtcraftGptImage2Quality::High, Some(S::Auto)) => 23,
+  };
+  let cost_in_usd_cents = cost_per_image * plan.num_images.as_u64();
+
+  ImageGenerationCostEstimate {
+    cost_in_credits: Some(cost_in_usd_cents),
+    cost_in_usd_cents: Some(cost_in_usd_cents),
+    is_free: false,
+    is_unlimited: false,
+    is_rate_limited: false,
+    has_watermark: false,
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_gpt_image_2::ArtcraftGptImage2NumImages;
+
+  fn plan(
+    quality: ArtcraftGptImage2Quality,
+    image_size: Option<ArtcraftGptImage2ImageSize>,
+    num_images: ArtcraftGptImage2NumImages,
+  ) -> PlanArtcraftGptImage2 {
+    PlanArtcraftGptImage2 {
+      prompt: Some("p".to_string()),
+      image_inputs: None,
+      image_size,
+      quality,
+      num_images,
+      idempotency_token: "test".to_string(),
+    }
+  }
+
+  fn cents(
+    quality: ArtcraftGptImage2Quality,
+    image_size: Option<ArtcraftGptImage2ImageSize>,
+    num_images: ArtcraftGptImage2NumImages,
+  ) -> u64 {
+    estimate_image_cost_artcraft_gpt_image_2(&plan(quality, image_size, num_images))
+      .cost_in_usd_cents.unwrap()
+  }
+
+  // -- Low quality (1c for all sizes) -------------------------------------------
+
+  #[test]
+  fn low_square() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Low, Some(ArtcraftGptImage2ImageSize::Square), ArtcraftGptImage2NumImages::One), 1);
+  }
+
+  #[test]
+  fn low_square_hd() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Low, Some(ArtcraftGptImage2ImageSize::SquareHd), ArtcraftGptImage2NumImages::One), 1);
+  }
+
+  #[test]
+  fn low_unset() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Low, None, ArtcraftGptImage2NumImages::One), 1);
+  }
+
+  #[test]
+  fn low_landscape_4x3() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Low, Some(ArtcraftGptImage2ImageSize::Landscape4x3), ArtcraftGptImage2NumImages::One), 1);
+  }
+
+  #[test]
+  fn low_four() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Low, None, ArtcraftGptImage2NumImages::Four), 4);
+  }
+
+  // -- Medium quality -----------------------------------------------------------
+
+  #[test]
+  fn medium_square() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Medium, Some(ArtcraftGptImage2ImageSize::Square), ArtcraftGptImage2NumImages::One), 6);
+  }
+
+  #[test]
+  fn medium_square_hd() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Medium, Some(ArtcraftGptImage2ImageSize::SquareHd), ArtcraftGptImage2NumImages::One), 6);
+  }
+
+  #[test]
+  fn medium_unset() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Medium, None, ArtcraftGptImage2NumImages::One), 6);
+  }
+
+  #[test]
+  fn medium_landscape_4x3() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Medium, Some(ArtcraftGptImage2ImageSize::Landscape4x3), ArtcraftGptImage2NumImages::One), 4);
+  }
+
+  #[test]
+  fn medium_portrait_4x3() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Medium, Some(ArtcraftGptImage2ImageSize::Portrait4x3), ArtcraftGptImage2NumImages::One), 4);
+  }
+
+  #[test]
+  fn medium_landscape_16x9() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Medium, Some(ArtcraftGptImage2ImageSize::Landscape16x9), ArtcraftGptImage2NumImages::One), 4);
+  }
+
+  #[test]
+  fn medium_portrait_16x9() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Medium, Some(ArtcraftGptImage2ImageSize::Portrait16x9), ArtcraftGptImage2NumImages::One), 4);
+  }
+
+  #[test]
+  fn medium_square_four() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::Medium, Some(ArtcraftGptImage2ImageSize::Square), ArtcraftGptImage2NumImages::Four), 24);
+  }
+
+  // -- High quality -------------------------------------------------------------
+
+  #[test]
+  fn high_square() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::High, Some(ArtcraftGptImage2ImageSize::Square), ArtcraftGptImage2NumImages::One), 22);
+  }
+
+  #[test]
+  fn high_square_hd() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::High, Some(ArtcraftGptImage2ImageSize::SquareHd), ArtcraftGptImage2NumImages::One), 23);
+  }
+
+  #[test]
+  fn high_unset() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::High, None, ArtcraftGptImage2NumImages::One), 22);
+  }
+
+  #[test]
+  fn high_landscape_4x3() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::High, Some(ArtcraftGptImage2ImageSize::Landscape4x3), ArtcraftGptImage2NumImages::One), 15);
+  }
+
+  #[test]
+  fn high_portrait_4x3() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::High, Some(ArtcraftGptImage2ImageSize::Portrait4x3), ArtcraftGptImage2NumImages::One), 15);
+  }
+
+  #[test]
+  fn high_landscape_16x9() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::High, Some(ArtcraftGptImage2ImageSize::Landscape16x9), ArtcraftGptImage2NumImages::One), 16);
+  }
+
+  #[test]
+  fn high_portrait_16x9() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::High, Some(ArtcraftGptImage2ImageSize::Portrait16x9), ArtcraftGptImage2NumImages::One), 16);
+  }
+
+  #[test]
+  fn high_square_four() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::High, Some(ArtcraftGptImage2ImageSize::Square), ArtcraftGptImage2NumImages::Four), 88);
+  }
+
+  #[test]
+  fn high_square_hd_four() {
+    assert_eq!(cents(ArtcraftGptImage2Quality::High, Some(ArtcraftGptImage2ImageSize::SquareHd), ArtcraftGptImage2NumImages::Four), 92);
+  }
+
+  // -- Metadata flags -----------------------------------------------------------
+
+  #[test]
+  fn metadata_flags_are_default() {
+    let estimate = estimate_image_cost_artcraft_gpt_image_2(&plan(
+      ArtcraftGptImage2Quality::Medium, None, ArtcraftGptImage2NumImages::One,
+    ));
+    assert!(!estimate.is_free);
+    assert!(!estimate.is_unlimited);
+    assert!(!estimate.is_rate_limited);
+    assert!(!estimate.has_watermark);
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_nano_banana.rs

@@ -4,7 +4,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_nano_banana::PlanArtcraftNanaBanana;
 
 pub(crate) fn estimate_image_cost_artcraft_nano_banana(
-  plan: &PlanArtcraftNanaBanana<'_>,
+  plan: &PlanArtcraftNanaBanana,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.04/image (4 cents). 1 credit = 1 USD cent.
   let cost_per_image: u64 = 4;
@@ -43,6 +43,7 @@ mod tests {
       image_inputs: None,
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_nano_banana_2.rs

@@ -6,14 +6,19 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_nano_banana_2::PlanArtcraftNanaBanana2;
 
 pub(crate) fn estimate_image_cost_artcraft_nano_banana_2(
-  plan: &PlanArtcraftNanaBanana2<'_>,
+  plan: &PlanArtcraftNanaBanana2,
 ) -> ImageGenerationCostEstimate {
-  // Pricing: $0.08/image at 0.5K, $0.15/image at 1K or 2K, $0.30/image at 4K.
-  // (Stored as USD cents.)
+  // Pricing (USD cents per image), scaled off the 1K base cost of $0.08:
+  //   0.5K → $0.06 (0.75×)
+  //   1K   → $0.08 (1×, default)
+  //   2K   → $0.12 (1.5×)
+  //   4K   → $0.16 (2×)
   let cost_per_image: u64 = match plan.resolution {
-    Some(NanaBanana2MultiFunctionImageGenImageResolution::HalfK) => 8,
-    Some(NanaBanana2MultiFunctionImageGenImageResolution::FourK) => 30,
-    _ => 15, // OneK, TwoK, or None (default 1K)
+    Some(NanaBanana2MultiFunctionImageGenImageResolution::HalfK) => 6,
+    Some(NanaBanana2MultiFunctionImageGenImageResolution::OneK) => 8,
+    Some(NanaBanana2MultiFunctionImageGenImageResolution::TwoK) => 12,
+    Some(NanaBanana2MultiFunctionImageGenImageResolution::FourK) => 16,
+    None => 8, // default 1K
   };
 
   let num_images: u64 = match plan.num_images {
@@ -51,6 +56,7 @@ mod tests {
       image_inputs: None,
       resolution,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,
@@ -66,17 +72,125 @@ mod tests {
       .expect("cost_in_usd_cents should be present")
   }
 
-  #[test]
-  fn test_estimate_cost_usd_cents() {
-    // 1K/2K: $0.15/image = 15 cents
-    assert_eq!(estimate_usd_cents(None, 1), 15);
-    assert_eq!(estimate_usd_cents(Some(CommonResolution::OneK), 1), 15);
-    assert_eq!(estimate_usd_cents(Some(CommonResolution::TwoK), 1), 15);
-    assert_eq!(estimate_usd_cents(Some(CommonResolution::OneK), 2), 30);
-    assert_eq!(estimate_usd_cents(Some(CommonResolution::OneK), 4), 60);
+  // ── Default (None → 1K → 8¢/image) ─────────────────────────────────────────
 
-    // 4K: $0.30/image = 30 cents
-    assert_eq!(estimate_usd_cents(Some(CommonResolution::FourK), 1), 30);
-    assert_eq!(estimate_usd_cents(Some(CommonResolution::FourK), 2), 60);
+  #[test]
+  fn default_resolution_one_image_costs_8_cents() {
+    assert_eq!(estimate_usd_cents(None, 1), 8);
+  }
+
+  #[test]
+  fn default_resolution_two_images_costs_16_cents() {
+    assert_eq!(estimate_usd_cents(None, 2), 16);
+  }
+
+  #[test]
+  fn default_resolution_three_images_costs_24_cents() {
+    assert_eq!(estimate_usd_cents(None, 3), 24);
+  }
+
+  #[test]
+  fn default_resolution_four_images_costs_32_cents() {
+    assert_eq!(estimate_usd_cents(None, 4), 32);
+  }
+
+  // ── 0.5K → 6¢/image (0.75× base) ───────────────────────────────────────────
+
+  #[test]
+  fn half_k_one_image_costs_6_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::HalfK), 1), 6);
+  }
+
+  #[test]
+  fn half_k_two_images_costs_12_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::HalfK), 2), 12);
+  }
+
+  #[test]
+  fn half_k_three_images_costs_18_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::HalfK), 3), 18);
+  }
+
+  #[test]
+  fn half_k_four_images_costs_24_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::HalfK), 4), 24);
+  }
+
+  // ── 1K → 8¢/image (base) ───────────────────────────────────────────────────
+
+  #[test]
+  fn one_k_one_image_costs_8_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::OneK), 1), 8);
+  }
+
+  #[test]
+  fn one_k_two_images_costs_16_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::OneK), 2), 16);
+  }
+
+  #[test]
+  fn one_k_three_images_costs_24_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::OneK), 3), 24);
+  }
+
+  #[test]
+  fn one_k_four_images_costs_32_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::OneK), 4), 32);
+  }
+
+  // ── 2K → 12¢/image (1.5× base) ─────────────────────────────────────────────
+
+  #[test]
+  fn two_k_one_image_costs_12_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::TwoK), 1), 12);
+  }
+
+  #[test]
+  fn two_k_two_images_costs_24_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::TwoK), 2), 24);
+  }
+
+  #[test]
+  fn two_k_three_images_costs_36_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::TwoK), 3), 36);
+  }
+
+  #[test]
+  fn two_k_four_images_costs_48_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::TwoK), 4), 48);
+  }
+
+  // ── 4K → 16¢/image (2× base) ───────────────────────────────────────────────
+
+  #[test]
+  fn four_k_one_image_costs_16_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::FourK), 1), 16);
+  }
+
+  #[test]
+  fn four_k_two_images_costs_32_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::FourK), 2), 32);
+  }
+
+  #[test]
+  fn four_k_three_images_costs_48_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::FourK), 3), 48);
+  }
+
+  #[test]
+  fn four_k_four_images_costs_64_cents() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::FourK), 4), 64);
+  }
+
+  // ── 3K (unsupported) falls back to 2K pricing ──────────────────────────────
+
+  #[test]
+  fn three_k_one_image_falls_back_to_two_k_pricing() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::ThreeK), 1), 12);
+  }
+
+  #[test]
+  fn three_k_four_images_falls_back_to_two_k_pricing() {
+    assert_eq!(estimate_usd_cents(Some(CommonResolution::ThreeK), 4), 48);
   }
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_nano_banana_pro.rs

@@ -6,7 +6,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_nano_banana_pro::PlanArtcraftNanaBananaPro;
 
 pub(crate) fn estimate_image_cost_artcraft_nano_banana_pro(
-  plan: &PlanArtcraftNanaBananaPro<'_>,
+  plan: &PlanArtcraftNanaBananaPro,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.15/image at 1K or 2K resolution, $0.30/image at 4K.
   // (Stored as USD cents.)
@@ -50,6 +50,7 @@ mod tests {
       image_inputs: None,
       resolution,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_qwen_edit_2511_angles.rs

@@ -4,7 +4,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_qwen_edit_2511_angles::PlanArtcraftQwenEdit2511Angles;
 
 pub(crate) fn estimate_image_cost_artcraft_qwen_edit_2511_angles(
-  plan: &PlanArtcraftQwenEdit2511Angles<'_>,
+  plan: &PlanArtcraftQwenEdit2511Angles,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.04/image (4 cents). 1 credit = 1 USD cent.
   let cost_per_image: u64 = 4;
@@ -43,9 +43,10 @@ mod tests {
       model: CommonImageModel::QwenEdit2511Angles,
       provider: Provider::Artcraft,
       prompt: None,
-      image_inputs: Some(ImageListRef::MediaFileTokens(&tokens)),
+      image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_seedream_4.rs

@@ -4,7 +4,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_seedream_4::PlanArtcraftSeedream4;
 
 pub(crate) fn estimate_image_cost_artcraft_seedream_4(
-  plan: &PlanArtcraftSeedream4<'_>,
+  plan: &PlanArtcraftSeedream4,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.03/image (3 cents). 1 credit = 1 USD cent.
   let cost_per_image: u64 = 3;
@@ -43,6 +43,7 @@ mod tests {
       image_inputs: None,
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_seedream_4p5.rs

@@ -4,7 +4,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_seedream_4p5::PlanArtcraftSeedream4p5;
 
 pub(crate) fn estimate_image_cost_artcraft_seedream_4p5(
-  plan: &PlanArtcraftSeedream4p5<'_>,
+  plan: &PlanArtcraftSeedream4p5,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.04/image (4 cents). 1 credit = 1 USD cent.
   let cost_per_image: u64 = 4;
@@ -43,6 +43,7 @@ mod tests {
       image_inputs: None,
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/estimate_image_cost_artcraft_seedream_5_lite.rs

@@ -4,7 +4,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_seedream_5_lite::PlanArtcraftSeedream5Lite;
 
 pub(crate) fn estimate_image_cost_artcraft_seedream_5_lite(
-  plan: &PlanArtcraftSeedream5Lite<'_>,
+  plan: &PlanArtcraftSeedream5Lite,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.04/image (4 cents). 1 credit = 1 USD cent.
   let cost_per_image: u64 = 4;
@@ -43,6 +43,7 @@ mod tests {
       image_inputs: None,
       resolution: None,
       aspect_ratio: None,
+      quality: None,
       image_batch_count: Some(image_batch_count),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       generation_mode_mismatch_strategy: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/artcraft/mod.rs

@@ -2,7 +2,9 @@ pub mod estimate_image_cost_artcraft_flux_1_dev;
 pub mod estimate_image_cost_artcraft_flux_1_schnell;
 pub mod estimate_image_cost_artcraft_flux_pro_1p1;
 pub mod estimate_image_cost_artcraft_flux_pro_1p1_ultra;
+pub mod estimate_image_cost_artcraft_gpt_image_1;
 pub mod estimate_image_cost_artcraft_gpt_image_1p5;
+pub mod estimate_image_cost_artcraft_gpt_image_2;
 pub mod estimate_image_cost_artcraft_nano_banana;
 pub mod estimate_image_cost_artcraft_nano_banana_2;
 pub mod estimate_image_cost_artcraft_nano_banana_pro;

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/fal/estimate_image_cost_fal_flux_1_dev.rs

@@ -2,7 +2,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::fal::plan_generate_image_fal_flux_1_dev::PlanFalFlux1Dev;
 
 pub(crate) fn estimate_image_cost_fal_flux_1_dev(
-  plan: &PlanFalFlux1Dev<'_>,
+  plan: &PlanFalFlux1Dev,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.025 per megapixel, billed by rounding up to nearest megapixel.
   // Default image sizes are ~1MP (1024x1024), so ~$0.025/image = 3 cents rounded up.

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/fal/estimate_image_cost_fal_flux_1_schnell.rs

@@ -2,7 +2,7 @@ use crate::generate::generate_image::image_generation_cost_estimate::ImageGenera
 use crate::generate::generate_image::plan::fal::plan_generate_image_fal_flux_1_schnell::PlanFalFlux1Schnell;
 
 pub(crate) fn estimate_image_cost_fal_flux_1_schnell(
-  plan: &PlanFalFlux1Schnell<'_>,
+  plan: &PlanFalFlux1Schnell,
 ) -> ImageGenerationCostEstimate {
   // Pricing: $0.003 per megapixel, billed by rounding up to nearest megapixel.
   // Default image sizes are ~1MP (1024x1024), so ~$0.003/image = 1 cent rounded up.

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/fal/estimate_image_cost_fal_flux_pro_1p1.rs

@@ -0,0 +1,21 @@
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+use crate::generate::generate_image::plan::fal::plan_generate_image_fal_flux_pro_1p1::PlanFalFluxPro11;
+
+pub(crate) fn estimate_image_cost_fal_flux_pro_1p1(
+  plan: &PlanFalFluxPro11,
+) -> ImageGenerationCostEstimate {
+  // Pricing: $0.04 per megapixel, billed by rounding up to nearest megapixel.
+  // Default image sizes are ~1MP (1024x1024), so ~$0.04/image = 4 cents.
+  let cost_per_image: u64 = 4;
+  let num_images = plan.num_images.as_u64();
+  let cost_in_usd_cents = cost_per_image * num_images;
+
+  ImageGenerationCostEstimate {
+    cost_in_credits: Some(cost_in_usd_cents),
+    cost_in_usd_cents: Some(cost_in_usd_cents),
+    is_free: false,
+    is_unlimited: false,
+    is_rate_limited: false,
+    has_watermark: false,
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/fal/estimate_image_cost_fal_flux_pro_1p1_ultra.rs

@@ -0,0 +1,20 @@
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+use crate::generate::generate_image::plan::fal::plan_generate_image_fal_flux_pro_1p1_ultra::PlanFalFluxPro11Ultra;
+
+pub(crate) fn estimate_image_cost_fal_flux_pro_1p1_ultra(
+  plan: &PlanFalFluxPro11Ultra,
+) -> ImageGenerationCostEstimate {
+  // Pricing: $0.06 per image.
+  let cost_per_image: u64 = 6;
+  let num_images = plan.num_images.as_u64();
+  let cost_in_usd_cents = cost_per_image * num_images;
+
+  ImageGenerationCostEstimate {
+    cost_in_credits: Some(cost_in_usd_cents),
+    cost_in_usd_cents: Some(cost_in_usd_cents),
+    is_free: false,
+    is_unlimited: false,
+    is_rate_limited: false,
+    has_watermark: false,
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/cost/fal/estimate_image_cost_fal_gpt_image_1.rs

@@ -0,0 +1,245 @@
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+use crate::generate::generate_image::plan::fal::plan_generate_image_fal_gpt_image_1::{
+  FalGptImage1ImageSize, FalGptImage1Quality, PlanFalGptImage1,
+};
+
+pub(crate) fn estimate_image_cost_fal_gpt_image_1(
+  plan: &PlanFalGptImage1,
+) -> ImageGenerationCostEstimate {
+  // Per fal docs (fal-ai/gpt-image-1/{text-to-image,edit-image}):
+  //
+  //   Output image cost (per output image):
+  //     Low:    $0.011 (1024×1024) / $0.016 (other) →  2¢ / 2¢
+  //     Medium: $0.042 (1024×1024) / $0.063 (other) →  5¢ / 7¢
+  //     High:   $0.167 (1024×1024) / $0.250 (other) → 17¢ / 25¢
+  //
+  //   Input image tokens (edit mode, per input image, high-fidelity assumed):
+  //     3,050 tokens × $0.005/1K tokens ≈ $0.01525 → 2¢ per input image
+  //
+  //   Input text tokens: free (we don't charge for these).
+  //
+  let is_square = matches!(plan.image_size, None | Some(FalGptImage1ImageSize::Square));
+  let output_cost_per_image: u64 = match (plan.quality, is_square) {
+    (FalGptImage1Quality::Low, true) => 2,
+    (FalGptImage1Quality::Low, false) => 2,
+    (FalGptImage1Quality::Medium, true) => 5,
+    (FalGptImage1Quality::Medium, false) => 7,
+    (FalGptImage1Quality::High, true) => 17,
+    (FalGptImage1Quality::High, false) => 25,
+  };
+
+  let num_output_images = plan.num_images.as_u64();
+  let output_cost = output_cost_per_image * num_output_images;
+
+  // Input image token cost: 2¢ per input image (high-fidelity estimate).
+  let input_image_cost: u64 = if plan.image_urls.is_empty() {
+    0
+  } else {
+    2 * plan.image_urls.len() as u64
+  };
+
+  let cost_in_usd_cents = output_cost + input_image_cost;
+
+  ImageGenerationCostEstimate {
+    cost_in_credits: Some(cost_in_usd_cents),
+    cost_in_usd_cents: Some(cost_in_usd_cents),
+    is_free: false,
+    is_unlimited: false,
+    is_rate_limited: false,
+    has_watermark: false,
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use crate::generate::generate_image::plan::fal::plan_generate_image_fal_gpt_image_1::FalGptImage1NumImages;
+
+  fn text_plan(
+    quality: FalGptImage1Quality,
+    image_size: Option<FalGptImage1ImageSize>,
+    num_images: FalGptImage1NumImages,
+  ) -> PlanFalGptImage1 {
+    PlanFalGptImage1 {
+      prompt: Some("p".to_string()),
+      image_urls: vec![],
+      image_size,
+      quality,
+      num_images,
+    }
+  }
+
+  fn edit_plan(
+    quality: FalGptImage1Quality,
+    image_size: Option<FalGptImage1ImageSize>,
+    num_images: FalGptImage1NumImages,
+    num_input_images: usize,
+  ) -> PlanFalGptImage1 {
+    let image_urls = (0..num_input_images)
+      .map(|i| format!("https://fake.example.com/img{}.png", i))
+      .collect();
+    PlanFalGptImage1 {
+      prompt: Some("p".to_string()),
+      image_urls,
+      image_size,
+      quality,
+      num_images,
+    }
+  }
+
+  fn cents_text(
+    quality: FalGptImage1Quality,
+    image_size: Option<FalGptImage1ImageSize>,
+    num_images: FalGptImage1NumImages,
+  ) -> u64 {
+    estimate_image_cost_fal_gpt_image_1(&text_plan(quality, image_size, num_images))
+      .cost_in_usd_cents
+      .unwrap()
+  }
+
+  fn cents_edit(
+    quality: FalGptImage1Quality,
+    image_size: Option<FalGptImage1ImageSize>,
+    num_images: FalGptImage1NumImages,
+    num_input_images: usize,
+  ) -> u64 {
+    estimate_image_cost_fal_gpt_image_1(&edit_plan(quality, image_size, num_images, num_input_images))
+      .cost_in_usd_cents
+      .unwrap()
+  }
+
+  // ── Low quality text-to-image (2¢/image, both sizes) ──────────────────
+
+  #[test]
+  fn low_square_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::Low, Some(FalGptImage1ImageSize::Square), FalGptImage1NumImages::One), 2);
+  }
+
+  #[test]
+  fn low_horizontal_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::Low, Some(FalGptImage1ImageSize::Horizontal), FalGptImage1NumImages::One), 2);
+  }
+
+  #[test]
+  fn low_vertical_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::Low, Some(FalGptImage1ImageSize::Vertical), FalGptImage1NumImages::One), 2);
+  }
+
+  #[test]
+  fn low_unset_size_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::Low, None, FalGptImage1NumImages::One), 2);
+  }
+
+  #[test]
+  fn low_four_images() {
+    assert_eq!(cents_text(FalGptImage1Quality::Low, None, FalGptImage1NumImages::Four), 8);
+  }
+
+  // ── Medium quality text-to-image (5¢ square, 7¢ wide/tall) ────────────
+
+  #[test]
+  fn medium_square_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::Medium, Some(FalGptImage1ImageSize::Square), FalGptImage1NumImages::One), 5);
+  }
+
+  #[test]
+  fn medium_horizontal_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::Medium, Some(FalGptImage1ImageSize::Horizontal), FalGptImage1NumImages::One), 7);
+  }
+
+  #[test]
+  fn medium_vertical_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::Medium, Some(FalGptImage1ImageSize::Vertical), FalGptImage1NumImages::One), 7);
+  }
+
+  #[test]
+  fn medium_square_four_images() {
+    assert_eq!(cents_text(FalGptImage1Quality::Medium, Some(FalGptImage1ImageSize::Square), FalGptImage1NumImages::Four), 20);
+  }
+
+  #[test]
+  fn medium_horizontal_four_images() {
+    assert_eq!(cents_text(FalGptImage1Quality::Medium, Some(FalGptImage1ImageSize::Horizontal), FalGptImage1NumImages::Four), 28);
+  }
+
+  // ── High quality text-to-image (17¢ square, 25¢ wide/tall) ────────────
+
+  #[test]
+  fn high_square_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::High, Some(FalGptImage1ImageSize::Square), FalGptImage1NumImages::One), 17);
+  }
+
+  #[test]
+  fn high_horizontal_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::High, Some(FalGptImage1ImageSize::Horizontal), FalGptImage1NumImages::One), 25);
+  }
+
+  #[test]
+  fn high_vertical_one_image() {
+    assert_eq!(cents_text(FalGptImage1Quality::High, Some(FalGptImage1ImageSize::Vertical), FalGptImage1NumImages::One), 25);
+  }
+
+  #[test]
+  fn high_square_two_images() {
+    assert_eq!(cents_text(FalGptImage1Quality::High, Some(FalGptImage1ImageSize::Square), FalGptImage1NumImages::Two), 34);
+  }
+
+  #[test]
+  fn high_horizontal_four_images() {
+    assert_eq!(cents_text(FalGptImage1Quality::High, Some(FalGptImage1ImageSize::Horizontal), FalGptImage1NumImages::Four), 100);
+  }
+
+  // ── Edit mode adds 2¢ per input image ─────────────────────────────────
+
+  #[test]
+  fn edit_high_square_one_output_one_input() {
+    // 17¢ output + 2¢ input = 19¢
+    assert_eq!(cents_edit(FalGptImage1Quality::High, Some(FalGptImage1ImageSize::Square), FalGptImage1NumImages::One, 1), 19);
+  }
+
+  #[test]
+  fn edit_high_square_one_output_three_inputs() {
+    // 17¢ output + 3×2¢ input = 23¢
+    assert_eq!(cents_edit(FalGptImage1Quality::High, Some(FalGptImage1ImageSize::Square), FalGptImage1NumImages::One, 3), 23);
+  }
+
+  #[test]
+  fn edit_medium_wide_two_outputs_five_inputs() {
+    // 2×7¢ output + 5×2¢ input = 24¢
+    assert_eq!(cents_edit(FalGptImage1Quality::Medium, Some(FalGptImage1ImageSize::Horizontal), FalGptImage1NumImages::Two, 5), 24);
+  }
+
+  #[test]
+  fn edit_low_square_one_output_two_inputs() {
+    // 2¢ output + 2×2¢ input = 6¢
+    assert_eq!(cents_edit(FalGptImage1Quality::Low, Some(FalGptImage1ImageSize::Square), FalGptImage1NumImages::One, 2), 6);
+  }
+
+  #[test]
+  fn edit_high_vertical_four_outputs_one_input() {
+    // 4×25¢ output + 1×2¢ input = 102¢
+    assert_eq!(cents_edit(FalGptImage1Quality::High, Some(FalGptImage1ImageSize::Vertical), FalGptImage1NumImages::Four, 1), 102);
+  }
+
+  // ── Text mode has no input image cost ─────────────────────────────────
+
+  #[test]
+  fn text_mode_no_input_cost() {
+    assert_eq!(cents_text(FalGptImage1Quality::High, Some(FalGptImage1ImageSize::Square), FalGptImage1NumImages::One), 17);
+  }
+
+  // ── Metadata flags ────────────────────────────────────────────────────
+
+  #[test]
+  fn metadata_flags_are_default() {
+    let estimate = estimate_image_cost_fal_gpt_image_1(&text_plan(
+      FalGptImage1Quality::Medium,
+      None,
+      FalGptImage1NumImages::One,
+    ));
+    assert!(!estimate.is_free);
+    assert!(!estimate.is_unlimited);
+    assert!(!estimate.is_rate_limited);
+    assert!(!estimate.has_watermark);
+  }
+}