rename CLAUDE.md to AGENTS.md

Opening a generated image/video and quickly clicking the backdrop to
close left the whole page unclickable, with no visible overlay to
explain why.

**Cause:** `Dialog.Overlay`/`Dialog.Content` are `forceMount`ed so
react-spring owns the leave animation. On close `Dialog.Root`'s `open`
flips false while the layer is still mounted, and Radix derives
`disableOutsidePointerEvents` from that flag, so its cleanup never
restores the `pointer-events: none` it set on `<body>`. Closing slowly
masked it; closing fast interrupts the leave spring so the clearing
render never comes.

**Fix:** `unregisterModal` now schedules `releaseStrandedBodyLock`,
clearing a lock nothing still owns. Bails if a modal is still registered
or a real open Radix dialog exists.

.claude/rules/testing.md

@@ -1,5 +1,25 @@
 # Testing
 
+## Database Fixture Tests
+
+- Live in-crate (e.g. `storyteller-web`'s omni_gen video pricing tests) and
+  use the `mysql_testing` crate (`crates/schema/database/mysql_testing`) for
+  guarded pools, schema setup, and account/session/wallet fixtures
+- They RUN BY DEFAULT with `cargo test -p storyteller-web` and from the IDE
+  (requires a local MySQL with an `artcraft_test` database). Machines/CI
+  without MySQL skip them via the off switch:
+  `SQLX_OFFLINE=true cargo test -p storyteller-web --features skip_database_tests`
+- They connect ONLY via `ARTCRAFT_TEST_DATABASE_URL` (default
+  `mysql://root:@localhost:3306/artcraft_test`); the guard panics on any
+  database whose name lacks "test", on `storyteller`/`artcraft`, and on
+  cloud hosts — see `mysql_testing/README.md`
+- Database tests run in PARALLEL: each test creates its own users, wallets,
+  and rows; schema setup single-flights via a MySQL named lock. Only tests
+  mutating shared/global state take
+  `mysql_testing::serial::acquire_serial_test_lock().await`
+- External providers must never be called: the harness stubs Kinovi with an
+  in-process HTTP server via `KINOVI_CUSTOM_API_HOST`/`KINOVI_CUSTOM_CDN_HOST`
+
 ## Running Tests
 
 - Most crates: `cargo test -p {crate_name}`

.sqlx/query-03919ba8286d18980ecaa0038df76f43f5388db0d3838181fa8f15f4cbb932af.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE generic_inference_jobs\nSET\n  status = ?,\n  on_success_result_entity_type = ?,\n  on_success_result_entity_token = ?,\n  failure_reason = NULL,\n  internal_debugging_failure_reason = NULL,\n  success_execution_millis = ?,\n  success_inference_execution_millis = ?,\n  retry_at = NULL,\n  successfully_completed_at = NOW()\nWHERE token = ?\nAND status NOT IN ('complete_success', 'complete_failure')\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 6
+    },
+    "nullable": []
+  },
+  "hash": "03919ba8286d18980ecaa0038df76f43f5388db0d3838181fa8f15f4cbb932af"
+}

.sqlx/query-258ac40d3fab39f110e1e82d50e73542423bfe9a21f8127e6cd83214c1726e25.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE generic_inference_jobs\nSET\n  status = ?,\n  assigned_worker = ?,\n  last_assigned_worker = ?,\n  assigned_cluster = ?,\n  first_started_at = NOW()\nWHERE token = ?\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 5
+    },
+    "nullable": []
+  },
+  "hash": "258ac40d3fab39f110e1e82d50e73542423bfe9a21f8127e6cd83214c1726e25"
+}

.sqlx/query-5ad1951163b15a9e241f949f2e66cde830d51d70b395f93000bc47ecb9c2083f.json

@@ -0,0 +1,135 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `token: McpSessionToken`,\n  user_token as `user_token: UserToken`,\n  maybe_mcp_client_name,\n  maybe_mcp_client_version,\n  maybe_mcp_client_vendor,\n  ip_address_creation,\n  ip_address_update,\n  created_at,\n  updated_at,\n  expires_at,\n  maybe_deleted_at\nFROM mcp_sessions\nWHERE user_token = ?\nORDER BY id DESC\nLIMIT ? OFFSET ?\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token: McpSessionToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "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": "maybe_mcp_client_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_mcp_client_version",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "maybe_mcp_client_vendor",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "ip_address_creation",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "ip_address_update",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "maybe_deleted_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": [
+      false,
+      false,
+      true,
+      true,
+      true,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true
+    ]
+  },
+  "hash": "5ad1951163b15a9e241f949f2e66cde830d51d70b395f93000bc47ecb9c2083f"
+}

.sqlx/query-62b3e2e058331a6819acd98c634b3bf2d10aa38d43b49ab69fb8637497beec2f.json

@@ -1,6 +1,6 @@
 {
   "db_name": "MySQL",
-  "query": "\nSELECT\n  users.token as `user_token: UserToken`,\n  users.username,\n  users.display_name,\n  users.email_address,\n  users.user_role_slug,\n  users.is_banned,\n  user_roles.can_ban_users\nFROM user_sessions\nINNER JOIN users\n  ON users.token = user_sessions.user_token\nLEFT OUTER JOIN user_roles\n  ON users.user_role_slug = user_roles.slug\nWHERE user_sessions.token = ?\n  AND user_sessions.deleted_at IS NULL\n  AND users.user_deleted_at IS NULL\n  AND users.mod_deleted_at IS NULL\nLIMIT 1\n    ",
+  "query": "\nSELECT\n  users.token as `user_token: UserToken`,\n  users.username,\n  users.display_name,\n  users.email_address,\n  users.user_role_slug,\n  users.is_banned,\n  user_roles.can_ban_users,\n  users.maybe_feature_flags,\n  api_keys.token as `api_key_token: ApiKeyToken`\nFROM api_keys\nINNER JOIN users\n  ON users.token = api_keys.owner_user_token\nLEFT OUTER JOIN user_roles\n  ON users.user_role_slug = user_roles.slug\nWHERE api_keys.api_key = ?\n  AND api_keys.maybe_deleted_at IS NULL\n  AND users.user_deleted_at IS NULL\n  AND users.mod_deleted_at IS NULL\nLIMIT 1\n    ",
   "describe": {
     "columns": [
       {
@@ -72,6 +72,26 @@
           "char_set": 63,
           "max_size": 1
         }
+      },
+      {
+        "ordinal": 7,
+        "name": "maybe_feature_flags",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "api_key_token: ApiKeyToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
       }
     ],
     "parameters": {
@@ -84,8 +104,10 @@
       false,
       false,
       false,
-      true
+      true,
+      true,
+      false
     ]
   },
-  "hash": "c77126adb36f9e2f0248720eb4d8c1cd9d14719f64a02678d8021e26addd2c18"
+  "hash": "62b3e2e058331a6819acd98c634b3bf2d10aa38d43b49ab69fb8637497beec2f"
 }

.sqlx/query-6ca0fcdf495624cf347f612586868f6dea93f52d9f942a92dcd2b3e6aba7c63c.json

@@ -0,0 +1,36 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `job_token: tokens::tokens::generic_inference_jobs::InferenceJobToken`,\n  maybe_prompt_token as `maybe_prompt_token: tokens::tokens::prompts::PromptToken`\nFROM generic_inference_jobs\nWHERE job_type = ?\nAND status = 'pending'\nORDER BY id ASC\nLIMIT 1\nFOR UPDATE SKIP LOCKED\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "job_token: tokens::tokens::generic_inference_jobs::InferenceJobToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "maybe_prompt_token: tokens::tokens::prompts::PromptToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      true
+    ]
+  },
+  "hash": "6ca0fcdf495624cf347f612586868f6dea93f52d9f942a92dcd2b3e6aba7c63c"
+}

.sqlx/query-827eb468e1f732f72e0dc8f655add2b50f12cb933bba230a1fd4abb594a1944a.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE mcp_sessions\nSET maybe_deleted_at = NOW()\nWHERE private_session_token = ?\n  AND maybe_deleted_at IS NULL\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "827eb468e1f732f72e0dc8f655add2b50f12cb933bba230a1fd4abb594a1944a"
+}

.sqlx/query-847acba63c2ee29b5d59bea4cdd88f12ec4b3e8a4317ab26a1e9039c0b66a1b2.json

@@ -0,0 +1,113 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  users.token as `user_token: UserToken`,\n  users.username,\n  users.display_name,\n  users.email_address,\n  users.user_role_slug,\n  users.is_banned,\n  user_roles.can_ban_users,\n  users.maybe_feature_flags,\n  mcp_sessions.token as `mcp_session_token: McpSessionToken`\nFROM mcp_sessions\nINNER JOIN users\n  ON users.token = mcp_sessions.user_token\nLEFT OUTER JOIN user_roles\n  ON users.user_role_slug = user_roles.slug\nWHERE mcp_sessions.private_session_token = ?\n  AND mcp_sessions.maybe_deleted_at IS NULL\n  AND mcp_sessions.expires_at > NOW()\n  AND users.user_deleted_at IS NULL\n  AND users.mod_deleted_at IS NULL\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "email_address",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "user_role_slug",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "is_banned",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "can_ban_users",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "maybe_feature_flags",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "mcp_session_token: McpSessionToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true,
+      true,
+      false
+    ]
+  },
+  "hash": "847acba63c2ee29b5d59bea4cdd88f12ec4b3e8a4317ab26a1e9039c0b66a1b2"
+}

.sqlx/query-8b61abdfcfcd5c601489521793ef5c8cbe47f408e5c7e9c9a6bf01c9c8a57247.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE mcp_sessions\nSET maybe_deleted_at = NOW()\nWHERE token = ?\n  AND maybe_deleted_at IS NULL\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "8b61abdfcfcd5c601489521793ef5c8cbe47f408e5c7e9c9a6bf01c9c8a57247"
+}

.sqlx/query-96599b4854248d84188b092db84edb50dc5402bb7771fd8ea96a96ad43e732c0.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE generic_inference_jobs\nSET\n  status = ?,\n  frontend_failure_category = ?,\n  failure_reason = ?,\n  internal_debugging_failure_reason = ?,\n  success_execution_millis = ?,\n  success_inference_execution_millis = ?\nWHERE token = ?\nAND status NOT IN ('complete_success', 'complete_failure')\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 7
+    },
+    "nullable": []
+  },
+  "hash": "96599b4854248d84188b092db84edb50dc5402bb7771fd8ea96a96ad43e732c0"
+}

.sqlx/query-c59cea297d441b4960074802809af5ff0bdf8969abb34c01101584bffd887010.json

@@ -0,0 +1,135 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `token: McpSessionToken`,\n  user_token as `user_token: UserToken`,\n  maybe_mcp_client_name,\n  maybe_mcp_client_version,\n  maybe_mcp_client_vendor,\n  ip_address_creation,\n  ip_address_update,\n  created_at,\n  updated_at,\n  expires_at,\n  maybe_deleted_at\nFROM mcp_sessions\nWHERE token = ?\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token: McpSessionToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "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": "maybe_mcp_client_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_mcp_client_version",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "maybe_mcp_client_vendor",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "ip_address_creation",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "ip_address_update",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "maybe_deleted_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      true,
+      true,
+      true,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true
+    ]
+  },
+  "hash": "c59cea297d441b4960074802809af5ff0bdf8969abb34c01101584bffd887010"
+}

.sqlx/query-cd04f4f7b48ae9da53b6a210111f8e3edff94dee30263e22b45d5e29dbe9245a.json

@@ -0,0 +1,179 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n    m.token as `token: tokens::tokens::media_files::MediaFileToken`,\n\n    m.media_class as `media_class: enums::by_table::media_files::media_file_class::MediaFileClass`,\n    m.media_type as `media_type: enums::by_table::media_files::media_file_type::MediaFileType`,\n\n    m.maybe_batch_token as `maybe_batch_token: tokens::tokens::batch_generations::BatchGenerationToken`,\n    m.maybe_prompt_token as `maybe_prompt_token: tokens::tokens::prompts::PromptToken`,\n\n    m.public_bucket_directory_hash,\n    m.maybe_public_bucket_prefix,\n    m.maybe_public_bucket_extension,\n\n    media_file_cover_image.public_bucket_directory_hash as maybe_file_cover_image_public_bucket_hash,\n    media_file_cover_image.maybe_public_bucket_prefix as maybe_file_cover_image_public_bucket_prefix,\n    media_file_cover_image.maybe_public_bucket_extension as maybe_file_cover_image_public_bucket_extension,\n\n    m.maybe_origin_filename,\n    m.maybe_duration_millis as `maybe_duration_millis: u64`,\n\n    m.created_at,\n    m.updated_at\n\nFROM media_files AS m\nLEFT OUTER JOIN media_files as media_file_cover_image\n    ON media_file_cover_image.token = m.maybe_cover_image_media_file_token\nWHERE\n    m.maybe_source_job_token = ?\n    AND m.maybe_creator_user_token = ?\n    AND m.user_deleted_at IS NULL\n    AND m.mod_deleted_at IS NULL\n    AND NOT m.is_intermediate_system_file\nORDER BY m.id ASC\nLIMIT ?\n      ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token: tokens::tokens::media_files::MediaFileToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "media_class: enums::by_table::media_files::media_file_class::MediaFileClass",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "media_type: enums::by_table::media_files::media_file_type::MediaFileType",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_batch_token: tokens::tokens::batch_generations::BatchGenerationToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "maybe_prompt_token: tokens::tokens::prompts::PromptToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "public_bucket_directory_hash",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "maybe_public_bucket_prefix",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "maybe_public_bucket_extension",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "maybe_file_cover_image_public_bucket_hash",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "maybe_file_cover_image_public_bucket_prefix",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "maybe_file_cover_image_public_bucket_extension",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "maybe_origin_filename",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 12,
+        "name": "maybe_duration_millis: u64",
+        "type_info": {
+          "type": "Long",
+          "flags": "",
+          "char_set": 63,
+          "max_size": 10
+        }
+      },
+      {
+        "ordinal": 13,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 14,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      true,
+      true,
+      false,
+      true,
+      true,
+      true,
+      true,
+      true,
+      true,
+      true,
+      false,
+      false
+    ]
+  },
+  "hash": "cd04f4f7b48ae9da53b6a210111f8e3edff94dee30263e22b45d5e29dbe9245a"
+}

.sqlx/query-cf2794c87868e77dfaa45bdbe630ae276dbb8c2d041442ba465af0b7a6d61af6.json

@@ -1,6 +1,6 @@
 {
   "db_name": "MySQL",
-  "query": "\nSELECT\n  users.token as `user_token: UserToken`,\n  users.username,\n  users.display_name,\n  users.email_address,\n  users.user_role_slug,\n  users.is_banned,\n  user_roles.can_ban_users,\n  api_keys.token as `api_key_token: ApiKeyToken`\nFROM api_keys\nINNER JOIN users\n  ON users.token = api_keys.owner_user_token\nLEFT OUTER JOIN user_roles\n  ON users.user_role_slug = user_roles.slug\nWHERE api_keys.api_key = ?\n  AND api_keys.maybe_deleted_at IS NULL\n  AND users.user_deleted_at IS NULL\n  AND users.mod_deleted_at IS NULL\nLIMIT 1\n    ",
+  "query": "\nSELECT\n  users.token as `user_token: UserToken`,\n  users.username,\n  users.display_name,\n  users.email_address,\n  users.user_role_slug,\n  users.is_banned,\n  user_roles.can_ban_users,\n  users.maybe_feature_flags\nFROM user_sessions\nINNER JOIN users\n  ON users.token = user_sessions.user_token\nLEFT OUTER JOIN user_roles\n  ON users.user_role_slug = user_roles.slug\nWHERE user_sessions.token = ?\n  AND user_sessions.deleted_at IS NULL\n  AND users.user_deleted_at IS NULL\n  AND users.mod_deleted_at IS NULL\nLIMIT 1\n    ",
   "describe": {
     "columns": [
       {
@@ -75,12 +75,12 @@
       },
       {
         "ordinal": 7,
-        "name": "api_key_token: ApiKeyToken",
+        "name": "maybe_feature_flags",
         "type_info": {
           "type": "VarString",
-          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "flags": "BINARY",
           "char_set": 224,
-          "max_size": 128
+          "max_size": 1020
         }
       }
     ],
@@ -95,8 +95,8 @@
       false,
       false,
       true,
-      false
+      true
     ]
   },
-  "hash": "9188e235caa439d50628333c2f4722b9f1a8f575c192d4d36a2039709c412ac0"
+  "hash": "cf2794c87868e77dfaa45bdbe630ae276dbb8c2d041442ba465af0b7a6d61af6"
 }

.sqlx/query-d88098343686ded52a71fc45a1b96d28ea3003975d6e7d20eee2022aa31d8189.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\n        INSERT INTO media_files\n        SET\n            token = ?,\n\n            media_class = ?,\n            media_type = ?,\n\n            is_user_upload = ?,\n            is_intermediate_system_file = ?,\n\n            origin_category = ?,\n            origin_product_category = ?,\n            maybe_origin_model_type = ?,\n            maybe_origin_model_token = ?,\n            maybe_origin_filename = ?,\n\n            maybe_batch_token = ?,\n            maybe_source_job_token = ?,\n\n            maybe_mime_type = ?,\n            file_size_bytes = ?,\n            maybe_duration_millis = ?,\n            maybe_audio_encoding = ?,\n            maybe_video_encoding = ?,\n            maybe_frame_width = ?,\n            maybe_frame_height = ?,\n            maybe_prompt_token = ?,\n            checksum_sha2 = ?,\n\n            maybe_engine_category = ?,\n\n            maybe_title = ?,\n            maybe_text_transcript = ?,\n\n            maybe_scene_source_media_file_token = ?,\n\n            public_bucket_directory_hash = ?,\n            maybe_public_bucket_prefix = ?,\n            maybe_public_bucket_extension = ?,\n\n            maybe_creator_user_token = ?,\n            maybe_creator_anonymous_visitor_token = ?,\n\n            creator_ip_address = ?,\n            creator_set_visibility = ?,\n\n            maybe_creator_file_synthetic_id = ?,\n            maybe_creator_category_synthetic_id = ?,\n\n            extra_file_modification_info = ?,\n\n            maybe_generation_provider = ?,\n\n            platform_type = ?,\n\n            maybe_cover_image_media_file_token = ?,\n\n            maybe_mod_user_token = ?,\n            is_generated_on_prem = ?,\n            generated_by_worker = ?,\n            generated_by_cluster = ?\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 42
+    },
+    "nullable": []
+  },
+  "hash": "d88098343686ded52a71fc45a1b96d28ea3003975d6e7d20eee2022aa31d8189"
+}

.sqlx/query-ed8f7ef94099d2dddf50f819316485351e149db72ce8a4f5cff6b57f4b84244d.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE mcp_sessions\nSET\n  expires_at = NOW() + INTERVAL ? DAY,\n  private_refresh_token = ?,\n  ip_address_update = ?\nWHERE private_session_token = ?\n  AND private_refresh_token = ?\n  AND maybe_deleted_at IS NULL\n  AND expires_at > NOW()\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 5
+    },
+    "nullable": []
+  },
+  "hash": "ed8f7ef94099d2dddf50f819316485351e149db72ce8a4f5cff6b57f4b84244d"
+}

.sqlx/query-f1d41ad17cb01f5aef0ce2eea042ccb3e5e649365a0befaf0f46492b75523442.json

@@ -0,0 +1,124 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `job_token: tokens::tokens::generic_inference_jobs::InferenceJobToken`,\n  status as `status: enums::common::job_status_plus::JobStatusPlus`,\n  job_type as `job_type: enums::by_table::generic_inference_jobs::inference_job_type::InferenceJobType`,\n  maybe_creator_user_token as `maybe_creator_user_token: tokens::tokens::users::UserToken`,\n  maybe_creator_anonymous_visitor_token as `maybe_creator_anonymous_visitor_token: tokens::tokens::anonymous_visitor_tracking::AnonymousVisitorTrackingToken`,\n  creator_ip_address,\n  maybe_prompt_token as `maybe_prompt_token: tokens::tokens::prompts::PromptToken`,\n  maybe_debug_log_event_token as `maybe_debug_log_event_token: tokens::tokens::non_unique::debug_logs_event_token::DebugLogEventToken`,\n  platform_type as `maybe_platform_type: enums::common::platform_type::PlatformType`,\n  on_success_result_entity_token as `maybe_result_media_file_token: tokens::tokens::media_files::MediaFileToken`\nFROM generic_inference_jobs\nWHERE token = ?\nAND job_type IN ('artcraft_minimax_h3_turbo', 'artcraft_minimax_h3_ultra')\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "job_token: tokens::tokens::generic_inference_jobs::InferenceJobToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "status: enums::common::job_status_plus::JobStatusPlus",
+        "type_info": {
+          "type": "String",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | ENUM",
+          "char_set": 224,
+          "max_size": 76
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "job_type: enums::by_table::generic_inference_jobs::inference_job_type::InferenceJobType",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_creator_user_token: tokens::tokens::users::UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "maybe_creator_anonymous_visitor_token: tokens::tokens::anonymous_visitor_tracking::AnonymousVisitorTrackingToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "creator_ip_address",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "maybe_prompt_token: tokens::tokens::prompts::PromptToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "maybe_debug_log_event_token: tokens::tokens::non_unique::debug_logs_event_token::DebugLogEventToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "maybe_platform_type: enums::common::platform_type::PlatformType",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "maybe_result_media_file_token: tokens::tokens::media_files::MediaFileToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      true,
+      true,
+      true,
+      false,
+      true,
+      true,
+      true,
+      true
+    ]
+  },
+  "hash": "f1d41ad17cb01f5aef0ce2eea042ccb3e5e649365a0befaf0f46492b75523442"
+}

.sqlx/query-f5bc4a956a20f6c0998585092a0922301d53c95ae8ea9cb808ae2dbcf8d0bb32.json

@@ -1,12 +0,0 @@
-{
-  "db_name": "MySQL",
-  "query": "\n        INSERT INTO media_files\n        SET\n            token = ?,\n\n            media_class = ?,\n            media_type = ?,\n\n            is_user_upload = ?,\n            is_intermediate_system_file = ?,\n\n            origin_category = ?,\n            origin_product_category = ?,\n            maybe_origin_model_type = ?,\n            maybe_origin_model_token = ?,\n            maybe_origin_filename = ?,\n\n            maybe_batch_token = ?,\n\n            maybe_mime_type = ?,\n            file_size_bytes = ?,\n            maybe_duration_millis = ?,\n            maybe_audio_encoding = ?,\n            maybe_video_encoding = ?,\n            maybe_frame_width = ?,\n            maybe_frame_height = ?,\n            maybe_prompt_token = ?,\n            checksum_sha2 = ?,\n\n            maybe_engine_category = ?,\n\n            maybe_title = ?,\n            maybe_text_transcript = ?,\n\n            maybe_scene_source_media_file_token = ?,\n\n            public_bucket_directory_hash = ?,\n            maybe_public_bucket_prefix = ?,\n            maybe_public_bucket_extension = ?,\n\n            maybe_creator_user_token = ?,\n            maybe_creator_anonymous_visitor_token = ?,\n\n            creator_ip_address = ?,\n            creator_set_visibility = ?,\n\n            maybe_creator_file_synthetic_id = ?,\n            maybe_creator_category_synthetic_id = ?,\n\n            extra_file_modification_info = ?,\n\n            maybe_generation_provider = ?,\n\n            platform_type = ?,\n\n            maybe_cover_image_media_file_token = ?,\n\n            maybe_mod_user_token = ?,\n            is_generated_on_prem = ?,\n            generated_by_worker = ?,\n            generated_by_cluster = ?\n        ",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Right": 41
-    },
-    "nullable": []
-  },
-  "hash": "f5bc4a956a20f6c0998585092a0922301d53c95ae8ea9cb808ae2dbcf8d0bb32"
-}

.sqlx/query-f67a73ea3d5751cc76d2d6f954bd939179b3e9005a359e04c3a4dd78f8fe562e.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO mcp_sessions\nSET\n  token = ?,\n  private_session_token = ?,\n  private_refresh_token = ?,\n  user_token = ?,\n  maybe_mcp_client_name = ?,\n  maybe_mcp_client_version = ?,\n  maybe_mcp_client_vendor = ?,\n  ip_address_creation = ?,\n  ip_address_update = ?,\n  created_at = NOW(),\n  expires_at = NOW() + INTERVAL ? DAY\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 10
+    },
+    "nullable": []
+  },
+  "hash": "f67a73ea3d5751cc76d2d6f954bd939179b3e9005a359e04c3a4dd78f8fe562e"
+}

AGENTS.md

@@ -0,0 +1,97 @@
+# AGENTS.md
+
+This file provides guidance for coding agents when working with the Artcraft monorepo.
+
+## Project Overview
+
+Artcraft is a web and desktop application for generating AI image and video. It is written in 
+Rust and TypeScript and contains desktop, server, and frontend components.
+
+## Project Structure
+
+```
+artcraft/
+├── _database/                           # Schema definitions and migrations (MySQL, SQLite, Elasticsearch, etc.)
+│   ├── elasticsearch/                   # Elasticsearch schema and queries
+│   └── sql/                             # MySQL and SQLite schema definitions and migrations
+│       ├── artcraft_migrations/         # ArtCraft desktop app SQLite migrations
+│       ├── migrations/                  # Server MySQL migrations
+│       └── migrations_squashed/         # Fully materialized MySQL schema definitions for most tables
+├── _tools/                              # Various 3rd party tool integrations and configurations
+│   └── postman/                         # Postman configs for test HTTP requests against development and production
+├── build/                               # Dockerfile build instructions for server components
+├── crates/                              # Rust workspace
+│   ├── api_clients/                     # HTTP clients for calling internal and 3rd party services
+│   ├── cli/                             # Command line tools
+│   ├── desktop/                         # Desktop (Tauri) apps
+│   │   └── artcraft/                    # (Important) ArtCraft, the desktop app. This is one of our main pieces of software
+│   ├── lib/                             # Various utility libraries for servers, CLI tools, desktop, etc.
+│   ├── schema/                          # Data definition layer: MySQL, SQlite, Redis, S3/R2 buckets, etc.
+│   │   ├── buckets/                     # Declares R2 cloud bucket topology
+│   │   ├── database/                    # MySQL, SQLite, Elasticsearch, Redis, etc.
+│   │   │   ├── elasticsearch_schema/    # Elasticsearch
+│   │   │   ├── migration/               # (deprecated) Online schema adapters for MySQL 
+│   │   │   ├── mysql_queries/           # Sqlx MySQL queries for our backend monolith `storyteller-web`, jobs, etc.
+│   │   │   ├── redis_common/            # Redis support
+│   │   │   ├── redis_schema/            # Redis key and HKEY topology
+│   │   │   ├── sqlite_queries/          # (deprecated) Sqlite queries
+│   │   │   └── sqlite_tasks/            # Queries for the ArtCraft desktop app's "tasks" database.
+│   │   ├── public/                      # Token identifier and enum variant definitions
+│   │   │   ├── composite_identifier/    # MySQL composite key system
+│   │   │   ├── enums/                   # MySQL "enums" stored in VARCHAR fields.
+│   │   │   └── tokens/                  # Primary database identifiers with Stripe-like ID prefixes, eg. "user_{entropy}"
+│   │   └── service/                     # Backend HTTP services and jobs
+│   │       ├── job/                     # Backend jobs.
+│   │       │   └── video_thumbnail_job/ # Render video thumbnails
+│   │       ├── plugins/                 # Collections of reusable Actix-Web HTTP functions (user and billing systems)
+│   │       └── web/                     # HTTP web servers
+│   │           └── storyteller_web/     # (Important) Our main HTTP API monolith and backend.
+│   └── frontend/                        # Nx typescript monorepo for our websites and Tauri desktop apps
+│       ├── apps/                        # Websites and Tauri desktop apps
+│       │   ├── artcraft/                # ArtCraft the Tauri app's frontend. Used in conjunction with `artcraft` the Rust crate.
+│       │   └── artcraft-website/        # The website for https://getartcraft.com
+│       └── libs/                        # Support libraries, reusable React components, etc.
+└── Cargo.toml                           # Rust monorepo workspace
+```
+
+## Code Style
+
+- Rust with no minimum supported version
+- Actix-web for HTTP services
+- SQLx for MySQL and SQLite; prefer `sqlx::query!` / `sqlx::query_as!` compile-time checked macros over runtime `sqlx::query()` whenever possible
+- MySQL queries belong in the `mysql_queries` crate, not in application/service crates like `storyteller-web` — call those query functions instead of embedding `sqlx::query!` / `sqlx::query()` in handlers. (Query-writing conventions live in `crates/schema/database/mysql_queries/AGENTS.md`.)
+- 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
+
+### File Layout
+
+Organize for top-to-bottom reading. Important things first, details later.
+
+- **Constants** at the top (after imports)
+- **Structs/enums** next; outer structs above inner sub-structs
+- **API types** in order: Request, Response, Error
+- **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
+
+## Markdown
+
+- **Tables must be space-padded so columns align in plain text.** Markdown
+  tables are read raw (terminals, diffs, editors) at least as often as
+  rendered, and condensed tables are unreadable there. Pad every cell to its
+  column width:
+
+  ```markdown
+  | Model        | Configuration | Credits    | Speed | Score   |
+  |--------------|---------------|--------------------|---------|
+  | Meshy 6      | text or image | 104        | 80.0  | +24     |
+  | Rodin 2.5    | text or image | 13         | 10.0  | +3      |
+  ```
+
+  Not: `| Model | Configuration | Credits | Speed | Score |` packed tight
+  with varying widths per row.

CLAUDE.md

@@ -1,96 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance for Claude Code when working with the Artcraft monorepo.
-
-## Project Overview
-
-Artcraft is a web and desktop application for generating AI image and video. It is written in 
-Rust and TypeScript and contains desktop, server, and frontend components.
-
-## Project Structure
-
-```
-artcraft/
-├── _database/                           # Schema definitions and migrations (MySQL, SQLite, Elasticsearch, etc.)
-│   ├── elasticsearch/                   # Elasticsearch schema and queries
-│   └── sql/                             # MySQL and SQLite schema definitions and migrations
-│       ├── artcraft_migrations/         # ArtCraft desktop app SQLite migrations
-│       ├── migrations/                  # Server MySQL migrations
-│       └── migrations_squashed/         # Fully materialized MySQL schema definitions for most tables
-├── _tools/                              # Various 3rd party tool integrations and configurations
-│   └── postman/                         # Postman configs for test HTTP requests against development and production
-├── build/                               # Dockerfile build instructions for server components
-├── crates/                              # Rust workspace
-│   ├── api_clients/                     # HTTP clients for calling internal and 3rd party services
-│   ├── cli/                             # Command line tools
-│   ├── desktop/                         # Desktop (Tauri) apps
-│   │   └── artcraft/                    # (Important) ArtCraft, the desktop app. This is one of our main pieces of software
-│   ├── lib/                             # Various utility libraries for servers, CLI tools, desktop, etc.
-│   ├── schema/                          # Data definition layer: MySQL, SQlite, Redis, S3/R2 buckets, etc.
-│   │   ├── buckets/                     # Declares R2 cloud bucket topology
-│   │   ├── database/                    # MySQL, SQLite, Elasticsearch, Redis, etc.
-│   │   │   ├── elasticsearch_schema/    # Elasticsearch
-│   │   │   ├── migration/               # (deprecated) Online schema adapters for MySQL 
-│   │   │   ├── mysql_queries/           # Sqlx MySQL queries for our backend monolith `storyteller-web`, jobs, etc.
-│   │   │   ├── redis_common/            # Redis support
-│   │   │   ├── redis_schema/            # Redis key and HKEY topology
-│   │   │   ├── sqlite_queries/          # (deprecated) Sqlite queries
-│   │   │   └── sqlite_tasks/            # Queries for the ArtCraft desktop app's "tasks" database.
-│   │   ├── public/                      # Token identifier and enum variant definitions
-│   │   │   ├── composite_identifier/    # MySQL composite key system
-│   │   │   ├── enums/                   # MySQL "enums" stored in VARCHAR fields.
-│   │   │   └── tokens/                  # Primary database identifiers with Stripe-like ID prefixes, eg. "user_{entropy}"
-│   │   └── service/                     # Backend HTTP services and jobs
-│   │       ├── job/                     # Backend jobs.
-│   │       │   └── video_thumbnail_job/ # Render video thumbnails
-│   │       ├── plugins/                 # Collections of reusable Actix-Web HTTP functions (user and billing systems)
-│   │       └── web/                     # HTTP web servers
-│   │           └── storyteller_web/     # (Important) Our main HTTP API monolith and backend.
-│   └── frontend/                        # Nx typescript monorepo for our websites and Tauri desktop apps
-│       ├── apps/                        # Websites and Tauri desktop apps
-│       │   ├── artcraft/                # ArtCraft the Tauri app's frontend. Used in conjunction with `artcraft` the Rust crate.
-│       │   └── artcraft-website/        # The website for https://getartcraft.com
-│       └── libs/                        # Support libraries, reusable React components, etc.
-└── Cargo.toml                           # Rust monorepo workspace
-```
-
-## Code Style
-
-- Rust with no minimum supported version
-- Actix-web for HTTP services
-- SQLx for MySQL and SQLite. MySQL queries belong in the `mysql_queries` crate, not in application/service crates like `storyteller-web` — call those query functions instead of embedding `sqlx::query!` / `sqlx::query()` in handlers. (Query-writing conventions live in `crates/schema/database/mysql_queries/CLAUDE.md`.)
-- 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
-
-### File Layout
-
-Organize for top-to-bottom reading. Important things first, details later.
-
-- **Constants** at the top (after imports)
-- **Structs/enums** next; outer structs above inner sub-structs
-- **API types** in order: Request, Response, Error
-- **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
-
-## Markdown
-
-- **Tables must be space-padded so columns align in plain text.** Markdown
-  tables are read raw (terminals, diffs, editors) at least as often as
-  rendered, and condensed tables are unreadable there. Pad every cell to its
-  column width:
-
-  ```markdown
-  | Model        | Configuration | Credits    | Speed | Score   |
-  |--------------|---------------|--------------------|---------|
-  | Meshy 6      | text or image | 104        | 80.0  | +24     |
-  | Rodin 2.5    | text or image | 13         | 10.0  | +3      |
-  ```
-
-  Not: `| Model | Configuration | Credits | Speed | Score |` packed tight
-  with varying widths per row.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Cargo.lock

@@ -7363,6 +7363,22 @@ dependencies = [
  "workspace-build-acceleration",
 ]
 
+[[package]]
+name = "mysql_testing"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "bcrypt",
+ "bucket_paths",
+ "chrono",
+ "enums",
+ "log",
+ "mysql_queries",
+ "sqlx",
+ "tokens",
+ "tokio",
+]
+
 [[package]]
 name = "mysqlclient-sys"
 version = "0.2.5"
@@ -11646,6 +11662,7 @@ dependencies = [
  "migration",
  "mimetypes",
  "mysql_queries",
+ "mysql_testing",
  "once_cell",
  "opaque_cursors",
  "pager",

Cargo.toml

@@ -120,6 +120,7 @@ members = [
   "crates/schema/database/elasticsearch_schema",
   "crates/schema/database/migration",
   "crates/schema/database/mysql_queries",
+  "crates/schema/database/mysql_testing",
   "crates/schema/database/redis_common",
   "crates/schema/database/redis_schema",
   "crates/schema/database/sqlite_tasks",
@@ -282,6 +283,7 @@ mimetypes = { path = "crates/lib/files/mimetypes" }
 muapi_client = { path = "crates/api_clients/muapi_client" }
 metrics = { path = "crates/lib/metrics" }
 mysql_queries = { path = "crates/schema/database/mysql_queries" }
+mysql_testing = { path = "crates/schema/database/mysql_testing" }
 pager = { path = "crates/lib/pager" }
 openai_sora_client = { path = "crates/api_clients/openai_sora_client" }
 primitives = { path = "crates/lib/data/primitives" }

_database/sql/migrations/2026-08-04-205103-0000_alter_media_files_add_maybe_source_job_token/down.sql

@@ -0,0 +1,7 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE media_files
+  DROP INDEX index_maybe_source_job_token,
+  DROP COLUMN maybe_source_job_token;

_database/sql/migrations/2026-08-04-205103-0000_alter_media_files_add_maybe_source_job_token/up.sql

@@ -0,0 +1,13 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- The inference job ('jinf_...') whose completion produced this media file.
+-- Only set for files written as job outputs; uploads and other origins stay NULL.
+ALTER TABLE media_files
+  ADD COLUMN maybe_source_job_token VARCHAR(32) DEFAULT NULL;
+
+-- For "outputs of this job"-style lookups.
+-- The column is all-NULL at creation time, so the index build is cheap.
+ALTER TABLE media_files
+  ADD INDEX index_maybe_source_job_token (maybe_source_job_token);

_database/sql/migrations/2026-08-27-084409-0000_create_mcp_sessions/down.sql

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

_database/sql/migrations/2026-08-27-084409-0000_create_mcp_sessions/up.sql

@@ -0,0 +1,65 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- Sessions for MCP and other non-human users.
+-- These work like `user_sessions`, but are created and consumed by MCP clients.
+CREATE TABLE mcp_sessions (
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Non-private "primary key" for the session.
+  -- Used as a key to delete/manage sessions in the dashboard.
+  token VARCHAR(32) NOT NULL,
+
+  -- Private entropy presented by clients; used for lookup of live sessions.
+  private_session_token VARCHAR(64) NOT NULL,
+
+  -- Private refresh credential. Presenting this on the refresh endpoint extends the
+  -- session's expiry and ROTATES this value — the previous refresh token becomes invalid.
+  private_refresh_token VARCHAR(64) NOT NULL,
+
+  -- The user that the session belongs to.
+  user_token VARCHAR(32) NOT NULL,
+
+  -- ========== CLIENT INFO ==========
+
+  -- Trimmed name of the MCP client, if any.
+  maybe_mcp_client_name VARCHAR(255) DEFAULT NULL,
+
+  -- Trimmed version of the MCP client, if any.
+  maybe_mcp_client_version VARCHAR(255) DEFAULT NULL,
+
+  -- Trimmed vendor of the MCP client, if any.
+  maybe_mcp_client_vendor VARCHAR(255) DEFAULT NULL,
+
+  -- ========== IP ADDRESSES ==========
+
+  -- IP address that created the session. Wide enough for IPv4/IPv6.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address that last updated the session. Wide enough for IPv4/IPv6.
+  ip_address_update VARCHAR(40) NOT NULL,
+
+  -- ========== TIMESTAMPS ==========
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- When the session expires, if not refreshed.
+  -- This must be set by the server code, or the session is invalid.
+  expires_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- Soft-delete timestamp. NULL means the session is live.
+  -- deletion = session termination
+  maybe_deleted_at TIMESTAMP NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (private_session_token),
+  UNIQUE KEY (private_refresh_token),
+  KEY fk_user_token (user_token),
+  KEY index_ip_address_creation (ip_address_creation),
+  KEY index_maybe_deleted_at (maybe_deleted_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations/AGENTS.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/CLAUDE.md

@@ -1,38 +0,0 @@
-# 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/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

_database/sql/migrations_squashed/AGENTS.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/CLAUDE.md

@@ -1,26 +0,0 @@
-# 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/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

_database/sql/migrations_squashed/mcp_sessions.sql

@@ -0,0 +1,65 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- Sessions for MCP and other non-human users.
+-- These work like `user_sessions`, but are created and consumed by MCP clients.
+CREATE TABLE mcp_sessions (
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Non-private "primary key" for the session.
+  -- Used as a key to delete/manage sessions in the dashboard.
+  token VARCHAR(32) NOT NULL,
+
+  -- Private entropy presented by clients; used for lookup of live sessions.
+  private_session_token VARCHAR(64) NOT NULL,
+
+  -- Private refresh credential. Presenting this on the refresh endpoint extends the
+  -- session's expiry and ROTATES this value — the previous refresh token becomes invalid.
+  private_refresh_token VARCHAR(64) NOT NULL,
+
+  -- The user that the session belongs to.
+  user_token VARCHAR(32) NOT NULL,
+
+  -- ========== CLIENT INFO ==========
+
+  -- Trimmed name of the MCP client, if any.
+  maybe_mcp_client_name VARCHAR(255) DEFAULT NULL,
+
+  -- Trimmed version of the MCP client, if any.
+  maybe_mcp_client_version VARCHAR(255) DEFAULT NULL,
+
+  -- Trimmed vendor of the MCP client, if any.
+  maybe_mcp_client_vendor VARCHAR(255) DEFAULT NULL,
+
+  -- ========== IP ADDRESSES ==========
+
+  -- IP address that created the session. Wide enough for IPv4/IPv6.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address that last updated the session. Wide enough for IPv4/IPv6.
+  ip_address_update VARCHAR(40) NOT NULL,
+
+  -- ========== TIMESTAMPS ==========
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- When the session expires, if not refreshed.
+  -- This must be set by the server code, or the session is invalid.
+  expires_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- Soft-delete timestamp. NULL means the session is live.
+  -- deletion = session termination
+  maybe_deleted_at TIMESTAMP NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (private_session_token),
+  UNIQUE KEY (private_refresh_token),
+  KEY fk_user_token (user_token),
+  KEY index_ip_address_creation (ip_address_creation),
+  KEY index_maybe_deleted_at (maybe_deleted_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations_squashed/media_files.sql

@@ -102,6 +102,10 @@ CREATE TABLE media_files (
   -- If the media file is generated as part of a batch, this designates the batch.
   maybe_batch_token VARCHAR(32) DEFAULT NULL,
 
+  -- The inference job ('jinf_...') whose completion produced this media file.
+  -- Only set for files written as job outputs; uploads and other origins stay NULL.
+  maybe_source_job_token VARCHAR(32) DEFAULT NULL,
+
   -- ========== METADATA ==========
 
   -- If the file is a user upload (not including studio renders).
@@ -327,6 +331,7 @@ CREATE TABLE media_files (
   KEY fk_maybe_origin_model_token (maybe_origin_model_token),
   KEY fk_maybe_origin_model_type_and_token (maybe_origin_model_type, maybe_origin_model_token),
   KEY index_maybe_batch_token (maybe_batch_token),
+  KEY index_maybe_source_job_token (maybe_source_job_token),
   KEY index_is_user_upload (is_user_upload),
   KEY index_is_intermediate_system_file (is_intermediate_system_file),
   KEY index_maybe_scene_source_media_file_token (maybe_scene_source_media_file_token),

_docs/pagescene_animations_handoff.md

@@ -0,0 +1,227 @@
+# PageScene Animations — Branch Handoff
+
+Branch: `frontend/pagescene-animations` (forked from `main` @ `6329045350`, 2026-08-04).
+Everything below is TypeScript-typechecked per-lib (`tsc -p <lib>/tsconfig.lib.json`); runtime
+verification status is tracked in the checklist at the bottom. Drag-and-drop has had one manual
+pass (confirmed working); most other surfaces have not been launched.
+
+## What this branch does
+
+Makes skeletal animations a first-class asset in the 3D editor (pagescene): browse them in the
+asset drawer, drag them onto characters or the timeline with live rig-compatibility feedback,
+play clips baked into uploaded models, preview animations everywhere models are previewed, and
+upload Mixamo FBX files (with or without mesh) end to end.
+
+## Commit map
+
+| Commit       | What                                                                    |
+|--------------|-------------------------------------------------------------------------|
+| `7af3fb9856` | Animations tab in AssetModal; AnimationsDrawer retired                   |
+| `1fcbc55780` | Pointer drag-and-drop with live rig-compatibility badge                  |
+| `79d7ade8bc` | Baked-in clips on the timeline (+ clip-row eligibility widened)          |
+| `142279414e` | Animation dropdown in Viewer3D + upload preview                          |
+| `913905308e` | Clip fixes: vanishing character, 1 s strips, select-to-delete, undo      |
+| `60251104e3` | FBX accepted at the picker, converted to GLB in-browser                  |
+| `0942ec4804` | Nx tsconfig references for the new ui-select dependency                  |
+| `d0c7b65a6e` | FBX conversion moved into a Web Worker (main-thread fallback)            |
+| `8e51b6c524` | Explicit "Upload as Animation" toggle + required duration_millis         |
+| `00ebeae10c` | User's uploaded animations merged into the Animations tab                |
+| `e1c7a0c7b0` | Persistent skeleton-helper toggle in the outliner                        |
+| `30f40c0ddb` | Previewer bone toggles + mesh-less framing/mixer-binding fixes           |
+| `5f7ba7bbc5` | AnimationsModal (All/Presets/Uploaded) + timeline quality-of-life        |
+| `d55735620a` | Timeline ruler tick marks + strip button spacing                         |
+| `79875d8c76` | Upload animations from the AnimationsModal (initialCategory)             |
+| *(this)*     | NodeHierarchyHelper: bone toggle works for converted mesh-less GLBs      |
+
+## Features
+
+### 1. Animations tab in the asset drawer (`AssetModal`)
+
+- New left-rail section fed by `GET /v1/media_files/list_featured?filter_engine_categories=animation`
+  (GLB/GLTF only — the clip loader is GLTF-based). Featured results REPLACE the 37 hardcoded
+  `demoAnimationItems`; demos are only the empty-API fallback.
+- The session user's own uploaded animations (`list/user`, same filter) render AHEAD of the
+  featured set. Fetched on every modal open and after each upload; fails silently for anonymous
+  users (`suppressErrorToast` on the user-media fetch path).
+- Card click appends the clip to the selected character's row at the earliest free slot (toast
+  when no character is selected or the row is full). The old right-docked `AnimationsDrawer` is
+  deleted; the old HTML5-DnD path (`ANIMATION_CLIP_MIME`) is gone with it.
+
+### 2. Drag-and-drop with rig-compatibility badge (`DndAsset`)
+
+- Animation cards ride the same pointer-drag pipeline as every other asset. On drag start the
+  clip's track node names are preloaded (`loadRawGlb`, cached per media id); hovering a
+  character (or any skinned object) checks those names against its nodes — the exact direct-bind
+  rule `CharacterAnimationManager` plays by. No retargeting (explicitly out of scope).
+- The shared `DragGhost` shows the verdict: green check (binds) / red slash (no target or rig
+  mismatch); nothing while the clip is still loading. Incompatible or slot-less drops are
+  rejected with a toast.
+- Drop targets: a character in the 3D scene (earliest free slot) or a timeline row
+  (`data-clip-drop-uuid`; pointer-x → time via the `data-timeline-ruler` rect).
+
+### 3. Timeline clips: behavior + UX
+
+- **Strips default to 1 s** and the strip width is the authoritative play window
+  (`LaneRuntime.stripDuration`): trimming genuinely cuts playback; loop repeats inside the
+  strip; a non-loop strip wider than its clip freezes on the last frame. On load a strip only
+  shrinks (clip shorter than default) — never grows.
+- **Rest-pose in gaps**: `Skeleton.pose()` was replaced with a rest-pose snapshot captured at
+  mixer creation (all nodes BELOW the object root; root excluded so gizmo/keyframes never snap
+  back). `pose()` rebuilds bone locals from inverse bind matrices and mis-scales cm-rigs — that
+  was the "character vanishes when moving a strip" bug.
+- **Selection UX**: strips are click-to-select; × renders only on the selected strip;
+  Del/Backspace deletes; removal is individually undoable (`RemoveClipLaneAction` — the one
+  exception to clip edits riding the timeline Save/Cancel session).
+- **Full rows reject adds**: `resolveFreeStart` returns null instead of accepting an
+  overlapping clamp.
+
+### 4. Baked-in clips
+
+- `ClipStrip.bakedClipIndex` marks a strip sourced from the object's own `animations[]`
+  (resolved synchronously — no media fetch). Objects with baked clips get a timeline clip row
+  with a "+" picker listing them.
+- Clip-row eligibility is wider than characters: any skinned object (creatures, rigged uploads)
+  accepts animation drags (bind check gates); baked-only objects get a row for the picker.
+- INVARIANT: baked clips are never removed from the THREE model. Removing a baked strip only
+  unschedules it; the clip stays on `object.animations` and in the picker. Library strips stay
+  fully removable.
+- Outliner metadata (`hasSkeleton`, `bakedClips`) is computed in `convert_object` and refreshed
+  after every GLB load (`SceneDeps.onGlbLoaded` → `refreshOutliner`).
+
+### 5. Previewers (Viewer3D + upload preview)
+
+- Both play baked clips: autoplay the first, dropdown with every clip + "T-pose (none)", hidden
+  entirely for animation-less models.
+- Both have a bone icon toggling a skeleton overlay — default ON when the model has no mesh
+  (Mixamo "without skin" exports), so animation-only files are visible. The upload thumbnail
+  snapshot then captures the skeleton render.
+- The overlay adapts to the rig kind: real `THREE.Bone` joints get `THREE.SkeletonHelper`;
+  mesh-less models whose joints re-imported as plain nodes get `NodeHierarchyHelper`
+  (exported from `viewer-3d`) — GLTF only round-trips bone-ness through a *skin*, and a
+  mesh-less export has no skin, so converted FBX animations lose `Bone`-ness entirely. The
+  toggle shows for `hasBones || !hasMesh`.
+- Latent bugs fixed: upload preview discarded `gltf.animations`; its child re-parenting loop
+  skipped every other child (`scene.add` mutates the array mid-forEach); its mixer bound before
+  the model entered the scene (silently played nothing); camera framing NaN'd on empty
+  bounding boxes (now falls back to bone world positions); camera now fits once, not per-child.
+
+### 6. FBX upload support
+
+- The 3D uploader accepts `.fbx` and normalizes it at the door: `FBXLoader` → `GLTFExporter`
+  → binary GLB with clips preserved. Runs in a dedicated Web Worker (transferred buffers, jobs
+  naturally serialized); a broken worker environment falls back to the main thread. The raw FBX
+  can never reach the backend — retry of a failed conversion re-converts.
+- Caveats: embedded textures may not survive; units are exported as parsed (cm-scaled Mixamo
+  rigs are not rescaled).
+
+### 7. Upload as Animation
+
+- Mutually exclusive checkbox next to "Upload as Character" → `engine_category=animation`.
+  Mesh-less files preselect it (preview loader reports `hasMesh:false`); a user click always
+  wins. Rig-type dropdown defaults to Mixamo (characters keep Mixamo ArKit first).
+- The backend-required `maybe_duration_millis` is read from the longest clip at submit time;
+  clip-less files are flagged and excluded client-side.
+
+### 8. Outliner skeleton toggle (`SkeletonHelperController`)
+
+- Bone icon on skinned rows toggles a persistent `SkeletonHelper` on LAYER 1 (editor-only —
+  the render camera renders layer 0, so skeletons never appear in captures/recordings).
+- Persists as `userData.skeletonVisible` through scene save/load (explicit restore in the proxy
+  load path). Reconciliation rides `OutlinerRefreshedEvent` — add/delete/load/new-scene and the
+  post-GLB-load refresh all funnel there.
+- FK/pose-mode compatible: `PoseModeChangedEvent("pose")` suppresses the persistent helper for
+  the posed character (FKHelper draws its own rig); exit restores it. The toggle state itself
+  is never touched.
+
+## Manual test checklist (outstanding)
+
+- [ ] Prod data: does `list_featured?filter_engine_categories=animation` return rows? If yes
+      they replace the demo clips in the tab; if empty, the 37 demos show.
+- [ ] Clip→rig bind smoke test on shipped characters (runtime-unverified `mixamorig:*`
+      assumption; a "bound 0 tracks" console warning means retargeting becomes the real task).
+- [ ] Creature experiment: drag a clip onto a creature — badge should reflect bind result.
+- [ ] Baked clips: "+" picker on an animated object's row; add/remove/re-add; save/reload
+      persistence (the `object.animations` stash on load is gated on `auto_add` — statically
+      unconfirmed for every load path).
+- [ ] Clip UX round: strips at 1 s; trim semantics; select → ×/Del; undo/redo of removal;
+      character stays visible when a strip moves off the playhead.
+- [ ] FBX round trip: pick `.fbx` → converts (worker; check console for worker load failures —
+      falls back to main thread) → skeleton visible + clip dropdown → Upload as Animation
+      preselected → appears at front of Animations tab → drag onto character → plays.
+- [ ] Converted-FBX scale: if placed objects come in ~100× too big, the converter needs a
+      normalize-scale step.
+- [ ] Outliner bone toggle: on/off, FK-mode enter/exit restore, save/reload persistence, and
+      absence from Capture/Record output.
+- [ ] Previewer dropdown + bone toggle across lightbox, media page, lightbox-modal,
+      ImageTo3DExperience, upload modal.
+
+## Debug pass + hardening round (post-review)
+
+A four-agent review of the combined branch produced 30 findings (5 high / 12 medium / 13 low);
+ALL have been fixed or explicitly closed, one commit per finding (range `72cb218e..b21732d1`).
+Highlights, roughly in commit order:
+
+- Highs: baked clips cloned per lane (shared-AnimationAction playback/removal corruption);
+  runtime revalidation for objects recreated under the same uuid (delete→undo, reloads) — later
+  hardened into LOOP-FREE terminal lane states (bound / missing / unbindable, reassessed only on
+  root-instance change; the pre-fetch rig gate is sound because every load path stamps the target
+  uuid only post-load); skeleton-helper sync self-heals across in-session reloads; upload modal
+  can no longer report success for empty/partial submissions; ref-guarded double-submit.
+- Mediums: strip removal mirrored into the Save/Cancel `saved` snapshot (Cancel can't resurrect,
+  no phantom undo); stale strip/keyframe selections pruned in the bridge + live-checked before
+  swallowing Del/Backspace; one winning lane per character at flush boundaries (blend-glitch
+  frame was being ENCODED into recordings); orphaned tracks/lanes filtered from scene JSON at
+  save; per-clip queued-drop tokens; animation raycasts gated to the canvas element + honest
+  front-most-surface occlusion; virtualized-grid thumbnail state keyed by item; one shared
+  lazily-fetched animation-library store (was double-fetch + double-toast + divergent lists);
+  previewer rest-pose snapshots replace `Skeleton.pose()` everywhere; all-node camera-framing
+  fallback for plain-node rigs; upload-preview races (superseded-load cancellation, snapshot
+  after helper creation, File-identity row statuses, retry re-entry).
+- Lows: duration-shrink re-fits strips; baked-clip picker portals out of the scrolling row list;
+  timeline resets on scene switch/new scene instead of leaking across; click-to-add accepts every
+  drag-eligible target; queued drops bail on a torn-down editor (`Editor.isLive`); top-level root
+  lookups unified; flick-click race killed via `wasDragGesture`; converting-overlay control reset;
+  conversion completions reload only the previewed entry; worker `onmessageerror` recovery +
+  corrupt-vs-clip-less error messages + explicit `initialCategory` wins over mesh-less
+  auto-detect; Uploaded tab pages past the 100-item cap.
+- Closed without code: the "compat cache stales on streaming characters" finding (invalidated —
+  uuid-resolvable roots are always fully loaded) and the Tauri `promptSignup` gap (desktop is
+  always signed in by adapter contract).
+
+## Landed since the original handoff
+
+- **AnimationsModal** (was deferred — now built, `5f7ba7bbc5`/`79875d8c76`): standalone modal
+  with All / Presets / Uploaded tabs, opened from an "Add Animation" button next to Enter Pose
+  Mode and from the "+" add-asset menu. Adding a clip expands the timeline and scrolls to the
+  character (`timelineRevealObjectUuid`); the modal closes after an add unless "Reopen after
+  adding" is on. Its "Upload animation" button opens `UploadModal3D` with
+  `initialCategory="animation"` (anonymous users get the signup prompt), landing on the
+  Uploaded tab afterwards. `AssetModal`'s animations tab was folded into this.
+- **Timeline QoL**: ruler tick marks (major/second/sub-tick), selected-object-only track
+  filter, directional expand/collapse chevrons, thumbnail-less animation cards get an icon
+  placeholder.
+
+## Deferred (explicitly out of scope for this branch)
+
+- **Split-screen preview window** (based on the `?output=` `DemoOutputOverlay`) — parked until
+  explicit approval.
+- **Retargeting** (`SkeletonUtils.retargetClip`) — too complex for now; mismatched rigs are
+  simply rejected by the bind check.
+- **Clip blending/layering** — one non-overlapping row per object, by design.
+
+## Key files
+
+| Area                | Files                                                                                     |
+|---------------------|-------------------------------------------------------------------------------------------|
+| Drawer tab          | `pagescene/src/lib/comps/AssetMenu/AssetModal.tsx`, `shared/ItemElement.tsx`               |
+| Drag-and-drop       | `pagescene/src/lib/DragAndDrop/DndAsset.ts`, `gallery-modal/src/lib/DragGhost.tsx`         |
+| Timeline data/engine| `pagescene/src/lib/engine/timeline/types.ts`, `engine/editor/TimelineController.ts`,       |
+|                     | `engine/animation/CharacterAnimationManager.ts`, `engine/editor/actions/RemoveClipLaneAction.ts` |
+| Timeline UI         | `pagescene/src/lib/comps/Timeline/TimelineEditor.tsx`, `TimelineClipRow.tsx`               |
+| Skeleton toggle     | `pagescene/src/lib/engine/editor/SkeletonHelperController.ts`, `comps/Outliner/Outliner.tsx` |
+| Previewers          | `viewer-3d/src/lib/viewer-3d.tsx`, `upload-modal/.../utilities/loadPreviewOnCanvas.ts`     |
+| FBX + upload        | `upload-modal/.../utilities/convertFbxToGlb.ts` (+ `.worker.ts`), `UploadModal3D.tsx`,     |
+|                     | `UploadFiles3D.tsx`, `utilities/readGlbAnimationDuration.ts`                               |
+
+The pagescene `CLAUDE.md` "Mixamo animation clips" section has been kept current with these
+changes and carries the same invariants in engine-doc form.

crates/AGENTS.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, KinoviWeb, Muapi)
+- `artcraft_api_defs` — shared HTTP API type definitions
+- `kinovi_web_client` — HTTP client for the Kinovi/KinoviWeb 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/CLAUDE.md

@@ -1,59 +0,0 @@
-# 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, KinoviWeb, Muapi)
-- `artcraft_api_defs` — shared HTTP API type definitions
-- `kinovi_web_client` — HTTP client for the Kinovi/KinoviWeb 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/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

crates/api_clients/artcraft/artcraft_api_defs/AGENTS.md

@@ -0,0 +1,22 @@
+# artcraft_api_defs
+
+Shared HTTP API type definitions used by both the server (`storyteller_web`) and clients.
+
+## Structure
+
+Organized by feature: `users/`, `media_file/`, `jobs/`, `moderation/`, etc.
+
+## Conventions
+
+- Request types: `#[derive(Deserialize, ToSchema)]`
+- Response types: `#[derive(Serialize, ToSchema)]`
+- Path params: `#[derive(Deserialize, ToSchema)]` with `PathInfo` suffix
+- Query params: `#[derive(Deserialize, IntoParams)]`
+
+## Orphan Rule
+
+Types that need `ResponseError` impl (actix-web) CANNOT live here because of Rust's orphan rule. Keep error response types in `storyteller_web` and only put data types here.
+
+## Dependencies
+
+Only `serde`, `serde_derive`, `utoipa`, `chrono`, `url`, and internal schema crates (`enums`, `tokens`). No actix-web dependency.

crates/api_clients/artcraft/artcraft_api_defs/CLAUDE.md

@@ -1,22 +0,0 @@
-# artcraft_api_defs
-
-Shared HTTP API type definitions used by both the server (`storyteller_web`) and clients.
-
-## Structure
-
-Organized by feature: `users/`, `media_file/`, `jobs/`, `moderation/`, etc.
-
-## Conventions
-
-- Request types: `#[derive(Deserialize, ToSchema)]`
-- Response types: `#[derive(Serialize, ToSchema)]`
-- Path params: `#[derive(Deserialize, ToSchema)]` with `PathInfo` suffix
-- Query params: `#[derive(Deserialize, IntoParams)]`
-
-## Orphan Rule
-
-Types that need `ResponseError` impl (actix-web) CANNOT live here because of Rust's orphan rule. Keep error response types in `storyteller_web` and only put data types here.
-
-## Dependencies
-
-Only `serde`, `serde_derive`, `utoipa`, `chrono`, `url`, and internal schema crates (`enums`, `tokens`). No actix-web dependency.

crates/api_clients/artcraft/artcraft_api_defs/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

crates/api_clients/artcraft/artcraft_api_defs/src/internal/minimax_jobs/mark_minimax_job_failure.rs

@@ -0,0 +1,29 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use enums::by_table::generic_inference_jobs::frontend_failure_category::FrontendFailureCategory;
+
+/// Request body for `POST /v1/internal/minimax_jobs/job/{job_token}/failure`.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct MarkMinimaxJobFailureRequest {
+  /// Optional failure class the frontend can localize and present.
+  pub maybe_frontend_failure_category: Option<FrontendFailureCategory>,
+
+  /// Optional failure reason we can show the user (512 characters max).
+  pub maybe_user_failure_reason: Option<String>,
+
+  /// Optional internal-only stack trace or error (512 characters max).
+  pub maybe_internal_debugging_failure_reason: Option<String>,
+
+  /// Optional total wall-clock runtime of the failed attempt, in milliseconds.
+  pub execution_duration_millis: Option<u64>,
+
+  /// Optional inference-only runtime of the failed attempt, in milliseconds.
+  pub inference_duration_millis: Option<u64>,
+}
+
+/// Response body for `POST /v1/internal/minimax_jobs/job/{job_token}/failure`.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct MarkMinimaxJobFailureResponse {
+  pub success: bool,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/internal/minimax_jobs/mark_minimax_job_success.rs

@@ -0,0 +1,29 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use tokens::tokens::media_files::MediaFileToken;
+
+// NB: The success request is form-multipart (video bytes + optional
+// `duration_millis` / `width` / `height` metadata fields), so its form struct
+// lives with the actix handler; only the response shape is declared here.
+
+/// Response body for `POST /v1/internal/minimax_jobs/job/{job_token}/success`.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct MarkMinimaxJobSuccessResponse {
+  pub success: bool,
+
+  /// The media file created from the uploaded video.
+  pub media_file_token: MediaFileToken,
+
+  /// Video duration stored on the media file record, in milliseconds
+  /// (worker-supplied, or probed from the file when not supplied).
+  pub maybe_duration_millis: Option<u64>,
+
+  /// Frame width stored on the media file record, in pixels
+  /// (worker-supplied, or probed from the file when not supplied).
+  pub maybe_width: Option<u32>,
+
+  /// Frame height stored on the media file record, in pixels
+  /// (worker-supplied, or probed from the file when not supplied).
+  pub maybe_height: Option<u32>,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/internal/minimax_jobs/minimax_worker_model.rs

@@ -0,0 +1,33 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+/// The first-party Minimax models a worker can request jobs for.
+///
+/// This is deliberately its own enum (not `CommonVideoModel`) so the internal
+/// worker API surface stays small and stable.
+#[derive(Copy, Clone, Debug, Eq, PartialEq, Serialize, Deserialize, ToSchema)]
+pub enum MinimaxWorkerModel {
+  #[serde(rename = "minimax_h3_turbo")]
+  MinimaxH3Turbo,
+
+  #[serde(rename = "minimax_h3_ultra")]
+  MinimaxH3Ultra,
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn serde_round_trip() {
+    let cases = [
+      (MinimaxWorkerModel::MinimaxH3Turbo, "\"minimax_h3_turbo\""),
+      (MinimaxWorkerModel::MinimaxH3Ultra, "\"minimax_h3_ultra\""),
+    ];
+    for (variant, json) in cases {
+      assert_eq!(serde_json::to_string(&variant).unwrap(), json);
+      let parsed: MinimaxWorkerModel = serde_json::from_str(json).unwrap();
+      assert_eq!(parsed, variant);
+    }
+  }
+}

crates/api_clients/artcraft/artcraft_api_defs/src/internal/minimax_jobs/mod.rs

@@ -0,0 +1,4 @@
+pub mod mark_minimax_job_failure;
+pub mod mark_minimax_job_success;
+pub mod minimax_worker_model;
+pub mod obtain_minimax_job;

crates/api_clients/artcraft/artcraft_api_defs/src/internal/minimax_jobs/obtain_minimax_job.rs

@@ -0,0 +1,85 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use enums::by_table::prompt_context_items::prompt_context_semantic_type::PromptContextSemanticType;
+use enums::common::generation::common_aspect_ratio::CommonAspectRatio;
+use enums::common::generation::common_bitrate::CommonBitrate;
+use enums::common::generation::common_generation_mode::CommonGenerationMode;
+use enums::common::generation::common_resolution::CommonResolution;
+use tokens::tokens::generic_inference_jobs::InferenceJobToken;
+use tokens::tokens::media_files::MediaFileToken;
+use tokens::tokens::prompts::PromptToken;
+
+use crate::common::responses::media_links::MediaLinks;
+use crate::internal::minimax_jobs::minimax_worker_model::MinimaxWorkerModel;
+
+/// Request body for `POST /v1/internal/minimax_jobs/obtain_job`.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct ObtainMinimaxJobRequest {
+  /// Which model the worker wants a job for.
+  pub model: MinimaxWorkerModel,
+
+  /// The worker's hostname (linux hostname, k8s pod name), if reported.
+  pub worker_hostname: Option<String>,
+
+  /// The cluster the worker runs in (e.g. "runpod", "lambdalabs"), if reported.
+  pub cluster_name: Option<String>,
+}
+
+/// Response body for `POST /v1/internal/minimax_jobs/obtain_job`.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct ObtainMinimaxJobResponse {
+  pub success: bool,
+
+  /// The obtained job, or `None` when no pending job is available.
+  pub maybe_job: Option<ObtainedMinimaxJob>,
+}
+
+/// A job the worker now holds a lock on (status was moved to `started`).
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct ObtainedMinimaxJob {
+  pub job_token: InferenceJobToken,
+
+  /// Echo of the requested model.
+  pub model: MinimaxWorkerModel,
+
+  /// The prompt and inputs the worker needs to run inference. Only `None`
+  /// when the job was somehow enqueued without a prompt record (or the
+  /// prompt lookup failed) — workers should fail such jobs via the failure
+  /// endpoint.
+  pub maybe_prompt: Option<MinimaxJobPromptDetails>,
+}
+
+/// The prompt (text + generation settings) and its attached media references.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct MinimaxJobPromptDetails {
+  pub prompt_token: PromptToken,
+
+  pub maybe_positive_prompt: Option<String>,
+  pub maybe_negative_prompt: Option<String>,
+
+  pub maybe_generation_mode: Option<CommonGenerationMode>,
+  pub maybe_aspect_ratio: Option<CommonAspectRatio>,
+  pub maybe_resolution: Option<CommonResolution>,
+  pub maybe_bitrate: Option<CommonBitrate>,
+  pub maybe_generate_audio: Option<bool>,
+  pub maybe_duration_seconds: Option<u32>,
+
+  /// Image / video / audio references attached to the prompt, with full CDN
+  /// links, in their original order.
+  pub media_references: Vec<MinimaxJobMediaReference>,
+}
+
+/// One media input attached to the prompt (start frame, end frame, or an
+/// image / video / audio reference), with full CDN links.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct MinimaxJobMediaReference {
+  pub media_file_token: MediaFileToken,
+
+  /// The role the media plays (start frame, end frame, image / video / audio
+  /// reference, etc.).
+  pub semantic_type: PromptContextSemanticType,
+
+  /// Full CDN links to the media file.
+  pub media_links: MediaLinks,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/internal/mod.rs

@@ -0,0 +1,4 @@
+//! Internal-facing API surfaces (worker fleets, etc.). These are
+//! authenticated with internal API keys, never consumer credentials.
+
+pub mod minimax_jobs;

crates/api_clients/artcraft/artcraft_api_defs/src/lib.rs

@@ -5,7 +5,9 @@ pub mod common;
 pub mod credits;
 pub mod folders;
 pub mod generate;
+pub mod internal;
 pub mod jobs;
+pub mod mcp_sessions;
 pub mod media_file;
 pub mod moderation;
 pub mod omni_api;

crates/api_clients/artcraft/artcraft_api_defs/src/mcp_sessions/common.rs

@@ -0,0 +1,42 @@
+use chrono::{DateTime, Utc};
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use tokens::tokens::mcp_sessions::McpSessionToken;
+
+/// Canonical wire shape for an MCP session, used by the dashboard list.
+///
+/// NB: the secret `private_session_token` is NEVER included here — it is returned exactly once,
+/// at creation time. The `token` is the non-private management handle.
+#[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
+pub struct McpSessionInfo {
+  pub token: McpSessionToken,
+
+  /// Trimmed name of the MCP client that created the session, if any.
+  pub maybe_mcp_client_name: Option<String>,
+
+  /// Trimmed version of the MCP client, if any.
+  pub maybe_mcp_client_version: Option<String>,
+
+  /// Trimmed vendor of the MCP client, if any.
+  pub maybe_mcp_client_vendor: Option<String>,
+
+  pub ip_address_creation: String,
+  pub ip_address_update: String,
+
+  pub created_at: DateTime<Utc>,
+  pub updated_at: DateTime<Utc>,
+
+  /// When the session expires, if not refreshed.
+  pub expires_at: DateTime<Utc>,
+
+  /// Termination timestamp. `None` for live (though possibly expired) sessions.
+  pub maybe_deleted_at: Option<DateTime<Utc>>,
+}
+
+/// Path info for endpoints addressed by the session's management `token` (NOT the secret
+/// `private_session_token`): `POST /v1/mcp/session/{token}/delete`.
+#[derive(Deserialize, ToSchema)]
+pub struct McpSessionPathInfo {
+  pub token: McpSessionToken,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/mcp_sessions/create_mcp_session.rs

@@ -0,0 +1,34 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use tokens::tokens::mcp_session_private::McpSessionPrivateToken;
+use tokens::tokens::mcp_session_refresh::McpSessionRefreshToken;
+
+// ── POST /v1/mcp/session/create ──
+
+#[derive(Deserialize, ToSchema)]
+pub struct CreateMcpSessionRequest {
+  /// Name of the MCP client creating the session, if any.
+  pub maybe_mcp_client_name: Option<String>,
+
+  /// Version of the MCP client, if any.
+  pub maybe_mcp_client_version: Option<String>,
+
+  /// Vendor of the MCP client, if any.
+  pub maybe_mcp_client_vendor: Option<String>,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct CreateMcpSessionSuccessResponse {
+  pub success: bool,
+
+  /// The secret credential the MCP client presents in the `Authorization` header. This is the
+  /// ONLY time it is ever returned — the caller must store it now, as it cannot be retrieved
+  /// again.
+  pub private_session_token: McpSessionPrivateToken,
+
+  /// The secret credential the MCP client presents on `/v1/mcp/session/refresh` to extend the
+  /// session. Each successful refresh returns a NEW refresh token and invalidates this one —
+  /// store whichever value is newest.
+  pub private_refresh_token: McpSessionRefreshToken,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/mcp_sessions/delete_mcp_session.rs

@@ -0,0 +1,9 @@
+use serde_derive::Serialize;
+use utoipa::ToSchema;
+
+// ── POST /v1/mcp/session/{token}/delete ──
+
+#[derive(Serialize, ToSchema)]
+pub struct DeleteMcpSessionSuccessResponse {
+  pub success: bool,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/mcp_sessions/list_mcp_sessions.rs

@@ -0,0 +1,24 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::{IntoParams, ToSchema};
+
+use crate::mcp_sessions::common::McpSessionInfo;
+
+// ── GET /v1/mcp/session/list ──
+
+#[derive(Deserialize, ToSchema, IntoParams)]
+pub struct ListMcpSessionsQueryParams {
+  /// Page size. Defaults server-side if omitted.
+  pub limit: Option<u32>,
+
+  /// Number of rows to skip. Defaults to 0.
+  pub offset: Option<u32>,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct ListMcpSessionsSuccessResponse {
+  pub success: bool,
+
+  /// The user's MCP sessions (including terminated ones), newest first. The secret
+  /// `private_session_token` is never listed.
+  pub mcp_sessions: Vec<McpSessionInfo>,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/mcp_sessions/mod.rs

@@ -0,0 +1,6 @@
+pub mod common;
+pub mod create_mcp_session;
+pub mod delete_mcp_session;
+pub mod list_mcp_sessions;
+pub mod refresh_mcp_session;
+pub mod revoke_mcp_session;

crates/api_clients/artcraft/artcraft_api_defs/src/mcp_sessions/refresh_mcp_session.rs

@@ -0,0 +1,22 @@
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use tokens::tokens::mcp_session_refresh::McpSessionRefreshToken;
+
+// ── POST /v1/mcp/session/refresh ──
+
+#[derive(Deserialize, ToSchema)]
+pub struct RefreshMcpSessionRequest {
+  /// The session's CURRENT refresh token (from creation, or from the most recent refresh).
+  /// A stale or wrong value is an error — refresh tokens rotate and are never replayable.
+  pub private_refresh_token: McpSessionRefreshToken,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct RefreshMcpSessionSuccessResponse {
+  pub success: bool,
+
+  /// The NEW refresh token to present on the next refresh. The one just used is now invalid —
+  /// the caller must store this replacement.
+  pub private_refresh_token: McpSessionRefreshToken,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/mcp_sessions/revoke_mcp_session.rs

@@ -0,0 +1,9 @@
+use serde_derive::Serialize;
+use utoipa::ToSchema;
+
+// ── POST /v1/mcp/session/revoke ──
+
+#[derive(Serialize, ToSchema)]
+pub struct RevokeMcpSessionSuccessResponse {
+  pub success: bool,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/media_file/job/list_media_files_by_job.rs

@@ -0,0 +1,61 @@
+//! Types for `GET /v1/media_files/by_job/{job_token}` — list the media files
+//! produced by an inference job.
+
+use chrono::{DateTime, Utc};
+use serde_derive::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use enums::by_table::media_files::media_file_class::MediaFileClass;
+use enums::by_table::media_files::media_file_type::MediaFileType;
+use tokens::tokens::batch_generations::BatchGenerationToken;
+use tokens::tokens::media_files::MediaFileToken;
+use tokens::tokens::prompts::PromptToken;
+
+use crate::common::responses::media_file_cover_image_details::MediaFileCoverImageDetails;
+use crate::common::responses::media_links::MediaLinks;
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct ListMediaFilesByJobSuccessResponse {
+  pub success: bool,
+
+  /// The job's output files, oldest first.
+  pub media_files: Vec<JobMediaFileInfo>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct JobMediaFileInfo {
+  pub token: MediaFileToken,
+
+  /// The coarse-grained class of media file: image, video, etc.
+  pub media_class: MediaFileClass,
+
+  /// Type of media will dictate which fields are populated and what
+  /// the frontend should display (eg. video player vs audio player).
+  /// This is closer in meaning to a "mime type".
+  pub media_type: MediaFileType,
+
+  /// If the file was generated as part of a batch, this is the token for the batch.
+  pub maybe_batch_token: Option<BatchGenerationToken>,
+
+  /// The foreign key to the prompt used to generate the media, if applicable.
+  pub maybe_prompt_token: Option<PromptToken>,
+
+  /// Rich CDN links to the media, including thumbnails, previews, and more.
+  pub media_links: MediaLinks,
+
+  /// Information about the cover image. Many media files do not require a cover image,
+  /// e.g. image files, video files with thumbnails, audio files, etc.
+  /// 3D files require them.
+  pub cover_image: MediaFileCoverImageDetails,
+
+  /// The original filename for uploaded files, if they were provided.
+  /// In the future we'll provide our own internal optional filenames.
+  pub maybe_original_filename: Option<String>,
+
+  /// Duration for audio and video files, if available.
+  /// Measured in milliseconds.
+  pub maybe_duration_millis: Option<u64>,
+
+  pub created_at: DateTime<Utc>,
+  pub updated_at: DateTime<Utc>,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/media_file/job/mod.rs

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

crates/api_clients/artcraft/artcraft_api_defs/src/media_file/mod.rs

@@ -1,4 +1,5 @@
 pub mod delete_media_file;
+pub mod job;
 pub mod list;
 pub mod list_batch_generated_media_files;
 pub mod list_session_project_media_files;

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

@@ -69,4 +69,23 @@ pub struct OmniGenVideoCostAndGenerateRequest {
   /// Some models will default this to true, others will default it to false,
   /// so it's best to be explicit.
   pub generate_audio: Option<bool>,
+
+  /// Frontend-supplied hints for cost estimation only. IGNORED by
+  /// generation — the generate endpoints measure inputs themselves (e.g.
+  /// ffprobing reference videos) and bill from those measurements.
+  pub estimate_only: Option<EstimateFields>,
+}
+
+/// These fields are ignored by generation. They're only used by the frontend
+/// to aid in cost estimation (e.g. Seedance 2.5 bills reference-video input
+/// seconds, so the cost quote needs the combined input duration without the
+/// server downloading and probing the files on every poll).
+#[derive(Clone, Copy, Serialize, Deserialize, ToSchema, Debug, Default)]
+pub struct EstimateFields {
+  /// Combined duration of all reference video inputs, in milliseconds.
+  pub total_input_video_duration_millis: Option<u32>,
+
+  /// Combined duration of all reference audio inputs, in milliseconds.
+  /// (No model bills audio input seconds yet; accepted for future models.)
+  pub total_input_audio_duration_millis: Option<u32>,
 }

crates/api_clients/artcraft/artcraft_client/src/datatypes/common_enums/generation/api_client_generation_provider.rs

@@ -14,6 +14,14 @@ pub enum ApiClientGenerationProvider {
   Midjourney,
   Sora,
   WorldLabs,
+  Higgsfield,
+  Krea,
+  Leonardo,
+  Magnific,
+  Openart,
+  Picsart,
+  Pixverse,
+  Runway,
   /// A value not known to this client build (preserved as-is).
   Unknown(String),
 }
@@ -27,6 +35,14 @@ impl From<String> for ApiClientGenerationProvider {
       "midjourney" => Self::Midjourney,
       "sora" => Self::Sora,
       "world_labs" => Self::WorldLabs,
+      "higgsfield" => Self::Higgsfield,
+      "krea" => Self::Krea,
+      "leonardo" => Self::Leonardo,
+      "magnific" => Self::Magnific,
+      "openart" => Self::Openart,
+      "picsart" => Self::Picsart,
+      "pixverse" => Self::Pixverse,
+      "runway" => Self::Runway,
       _ => Self::Unknown(value),
     }
   }
@@ -41,6 +57,14 @@ impl From<ApiClientGenerationProvider> for String {
       ApiClientGenerationProvider::Midjourney => "midjourney".to_string(),
       ApiClientGenerationProvider::Sora => "sora".to_string(),
       ApiClientGenerationProvider::WorldLabs => "world_labs".to_string(),
+      ApiClientGenerationProvider::Higgsfield => "higgsfield".to_string(),
+      ApiClientGenerationProvider::Krea => "krea".to_string(),
+      ApiClientGenerationProvider::Leonardo => "leonardo".to_string(),
+      ApiClientGenerationProvider::Magnific => "magnific".to_string(),
+      ApiClientGenerationProvider::Openart => "openart".to_string(),
+      ApiClientGenerationProvider::Picsart => "picsart".to_string(),
+      ApiClientGenerationProvider::Pixverse => "pixverse".to_string(),
+      ApiClientGenerationProvider::Runway => "runway".to_string(),
       ApiClientGenerationProvider::Unknown(other) => other,
     }
   }
@@ -73,6 +97,14 @@ mod tests {
       (ApiClientGenerationProvider::Midjourney, "midjourney"),
       (ApiClientGenerationProvider::Sora, "sora"),
       (ApiClientGenerationProvider::WorldLabs, "world_labs"),
+      (ApiClientGenerationProvider::Higgsfield, "higgsfield"),
+      (ApiClientGenerationProvider::Krea, "krea"),
+      (ApiClientGenerationProvider::Leonardo, "leonardo"),
+      (ApiClientGenerationProvider::Magnific, "magnific"),
+      (ApiClientGenerationProvider::Openart, "openart"),
+      (ApiClientGenerationProvider::Picsart, "picsart"),
+      (ApiClientGenerationProvider::Pixverse, "pixverse"),
+      (ApiClientGenerationProvider::Runway, "runway"),
     ];
     for (variant, s) in all {
       assert_eq!(String::from(variant.clone()), s, "serialize mismatch for {:?}", variant);

crates/api_clients/artcraft/artcraft_client/src/datatypes/common_enums/generation/api_client_image_model.rs

@@ -16,6 +16,8 @@ pub enum ApiClientImageModel {
   GptImage1p5,
   GptImage2,
   GrokImagineImage,
+  GptImage2p5Flare,
+  GptImage2p5Sunburst,
   GrokImagineImageQuality,
   Midjourney7,
   Midjourney7Niji,
@@ -42,6 +44,8 @@ impl From<String> for ApiClientImageModel {
       "gpt_image_1" => Self::GptImage1,
       "gpt_image_1p5" => Self::GptImage1p5,
       "gpt_image_2" => Self::GptImage2,
+      "gpt_image_2p5_flare" => Self::GptImage2p5Flare,
+      "gpt_image_2p5_sunburst" => Self::GptImage2p5Sunburst,
       "grok_imagine_image" => Self::GrokImagineImage,
       "grok_imagine_image_q" => Self::GrokImagineImageQuality,
       "midjourney_7" => Self::Midjourney7,
@@ -70,6 +74,8 @@ impl From<ApiClientImageModel> for String {
       ApiClientImageModel::GptImage1 => "gpt_image_1".to_string(),
       ApiClientImageModel::GptImage1p5 => "gpt_image_1p5".to_string(),
       ApiClientImageModel::GptImage2 => "gpt_image_2".to_string(),
+      ApiClientImageModel::GptImage2p5Flare => "gpt_image_2p5_flare".to_string(),
+      ApiClientImageModel::GptImage2p5Sunburst => "gpt_image_2p5_sunburst".to_string(),
       ApiClientImageModel::GrokImagineImage => "grok_imagine_image".to_string(),
       ApiClientImageModel::GrokImagineImageQuality => "grok_imagine_image_q".to_string(),
       ApiClientImageModel::Midjourney7 => "midjourney_7".to_string(),
@@ -116,6 +122,8 @@ mod tests {
       (ApiClientImageModel::GptImage1, "gpt_image_1"),
       (ApiClientImageModel::GptImage1p5, "gpt_image_1p5"),
       (ApiClientImageModel::GptImage2, "gpt_image_2"),
+      (ApiClientImageModel::GptImage2p5Flare, "gpt_image_2p5_flare"),
+      (ApiClientImageModel::GptImage2p5Sunburst, "gpt_image_2p5_sunburst"),
       (ApiClientImageModel::GrokImagineImage, "grok_imagine_image"),
       (ApiClientImageModel::GrokImagineImageQuality, "grok_imagine_image_q"),
       (ApiClientImageModel::Midjourney7, "midjourney_7"),

crates/api_clients/artcraft/artcraft_client/src/datatypes/common_enums/generation/api_client_video_model.rs

@@ -25,8 +25,6 @@ pub enum ApiClientVideoModel {
   Seedance2p0Fast,
   Seedance2p0BytePlus,
   Seedance2p0BytePlusFast,
-  Seedance2p0Ultra,
-  Seedance2p0UltraFast,
   Seedance2p0BytePlusUltra,
   Seedance2p0BytePlusUltraFast,
   Seedance2p0Mini,
@@ -65,8 +63,6 @@ impl From<String> for ApiClientVideoModel {
       "seedance_2p0_fast" => Self::Seedance2p0Fast,
       "seedance_2p0_bp" => Self::Seedance2p0BytePlus,
       "seedance_2p0_bp_fast" => Self::Seedance2p0BytePlusFast,
-      "seedance_2p0_u" => Self::Seedance2p0Ultra,
-      "seedance_2p0_u_fast" => Self::Seedance2p0UltraFast,
       "seedance_2p0_bpu" => Self::Seedance2p0BytePlusUltra,
       "seedance_2p0_bpu_fast" => Self::Seedance2p0BytePlusUltraFast,
       "seedance_2p0_mini" => Self::Seedance2p0Mini,
@@ -106,8 +102,6 @@ impl From<ApiClientVideoModel> for String {
       ApiClientVideoModel::Seedance2p0Fast => "seedance_2p0_fast".to_string(),
       ApiClientVideoModel::Seedance2p0BytePlus => "seedance_2p0_bp".to_string(),
       ApiClientVideoModel::Seedance2p0BytePlusFast => "seedance_2p0_bp_fast".to_string(),
-      ApiClientVideoModel::Seedance2p0Ultra => "seedance_2p0_u".to_string(),
-      ApiClientVideoModel::Seedance2p0UltraFast => "seedance_2p0_u_fast".to_string(),
       ApiClientVideoModel::Seedance2p0BytePlusUltra => "seedance_2p0_bpu".to_string(),
       ApiClientVideoModel::Seedance2p0BytePlusUltraFast => "seedance_2p0_bpu_fast".to_string(),
       ApiClientVideoModel::Seedance2p0Mini => "seedance_2p0_mini".to_string(),
@@ -165,8 +159,6 @@ mod tests {
       (ApiClientVideoModel::Seedance2p0Fast, "seedance_2p0_fast"),
       (ApiClientVideoModel::Seedance2p0BytePlus, "seedance_2p0_bp"),
       (ApiClientVideoModel::Seedance2p0BytePlusFast, "seedance_2p0_bp_fast"),
-      (ApiClientVideoModel::Seedance2p0Ultra, "seedance_2p0_u"),
-      (ApiClientVideoModel::Seedance2p0UltraFast, "seedance_2p0_u_fast"),
       (ApiClientVideoModel::Seedance2p0BytePlusUltra, "seedance_2p0_bpu"),
       (ApiClientVideoModel::Seedance2p0BytePlusUltraFast, "seedance_2p0_bpu_fast"),
       (ApiClientVideoModel::Seedance2p0Mini, "seedance_2p0_mini"),

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

@@ -19,6 +19,10 @@ pub enum RouterImageModel {
   GptImage1p5,
   #[serde(rename = "gpt_image_2")]
   GptImage2,
+  #[serde(rename = "gpt_image_2p5_flare")]
+  GptImage2p5Flare,
+  #[serde(rename = "gpt_image_2p5_sunburst")]
+  GptImage2p5Sunburst,
   #[serde(rename = "grok_imagine_image")]
   GrokImagineImage,
   #[serde(rename = "grok_imagine_image_q")]
@@ -87,4 +91,14 @@ mod tests {
   fn seedream_5p0_pro_ultra_serializes_to_seedream_5p0_pro_u() {
     assert_round_trip(RouterImageModel::Seedream5p0ProUltra, "seedream_5p0_pro_u");
   }
+
+  #[test]
+  fn gpt_image_2p5_flare_serializes_to_gpt_image_2p5_flare() {
+    assert_round_trip(RouterImageModel::GptImage2p5Flare, "gpt_image_2p5_flare");
+  }
+
+  #[test]
+  fn gpt_image_2p5_sunburst_serializes_to_gpt_image_2p5_sunburst() {
+    assert_round_trip(RouterImageModel::GptImage2p5Sunburst, "gpt_image_2p5_sunburst");
+  }
 }

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

@@ -14,6 +14,12 @@ pub enum RouterVideoModel {
   #[serde(rename = "grok_imagine_video_1p5")]
   GrokImagineVideo1p5,
 
+  #[serde(rename = "flux_3")]
+  Flux3,
+
+  #[serde(rename = "flux_3_draft")]
+  Flux3Draft,
+
   #[serde(rename = "kling_1p6_pro")]
   Kling16Pro,
 
@@ -35,6 +41,15 @@ pub enum RouterVideoModel {
   #[serde(rename = "kling_3p0_pro")]
   Kling3p0Pro,
 
+  #[serde(rename = "minimax_h3")]
+  MinimaxH3,
+
+  #[serde(rename = "minimax_h3_turbo")]
+  MinimaxH3Turbo,
+
+  #[serde(rename = "minimax_h3_ultra")]
+  MinimaxH3Ultra,
+
   #[serde(rename = "seedance_1p0_lite")]
   Seedance10Lite,
 
@@ -53,11 +68,7 @@ pub enum RouterVideoModel {
   #[serde(rename = "seedance_2p0_bp_fast")]
   Seedance2p0BytePlusFast,
 
-  #[serde(rename = "seedance_2p0_u")]
-  Seedance2p0Ultra,
 
-  #[serde(rename = "seedance_2p0_u_fast")]
-  Seedance2p0UltraFast,
 
   #[serde(rename = "seedance_2p0_bpu")]
   Seedance2p0BytePlusUltra,
@@ -77,6 +88,12 @@ pub enum RouterVideoModel {
   #[serde(rename = "seedance_2p5_preview")]
   Seedance2p5Preview,
 
+  #[serde(rename = "seedance_2p5")]
+  Seedance2p5,
+
+  #[serde(rename = "seedance_2p5_u")]
+  Seedance2p5Ultra,
+
   #[serde(rename = "happy_horse_1p0")]
   HappyHorse1p0,
 
@@ -141,6 +158,20 @@ mod tests {
     assert_serde_round_trip(RouterVideoModel::Seedance2p5Preview, "seedance_2p5_preview");
   }
 
+  #[test]
+  fn seedance_2p5_serializes() {
+    // NB: This string must match `CommonVideoModel` — the two enums convert
+    // via serde string round-trip in the omni handlers.
+    assert_serde_round_trip(RouterVideoModel::Seedance2p5, "seedance_2p5");
+  }
+
+  #[test]
+  fn seedance_2p5_ultra_serializes() {
+    // NB: This string must match `CommonVideoModel` — the two enums convert
+    // via serde string round-trip in the omni handlers.
+    assert_serde_round_trip(RouterVideoModel::Seedance2p5Ultra, "seedance_2p5_u");
+  }
+
   #[test]
   fn veo_3p1_lite_and_vidu_variants_serialize() {
     // NB: These strings must match `CommonVideoModel` — the two enums convert
@@ -149,4 +180,27 @@ mod tests {
     assert_serde_round_trip(RouterVideoModel::ViduQ3, "vidu_q3");
     assert_serde_round_trip(RouterVideoModel::ViduQ3Turbo, "vidu_q3_turbo");
   }
+
+  #[test]
+  fn flux_3_variants_serialize() {
+    // NB: These strings must match `CommonVideoModel` — the two enums convert
+    // via serde string round-trip in the omni handlers.
+    assert_serde_round_trip(RouterVideoModel::Flux3, "flux_3");
+    assert_serde_round_trip(RouterVideoModel::Flux3Draft, "flux_3_draft");
+  }
+
+  #[test]
+  fn minimax_h3_serializes() {
+    // NB: This string must match `CommonVideoModel` — the two enums convert
+    // via serde string round-trip in the omni handlers.
+    assert_serde_round_trip(RouterVideoModel::MinimaxH3, "minimax_h3");
+  }
+
+  #[test]
+  fn minimax_h3_turbo_and_ultra_serialize() {
+    // NB: These strings must match `CommonVideoModel` — the two enums convert
+    // via serde string round-trip in the omni handlers.
+    assert_serde_round_trip(RouterVideoModel::MinimaxH3Turbo, "minimax_h3_turbo");
+    assert_serde_round_trip(RouterVideoModel::MinimaxH3Ultra, "minimax_h3_ultra");
+  }
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_audio/providers/kinovi/resolve.rs

@@ -71,7 +71,7 @@ pub(crate) async fn resolve_and_upload_audio_ref(
       })?
     }
   };
-  upload_to_kinovi_web(session, &source_url).await
+  upload_to_kinovi_web(session, &source_url, None).await
 }
 
 #[cfg(test)]

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/generate_image_request_builder.rs

@@ -16,6 +16,8 @@ use crate::generate::generate_image::providers::artcraft::flux_pro_1p1_ultra::bu
 use crate::generate::generate_image::providers::artcraft::gpt_image_1::build::build_artcraft_gpt_image_1;
 use crate::generate::generate_image::providers::artcraft::gpt_image_1p5::build::build_artcraft_gpt_image_1p5;
 use crate::generate::generate_image::providers::artcraft::gpt_image_2::build::build_artcraft_gpt_image_2;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_flare::build::build_artcraft_gpt_image_2p5_flare;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_sunburst::build::build_artcraft_gpt_image_2p5_sunburst;
 use crate::generate::generate_image::providers::artcraft::midjourney_7::build::build_artcraft_midjourney_7;
 use crate::generate::generate_image::providers::artcraft::midjourney_7_niji::build::build_artcraft_midjourney_7_niji;
 use crate::generate::generate_image::providers::artcraft::midjourney_8::build::build_artcraft_midjourney_8;
@@ -36,6 +38,8 @@ use crate::generate::generate_image::providers::fal::flux_pro_1p1_ultra::build::
 use crate::generate::generate_image::providers::fal::gpt_image_1::build::build_fal_gpt_image_1;
 use crate::generate::generate_image::providers::fal::gpt_image_1p5::build::build_fal_gpt_image_1p5;
 use crate::generate::generate_image::providers::fal::gpt_image_2::build::build_fal_gpt_image_2;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_flare::build::build_fal_gpt_image_2p5_flare;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_sunburst::build::build_fal_gpt_image_2p5_sunburst;
 use crate::generate::generate_image::providers::fal::nano_banana::build::build_fal_nano_banana;
 use crate::generate::generate_image::providers::fal::nano_banana_2::build::build_fal_nano_banana_2;
 use crate::generate::generate_image::providers::fal::nano_banana_pro::build::build_fal_nano_banana_pro;
@@ -116,6 +120,8 @@ impl GenerateImageRequestBuilder {
       (RouterProvider::Artcraft, RouterImageModel::GptImage1) => build_artcraft_gpt_image_1(self),
       (RouterProvider::Artcraft, RouterImageModel::GptImage1p5) => build_artcraft_gpt_image_1p5(self),
       (RouterProvider::Artcraft, RouterImageModel::GptImage2) => build_artcraft_gpt_image_2(self),
+      (RouterProvider::Artcraft, RouterImageModel::GptImage2p5Flare) => build_artcraft_gpt_image_2p5_flare(self),
+      (RouterProvider::Artcraft, RouterImageModel::GptImage2p5Sunburst) => build_artcraft_gpt_image_2p5_sunburst(self),
       (RouterProvider::Artcraft, RouterImageModel::NanoBanana) => build_artcraft_nano_banana(self),
       (RouterProvider::Artcraft, RouterImageModel::NanoBanana2) => build_artcraft_nano_banana_2(self),
       (RouterProvider::Artcraft, RouterImageModel::NanoBananaPro) => build_artcraft_nano_banana_pro(self),
@@ -137,6 +143,8 @@ impl GenerateImageRequestBuilder {
       (RouterProvider::Fal, RouterImageModel::GptImage1) => build_fal_gpt_image_1(self),
       (RouterProvider::Fal, RouterImageModel::GptImage1p5) => build_fal_gpt_image_1p5(self),
       (RouterProvider::Fal, RouterImageModel::GptImage2) => build_fal_gpt_image_2(self),
+      (RouterProvider::Fal, RouterImageModel::GptImage2p5Flare) => build_fal_gpt_image_2p5_flare(self),
+      (RouterProvider::Fal, RouterImageModel::GptImage2p5Sunburst) => build_fal_gpt_image_2p5_sunburst(self),
       (RouterProvider::Fal, RouterImageModel::NanoBanana) => build_fal_nano_banana(self),
       (RouterProvider::Fal, RouterImageModel::NanoBanana2) => build_fal_nano_banana_2(self),
       (RouterProvider::Fal, RouterImageModel::NanoBananaPro) => build_fal_nano_banana_pro(self),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/image_generation_request.rs

@@ -19,6 +19,10 @@ use crate::generate::generate_image::providers::artcraft::gpt_image_1p5::cost::A
 use crate::generate::generate_image::providers::artcraft::gpt_image_1p5::request::ArtcraftGptImage1p5RequestState;
 use crate::generate::generate_image::providers::artcraft::gpt_image_2::cost::ArtcraftGptImage2CostState;
 use crate::generate::generate_image::providers::artcraft::gpt_image_2::request::ArtcraftGptImage2RequestState;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_flare::cost::ArtcraftGptImage2p5FlareCostState;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_flare::request::ArtcraftGptImage2p5FlareRequestState;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_sunburst::cost::ArtcraftGptImage2p5SunburstCostState;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_sunburst::request::ArtcraftGptImage2p5SunburstRequestState;
 use crate::generate::generate_image::providers::artcraft::midjourney_7::cost::ArtcraftMidjourney7CostState;
 use crate::generate::generate_image::providers::artcraft::midjourney_7::request::ArtcraftMidjourney7RequestState;
 use crate::generate::generate_image::providers::artcraft::midjourney_7_niji::cost::ArtcraftMidjourney7NijiCostState;
@@ -59,6 +63,10 @@ use crate::generate::generate_image::providers::fal::gpt_image_1p5::cost::FalGpt
 use crate::generate::generate_image::providers::fal::gpt_image_1p5::request::FalGptImage1p5RequestState;
 use crate::generate::generate_image::providers::fal::gpt_image_2::cost::FalGptImage2CostState;
 use crate::generate::generate_image::providers::fal::gpt_image_2::request::FalGptImage2RequestState;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_flare::cost::FalGptImage2p5FlareCostState;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_flare::request::FalGptImage2p5FlareRequestState;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_sunburst::cost::FalGptImage2p5SunburstCostState;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_sunburst::request::FalGptImage2p5SunburstRequestState;
 use crate::generate::generate_image::providers::fal::nano_banana::cost::FalNanoBananaCostState;
 use crate::generate::generate_image::providers::fal::nano_banana::request::FalNanoBananaRequestState;
 use crate::generate::generate_image::providers::fal::nano_banana_2::cost::FalNanoBanana2CostState;
@@ -92,6 +100,8 @@ pub enum ImageGenerationRequest {
   ArtcraftGptImage1(ArtcraftGptImage1RequestState),
   ArtcraftGptImage1p5(ArtcraftGptImage1p5RequestState),
   ArtcraftGptImage2(ArtcraftGptImage2RequestState),
+  ArtcraftGptImage2p5Flare(ArtcraftGptImage2p5FlareRequestState),
+  ArtcraftGptImage2p5Sunburst(ArtcraftGptImage2p5SunburstRequestState),
   ArtcraftNanoBanana(ArtcraftNanoBananaRequestState),
   ArtcraftNanoBanana2(ArtcraftNanoBanana2RequestState),
   ArtcraftNanoBananaPro(ArtcraftNanoBananaProRequestState),
@@ -114,6 +124,8 @@ pub enum ImageGenerationRequest {
   FalGptImage1(FalGptImage1RequestState),
   FalGptImage1p5(FalGptImage1p5RequestState),
   FalGptImage2(FalGptImage2RequestState),
+  FalGptImage2p5Flare(FalGptImage2p5FlareRequestState),
+  FalGptImage2p5Sunburst(FalGptImage2p5SunburstRequestState),
   FalNanoBanana(FalNanoBananaRequestState),
   FalNanoBanana2(FalNanoBanana2RequestState),
   FalNanoBananaPro(FalNanoBananaProRequestState),
@@ -140,6 +152,8 @@ impl ImageGenerationRequest {
       Self::ArtcraftGptImage1(_) => RouterProvider::Artcraft,
       Self::ArtcraftGptImage1p5(_) => RouterProvider::Artcraft,
       Self::ArtcraftGptImage2(_) => RouterProvider::Artcraft,
+      Self::ArtcraftGptImage2p5Flare(_) => RouterProvider::Artcraft,
+      Self::ArtcraftGptImage2p5Sunburst(_) => RouterProvider::Artcraft,
       Self::ArtcraftNanoBanana(_) => RouterProvider::Artcraft,
       Self::ArtcraftNanoBanana2(_) => RouterProvider::Artcraft,
       Self::ArtcraftNanoBananaPro(_) => RouterProvider::Artcraft,
@@ -161,6 +175,8 @@ impl ImageGenerationRequest {
       Self::FalGptImage1(_) => RouterProvider::Fal,
       Self::FalGptImage1p5(_) => RouterProvider::Fal,
       Self::FalGptImage2(_) => RouterProvider::Fal,
+      Self::FalGptImage2p5Flare(_) => RouterProvider::Fal,
+      Self::FalGptImage2p5Sunburst(_) => RouterProvider::Fal,
       Self::FalNanoBanana(_) => RouterProvider::Fal,
       Self::FalNanoBanana2(_) => RouterProvider::Fal,
       Self::FalNanoBananaPro(_) => RouterProvider::Fal,
@@ -201,6 +217,12 @@ impl ImageGenerationRequest {
       Self::ArtcraftGptImage2(request) => {
         Ok(ArtcraftGptImage2CostState::from_request(request).estimate_cost())
       }
+      Self::ArtcraftGptImage2p5Flare(request) => {
+        Ok(ArtcraftGptImage2p5FlareCostState::from_request(request).estimate_cost())
+      }
+      Self::ArtcraftGptImage2p5Sunburst(request) => {
+        Ok(ArtcraftGptImage2p5SunburstCostState::from_request(request).estimate_cost())
+      }
       Self::ArtcraftNanoBanana(request) => {
         Ok(ArtcraftNanoBananaCostState::from_request(request).estimate_cost())
       }
@@ -249,6 +271,8 @@ impl ImageGenerationRequest {
       Self::FalGptImage1(request) => Ok(FalGptImage1CostState::from_request(request).estimate_cost()),
       Self::FalGptImage1p5(request) => Ok(FalGptImage1p5CostState::from_request(request).estimate_cost()),
       Self::FalGptImage2(request) => Ok(FalGptImage2CostState::from_request(request).estimate_cost()),
+      Self::FalGptImage2p5Flare(request) => Ok(FalGptImage2p5FlareCostState::from_request(request).estimate_cost()),
+      Self::FalGptImage2p5Sunburst(request) => Ok(FalGptImage2p5SunburstCostState::from_request(request).estimate_cost()),
       Self::FalNanoBanana(request) => Ok(FalNanoBananaCostState::from_request(request).estimate_cost()),
       Self::FalNanoBanana2(request) => Ok(FalNanoBanana2CostState::from_request(request).estimate_cost()),
       Self::FalNanoBananaPro(request) => Ok(FalNanoBananaProCostState::from_request(request).estimate_cost()),
@@ -296,6 +320,14 @@ impl ImageGenerationRequest {
         let artcraft_client = client.get_artcraft_client_ref()?;
         request.send(artcraft_client).await
       }
+      Self::ArtcraftGptImage2p5Flare(request) => {
+        let artcraft_client = client.get_artcraft_client_ref()?;
+        request.send(artcraft_client).await
+      }
+      Self::ArtcraftGptImage2p5Sunburst(request) => {
+        let artcraft_client = client.get_artcraft_client_ref()?;
+        request.send(artcraft_client).await
+      }
       Self::ArtcraftNanoBanana(request) => {
         let artcraft_client = client.get_artcraft_client_ref()?;
         request.send(artcraft_client).await
@@ -379,6 +411,14 @@ impl ImageGenerationRequest {
         let fal_client = client.get_fal_client_ref()?;
         request.send(fal_client).await
       }
+      Self::FalGptImage2p5Flare(request) => {
+        let fal_client = client.get_fal_client_ref()?;
+        request.send(fal_client).await
+      }
+      Self::FalGptImage2p5Sunburst(request) => {
+        let fal_client = client.get_fal_client_ref()?;
+        request.send(fal_client).await
+      }
       Self::FalNanoBanana(request) => {
         // nano_banana (Gemini 2.5 Flash) is webhook-required.
         let fal_client = client.get_fal_client_ref()?;

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/artcraft/build_common.rs

@@ -22,14 +22,15 @@ use crate::generate::generate_image::generate_image_request_builder::GenerateIma
 /// Per-model build functions are expected to validate model-specific
 /// constraints (e.g. unsupported aspect ratios) BEFORE calling this helper.
 /// Validation that's identical across every Artcraft image model — batch count
-/// (1..=4) and image_inputs shape — lives here.
+/// (1..=[`max_batch_count`]) and image_inputs shape — lives here.
 pub fn build_artcraft_omni_image_request(
   builder: GenerateImageRequestBuilder,
   model: CommonImageModelEnum,
 ) -> Result<OmniGenImageCostAndGenerateRequest, ArtcraftRouterError> {
   let strategy = builder.request_mismatch_mitigation_strategy;
 
-  let image_batch_count = plan_batch_count(builder.image_batch_count, strategy)?;
+  let image_batch_count =
+    plan_batch_count_with_max(builder.image_batch_count, strategy, max_batch_count(model))?;
   let image_media_tokens = resolve_image_list_ref(builder.image_inputs.clone())?;
 
   let aspect_ratio = builder.aspect_ratio.map(to_aspect_ratio_enum);
@@ -52,26 +53,47 @@ pub fn build_artcraft_omni_image_request(
   })
 }
 
+/// The largest batch each Artcraft image model accepts. Seedream 5.0 Pro and
+/// Ultra accept batches of up to 8; every other model caps at 4.
+pub fn max_batch_count(model: CommonImageModelEnum) -> u16 {
+  match model {
+    CommonImageModelEnum::Seedream5p0Pro | CommonImageModelEnum::Seedream5p0ProUltra => 8,
+    _ => 4,
+  }
+}
+
 /// Validate batch count (1..=4). Mirrors the v1 plan-level validation that
 /// every Artcraft image model performs.
 pub fn plan_batch_count(
   image_batch_count: Option<u16>,
   strategy: RequestMismatchMitigationStrategy,
+) -> Result<u16, ArtcraftRouterError> {
+  plan_batch_count_with_max(image_batch_count, strategy, 4)
+}
+
+/// Validate batch count (1..=`max`), clamping or erroring per the mitigation
+/// strategy when the request exceeds the model's cap.
+pub fn plan_batch_count_with_max(
+  image_batch_count: Option<u16>,
+  strategy: RequestMismatchMitigationStrategy,
+  max: u16,
 ) -> Result<u16, ArtcraftRouterError> {
   let count = image_batch_count.unwrap_or(1);
-  match count {
-    0 => Err(ArtcraftRouterError::Client(ClientError::UserRequestedZeroGenerations)),
-    1..=4 => Ok(count),
-    _ => match strategy {
-      RequestMismatchMitigationStrategy::ErrorOut => {
-        Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
-          field: "image_batch_count",
-          value: format!("{}", count),
-        }))
-      }
-      RequestMismatchMitigationStrategy::PayMoreUpgrade
-      | RequestMismatchMitigationStrategy::PayLessDowngrade => Ok(4),
-    },
+  if count == 0 {
+    return Err(ArtcraftRouterError::Client(ClientError::UserRequestedZeroGenerations));
+  }
+  if count <= max {
+    return Ok(count);
+  }
+  match strategy {
+    RequestMismatchMitigationStrategy::ErrorOut => {
+      Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
+        field: "image_batch_count",
+        value: format!("{}", count),
+      }))
+    }
+    RequestMismatchMitigationStrategy::PayMoreUpgrade
+    | RequestMismatchMitigationStrategy::PayLessDowngrade => Ok(max),
   }
 }
 

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/artcraft/gpt_image_2p5_common_cost.rs

@@ -0,0 +1,290 @@
+use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_image_cost_and_generate_request::OmniGenImageCostAndGenerateRequest;
+use enums::common::generation::common_aspect_ratio::CommonAspectRatio as CommonAspectRatioEnum;
+use enums::common::generation::common_quality::CommonQuality as CommonQualityEnum;
+use enums::common::generation::common_resolution::CommonResolution as CommonResolutionEnum;
+use fal_client::requests::api::image::common::gpt_image_2_resolution::GptImage2Resolution;
+use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_image_size::GptImage2p5ImageSize;
+
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+
+/// Artcraft price per output image, in hundredths of a US cent, by output dimensions and
+/// quality (`[low, medium, high]`). Rows are stored landscape-first; portrait orientations of
+/// the same dimensions price identically. Dimensions come from the aspect ratio preset and
+/// resolution tier the same way the Fal request builder derives them.
+const OUTPUT_IMAGE_PRICE_TABLE: &[(u32, u32, [u64; 3])] = &[
+  // 1:1
+  (1024, 1024, [ 65, 152,  582]),
+  (2048, 2048, [103, 239,  919]),
+  (2880, 2880, [151, 352, 1357]),
+  // 4:3
+  (1024,  768, [ 46, 105,  400]),
+  (2048, 1536, [ 73, 170,  652]),
+  (3072, 2304, [120, 279, 1073]),
+  (3312, 2480, [134, 311, 1194]),
+  // 16:9
+  (1088,  608, [ 32,  75,  285]),
+  (1920, 1080, [ 49, 114,  436]),
+  (2048, 1152, [ 53, 121,  467]),
+  (3072, 1728, [ 87, 204,  783]),
+  (3840, 2160, [124, 286, 1102]),
+];
+
+/// Artcraft price per reference image on an edit request, in hundredths of a US cent.
+const REFERENCE_IMAGE_PRICE: u64 = 88;
+
+/// The inputs that determine an Artcraft GPT Image 2.5 price. Shared by Flare and Sunburst,
+/// which are priced identically.
+#[derive(Clone, Debug)]
+pub struct ArtcraftGptImage2p5CostInputs {
+  pub quality: Option<CommonQualityEnum>,
+  pub aspect_ratio: Option<CommonAspectRatioEnum>,
+  pub resolution: Option<CommonResolutionEnum>,
+  pub num_reference_images: usize,
+  pub num_images: u16,
+}
+
+impl ArtcraftGptImage2p5CostInputs {
+  pub fn from_omni_request(request: &OmniGenImageCostAndGenerateRequest) -> Self {
+    Self {
+      quality: request.quality,
+      aspect_ratio: request.aspect_ratio,
+      resolution: request.resolution,
+      num_reference_images: request.image_media_tokens.as_ref().map(|tokens| tokens.len()).unwrap_or(0),
+      num_images: request.image_batch_count.unwrap_or(1),
+    }
+  }
+
+  /// Per-image price rounded up to whole cents, times the batch size. Quality defaults to
+  /// high. Without an aspect ratio, text-to-image prices as landscape 4:3 and edit as auto,
+  /// matching the Fal defaults the request would fall back to.
+  pub fn estimate_cost(&self) -> ImageGenerationCostEstimate {
+    let quality = self.quality.unwrap_or(CommonQualityEnum::High);
+    let (width, height) = self.output_dimensions();
+    let hundredths_per_image = output_image_price(quality, width, height)
+      + REFERENCE_IMAGE_PRICE * self.num_reference_images as u64;
+    let cost_in_usd_cents = hundredths_per_image.div_ceil(100) * self.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,
+      failures_are_refunded: None,
+    }
+  }
+
+  fn output_dimensions(&self) -> (u32, u32) {
+    let is_edit = self.num_reference_images > 0;
+    let default_size = if is_edit { GptImage2p5ImageSize::Auto } else { GptImage2p5ImageSize::Landscape4x3 };
+    let size = self.aspect_ratio.map(to_image_size).unwrap_or(default_size);
+    size.estimated_output_dimensions(self.resolution.map(to_resolution))
+  }
+}
+
+/// Look up the per-image price. Dimensions not in the table fall back to the largest row,
+/// which is the most expensive.
+fn output_image_price(quality: CommonQualityEnum, width: u32, height: u32) -> u64 {
+  let prices = lookup_price_row(width, height)
+    .unwrap_or_else(|| OUTPUT_IMAGE_PRICE_TABLE[OUTPUT_IMAGE_PRICE_TABLE.len() - 1].2);
+  match quality {
+    CommonQualityEnum::Low => prices[0],
+    CommonQualityEnum::Medium => prices[1],
+    CommonQualityEnum::High => prices[2],
+  }
+}
+
+fn lookup_price_row(width: u32, height: u32) -> Option<[u64; 3]> {
+  let long_edge = width.max(height);
+  let short_edge = width.min(height);
+  OUTPUT_IMAGE_PRICE_TABLE.iter()
+    .find(|(w, h, _)| *w == long_edge && *h == short_edge)
+    .map(|(_, _, prices)| *prices)
+}
+
+/// Mirrors the Fal request builder's aspect ratio mapping.
+fn to_image_size(aspect_ratio: CommonAspectRatioEnum) -> GptImage2p5ImageSize {
+  use CommonAspectRatioEnum as Ar;
+  match aspect_ratio {
+    Ar::Auto | Ar::Auto2k | Ar::Auto3k | Ar::Auto4k => GptImage2p5ImageSize::Auto,
+    Ar::Square => GptImage2p5ImageSize::Square,
+    Ar::SquareHd => GptImage2p5ImageSize::SquareHd,
+    Ar::WideFourByThree | Ar::WideFiveByFour => GptImage2p5ImageSize::Landscape4x3,
+    Ar::WideThreeByTwo | Ar::WideSixteenByNine | Ar::WideTwentyOneByNine | Ar::Wide => GptImage2p5ImageSize::Landscape16x9,
+    Ar::TallThreeByFour | Ar::TallFourByFive => GptImage2p5ImageSize::Portrait4x3,
+    Ar::TallTwoByThree | Ar::TallNineBySixteen | Ar::TallNineByTwentyOne | Ar::Tall => GptImage2p5ImageSize::Portrait16x9,
+  }
+}
+
+/// Mirrors the Fal request builder's resolution mapping.
+fn to_resolution(resolution: CommonResolutionEnum) -> GptImage2Resolution {
+  use CommonResolutionEnum as R;
+  match resolution {
+    R::HalfK | R::FourEightyP | R::SevenTwentyP | R::OneK => GptImage2Resolution::OneK,
+    R::TenEightyP | R::TwoK => GptImage2Resolution::TwoK,
+    R::ThreeK => GptImage2Resolution::ThreeK,
+    R::FourK => GptImage2Resolution::FourK,
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use CommonAspectRatioEnum as Ar;
+  use CommonQualityEnum as Q;
+  use CommonResolutionEnum as R;
+
+  const ALL_ASPECT_RATIOS: &[Ar] = &[
+    Ar::Auto, Ar::Auto2k, Ar::Auto3k, Ar::Auto4k, Ar::Square, Ar::SquareHd,
+    Ar::WideFourByThree, Ar::WideFiveByFour, Ar::WideThreeByTwo, Ar::WideSixteenByNine,
+    Ar::WideTwentyOneByNine, Ar::Wide, Ar::TallThreeByFour, Ar::TallFourByFive,
+    Ar::TallTwoByThree, Ar::TallNineBySixteen, Ar::TallNineByTwentyOne, Ar::Tall,
+  ];
+
+  const ALL_RESOLUTIONS: &[Option<R>] = &[
+    None, Some(R::HalfK), Some(R::FourEightyP), Some(R::SevenTwentyP), Some(R::OneK),
+    Some(R::TenEightyP), Some(R::TwoK), Some(R::ThreeK), Some(R::FourK),
+  ];
+
+  // (aspect_ratio, resolution, [low, medium, high]) — cents per image, text-to-image
+  const TEXT_GRID: &[(Option<Ar>, Option<R>, [u64; 3])] = &[
+    (None,                        None,           [1, 2,  4]), // landscape 4:3 default
+    (Some(Ar::Square),            None,           [1, 2,  6]),
+    (Some(Ar::Square),            Some(R::OneK),  [1, 2,  6]),
+    (Some(Ar::Square),            Some(R::TwoK),  [2, 3, 10]),
+    (Some(Ar::Square),            Some(R::ThreeK), [2, 4, 14]),
+    (Some(Ar::Square),            Some(R::FourK), [2, 4, 14]),
+    (Some(Ar::SquareHd),          None,           [2, 3, 10]),
+    (Some(Ar::SquareHd),          Some(R::OneK),  [1, 2,  6]),
+    (Some(Ar::WideFourByThree),   None,           [1, 2,  4]),
+    (Some(Ar::WideFourByThree),   Some(R::TwoK),  [1, 2,  7]),
+    (Some(Ar::WideFourByThree),   Some(R::ThreeK), [2, 3, 11]),
+    (Some(Ar::WideFourByThree),   Some(R::FourK), [2, 4, 12]),
+    (Some(Ar::TallThreeByFour),   None,           [1, 2,  4]),
+    (Some(Ar::TallFourByFive),    Some(R::FourK), [2, 4, 12]),
+    (Some(Ar::WideSixteenByNine), None,           [1, 2,  5]),
+    (Some(Ar::WideSixteenByNine), Some(R::OneK),  [1, 1,  3]),
+    (Some(Ar::WideSixteenByNine), Some(R::TenEightyP), [1, 2, 5]),
+    (Some(Ar::WideSixteenByNine), Some(R::TwoK),  [1, 2,  5]),
+    (Some(Ar::WideSixteenByNine), Some(R::ThreeK), [1, 3,  8]),
+    (Some(Ar::WideSixteenByNine), Some(R::FourK), [2, 3, 12]),
+    (Some(Ar::TallNineBySixteen), None,           [1, 2,  5]),
+    (Some(Ar::Wide),              Some(R::HalfK), [1, 1,  3]),
+    (Some(Ar::Tall),              Some(R::ThreeK), [1, 3,  8]),
+    (Some(Ar::Auto),              None,           [2, 3, 12]),
+    (Some(Ar::Auto4k),            Some(R::OneK),  [2, 3, 12]),
+  ];
+
+  mod text_to_image_tests {
+    use super::*;
+
+    #[test]
+    fn grid() {
+      for &(aspect_ratio, resolution, expected) in TEXT_GRID {
+        for (quality, expected) in [Q::Low, Q::Medium, Q::High].into_iter().zip(expected) {
+          let actual = make_inputs(0, Some(quality), aspect_ratio, resolution, 1).estimate_cost().cost_in_usd_cents.unwrap();
+          assert_eq!(actual, expected, "{aspect_ratio:?} {resolution:?} {quality:?}");
+        }
+      }
+    }
+
+    #[test]
+    fn quality_defaults_to_high() {
+      assert_eq!(cents(make_inputs(0, None, Some(Ar::Square), None, 1)), 6);
+    }
+
+    #[test]
+    fn batch_multiplies_per_image_cents() {
+      for &(aspect_ratio, resolution, _) in TEXT_GRID {
+        let per_image = cents(make_inputs(0, Some(Q::High), aspect_ratio, resolution, 1));
+        for batch in 2..=4u16 {
+          assert_eq!(cents(make_inputs(0, Some(Q::High), aspect_ratio, resolution, batch)), per_image * batch as u64);
+        }
+      }
+    }
+  }
+
+  mod edit_image_tests {
+    use super::*;
+
+    #[test]
+    fn no_aspect_ratio_prices_as_auto() {
+      // 1102 + 88 = 1190
+      assert_eq!(cents(make_inputs(1, Some(Q::High), None, None, 1)), 12);
+      assert_eq!(cents(make_inputs(1, Some(Q::High), Some(Ar::Auto), None, 1)), 12);
+    }
+
+    #[test]
+    fn reference_images_add_to_price() {
+      // Square high 582, plus 88 per reference image
+      assert_eq!(cents(make_inputs(1, Some(Q::High), Some(Ar::Square), None, 1)), 7);   // 670
+      assert_eq!(cents(make_inputs(4, Some(Q::High), Some(Ar::Square), None, 1)), 10);  // 934
+      assert_eq!(cents(make_inputs(16, Some(Q::High), Some(Ar::Square), None, 1)), 20); // 1990
+      assert_eq!(cents(make_inputs(1, Some(Q::Low), Some(Ar::Square), None, 1)), 2);    // 153
+    }
+
+    #[test]
+    fn batch_multiplies_per_image_cents() {
+      assert_eq!(cents(make_inputs(1, Some(Q::High), Some(Ar::Square), None, 4)), 28);
+    }
+  }
+
+  mod table_coverage_tests {
+    use super::*;
+
+    #[test]
+    fn every_reachable_dimension_has_a_table_row() {
+      for &aspect_ratio in ALL_ASPECT_RATIOS {
+        for &resolution in ALL_RESOLUTIONS {
+          for refs in [0, 1] {
+            let (w, h) = make_inputs(refs, None, Some(aspect_ratio), resolution, 1).output_dimensions();
+            assert!(lookup_price_row(w, h).is_some(), "{aspect_ratio:?} {resolution:?} => {w}x{h} missing from price table");
+          }
+        }
+      }
+      for refs in [0, 1] {
+        for &resolution in ALL_RESOLUTIONS {
+          let (w, h) = make_inputs(refs, None, None, resolution, 1).output_dimensions();
+          assert!(lookup_price_row(w, h).is_some(), "no aspect, {resolution:?}, {refs} refs => {w}x{h} missing from price table");
+        }
+      }
+    }
+
+    #[test]
+    fn unknown_dimensions_fall_back_to_most_expensive_row() {
+      assert_eq!(output_image_price(Q::High, 640, 640), 1102);
+    }
+
+    #[test]
+    fn orientation_does_not_change_price() {
+      assert_eq!(output_image_price(Q::High, 768, 1024), output_image_price(Q::High, 1024, 768));
+      assert_eq!(output_image_price(Q::Medium, 1080, 1920), output_image_price(Q::Medium, 1920, 1080));
+    }
+
+    #[test]
+    fn prices_rise_with_quality_and_size() {
+      for &(_, _, prices) in OUTPUT_IMAGE_PRICE_TABLE {
+        assert!(prices[0] < prices[1] && prices[1] < prices[2], "{prices:?}");
+      }
+      assert!(output_image_price(Q::High, 1024, 1024) < output_image_price(Q::High, 2048, 2048));
+      assert!(output_image_price(Q::High, 2048, 2048) < output_image_price(Q::High, 2880, 2880));
+      assert!(output_image_price(Q::High, 1088, 608) < output_image_price(Q::High, 1920, 1080));
+      assert!(output_image_price(Q::High, 3072, 1728) < output_image_price(Q::High, 3840, 2160));
+    }
+  }
+
+  fn cents(inputs: ArtcraftGptImage2p5CostInputs) -> u64 {
+    inputs.estimate_cost().cost_in_usd_cents.unwrap()
+  }
+
+  fn make_inputs(
+    num_reference_images: usize,
+    quality: Option<Q>,
+    aspect_ratio: Option<Ar>,
+    resolution: Option<R>,
+    num_images: u16,
+  ) -> ArtcraftGptImage2p5CostInputs {
+    ArtcraftGptImage2p5CostInputs { quality, aspect_ratio, resolution, num_reference_images, num_images }
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/artcraft/gpt_image_2p5_flare/build.rs

@@ -0,0 +1,114 @@
+use enums::common::generation::common_image_model::CommonImageModel as CommonImageModelEnum;
+
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
+use crate::generate::generate_image::image_generation_draft_or_request::ImageGenerationDraftOrRequest;
+use crate::generate::generate_image::image_generation_request::ImageGenerationRequest;
+use crate::generate::generate_image::providers::artcraft::build_common::build_artcraft_omni_image_request;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_flare::request::ArtcraftGptImage2p5FlareRequestState;
+
+pub fn build_artcraft_gpt_image_2p5_flare(
+  builder: GenerateImageRequestBuilder,
+) -> Result<ImageGenerationDraftOrRequest, ArtcraftRouterError> {
+  let request = build_artcraft_omni_image_request(builder, CommonImageModelEnum::GptImage2p5Flare)?;
+  Ok(ImageGenerationDraftOrRequest::Request(
+    ImageGenerationRequest::ArtcraftGptImage2p5Flare(ArtcraftGptImage2p5FlareRequestState { request }),
+  ))
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_image_cost_and_generate_request::OmniGenImageCostAndGenerateRequest;
+  use enums::common::generation::common_aspect_ratio::CommonAspectRatio as CommonAspectRatioEnum;
+  use enums::common::generation::common_quality::CommonQuality as CommonQualityEnum;
+  use enums::common::generation::common_resolution::CommonResolution as CommonResolutionEnum;
+  use tokens::tokens::media_files::MediaFileToken;
+
+  use crate::api::image_list_ref::ImageListRef;
+  use crate::api::router_aspect_ratio::RouterAspectRatio;
+  use crate::api::router_image_model::RouterImageModel;
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_quality::RouterQuality;
+  use crate::api::router_resolution::RouterResolution;
+  use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+  use crate::errors::client_error::ClientError;
+
+  #[test]
+  fn build2_routes_to_omni_request_with_flare_model() {
+    let request = unwrap_request(base_builder().build2());
+    assert_eq!(request.model, Some(CommonImageModelEnum::GptImage2p5Flare));
+    assert_eq!(request.prompt.as_deref(), Some("a cat in space"));
+    assert_eq!(request.image_batch_count, Some(1));
+    assert!(request.image_media_tokens.is_none());
+    assert!(request.aspect_ratio.is_none());
+    assert!(request.resolution.is_none());
+    assert!(request.quality.is_none());
+    assert!(request.idempotency_token.is_some());
+  }
+
+  #[test]
+  fn omni_request_carries_all_generation_fields() {
+    let request = unwrap_request(GenerateImageRequestBuilder {
+      aspect_ratio: Some(RouterAspectRatio::WideSixteenByNine),
+      resolution: Some(RouterResolution::TwoK),
+      quality: Some(RouterQuality::Medium),
+      image_batch_count: Some(3),
+      idempotency_token: Some("idem-123".to_string()),
+      image_inputs: Some(ImageListRef::MediaFileTokens(vec![MediaFileToken::generate(), MediaFileToken::generate()])),
+      ..base_builder()
+    }.build2());
+    assert_eq!(request.aspect_ratio, Some(CommonAspectRatioEnum::WideSixteenByNine));
+    assert_eq!(request.resolution, Some(CommonResolutionEnum::TwoK));
+    assert_eq!(request.quality, Some(CommonQualityEnum::Medium));
+    assert_eq!(request.image_batch_count, Some(3));
+    assert_eq!(request.idempotency_token.as_deref(), Some("idem-123"));
+    assert_eq!(request.image_media_tokens.map(|tokens| tokens.len()), Some(2));
+  }
+
+  #[test]
+  fn batch_count_is_validated() {
+    assert!(matches!(
+      GenerateImageRequestBuilder { image_batch_count: Some(0), ..base_builder() }.build2(),
+      Err(ArtcraftRouterError::Client(ClientError::UserRequestedZeroGenerations))
+    ));
+    assert!(matches!(
+      GenerateImageRequestBuilder { image_batch_count: Some(5), ..base_builder() }.build2(),
+      Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption { .. }))
+    ));
+    let request = unwrap_request(GenerateImageRequestBuilder {
+      image_batch_count: Some(5),
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::PayLessDowngrade,
+      ..base_builder()
+    }.build2());
+    assert_eq!(request.image_batch_count, Some(4));
+  }
+
+  fn base_builder() -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
+      model: RouterImageModel::GptImage2p5Flare,
+      provider: RouterProvider::Artcraft,
+      prompt: Some("a cat in space".to_string()),
+      image_inputs: None,
+      resolution: None,
+      aspect_ratio: None,
+      quality: None,
+      image_batch_count: None,
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+    }
+  }
+
+  fn unwrap_request(result: Result<ImageGenerationDraftOrRequest, ArtcraftRouterError>) -> OmniGenImageCostAndGenerateRequest {
+    let ImageGenerationDraftOrRequest::Request(
+      ImageGenerationRequest::ArtcraftGptImage2p5Flare(state)
+    ) = result.expect("build should succeed") else {
+      panic!("expected Artcraft GPT Image 2.5 Flare request")
+    };
+    state.request
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/artcraft/gpt_image_2p5_flare/cost.rs

@@ -0,0 +1,106 @@
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_common_cost::ArtcraftGptImage2p5CostInputs;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_flare::request::ArtcraftGptImage2p5FlareRequestState;
+
+/// Cost state for Artcraft GPT Image 2.5 Flare. The price table is shared with the other
+/// GPT Image 2.5 variant; see `gpt_image_2p5_common_cost`.
+#[derive(Clone, Debug)]
+pub struct ArtcraftGptImage2p5FlareCostState {
+  inputs: ArtcraftGptImage2p5CostInputs,
+}
+
+impl ArtcraftGptImage2p5FlareCostState {
+  pub fn from_request(request: &ArtcraftGptImage2p5FlareRequestState) -> Self {
+    Self { inputs: ArtcraftGptImage2p5CostInputs::from_omni_request(&request.request) }
+  }
+
+  pub fn estimate_cost(&self) -> ImageGenerationCostEstimate {
+    self.inputs.estimate_cost()
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use tokens::tokens::media_files::MediaFileToken;
+
+  use crate::api::image_list_ref::ImageListRef;
+  use crate::api::router_aspect_ratio::RouterAspectRatio;
+  use crate::api::router_image_model::RouterImageModel;
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_quality::RouterQuality;
+  use crate::api::router_resolution::RouterResolution;
+  use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
+  use RouterAspectRatio as Ar;
+  use RouterQuality as Q;
+  use RouterResolution as R;
+
+  // (reference_images, quality, aspect_ratio, resolution, batch, expected_cents)
+  const CASES: &[(usize, Option<Q>, Option<Ar>, Option<R>, u16, u64)] = &[
+    (0, None,            None,                        None,           1,  4),
+    (0, Some(Q::Low),    Some(Ar::Square),            None,           1,  1),
+    (0, Some(Q::Medium), Some(Ar::Square),            None,           1,  2),
+    (0, Some(Q::High),   Some(Ar::Square),            None,           1,  6),
+    (0, Some(Q::High),   Some(Ar::Square),            None,           4, 24),
+    (0, Some(Q::High),   Some(Ar::SquareHd),          None,           1, 10),
+    (0, Some(Q::High),   Some(Ar::Square),            Some(R::TwoK),  1, 10),
+    (0, Some(Q::High),   Some(Ar::Square),            Some(R::FourK), 1, 14),
+    (0, Some(Q::High),   Some(Ar::WideFourByThree),   None,           1,  4),
+    (0, Some(Q::High),   Some(Ar::WideSixteenByNine), None,           1,  5),
+    (0, Some(Q::High),   Some(Ar::WideSixteenByNine), Some(R::OneK),  1,  3),
+    (0, Some(Q::High),   Some(Ar::WideSixteenByNine), Some(R::FourK), 1, 12),
+    (0, Some(Q::Medium), Some(Ar::TallNineBySixteen), Some(R::ThreeK), 2, 6),
+    (0, Some(Q::High),   Some(Ar::Auto),              None,           1, 12),
+    (1, None,            None,                        None,           1, 12),
+    (1, Some(Q::High),   Some(Ar::Square),            None,           1,  7),
+    (4, Some(Q::High),   Some(Ar::Square),            None,           1, 10),
+    (1, Some(Q::High),   Some(Ar::Square),            None,           4, 28),
+    (1, Some(Q::Low),    Some(Ar::Square),            None,           1,  2),
+  ];
+
+  #[test]
+  fn costs_through_build2() {
+    for &(refs, quality, aspect_ratio, resolution, batch, expected) in CASES {
+      assert_eq!(cost_cents(refs, quality, aspect_ratio, resolution, batch), expected, "{refs} refs {quality:?} {aspect_ratio:?} {resolution:?} x{batch}");
+    }
+  }
+
+  #[test]
+  fn estimate_flags() {
+    let cost = builder(0, Some(Q::High), Some(Ar::Square), None, 1).build2().unwrap().estimate_cost().unwrap();
+    assert_eq!(cost.cost_in_credits, cost.cost_in_usd_cents);
+    assert!(!cost.is_free);
+    assert!(!cost.is_unlimited);
+    assert!(!cost.is_rate_limited);
+    assert!(!cost.has_watermark);
+  }
+
+  fn cost_cents(refs: usize, quality: Option<Q>, aspect_ratio: Option<Ar>, resolution: Option<R>, batch: u16) -> u64 {
+    builder(refs, quality, aspect_ratio, resolution, batch)
+      .build2().unwrap().estimate_cost().unwrap().cost_in_usd_cents.unwrap()
+  }
+
+  fn builder(refs: usize, quality: Option<Q>, aspect_ratio: Option<Ar>, resolution: Option<R>, batch: u16) -> GenerateImageRequestBuilder {
+    let image_inputs = if refs == 0 {
+      None
+    } else {
+      Some(ImageListRef::MediaFileTokens((0..refs).map(|_| MediaFileToken::generate()).collect()))
+    };
+    GenerateImageRequestBuilder {
+      model: RouterImageModel::GptImage2p5Flare,
+      provider: RouterProvider::Artcraft,
+      prompt: Some("a cat in space".to_string()),
+      image_inputs,
+      resolution,
+      aspect_ratio,
+      quality,
+      image_batch_count: Some(batch),
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+    }
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/artcraft/gpt_image_2p5_flare/request.rs

@@ -0,0 +1,17 @@
+use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_image_cost_and_generate_request::OmniGenImageCostAndGenerateRequest;
+
+use crate::client::router_artcraft_client::RouterArtcraftClient;
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_image::generate_image_response::GenerateImageResponse;
+use crate::generate::generate_image::providers::artcraft::request_common::send_artcraft_omni_image_request;
+
+#[derive(Clone, Debug)]
+pub struct ArtcraftGptImage2p5FlareRequestState {
+  pub request: OmniGenImageCostAndGenerateRequest,
+}
+
+impl ArtcraftGptImage2p5FlareRequestState {
+  pub async fn send(&self, client: &RouterArtcraftClient) -> Result<GenerateImageResponse, ArtcraftRouterError> {
+    send_artcraft_omni_image_request(&self.request, client).await
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/artcraft/gpt_image_2p5_sunburst/build.rs

@@ -0,0 +1,114 @@
+use enums::common::generation::common_image_model::CommonImageModel as CommonImageModelEnum;
+
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
+use crate::generate::generate_image::image_generation_draft_or_request::ImageGenerationDraftOrRequest;
+use crate::generate::generate_image::image_generation_request::ImageGenerationRequest;
+use crate::generate::generate_image::providers::artcraft::build_common::build_artcraft_omni_image_request;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_sunburst::request::ArtcraftGptImage2p5SunburstRequestState;
+
+pub fn build_artcraft_gpt_image_2p5_sunburst(
+  builder: GenerateImageRequestBuilder,
+) -> Result<ImageGenerationDraftOrRequest, ArtcraftRouterError> {
+  let request = build_artcraft_omni_image_request(builder, CommonImageModelEnum::GptImage2p5Sunburst)?;
+  Ok(ImageGenerationDraftOrRequest::Request(
+    ImageGenerationRequest::ArtcraftGptImage2p5Sunburst(ArtcraftGptImage2p5SunburstRequestState { request }),
+  ))
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_image_cost_and_generate_request::OmniGenImageCostAndGenerateRequest;
+  use enums::common::generation::common_aspect_ratio::CommonAspectRatio as CommonAspectRatioEnum;
+  use enums::common::generation::common_quality::CommonQuality as CommonQualityEnum;
+  use enums::common::generation::common_resolution::CommonResolution as CommonResolutionEnum;
+  use tokens::tokens::media_files::MediaFileToken;
+
+  use crate::api::image_list_ref::ImageListRef;
+  use crate::api::router_aspect_ratio::RouterAspectRatio;
+  use crate::api::router_image_model::RouterImageModel;
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_quality::RouterQuality;
+  use crate::api::router_resolution::RouterResolution;
+  use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+  use crate::errors::client_error::ClientError;
+
+  #[test]
+  fn build2_routes_to_omni_request_with_sunburst_model() {
+    let request = unwrap_request(base_builder().build2());
+    assert_eq!(request.model, Some(CommonImageModelEnum::GptImage2p5Sunburst));
+    assert_eq!(request.prompt.as_deref(), Some("a cat in space"));
+    assert_eq!(request.image_batch_count, Some(1));
+    assert!(request.image_media_tokens.is_none());
+    assert!(request.aspect_ratio.is_none());
+    assert!(request.resolution.is_none());
+    assert!(request.quality.is_none());
+    assert!(request.idempotency_token.is_some());
+  }
+
+  #[test]
+  fn omni_request_carries_all_generation_fields() {
+    let request = unwrap_request(GenerateImageRequestBuilder {
+      aspect_ratio: Some(RouterAspectRatio::WideSixteenByNine),
+      resolution: Some(RouterResolution::TwoK),
+      quality: Some(RouterQuality::Medium),
+      image_batch_count: Some(3),
+      idempotency_token: Some("idem-123".to_string()),
+      image_inputs: Some(ImageListRef::MediaFileTokens(vec![MediaFileToken::generate(), MediaFileToken::generate()])),
+      ..base_builder()
+    }.build2());
+    assert_eq!(request.aspect_ratio, Some(CommonAspectRatioEnum::WideSixteenByNine));
+    assert_eq!(request.resolution, Some(CommonResolutionEnum::TwoK));
+    assert_eq!(request.quality, Some(CommonQualityEnum::Medium));
+    assert_eq!(request.image_batch_count, Some(3));
+    assert_eq!(request.idempotency_token.as_deref(), Some("idem-123"));
+    assert_eq!(request.image_media_tokens.map(|tokens| tokens.len()), Some(2));
+  }
+
+  #[test]
+  fn batch_count_is_validated() {
+    assert!(matches!(
+      GenerateImageRequestBuilder { image_batch_count: Some(0), ..base_builder() }.build2(),
+      Err(ArtcraftRouterError::Client(ClientError::UserRequestedZeroGenerations))
+    ));
+    assert!(matches!(
+      GenerateImageRequestBuilder { image_batch_count: Some(5), ..base_builder() }.build2(),
+      Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption { .. }))
+    ));
+    let request = unwrap_request(GenerateImageRequestBuilder {
+      image_batch_count: Some(5),
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::PayLessDowngrade,
+      ..base_builder()
+    }.build2());
+    assert_eq!(request.image_batch_count, Some(4));
+  }
+
+  fn base_builder() -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
+      model: RouterImageModel::GptImage2p5Sunburst,
+      provider: RouterProvider::Artcraft,
+      prompt: Some("a cat in space".to_string()),
+      image_inputs: None,
+      resolution: None,
+      aspect_ratio: None,
+      quality: None,
+      image_batch_count: None,
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+    }
+  }
+
+  fn unwrap_request(result: Result<ImageGenerationDraftOrRequest, ArtcraftRouterError>) -> OmniGenImageCostAndGenerateRequest {
+    let ImageGenerationDraftOrRequest::Request(
+      ImageGenerationRequest::ArtcraftGptImage2p5Sunburst(state)
+    ) = result.expect("build should succeed") else {
+      panic!("expected Artcraft GPT Image 2.5 Sunburst request")
+    };
+    state.request
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/artcraft/gpt_image_2p5_sunburst/cost.rs

@@ -0,0 +1,106 @@
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_common_cost::ArtcraftGptImage2p5CostInputs;
+use crate::generate::generate_image::providers::artcraft::gpt_image_2p5_sunburst::request::ArtcraftGptImage2p5SunburstRequestState;
+
+/// Cost state for Artcraft GPT Image 2.5 Sunburst. The price table is shared with the other
+/// GPT Image 2.5 variant; see `gpt_image_2p5_common_cost`.
+#[derive(Clone, Debug)]
+pub struct ArtcraftGptImage2p5SunburstCostState {
+  inputs: ArtcraftGptImage2p5CostInputs,
+}
+
+impl ArtcraftGptImage2p5SunburstCostState {
+  pub fn from_request(request: &ArtcraftGptImage2p5SunburstRequestState) -> Self {
+    Self { inputs: ArtcraftGptImage2p5CostInputs::from_omni_request(&request.request) }
+  }
+
+  pub fn estimate_cost(&self) -> ImageGenerationCostEstimate {
+    self.inputs.estimate_cost()
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use tokens::tokens::media_files::MediaFileToken;
+
+  use crate::api::image_list_ref::ImageListRef;
+  use crate::api::router_aspect_ratio::RouterAspectRatio;
+  use crate::api::router_image_model::RouterImageModel;
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_quality::RouterQuality;
+  use crate::api::router_resolution::RouterResolution;
+  use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
+  use RouterAspectRatio as Ar;
+  use RouterQuality as Q;
+  use RouterResolution as R;
+
+  // (reference_images, quality, aspect_ratio, resolution, batch, expected_cents)
+  const CASES: &[(usize, Option<Q>, Option<Ar>, Option<R>, u16, u64)] = &[
+    (0, None,            None,                        None,           1,  4),
+    (0, Some(Q::Low),    Some(Ar::Square),            None,           1,  1),
+    (0, Some(Q::Medium), Some(Ar::Square),            None,           1,  2),
+    (0, Some(Q::High),   Some(Ar::Square),            None,           1,  6),
+    (0, Some(Q::High),   Some(Ar::Square),            None,           4, 24),
+    (0, Some(Q::High),   Some(Ar::SquareHd),          None,           1, 10),
+    (0, Some(Q::High),   Some(Ar::Square),            Some(R::TwoK),  1, 10),
+    (0, Some(Q::High),   Some(Ar::Square),            Some(R::FourK), 1, 14),
+    (0, Some(Q::High),   Some(Ar::WideFourByThree),   None,           1,  4),
+    (0, Some(Q::High),   Some(Ar::WideSixteenByNine), None,           1,  5),
+    (0, Some(Q::High),   Some(Ar::WideSixteenByNine), Some(R::OneK),  1,  3),
+    (0, Some(Q::High),   Some(Ar::WideSixteenByNine), Some(R::FourK), 1, 12),
+    (0, Some(Q::Medium), Some(Ar::TallNineBySixteen), Some(R::ThreeK), 2, 6),
+    (0, Some(Q::High),   Some(Ar::Auto),              None,           1, 12),
+    (1, None,            None,                        None,           1, 12),
+    (1, Some(Q::High),   Some(Ar::Square),            None,           1,  7),
+    (4, Some(Q::High),   Some(Ar::Square),            None,           1, 10),
+    (1, Some(Q::High),   Some(Ar::Square),            None,           4, 28),
+    (1, Some(Q::Low),    Some(Ar::Square),            None,           1,  2),
+  ];
+
+  #[test]
+  fn costs_through_build2() {
+    for &(refs, quality, aspect_ratio, resolution, batch, expected) in CASES {
+      assert_eq!(cost_cents(refs, quality, aspect_ratio, resolution, batch), expected, "{refs} refs {quality:?} {aspect_ratio:?} {resolution:?} x{batch}");
+    }
+  }
+
+  #[test]
+  fn estimate_flags() {
+    let cost = builder(0, Some(Q::High), Some(Ar::Square), None, 1).build2().unwrap().estimate_cost().unwrap();
+    assert_eq!(cost.cost_in_credits, cost.cost_in_usd_cents);
+    assert!(!cost.is_free);
+    assert!(!cost.is_unlimited);
+    assert!(!cost.is_rate_limited);
+    assert!(!cost.has_watermark);
+  }
+
+  fn cost_cents(refs: usize, quality: Option<Q>, aspect_ratio: Option<Ar>, resolution: Option<R>, batch: u16) -> u64 {
+    builder(refs, quality, aspect_ratio, resolution, batch)
+      .build2().unwrap().estimate_cost().unwrap().cost_in_usd_cents.unwrap()
+  }
+
+  fn builder(refs: usize, quality: Option<Q>, aspect_ratio: Option<Ar>, resolution: Option<R>, batch: u16) -> GenerateImageRequestBuilder {
+    let image_inputs = if refs == 0 {
+      None
+    } else {
+      Some(ImageListRef::MediaFileTokens((0..refs).map(|_| MediaFileToken::generate()).collect()))
+    };
+    GenerateImageRequestBuilder {
+      model: RouterImageModel::GptImage2p5Sunburst,
+      provider: RouterProvider::Artcraft,
+      prompt: Some("a cat in space".to_string()),
+      image_inputs,
+      resolution,
+      aspect_ratio,
+      quality,
+      image_batch_count: Some(batch),
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+    }
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/artcraft/gpt_image_2p5_sunburst/request.rs

@@ -0,0 +1,17 @@
+use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_image_cost_and_generate_request::OmniGenImageCostAndGenerateRequest;
+
+use crate::client::router_artcraft_client::RouterArtcraftClient;
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_image::generate_image_response::GenerateImageResponse;
+use crate::generate::generate_image::providers::artcraft::request_common::send_artcraft_omni_image_request;
+
+#[derive(Clone, Debug)]
+pub struct ArtcraftGptImage2p5SunburstRequestState {
+  pub request: OmniGenImageCostAndGenerateRequest,
+}
+
+impl ArtcraftGptImage2p5SunburstRequestState {
+  pub async fn send(&self, client: &RouterArtcraftClient) -> Result<GenerateImageResponse, ArtcraftRouterError> {
+    send_artcraft_omni_image_request(&self.request, client).await
+  }
+}

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

@@ -8,6 +8,9 @@ pub mod flux_pro_1p1_ultra;
 pub mod gpt_image_1;
 pub mod gpt_image_1p5;
 pub mod gpt_image_2;
+pub(crate) mod gpt_image_2p5_common_cost;
+pub mod gpt_image_2p5_flare;
+pub mod gpt_image_2p5_sunburst;
 pub mod midjourney_7;
 pub mod midjourney_7_niji;
 pub mod midjourney_8;

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/fal/gpt_image_2p5_common/mod.rs

@@ -0,0 +1,5 @@
+//! Planning and transport shared by the GPT Image 2.5 Flare and Sunburst Fal providers.
+//! The two models take identical parameters; only the Fal endpoint differs.
+
+pub mod plan;
+pub mod send;

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/fal/gpt_image_2p5_common/plan.rs

@@ -0,0 +1,330 @@
+use fal_client::requests::api::image::common::gpt_image_2_resolution::GptImage2Resolution;
+use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_edit_image_params::GptImage2p5EditImageParams;
+use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_image_size::GptImage2p5ImageSize;
+use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_num_images::GptImage2p5NumImages;
+use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_quality::GptImage2p5Quality;
+use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_text_to_image_params::GptImage2p5TextToImageParams;
+
+use crate::api::image_list_ref::ImageListRef;
+use crate::api::router_aspect_ratio::RouterAspectRatio;
+use crate::api::router_quality::RouterQuality;
+use crate::api::router_resolution::RouterResolution;
+use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::errors::client_error::ClientError;
+use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
+
+/// Planned GPT Image 2.5 parameters. The mode is chosen by whether the builder carries
+/// reference images: none means text-to-image, one or more means edit.
+#[derive(Clone, Debug)]
+pub enum PlannedGptImage2p5Params {
+  TextToImage(GptImage2p5TextToImageParams),
+  EditImage(GptImage2p5EditImageParams),
+}
+
+pub fn plan_gpt_image_2p5_params(
+  builder: &GenerateImageRequestBuilder,
+) -> Result<PlannedGptImage2p5Params, ArtcraftRouterError> {
+  let prompt = builder.prompt.clone().unwrap_or_default();
+  let image_urls = resolve_image_urls(builder.image_inputs.clone())?;
+  let num_images = plan_num_images(builder.image_batch_count, builder.request_mismatch_mitigation_strategy)?;
+  let image_size = plan_image_size(builder.aspect_ratio);
+  let resolution = plan_resolution(builder.resolution);
+  let quality = Some(plan_quality(builder.quality));
+
+  if image_urls.is_empty() {
+    Ok(PlannedGptImage2p5Params::TextToImage(GptImage2p5TextToImageParams {
+      prompt,
+      num_images,
+      image_size,
+      resolution,
+      quality,
+      background: None,
+      output_format: None,
+      output_compression: None,
+    }))
+  } else {
+    Ok(PlannedGptImage2p5Params::EditImage(GptImage2p5EditImageParams {
+      prompt,
+      image_urls,
+      mask_url: None,
+      num_images,
+      image_size,
+      resolution,
+      quality,
+      background: None,
+      output_format: None,
+      output_compression: None,
+    }))
+  }
+}
+
+fn plan_num_images(
+  count: Option<u16>,
+  strategy: RequestMismatchMitigationStrategy,
+) -> Result<GptImage2p5NumImages, ArtcraftRouterError> {
+  let count = count.unwrap_or(1);
+  match count {
+    0 => Err(ArtcraftRouterError::Client(ClientError::UserRequestedZeroGenerations)),
+    1 => Ok(GptImage2p5NumImages::One),
+    2 => Ok(GptImage2p5NumImages::Two),
+    3 => Ok(GptImage2p5NumImages::Three),
+    4 => Ok(GptImage2p5NumImages::Four),
+    _ => match strategy {
+      RequestMismatchMitigationStrategy::ErrorOut => {
+        Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
+          field: "image_batch_count",
+          value: format!("{}", count),
+        }))
+      }
+      _ => Ok(GptImage2p5NumImages::Four),
+    },
+  }
+}
+
+/// The router only exposes low / medium / high; GPT Image 2.5's `xhigh` and `max` tiers are
+/// not reachable through it. Fal's default (`high`) applies when unspecified.
+fn plan_quality(quality: Option<RouterQuality>) -> GptImage2p5Quality {
+  match quality {
+    Some(RouterQuality::Low) => GptImage2p5Quality::Low,
+    Some(RouterQuality::Medium) => GptImage2p5Quality::Medium,
+    Some(RouterQuality::High) | None => GptImage2p5Quality::High,
+  }
+}
+
+fn plan_resolution(resolution: Option<RouterResolution>) -> Option<GptImage2Resolution> {
+  resolution.map(|r| match r {
+    RouterResolution::HalfK
+    | RouterResolution::FourEightyP
+    | RouterResolution::SevenTwentyP
+    | RouterResolution::OneK => GptImage2Resolution::OneK,
+    RouterResolution::TenEightyP | RouterResolution::TwoK => GptImage2Resolution::TwoK,
+    RouterResolution::ThreeK => GptImage2Resolution::ThreeK,
+    RouterResolution::FourK => GptImage2Resolution::FourK,
+  })
+}
+
+/// `None` lets Fal apply its own default (`landscape_4_3` for text-to-image, `auto` for edit).
+fn plan_image_size(aspect_ratio: Option<RouterAspectRatio>) -> Option<GptImage2p5ImageSize> {
+  aspect_ratio.map(|ar| match ar {
+    RouterAspectRatio::Auto
+    | RouterAspectRatio::Auto2k
+    | RouterAspectRatio::Auto3k
+    | RouterAspectRatio::Auto4k => GptImage2p5ImageSize::Auto,
+    RouterAspectRatio::Square => GptImage2p5ImageSize::Square,
+    RouterAspectRatio::SquareHd => GptImage2p5ImageSize::SquareHd,
+    RouterAspectRatio::WideFourByThree
+    | RouterAspectRatio::WideFiveByFour => GptImage2p5ImageSize::Landscape4x3,
+    RouterAspectRatio::WideThreeByTwo
+    | RouterAspectRatio::WideSixteenByNine
+    | RouterAspectRatio::WideTwentyOneByNine
+    | RouterAspectRatio::Wide => GptImage2p5ImageSize::Landscape16x9,
+    RouterAspectRatio::TallThreeByFour
+    | RouterAspectRatio::TallFourByFive => GptImage2p5ImageSize::Portrait4x3,
+    RouterAspectRatio::TallTwoByThree
+    | RouterAspectRatio::TallNineBySixteen
+    | RouterAspectRatio::TallNineByTwentyOne
+    | RouterAspectRatio::Tall => GptImage2p5ImageSize::Portrait16x9,
+  })
+}
+
+fn resolve_image_urls(
+  image_inputs: Option<ImageListRef>,
+) -> Result<Vec<String>, ArtcraftRouterError> {
+  match image_inputs {
+    None => Ok(vec![]),
+    Some(ImageListRef::Urls(urls)) => Ok(urls),
+    Some(ImageListRef::MediaFileTokens(_)) => {
+      Err(ArtcraftRouterError::Client(ClientError::FalOnlySupportsUrls))
+    }
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use std::fmt::Debug;
+
+  use crate::api::router_image_model::RouterImageModel;
+  use crate::api::router_provider::RouterProvider;
+
+  const IMAGE_URL: &str = "https://example.com/img.jpg";
+
+  #[test]
+  fn mode_is_based_on_image_urls() {
+    let text = unwrap_t2i(plan_gpt_image_2p5_params(&base_builder()));
+    assert_eq!(text.prompt, "a cat in space");
+
+    let edit = unwrap_edit(plan_gpt_image_2p5_params(&with_reference_image(base_builder())));
+    assert_eq!(edit.prompt, "a cat in space");
+    assert_eq!(edit.image_urls, vec![IMAGE_URL]);
+    assert!(edit.mask_url.is_none());
+  }
+
+  #[test]
+  fn optional_fal_fields_are_left_to_fal_defaults() {
+    let text = unwrap_t2i(plan_gpt_image_2p5_params(&base_builder()));
+    assert!(text.background.is_none());
+    assert!(text.output_format.is_none());
+    assert!(text.output_compression.is_none());
+    assert!(text.image_size.is_none());
+    assert!(text.resolution.is_none());
+  }
+
+  #[test]
+  fn media_file_tokens_are_rejected() {
+    let result = plan_gpt_image_2p5_params(&GenerateImageRequestBuilder {
+      image_inputs: Some(ImageListRef::MediaFileTokens(vec![])),
+      ..base_builder()
+    });
+    assert!(matches!(result, Err(ArtcraftRouterError::Client(ClientError::FalOnlySupportsUrls))));
+  }
+
+  #[test]
+  fn num_images_maps_exhaustively_for_text_and_edit() {
+    let cases = [(1, "One"), (2, "Two"), (3, "Three"), (4, "Four")];
+    for (count, expected) in cases {
+      let text = unwrap_t2i(plan_gpt_image_2p5_params(&GenerateImageRequestBuilder {
+        image_batch_count: Some(count),
+        ..base_builder()
+      }));
+      assert_debug(text.num_images, expected);
+
+      let edit = unwrap_edit(plan_gpt_image_2p5_params(&with_reference_image(GenerateImageRequestBuilder {
+        image_batch_count: Some(count),
+        ..base_builder()
+      })));
+      assert_debug(edit.num_images, expected);
+    }
+  }
+
+  #[test]
+  fn num_images_rejects_zero_and_handles_overflow_by_strategy() {
+    assert!(matches!(
+      plan_gpt_image_2p5_params(&GenerateImageRequestBuilder { image_batch_count: Some(0), ..base_builder() }),
+      Err(ArtcraftRouterError::Client(ClientError::UserRequestedZeroGenerations))
+    ));
+    assert!(matches!(
+      plan_gpt_image_2p5_params(&GenerateImageRequestBuilder { image_batch_count: Some(5), ..base_builder() }),
+      Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption { .. }))
+    ));
+    let text = unwrap_t2i(plan_gpt_image_2p5_params(&GenerateImageRequestBuilder {
+      image_batch_count: Some(5),
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::PayMoreUpgrade,
+      ..base_builder()
+    }));
+    assert_debug(text.num_images, "Four");
+  }
+
+  #[test]
+  fn quality_maps_exhaustively_for_text_and_edit() {
+    let cases = [
+      (None, "Some(High)"),
+      (Some(RouterQuality::Low), "Some(Low)"),
+      (Some(RouterQuality::Medium), "Some(Medium)"),
+      (Some(RouterQuality::High), "Some(High)"),
+    ];
+    for (quality, expected) in cases {
+      let text = unwrap_t2i(plan_gpt_image_2p5_params(&GenerateImageRequestBuilder { quality, ..base_builder() }));
+      assert_debug(text.quality, expected);
+      let edit = unwrap_edit(plan_gpt_image_2p5_params(&with_reference_image(GenerateImageRequestBuilder { quality, ..base_builder() })));
+      assert_debug(edit.quality, expected);
+    }
+  }
+
+  #[test]
+  fn resolution_maps_exhaustively_for_text_and_edit() {
+    let cases = [
+      (None, "None"),
+      (Some(RouterResolution::HalfK), "Some(OneK)"),
+      (Some(RouterResolution::FourEightyP), "Some(OneK)"),
+      (Some(RouterResolution::SevenTwentyP), "Some(OneK)"),
+      (Some(RouterResolution::OneK), "Some(OneK)"),
+      (Some(RouterResolution::TenEightyP), "Some(TwoK)"),
+      (Some(RouterResolution::TwoK), "Some(TwoK)"),
+      (Some(RouterResolution::ThreeK), "Some(ThreeK)"),
+      (Some(RouterResolution::FourK), "Some(FourK)"),
+    ];
+    for (resolution, expected) in cases {
+      let text = unwrap_t2i(plan_gpt_image_2p5_params(&GenerateImageRequestBuilder { resolution, ..base_builder() }));
+      assert_debug(text.resolution, expected);
+      let edit = unwrap_edit(plan_gpt_image_2p5_params(&with_reference_image(GenerateImageRequestBuilder { resolution, ..base_builder() })));
+      assert_debug(edit.resolution, expected);
+    }
+  }
+
+  #[test]
+  fn aspect_ratio_maps_exhaustively_for_text_and_edit() {
+    let cases = [
+      (None, "None"),
+      (Some(RouterAspectRatio::Auto), "Some(Auto)"),
+      (Some(RouterAspectRatio::Auto2k), "Some(Auto)"),
+      (Some(RouterAspectRatio::Auto3k), "Some(Auto)"),
+      (Some(RouterAspectRatio::Auto4k), "Some(Auto)"),
+      (Some(RouterAspectRatio::Square), "Some(Square)"),
+      (Some(RouterAspectRatio::SquareHd), "Some(SquareHd)"),
+      (Some(RouterAspectRatio::WideThreeByTwo), "Some(Landscape16x9)"),
+      (Some(RouterAspectRatio::WideFourByThree), "Some(Landscape4x3)"),
+      (Some(RouterAspectRatio::WideFiveByFour), "Some(Landscape4x3)"),
+      (Some(RouterAspectRatio::WideSixteenByNine), "Some(Landscape16x9)"),
+      (Some(RouterAspectRatio::WideTwentyOneByNine), "Some(Landscape16x9)"),
+      (Some(RouterAspectRatio::Wide), "Some(Landscape16x9)"),
+      (Some(RouterAspectRatio::TallTwoByThree), "Some(Portrait16x9)"),
+      (Some(RouterAspectRatio::TallThreeByFour), "Some(Portrait4x3)"),
+      (Some(RouterAspectRatio::TallFourByFive), "Some(Portrait4x3)"),
+      (Some(RouterAspectRatio::TallNineBySixteen), "Some(Portrait16x9)"),
+      (Some(RouterAspectRatio::TallNineByTwentyOne), "Some(Portrait16x9)"),
+      (Some(RouterAspectRatio::Tall), "Some(Portrait16x9)"),
+    ];
+    for (aspect_ratio, expected) in cases {
+      let text = unwrap_t2i(plan_gpt_image_2p5_params(&GenerateImageRequestBuilder { aspect_ratio, ..base_builder() }));
+      assert_debug(text.image_size, expected);
+      let edit = unwrap_edit(plan_gpt_image_2p5_params(&with_reference_image(GenerateImageRequestBuilder { aspect_ratio, ..base_builder() })));
+      assert_debug(edit.image_size, expected);
+    }
+  }
+
+  fn base_builder() -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
+      model: RouterImageModel::GptImage2p5Flare,
+      provider: RouterProvider::Fal,
+      prompt: Some("a cat in space".to_string()),
+      image_inputs: None,
+      resolution: None,
+      aspect_ratio: None,
+      quality: None,
+      image_batch_count: None,
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+    }
+  }
+
+  fn with_reference_image(builder: GenerateImageRequestBuilder) -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
+      image_inputs: Some(ImageListRef::Urls(vec![IMAGE_URL.to_string()])),
+      ..builder
+    }
+  }
+
+  fn unwrap_t2i(result: Result<PlannedGptImage2p5Params, ArtcraftRouterError>) -> GptImage2p5TextToImageParams {
+    match result.expect("plan should succeed") {
+      PlannedGptImage2p5Params::TextToImage(params) => params,
+      PlannedGptImage2p5Params::EditImage(_) => panic!("expected text-to-image"),
+    }
+  }
+
+  fn unwrap_edit(result: Result<PlannedGptImage2p5Params, ArtcraftRouterError>) -> GptImage2p5EditImageParams {
+    match result.expect("plan should succeed") {
+      PlannedGptImage2p5Params::EditImage(params) => params,
+      PlannedGptImage2p5Params::TextToImage(_) => panic!("expected edit-image"),
+    }
+  }
+
+  fn assert_debug<T: Debug>(actual: T, expected: &str) {
+    assert_eq!(format!("{:?}", actual), expected);
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/fal/gpt_image_2p5_common/send.rs

@@ -0,0 +1,42 @@
+use std::fmt::Debug;
+use std::sync::Arc;
+
+use fal_client::requests::traits::fal_endpoint_trait::FalEndpoint;
+
+use crate::client::router_fal_client::RouterFalClient;
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_image::generate_image_response::{FalImageResponsePayload, GenerateImageResponse};
+
+/// Send any GPT Image 2.5 request (Flare or Sunburst, text-to-image or edit) to Fal, via
+/// webhook when the client has one configured and via the queue otherwise.
+pub async fn send_gpt_image_2p5_request<T>(
+  request: &T,
+  client: &RouterFalClient,
+) -> Result<GenerateImageResponse, ArtcraftRouterError>
+where
+  T: FalEndpoint + Clone + Debug + Send + Sync + 'static,
+{
+  let outbound: Arc<dyn Debug + Send + Sync> = Arc::new(request.clone());
+
+  let payload = if let Some(webhook_url) = &client.webhook_url {
+    let response = request.send_webhook_request(&client.api_key, webhook_url).await?;
+    FalImageResponsePayload {
+      request_id: response.request_id,
+      gateway_request_id: response.gateway_request_id,
+      maybe_status_url: None,
+      maybe_response_url: None,
+      maybe_outbound_request: Some(outbound),
+    }
+  } else {
+    let response = request.send_queue_request(&client.api_key).await?;
+    FalImageResponsePayload {
+      request_id: Some(response.request_id),
+      gateway_request_id: None,
+      maybe_status_url: Some(response.status_url),
+      maybe_response_url: Some(response.response_url),
+      maybe_outbound_request: Some(outbound),
+    }
+  };
+
+  Ok(GenerateImageResponse::Fal(payload))
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/fal/gpt_image_2p5_flare/build.rs

@@ -0,0 +1,129 @@
+use fal_client::requests::api::image::edit::gpt_image_2p5_flare_edit_image::api::GptImage2p5FlareEditImageRequest;
+use fal_client::requests::api::image::text::gpt_image_2p5_flare_text_to_image::api::GptImage2p5FlareTextToImageRequest;
+
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
+use crate::generate::generate_image::image_generation_draft_or_request::ImageGenerationDraftOrRequest;
+use crate::generate::generate_image::image_generation_request::ImageGenerationRequest;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_common::plan::{plan_gpt_image_2p5_params, PlannedGptImage2p5Params};
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_flare::request::FalGptImage2p5FlareRequestState;
+
+/// Text-to-image and edit share one model entry; the mode is chosen by whether the builder
+/// carries reference images. Planning is shared with the other GPT Image 2.5 variant.
+pub fn build_fal_gpt_image_2p5_flare(
+  builder: GenerateImageRequestBuilder,
+) -> Result<ImageGenerationDraftOrRequest, ArtcraftRouterError> {
+  let state = match plan_gpt_image_2p5_params(&builder)? {
+    PlannedGptImage2p5Params::TextToImage(params) => {
+      FalGptImage2p5FlareRequestState::TextToImage(GptImage2p5FlareTextToImageRequest { params })
+    }
+    PlannedGptImage2p5Params::EditImage(params) => {
+      FalGptImage2p5FlareRequestState::EditImage(GptImage2p5FlareEditImageRequest { params })
+    }
+  };
+
+  Ok(ImageGenerationDraftOrRequest::Request(
+    ImageGenerationRequest::FalGptImage2p5Flare(state),
+  ))
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use fal_client::requests::traits::fal_endpoint_trait::FalEndpoint;
+
+  use crate::api::image_list_ref::ImageListRef;
+  use crate::api::router_aspect_ratio::RouterAspectRatio;
+  use crate::api::router_image_model::RouterImageModel;
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_quality::RouterQuality;
+  use crate::api::router_resolution::RouterResolution;
+  use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+
+  #[test]
+  fn build2_routes_to_flare_text_to_image() {
+    let request = unwrap_t2i(base_builder().build2());
+    assert_eq!(request.params.prompt, "a cat in space");
+    assert_eq!(GptImage2p5FlareTextToImageRequest::ENDPOINT, "openai/gpt-image-2.5/flare/text-to-image");
+  }
+
+  #[test]
+  fn build2_routes_to_flare_edit_when_reference_images_present() {
+    let request = unwrap_edit(GenerateImageRequestBuilder {
+      image_inputs: Some(ImageListRef::Urls(vec!["https://example.com/img.jpg".to_string()])),
+      ..base_builder()
+    }.build2());
+    assert_eq!(request.params.image_urls, vec!["https://example.com/img.jpg"]);
+    assert_eq!(GptImage2p5FlareEditImageRequest::ENDPOINT, "openai/gpt-image-2.5/flare/edit");
+  }
+
+  #[test]
+  fn planned_fields_reach_the_fal_request() {
+    let request = unwrap_t2i(GenerateImageRequestBuilder {
+      aspect_ratio: Some(RouterAspectRatio::WideSixteenByNine),
+      resolution: Some(RouterResolution::TwoK),
+      quality: Some(RouterQuality::Medium),
+      image_batch_count: Some(3),
+      ..base_builder()
+    }.build2());
+    assert_eq!(format!("{:?}", request.params.image_size), "Some(Landscape16x9)");
+    assert_eq!(format!("{:?}", request.params.resolution), "Some(TwoK)");
+    assert_eq!(format!("{:?}", request.params.quality), "Some(Medium)");
+    assert_eq!(format!("{:?}", request.params.num_images), "Three");
+  }
+
+  #[test]
+  fn raw_wire_request_matches_fal_schema() {
+    let request = unwrap_t2i(GenerateImageRequestBuilder {
+      aspect_ratio: Some(RouterAspectRatio::Square),
+      quality: Some(RouterQuality::High),
+      image_batch_count: Some(2),
+      ..base_builder()
+    }.build2());
+    let json = serde_json::to_value(request.to_raw_request().unwrap()).unwrap();
+    assert_eq!(json, serde_json::json!({
+      "prompt": "a cat in space",
+      "image_size": "square",
+      "quality": "high",
+      "num_images": 2,
+      "output_format": "png",
+    }));
+  }
+
+  fn base_builder() -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
+      model: RouterImageModel::GptImage2p5Flare,
+      provider: RouterProvider::Fal,
+      prompt: Some("a cat in space".to_string()),
+      image_inputs: None,
+      resolution: None,
+      aspect_ratio: None,
+      quality: None,
+      image_batch_count: None,
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+    }
+  }
+
+  fn unwrap_t2i(result: Result<ImageGenerationDraftOrRequest, ArtcraftRouterError>) -> GptImage2p5FlareTextToImageRequest {
+    let ImageGenerationDraftOrRequest::Request(
+      ImageGenerationRequest::FalGptImage2p5Flare(FalGptImage2p5FlareRequestState::TextToImage(request))
+    ) = result.expect("build should succeed") else {
+      panic!("expected GPT Image 2.5 Flare text-to-image request")
+    };
+    request
+  }
+
+  fn unwrap_edit(result: Result<ImageGenerationDraftOrRequest, ArtcraftRouterError>) -> GptImage2p5FlareEditImageRequest {
+    let ImageGenerationDraftOrRequest::Request(
+      ImageGenerationRequest::FalGptImage2p5Flare(FalGptImage2p5FlareRequestState::EditImage(request))
+    ) = result.expect("build should succeed") else {
+      panic!("expected GPT Image 2.5 Flare edit-image request")
+    };
+    request
+  }
+}

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

@@ -0,0 +1,133 @@
+use fal_client::requests::traits::fal_request_cost_calculator_trait::FalRequestCostCalculator;
+
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_flare::request::FalGptImage2p5FlareRequestState;
+
+/// Cost state for Fal GPT Image 2.5 Flare. Delegates to `fal_client`'s calculator, which
+/// prices by output dimensions (aspect ratio and resolution tier), quality, batch size and,
+/// for edits, the number of reference images.
+#[derive(Clone, Debug)]
+pub struct FalGptImage2p5FlareCostState {
+  cost_in_usd_cents: u64,
+}
+
+impl FalGptImage2p5FlareCostState {
+  pub fn from_request(request: &FalGptImage2p5FlareRequestState) -> Self {
+    let cost_in_usd_cents = match request {
+      FalGptImage2p5FlareRequestState::TextToImage(request) => request.calculate_cost_in_cents(),
+      FalGptImage2p5FlareRequestState::EditImage(request) => request.calculate_cost_in_cents(),
+    };
+    Self { cost_in_usd_cents }
+  }
+
+  pub fn estimate_cost(&self) -> ImageGenerationCostEstimate {
+    ImageGenerationCostEstimate {
+      cost_in_credits: Some(self.cost_in_usd_cents),
+      cost_in_usd_cents: Some(self.cost_in_usd_cents),
+      is_free: false,
+      is_unlimited: false,
+      is_rate_limited: false,
+      has_watermark: false,
+      failures_are_refunded: None,
+    }
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use crate::api::image_list_ref::ImageListRef;
+  use crate::api::router_aspect_ratio::RouterAspectRatio;
+  use crate::api::router_image_model::RouterImageModel;
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_quality::RouterQuality;
+  use crate::api::router_resolution::RouterResolution;
+  use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
+  use RouterAspectRatio as Ar;
+  use RouterQuality as Q;
+  use RouterResolution as R;
+
+  // (quality, aspect_ratio, resolution, batch, expected_cents) — text-to-image
+  const TEXT_CASES: &[(Option<Q>, Option<Ar>, Option<R>, u16, u64)] = &[
+    (None,            None,                    None,          1,  4), // Fal default: landscape_4_3, high
+    (Some(Q::Low),    Some(Ar::Square),        None,          1,  1),
+    (Some(Q::Medium), Some(Ar::Square),        None,          1,  2),
+    (Some(Q::High),   Some(Ar::Square),        None,          1,  6),
+    (Some(Q::High),   Some(Ar::Square),        None,          4, 24),
+    (Some(Q::High),   Some(Ar::SquareHd),      None,          1,  9),
+    (Some(Q::High),   Some(Ar::Square),        Some(R::TwoK), 1,  9),
+    (Some(Q::High),   Some(Ar::Square),        Some(R::FourK), 1, 13),
+    (Some(Q::High),   Some(Ar::WideFourByThree), None,        1,  4),
+    (Some(Q::High),   Some(Ar::TallThreeByFour), None,        1,  4),
+    (Some(Q::High),   Some(Ar::WideSixteenByNine), None,      1,  4),
+    (Some(Q::High),   Some(Ar::WideSixteenByNine), Some(R::OneK), 1, 3),
+    (Some(Q::High),   Some(Ar::WideSixteenByNine), Some(R::FourK), 1, 11),
+    (Some(Q::Medium), Some(Ar::TallNineBySixteen), Some(R::ThreeK), 2, 4),
+    (Some(Q::High),   Some(Ar::Auto),          None,          1, 11),
+    (Some(Q::High),   Some(Ar::Auto4k),        None,          1, 11),
+  ];
+
+  // (reference_images, quality, aspect_ratio, resolution, batch, expected_cents) — edit
+  const EDIT_CASES: &[(usize, Option<Q>, Option<Ar>, Option<R>, u16, u64)] = &[
+    (1, None,          None,             None,          1, 11), // Fal default: auto, high
+    (1, Some(Q::Low),  Some(Ar::Square), None,          1,  2),
+    (1, Some(Q::High), Some(Ar::Square), None,          1,  7),
+    (3, Some(Q::High), Some(Ar::Square), None,          1,  8),
+    (1, Some(Q::High), Some(Ar::Square), None,          4, 28),
+    (1, Some(Q::High), Some(Ar::WideSixteenByNine), Some(R::FourK), 1, 11),
+    (2, Some(Q::High), Some(Ar::Auto),   None,          1, 12),
+  ];
+
+  #[test]
+  fn text_to_image_costs() {
+    for &(quality, aspect_ratio, resolution, batch, expected) in TEXT_CASES {
+      assert_eq!(cost_cents(0, quality, aspect_ratio, resolution, batch), expected, "{quality:?} {aspect_ratio:?} {resolution:?} x{batch}");
+    }
+  }
+
+  #[test]
+  fn edit_image_costs() {
+    for &(refs, quality, aspect_ratio, resolution, batch, expected) in EDIT_CASES {
+      assert_eq!(cost_cents(refs, quality, aspect_ratio, resolution, batch), expected, "{refs} refs {quality:?} {aspect_ratio:?} {resolution:?} x{batch}");
+    }
+  }
+
+  #[test]
+  fn estimate_flags() {
+    let cost = builder(0, Some(Q::High), Some(Ar::Square), None, 1).build2().unwrap().estimate_cost().unwrap();
+    assert_eq!(cost.cost_in_credits, cost.cost_in_usd_cents);
+    assert!(!cost.is_free);
+    assert!(!cost.is_unlimited);
+    assert!(!cost.is_rate_limited);
+    assert!(!cost.has_watermark);
+  }
+
+  fn cost_cents(refs: usize, quality: Option<Q>, aspect_ratio: Option<Ar>, resolution: Option<R>, batch: u16) -> u64 {
+    builder(refs, quality, aspect_ratio, resolution, batch)
+      .build2().unwrap().estimate_cost().unwrap().cost_in_usd_cents.unwrap()
+  }
+
+  fn builder(refs: usize, quality: Option<Q>, aspect_ratio: Option<Ar>, resolution: Option<R>, batch: u16) -> GenerateImageRequestBuilder {
+    let image_inputs = if refs == 0 {
+      None
+    } else {
+      Some(ImageListRef::Urls(vec!["https://example.com/img.jpg".to_string(); refs]))
+    };
+    GenerateImageRequestBuilder {
+      model: RouterImageModel::GptImage2p5Flare,
+      provider: RouterProvider::Fal,
+      prompt: Some("a cat in space".to_string()),
+      image_inputs,
+      resolution,
+      aspect_ratio,
+      quality,
+      image_batch_count: Some(batch),
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+    }
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/fal/gpt_image_2p5_flare/request.rs

@@ -0,0 +1,86 @@
+use fal_client::requests::api::image::edit::gpt_image_2p5_flare_edit_image::api::GptImage2p5FlareEditImageRequest;
+use fal_client::requests::api::image::text::gpt_image_2p5_flare_text_to_image::api::GptImage2p5FlareTextToImageRequest;
+
+use crate::client::router_fal_client::RouterFalClient;
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_image::generate_image_response::GenerateImageResponse;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_common::send::send_gpt_image_2p5_request;
+
+#[derive(Clone, Debug)]
+pub enum FalGptImage2p5FlareRequestState {
+  TextToImage(GptImage2p5FlareTextToImageRequest),
+  EditImage(GptImage2p5FlareEditImageRequest),
+}
+
+impl FalGptImage2p5FlareRequestState {
+  pub async fn send(&self, client: &RouterFalClient) -> Result<GenerateImageResponse, ArtcraftRouterError> {
+    match self {
+      Self::TextToImage(request) => send_gpt_image_2p5_request(request, client).await,
+      Self::EditImage(request) => send_gpt_image_2p5_request(request, client).await,
+    }
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use fal_client::creds::fal_api_key::FalApiKey;
+  use fal_client::requests::api::image::common::gpt_image_2_resolution::GptImage2Resolution;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_edit_image_params::GptImage2p5EditImageParams;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_image_size::GptImage2p5ImageSize;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_num_images::GptImage2p5NumImages;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_quality::GptImage2p5Quality;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_text_to_image_params::GptImage2p5TextToImageParams;
+  use test_data::web::image_urls::JUNO_AT_LAKE_IMAGE_URL;
+
+  #[tokio::test]
+  #[ignore] // requires real API key, incurs cost
+  async fn send_text_to_image_webhook() {
+    let request = FalGptImage2p5FlareRequestState::TextToImage(GptImage2p5FlareTextToImageRequest {
+      params: GptImage2p5TextToImageParams {
+        prompt: "a polished product photo of a glass compass".to_string(),
+        num_images: GptImage2p5NumImages::One,
+        image_size: Some(GptImage2p5ImageSize::Square),
+        resolution: Some(GptImage2Resolution::OneK),
+        quality: Some(GptImage2p5Quality::Low),
+        background: None,
+        output_format: None,
+        output_compression: None,
+      },
+    });
+    let response = request.send(&client_with_webhook()).await.expect("send should succeed");
+    let payload = response.get_fal_payload().expect("expected Fal payload");
+    assert!(payload.request_id.is_some() || payload.gateway_request_id.is_some());
+  }
+
+  #[tokio::test]
+  #[ignore] // requires real API key, incurs cost
+  async fn send_edit_image_webhook() {
+    let request = FalGptImage2p5FlareRequestState::EditImage(GptImage2p5FlareEditImageRequest {
+      params: GptImage2p5EditImageParams {
+        prompt: "make this look like an elegant magazine cover image".to_string(),
+        image_urls: vec![JUNO_AT_LAKE_IMAGE_URL.to_string()],
+        mask_url: None,
+        num_images: GptImage2p5NumImages::One,
+        image_size: Some(GptImage2p5ImageSize::Square),
+        resolution: Some(GptImage2Resolution::OneK),
+        quality: Some(GptImage2p5Quality::Low),
+        background: None,
+        output_format: None,
+        output_compression: None,
+      },
+    });
+    let response = request.send(&client_with_webhook()).await.expect("send should succeed");
+    let payload = response.get_fal_payload().expect("expected Fal payload");
+    assert!(payload.request_id.is_some() || payload.gateway_request_id.is_some());
+  }
+
+  fn client_with_webhook() -> RouterFalClient {
+    let secret = std::fs::read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")
+      .expect("Failed to read fal_api_key.txt");
+    RouterFalClient::new_with_webhook(
+      FalApiKey::from_str(secret.trim()),
+      "https://example.com/fal-webhook-test".to_string(),
+    )
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/fal/gpt_image_2p5_sunburst/build.rs

@@ -0,0 +1,129 @@
+use fal_client::requests::api::image::edit::gpt_image_2p5_sunburst_edit_image::api::GptImage2p5SunburstEditImageRequest;
+use fal_client::requests::api::image::text::gpt_image_2p5_sunburst_text_to_image::api::GptImage2p5SunburstTextToImageRequest;
+
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
+use crate::generate::generate_image::image_generation_draft_or_request::ImageGenerationDraftOrRequest;
+use crate::generate::generate_image::image_generation_request::ImageGenerationRequest;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_common::plan::{plan_gpt_image_2p5_params, PlannedGptImage2p5Params};
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_sunburst::request::FalGptImage2p5SunburstRequestState;
+
+/// Text-to-image and edit share one model entry; the mode is chosen by whether the builder
+/// carries reference images. Planning is shared with the other GPT Image 2.5 variant.
+pub fn build_fal_gpt_image_2p5_sunburst(
+  builder: GenerateImageRequestBuilder,
+) -> Result<ImageGenerationDraftOrRequest, ArtcraftRouterError> {
+  let state = match plan_gpt_image_2p5_params(&builder)? {
+    PlannedGptImage2p5Params::TextToImage(params) => {
+      FalGptImage2p5SunburstRequestState::TextToImage(GptImage2p5SunburstTextToImageRequest { params })
+    }
+    PlannedGptImage2p5Params::EditImage(params) => {
+      FalGptImage2p5SunburstRequestState::EditImage(GptImage2p5SunburstEditImageRequest { params })
+    }
+  };
+
+  Ok(ImageGenerationDraftOrRequest::Request(
+    ImageGenerationRequest::FalGptImage2p5Sunburst(state),
+  ))
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use fal_client::requests::traits::fal_endpoint_trait::FalEndpoint;
+
+  use crate::api::image_list_ref::ImageListRef;
+  use crate::api::router_aspect_ratio::RouterAspectRatio;
+  use crate::api::router_image_model::RouterImageModel;
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_quality::RouterQuality;
+  use crate::api::router_resolution::RouterResolution;
+  use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+
+  #[test]
+  fn build2_routes_to_sunburst_text_to_image() {
+    let request = unwrap_t2i(base_builder().build2());
+    assert_eq!(request.params.prompt, "a cat in space");
+    assert_eq!(GptImage2p5SunburstTextToImageRequest::ENDPOINT, "openai/gpt-image-2.5/sunburst/text-to-image");
+  }
+
+  #[test]
+  fn build2_routes_to_sunburst_edit_when_reference_images_present() {
+    let request = unwrap_edit(GenerateImageRequestBuilder {
+      image_inputs: Some(ImageListRef::Urls(vec!["https://example.com/img.jpg".to_string()])),
+      ..base_builder()
+    }.build2());
+    assert_eq!(request.params.image_urls, vec!["https://example.com/img.jpg"]);
+    assert_eq!(GptImage2p5SunburstEditImageRequest::ENDPOINT, "openai/gpt-image-2.5/sunburst/edit");
+  }
+
+  #[test]
+  fn planned_fields_reach_the_fal_request() {
+    let request = unwrap_t2i(GenerateImageRequestBuilder {
+      aspect_ratio: Some(RouterAspectRatio::WideSixteenByNine),
+      resolution: Some(RouterResolution::TwoK),
+      quality: Some(RouterQuality::Medium),
+      image_batch_count: Some(3),
+      ..base_builder()
+    }.build2());
+    assert_eq!(format!("{:?}", request.params.image_size), "Some(Landscape16x9)");
+    assert_eq!(format!("{:?}", request.params.resolution), "Some(TwoK)");
+    assert_eq!(format!("{:?}", request.params.quality), "Some(Medium)");
+    assert_eq!(format!("{:?}", request.params.num_images), "Three");
+  }
+
+  #[test]
+  fn raw_wire_request_matches_fal_schema() {
+    let request = unwrap_t2i(GenerateImageRequestBuilder {
+      aspect_ratio: Some(RouterAspectRatio::Square),
+      quality: Some(RouterQuality::High),
+      image_batch_count: Some(2),
+      ..base_builder()
+    }.build2());
+    let json = serde_json::to_value(request.to_raw_request().unwrap()).unwrap();
+    assert_eq!(json, serde_json::json!({
+      "prompt": "a cat in space",
+      "image_size": "square",
+      "quality": "high",
+      "num_images": 2,
+      "output_format": "png",
+    }));
+  }
+
+  fn base_builder() -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
+      model: RouterImageModel::GptImage2p5Sunburst,
+      provider: RouterProvider::Fal,
+      prompt: Some("a cat in space".to_string()),
+      image_inputs: None,
+      resolution: None,
+      aspect_ratio: None,
+      quality: None,
+      image_batch_count: None,
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+    }
+  }
+
+  fn unwrap_t2i(result: Result<ImageGenerationDraftOrRequest, ArtcraftRouterError>) -> GptImage2p5SunburstTextToImageRequest {
+    let ImageGenerationDraftOrRequest::Request(
+      ImageGenerationRequest::FalGptImage2p5Sunburst(FalGptImage2p5SunburstRequestState::TextToImage(request))
+    ) = result.expect("build should succeed") else {
+      panic!("expected GPT Image 2.5 Sunburst text-to-image request")
+    };
+    request
+  }
+
+  fn unwrap_edit(result: Result<ImageGenerationDraftOrRequest, ArtcraftRouterError>) -> GptImage2p5SunburstEditImageRequest {
+    let ImageGenerationDraftOrRequest::Request(
+      ImageGenerationRequest::FalGptImage2p5Sunburst(FalGptImage2p5SunburstRequestState::EditImage(request))
+    ) = result.expect("build should succeed") else {
+      panic!("expected GPT Image 2.5 Sunburst edit-image request")
+    };
+    request
+  }
+}

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

@@ -0,0 +1,133 @@
+use fal_client::requests::traits::fal_request_cost_calculator_trait::FalRequestCostCalculator;
+
+use crate::generate::generate_image::image_generation_cost_estimate::ImageGenerationCostEstimate;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_sunburst::request::FalGptImage2p5SunburstRequestState;
+
+/// Cost state for Fal GPT Image 2.5 Sunburst. Delegates to `fal_client`'s calculator, which
+/// prices by output dimensions (aspect ratio and resolution tier), quality, batch size and,
+/// for edits, the number of reference images.
+#[derive(Clone, Debug)]
+pub struct FalGptImage2p5SunburstCostState {
+  cost_in_usd_cents: u64,
+}
+
+impl FalGptImage2p5SunburstCostState {
+  pub fn from_request(request: &FalGptImage2p5SunburstRequestState) -> Self {
+    let cost_in_usd_cents = match request {
+      FalGptImage2p5SunburstRequestState::TextToImage(request) => request.calculate_cost_in_cents(),
+      FalGptImage2p5SunburstRequestState::EditImage(request) => request.calculate_cost_in_cents(),
+    };
+    Self { cost_in_usd_cents }
+  }
+
+  pub fn estimate_cost(&self) -> ImageGenerationCostEstimate {
+    ImageGenerationCostEstimate {
+      cost_in_credits: Some(self.cost_in_usd_cents),
+      cost_in_usd_cents: Some(self.cost_in_usd_cents),
+      is_free: false,
+      is_unlimited: false,
+      is_rate_limited: false,
+      has_watermark: false,
+      failures_are_refunded: None,
+    }
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use crate::api::image_list_ref::ImageListRef;
+  use crate::api::router_aspect_ratio::RouterAspectRatio;
+  use crate::api::router_image_model::RouterImageModel;
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_quality::RouterQuality;
+  use crate::api::router_resolution::RouterResolution;
+  use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
+  use RouterAspectRatio as Ar;
+  use RouterQuality as Q;
+  use RouterResolution as R;
+
+  // (quality, aspect_ratio, resolution, batch, expected_cents) — text-to-image
+  const TEXT_CASES: &[(Option<Q>, Option<Ar>, Option<R>, u16, u64)] = &[
+    (None,            None,                    None,          1,  4), // Fal default: landscape_4_3, high
+    (Some(Q::Low),    Some(Ar::Square),        None,          1,  1),
+    (Some(Q::Medium), Some(Ar::Square),        None,          1,  2),
+    (Some(Q::High),   Some(Ar::Square),        None,          1,  6),
+    (Some(Q::High),   Some(Ar::Square),        None,          4, 24),
+    (Some(Q::High),   Some(Ar::SquareHd),      None,          1,  9),
+    (Some(Q::High),   Some(Ar::Square),        Some(R::TwoK), 1,  9),
+    (Some(Q::High),   Some(Ar::Square),        Some(R::FourK), 1, 13),
+    (Some(Q::High),   Some(Ar::WideFourByThree), None,        1,  4),
+    (Some(Q::High),   Some(Ar::TallThreeByFour), None,        1,  4),
+    (Some(Q::High),   Some(Ar::WideSixteenByNine), None,      1,  4),
+    (Some(Q::High),   Some(Ar::WideSixteenByNine), Some(R::OneK), 1, 3),
+    (Some(Q::High),   Some(Ar::WideSixteenByNine), Some(R::FourK), 1, 11),
+    (Some(Q::Medium), Some(Ar::TallNineBySixteen), Some(R::ThreeK), 2, 4),
+    (Some(Q::High),   Some(Ar::Auto),          None,          1, 11),
+    (Some(Q::High),   Some(Ar::Auto4k),        None,          1, 11),
+  ];
+
+  // (reference_images, quality, aspect_ratio, resolution, batch, expected_cents) — edit
+  const EDIT_CASES: &[(usize, Option<Q>, Option<Ar>, Option<R>, u16, u64)] = &[
+    (1, None,          None,             None,          1, 11), // Fal default: auto, high
+    (1, Some(Q::Low),  Some(Ar::Square), None,          1,  2),
+    (1, Some(Q::High), Some(Ar::Square), None,          1,  7),
+    (3, Some(Q::High), Some(Ar::Square), None,          1,  8),
+    (1, Some(Q::High), Some(Ar::Square), None,          4, 28),
+    (1, Some(Q::High), Some(Ar::WideSixteenByNine), Some(R::FourK), 1, 11),
+    (2, Some(Q::High), Some(Ar::Auto),   None,          1, 12),
+  ];
+
+  #[test]
+  fn text_to_image_costs() {
+    for &(quality, aspect_ratio, resolution, batch, expected) in TEXT_CASES {
+      assert_eq!(cost_cents(0, quality, aspect_ratio, resolution, batch), expected, "{quality:?} {aspect_ratio:?} {resolution:?} x{batch}");
+    }
+  }
+
+  #[test]
+  fn edit_image_costs() {
+    for &(refs, quality, aspect_ratio, resolution, batch, expected) in EDIT_CASES {
+      assert_eq!(cost_cents(refs, quality, aspect_ratio, resolution, batch), expected, "{refs} refs {quality:?} {aspect_ratio:?} {resolution:?} x{batch}");
+    }
+  }
+
+  #[test]
+  fn estimate_flags() {
+    let cost = builder(0, Some(Q::High), Some(Ar::Square), None, 1).build2().unwrap().estimate_cost().unwrap();
+    assert_eq!(cost.cost_in_credits, cost.cost_in_usd_cents);
+    assert!(!cost.is_free);
+    assert!(!cost.is_unlimited);
+    assert!(!cost.is_rate_limited);
+    assert!(!cost.has_watermark);
+  }
+
+  fn cost_cents(refs: usize, quality: Option<Q>, aspect_ratio: Option<Ar>, resolution: Option<R>, batch: u16) -> u64 {
+    builder(refs, quality, aspect_ratio, resolution, batch)
+      .build2().unwrap().estimate_cost().unwrap().cost_in_usd_cents.unwrap()
+  }
+
+  fn builder(refs: usize, quality: Option<Q>, aspect_ratio: Option<Ar>, resolution: Option<R>, batch: u16) -> GenerateImageRequestBuilder {
+    let image_inputs = if refs == 0 {
+      None
+    } else {
+      Some(ImageListRef::Urls(vec!["https://example.com/img.jpg".to_string(); refs]))
+    };
+    GenerateImageRequestBuilder {
+      model: RouterImageModel::GptImage2p5Sunburst,
+      provider: RouterProvider::Fal,
+      prompt: Some("a cat in space".to_string()),
+      image_inputs,
+      resolution,
+      aspect_ratio,
+      quality,
+      image_batch_count: Some(batch),
+      horizontal_angle: None,
+      vertical_angle: None,
+      zoom: None,
+      request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
+      generation_mode_mismatch_strategy: None,
+      idempotency_token: None,
+    }
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/fal/gpt_image_2p5_sunburst/request.rs

@@ -0,0 +1,86 @@
+use fal_client::requests::api::image::edit::gpt_image_2p5_sunburst_edit_image::api::GptImage2p5SunburstEditImageRequest;
+use fal_client::requests::api::image::text::gpt_image_2p5_sunburst_text_to_image::api::GptImage2p5SunburstTextToImageRequest;
+
+use crate::client::router_fal_client::RouterFalClient;
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_image::generate_image_response::GenerateImageResponse;
+use crate::generate::generate_image::providers::fal::gpt_image_2p5_common::send::send_gpt_image_2p5_request;
+
+#[derive(Clone, Debug)]
+pub enum FalGptImage2p5SunburstRequestState {
+  TextToImage(GptImage2p5SunburstTextToImageRequest),
+  EditImage(GptImage2p5SunburstEditImageRequest),
+}
+
+impl FalGptImage2p5SunburstRequestState {
+  pub async fn send(&self, client: &RouterFalClient) -> Result<GenerateImageResponse, ArtcraftRouterError> {
+    match self {
+      Self::TextToImage(request) => send_gpt_image_2p5_request(request, client).await,
+      Self::EditImage(request) => send_gpt_image_2p5_request(request, client).await,
+    }
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use fal_client::creds::fal_api_key::FalApiKey;
+  use fal_client::requests::api::image::common::gpt_image_2_resolution::GptImage2Resolution;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_edit_image_params::GptImage2p5EditImageParams;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_image_size::GptImage2p5ImageSize;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_num_images::GptImage2p5NumImages;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_quality::GptImage2p5Quality;
+  use fal_client::requests::api::image::common::gpt_image_2p5::gpt_image_2p5_text_to_image_params::GptImage2p5TextToImageParams;
+  use test_data::web::image_urls::JUNO_AT_LAKE_IMAGE_URL;
+
+  #[tokio::test]
+  #[ignore] // requires real API key, incurs cost
+  async fn send_text_to_image_webhook() {
+    let request = FalGptImage2p5SunburstRequestState::TextToImage(GptImage2p5SunburstTextToImageRequest {
+      params: GptImage2p5TextToImageParams {
+        prompt: "a polished product photo of a glass compass".to_string(),
+        num_images: GptImage2p5NumImages::One,
+        image_size: Some(GptImage2p5ImageSize::Square),
+        resolution: Some(GptImage2Resolution::OneK),
+        quality: Some(GptImage2p5Quality::Low),
+        background: None,
+        output_format: None,
+        output_compression: None,
+      },
+    });
+    let response = request.send(&client_with_webhook()).await.expect("send should succeed");
+    let payload = response.get_fal_payload().expect("expected Fal payload");
+    assert!(payload.request_id.is_some() || payload.gateway_request_id.is_some());
+  }
+
+  #[tokio::test]
+  #[ignore] // requires real API key, incurs cost
+  async fn send_edit_image_webhook() {
+    let request = FalGptImage2p5SunburstRequestState::EditImage(GptImage2p5SunburstEditImageRequest {
+      params: GptImage2p5EditImageParams {
+        prompt: "make this look like an elegant magazine cover image".to_string(),
+        image_urls: vec![JUNO_AT_LAKE_IMAGE_URL.to_string()],
+        mask_url: None,
+        num_images: GptImage2p5NumImages::One,
+        image_size: Some(GptImage2p5ImageSize::Square),
+        resolution: Some(GptImage2Resolution::OneK),
+        quality: Some(GptImage2p5Quality::Low),
+        background: None,
+        output_format: None,
+        output_compression: None,
+      },
+    });
+    let response = request.send(&client_with_webhook()).await.expect("send should succeed");
+    let payload = response.get_fal_payload().expect("expected Fal payload");
+    assert!(payload.request_id.is_some() || payload.gateway_request_id.is_some());
+  }
+
+  fn client_with_webhook() -> RouterFalClient {
+    let secret = std::fs::read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")
+      .expect("Failed to read fal_api_key.txt");
+    RouterFalClient::new_with_webhook(
+      FalApiKey::from_str(secret.trim()),
+      "https://example.com/fal-webhook-test".to_string(),
+    )
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/providers/fal/mod.rs

@@ -6,6 +6,9 @@ pub mod flux_pro_1p1_ultra;
 pub mod gpt_image_1;
 pub mod gpt_image_1p5;
 pub mod gpt_image_2;
+pub mod gpt_image_2p5_common;
+pub mod gpt_image_2p5_flare;
+pub mod gpt_image_2p5_sunburst;
 pub mod nano_banana;
 pub mod nano_banana_2;
 pub mod nano_banana_pro;

crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/AGENTS.md

@@ -0,0 +1,127 @@
+# generate_video
+
+This module implements the v2 video generation pipeline. It replaces the v1 system
+(in `generate_video/`) with a two-phase approach that separates request planning from
+execution, allowing cost estimation and media uploads to happen at the right time.
+
+## Lifecycle
+
+```
+GenerateVideoRequestBuilder
+    │
+    ▼ build2()
+VideoGenerationDraftOrRequest
+    │
+    ├─ Draft(VideoGenerationDraftRequest)
+    │       │
+    │       ▼ estimate_cost()   ← cost estimate from draft state
+    │       │
+    │       ▼ finalize(context) ← uploads media, resolves tokens
+    │       │
+    │       ▼
+    │   VideoGenerationRequest
+    │       │
+    │       ▼ estimate_cost()   ← cost estimate from finalized request
+    │       │
+    │       ▼ send_request()    ← fires the API call
+    │       │
+    │       ▼
+    │   GenerateVideoResponse
+    │
+    └─ Request(VideoGenerationRequest)  ← skips draft phase (used by Artcraft provider)
+```
+
+### Key types
+
+- **`GenerateVideoRequestBuilder`** — generic builder with provider/model/prompt/resolution/etc.
+  Located in `generate_video/generate_video_request_builder.rs`. The `use_new_builder()` method
+  gates which provider+model combos use the v2 path. `build2()` dispatches to the correct
+  provider's build function.
+
+- **`VideoGenerationDraftOrRequest`** — the output of `build2()`. Either `Draft` (for providers
+  that need media upload/resolution, like Kinovi) or `Request` (for providers that work with
+  media file tokens directly, like Artcraft).
+
+- **`VideoGenerationDraftRequest`** — enum with one variant per provider+model. Holds
+  materialized settings (resolution, duration, batch count) plus unresolved media references.
+  Can estimate cost without network calls.
+
+- **`VideoGenerationDraftContext`** — context needed during `finalize()`: the provider client,
+  media file token-to-URL map, and character token-to-ID map.
+
+- **`VideoGenerationRequest`** — enum with one variant per provider+model. Holds a fully
+  materialized request ready to send. All media URLs are resolved and uploaded.
+
+### Cost estimation
+
+Cost can be estimated at two stages:
+1. **From draft** — before `finalize()`. Uses the planned resolution/duration/batch count.
+   Good for showing the user a price before committing.
+2. **From request** — after `finalize()`. Uses the final materialized request. Should match
+   the draft estimate for the same parameters.
+
+## Module layout
+
+```
+generate_video/
+├── mod.rs
+├── video_generation_draft.rs           ← VideoGenerationDraftRequest enum
+├── video_generation_draft_context.rs   ← context for finalize()
+├── video_generation_draft_or_request.rs
+├── video_generation_request.rs         ← VideoGenerationRequest enum
+└── providers/
+    ├── artcraft/                       ← Artcraft provider (uses media file tokens directly)
+    │   ├── seedance_2p0/              ← Seedance 2.0 Pro model (skips draft, returns Request directly)
+    │   │   ├── mod.rs
+    │   │   ├── build.rs               ← builder → Request conversion + plan helpers
+    │   │   ├── cost.rs                ← standalone cost estimation (independent of kinovi_web_client)
+    │   │   └── request.rs             ← request state + send() via Artcraft multi-function API
+    │   └── seedance_2p0_fast/         ← Seedance 2.0 Fast model (skips draft, 480p/720p only)
+    │       ├── mod.rs
+    │       ├── build.rs               ← builder → Request conversion + plan helpers (no 1080p)
+    │       ├── cost.rs                ← standalone cost estimation with Fast-specific pricing
+    │       └── request.rs             ← request state + send() via Artcraft omni-gen API
+    └── kinovi/                         ← Kinovi/KinoviWeb provider
+        ├── mod.rs
+        ├── resolve.rs                  ← shared: media token resolution, upload helpers
+        ├── upload.rs                   ← shared: download + re-upload to KinoviWeb CDN
+        ├── seedance_2p0/              ← Seedance 2.0 Pro model
+        │   ├── mod.rs
+        │   ├── build.rs               ← builder → draft conversion + plan helpers
+        │   ├── cost.rs                ← cost estimation state
+        │   ├── draft.rs               ← draft state + finalize (to_request)
+        │   └── request.rs             ← request state + send()
+        └── seedance_2p0_fast/         ← Seedance 2.0 Fast model
+            ├── mod.rs
+            ├── build.rs
+            ├── cost.rs
+            ├── draft.rs
+            └── request.rs
+```
+
+## Adding a new provider or model
+
+1. **Create the module** under `providers/{provider}/{model}/` with these files:
+   - `mod.rs` — declares sub-modules
+   - `build.rs` — `build_{provider}_{model}(builder) -> VideoGenerationDraftOrRequest`.
+     Contains `plan_*` helpers for aspect ratio, resolution, batch count, duration.
+   - `draft.rs` — draft state struct with `to_request()` async method for finalization.
+     **Not needed** if the provider uses media tokens directly (no upload/resolution needed);
+     in that case `build.rs` returns `VideoGenerationDraftOrRequest::Request(...)` directly.
+   - `cost.rs` — cost state with `from_request()` and `estimate_cost()`. Add `from_draft()`
+     if the provider uses the draft phase.
+   - `request.rs` — request state with `send()` async method.
+
+2. **Register the module** in the parent provider's `mod.rs`.
+
+3. **Add enum variants** in:
+   - `video_generation_draft.rs` — `VideoGenerationDraftRequest` enum + `estimate_cost` + `finalize`
+     (skip if provider has no draft phase)
+   - `video_generation_request.rs` — `VideoGenerationRequest` enum + `estimate_cost` + `send_request`
+
+4. **Wire into the builder** in `generate_video_request_builder.rs`:
+   - Add the `(Provider, Model)` pair to `use_new_builder()` returning `true`
+   - Add the dispatch arm in `build2()`
+
+5. **Tests**: each `build.rs` and `cost.rs` should have comprehensive tests. `request.rs`
+   should have `#[ignore]` live API tests for manual verification.

crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/CLAUDE.md

@@ -1,127 +0,0 @@
-# generate_video
-
-This module implements the v2 video generation pipeline. It replaces the v1 system
-(in `generate_video/`) with a two-phase approach that separates request planning from
-execution, allowing cost estimation and media uploads to happen at the right time.
-
-## Lifecycle
-
-```
-GenerateVideoRequestBuilder
-    │
-    ▼ build2()
-VideoGenerationDraftOrRequest
-    │
-    ├─ Draft(VideoGenerationDraftRequest)
-    │       │
-    │       ▼ estimate_cost()   ← cost estimate from draft state
-    │       │
-    │       ▼ finalize(context) ← uploads media, resolves tokens
-    │       │
-    │       ▼
-    │   VideoGenerationRequest
-    │       │
-    │       ▼ estimate_cost()   ← cost estimate from finalized request
-    │       │
-    │       ▼ send_request()    ← fires the API call
-    │       │
-    │       ▼
-    │   GenerateVideoResponse
-    │
-    └─ Request(VideoGenerationRequest)  ← skips draft phase (used by Artcraft provider)
-```
-
-### Key types
-
-- **`GenerateVideoRequestBuilder`** — generic builder with provider/model/prompt/resolution/etc.
-  Located in `generate_video/generate_video_request_builder.rs`. The `use_new_builder()` method
-  gates which provider+model combos use the v2 path. `build2()` dispatches to the correct
-  provider's build function.
-
-- **`VideoGenerationDraftOrRequest`** — the output of `build2()`. Either `Draft` (for providers
-  that need media upload/resolution, like Kinovi) or `Request` (for providers that work with
-  media file tokens directly, like Artcraft).
-
-- **`VideoGenerationDraftRequest`** — enum with one variant per provider+model. Holds
-  materialized settings (resolution, duration, batch count) plus unresolved media references.
-  Can estimate cost without network calls.
-
-- **`VideoGenerationDraftContext`** — context needed during `finalize()`: the provider client,
-  media file token-to-URL map, and character token-to-ID map.
-
-- **`VideoGenerationRequest`** — enum with one variant per provider+model. Holds a fully
-  materialized request ready to send. All media URLs are resolved and uploaded.
-
-### Cost estimation
-
-Cost can be estimated at two stages:
-1. **From draft** — before `finalize()`. Uses the planned resolution/duration/batch count.
-   Good for showing the user a price before committing.
-2. **From request** — after `finalize()`. Uses the final materialized request. Should match
-   the draft estimate for the same parameters.
-
-## Module layout
-
-```
-generate_video/
-├── mod.rs
-├── video_generation_draft.rs           ← VideoGenerationDraftRequest enum
-├── video_generation_draft_context.rs   ← context for finalize()
-├── video_generation_draft_or_request.rs
-├── video_generation_request.rs         ← VideoGenerationRequest enum
-└── providers/
-    ├── artcraft/                       ← Artcraft provider (uses media file tokens directly)
-    │   ├── seedance_2p0/              ← Seedance 2.0 Pro model (skips draft, returns Request directly)
-    │   │   ├── mod.rs
-    │   │   ├── build.rs               ← builder → Request conversion + plan helpers
-    │   │   ├── cost.rs                ← standalone cost estimation (independent of kinovi_web_client)
-    │   │   └── request.rs             ← request state + send() via Artcraft multi-function API
-    │   └── seedance_2p0_fast/         ← Seedance 2.0 Fast model (skips draft, 480p/720p only)
-    │       ├── mod.rs
-    │       ├── build.rs               ← builder → Request conversion + plan helpers (no 1080p)
-    │       ├── cost.rs                ← standalone cost estimation with Fast-specific pricing
-    │       └── request.rs             ← request state + send() via Artcraft omni-gen API
-    └── kinovi/                         ← Kinovi/KinoviWeb provider
-        ├── mod.rs
-        ├── resolve.rs                  ← shared: media token resolution, upload helpers
-        ├── upload.rs                   ← shared: download + re-upload to KinoviWeb CDN
-        ├── seedance_2p0/              ← Seedance 2.0 Pro model
-        │   ├── mod.rs
-        │   ├── build.rs               ← builder → draft conversion + plan helpers
-        │   ├── cost.rs                ← cost estimation state
-        │   ├── draft.rs               ← draft state + finalize (to_request)
-        │   └── request.rs             ← request state + send()
-        └── seedance_2p0_fast/         ← Seedance 2.0 Fast model
-            ├── mod.rs
-            ├── build.rs
-            ├── cost.rs
-            ├── draft.rs
-            └── request.rs
-```
-
-## Adding a new provider or model
-
-1. **Create the module** under `providers/{provider}/{model}/` with these files:
-   - `mod.rs` — declares sub-modules
-   - `build.rs` — `build_{provider}_{model}(builder) -> VideoGenerationDraftOrRequest`.
-     Contains `plan_*` helpers for aspect ratio, resolution, batch count, duration.
-   - `draft.rs` — draft state struct with `to_request()` async method for finalization.
-     **Not needed** if the provider uses media tokens directly (no upload/resolution needed);
-     in that case `build.rs` returns `VideoGenerationDraftOrRequest::Request(...)` directly.
-   - `cost.rs` — cost state with `from_request()` and `estimate_cost()`. Add `from_draft()`
-     if the provider uses the draft phase.
-   - `request.rs` — request state with `send()` async method.
-
-2. **Register the module** in the parent provider's `mod.rs`.
-
-3. **Add enum variants** in:
-   - `video_generation_draft.rs` — `VideoGenerationDraftRequest` enum + `estimate_cost` + `finalize`
-     (skip if provider has no draft phase)
-   - `video_generation_request.rs` — `VideoGenerationRequest` enum + `estimate_cost` + `send_request`
-
-4. **Wire into the builder** in `generate_video_request_builder.rs`:
-   - Add the `(Provider, Model)` pair to `use_new_builder()` returning `true`
-   - Add the dispatch arm in `build2()`
-
-5. **Tests**: each `build.rs` and `cost.rs` should have comprehensive tests. `request.rs`
-   should have `#[ignore]` live API tests for manual verification.

crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/generate_video_request_builder.rs

@@ -26,8 +26,6 @@ use crate::generate::generate_video::providers::artcraft::seedance_1p0_lite::bui
 use crate::generate::generate_video::providers::artcraft::seedance_1p5_pro::build::build_artcraft_seedance_1p5_pro;
 use crate::generate::generate_video::providers::artcraft::seedance_2p0::build::build_artcraft_seedance_2p0;
 use crate::generate::generate_video::providers::artcraft::seedance_2p0_fast::build::build_artcraft_seedance_2p0_fast;
-use crate::generate::generate_video::providers::artcraft::seedance_2p0_u::build::build_artcraft_seedance_2p0_u;
-use crate::generate::generate_video::providers::artcraft::seedance_2p0_u_fast::build::build_artcraft_seedance_2p0_u_fast;
 use crate::generate::generate_video::providers::artcraft::seedance_2p0_bp::build::build_artcraft_seedance_2p0_bp;
 use crate::generate::generate_video::providers::artcraft::seedance_2p0_bp_fast::build::build_artcraft_seedance_2p0_bp_fast;
 use crate::generate::generate_video::providers::artcraft::seedance_2p0_bpu::build::build_artcraft_seedance_2p0_bpu;
@@ -43,12 +41,13 @@ use crate::generate::generate_video::providers::artcraft::veo_3_fast::build::bui
 use crate::generate::generate_video::providers::artcraft::veo_3p1::build::build_artcraft_veo_3p1;
 use crate::generate::generate_video::providers::artcraft::veo_3p1_fast::build::build_artcraft_veo_3p1_fast;
 use crate::generate::generate_video::providers::artcraft::veo_3p1_lite::build::build_artcraft_veo_3p1_lite;
+use crate::generate::generate_video::providers::artcraft::flux_3::build::build_artcraft_flux_3;
+use crate::generate::generate_video::providers::artcraft::flux_3_draft::build::build_artcraft_flux_3_draft;
+use crate::generate::generate_video::providers::artcraft::minimax_h3::build::build_artcraft_minimax_h3;
 use crate::generate::generate_video::providers::artcraft::vidu_q3::build::build_artcraft_vidu_q3;
 use crate::generate::generate_video::providers::artcraft::vidu_q3_turbo::build::build_artcraft_vidu_q3_turbo;
 use crate::generate::generate_video::providers::kinovi::happy_horse_1p0::build::build_kinovi_happy_horse_1p0;
 use crate::generate::generate_video::providers::kinovi::seedance_2p0::build::build_kinovi_seedance_2p0;
-use crate::generate::generate_video::providers::gmicloud::seedance_2p0_g::build::build_gmicloud_seedance_2p0_u;
-use crate::generate::generate_video::providers::gmicloud::seedance_2p0_fast_g::build::build_gmicloud_seedance_2p0_u_fast;
 use crate::generate::generate_video::providers::grok_api::grok_imagine_video::build::build_grok_api_grok_imagine_video;
 use crate::generate::generate_video::providers::grok_api::grok_imagine_video_1p5::build::build_grok_api_grok_imagine_video_1p5;
 use crate::generate::generate_video::providers::fal::kling_1_6_pro::build::build_fal_kling_1_6_pro;
@@ -68,11 +67,17 @@ use crate::generate::generate_video::providers::fal::veo_3_fast::build::build_fa
 use crate::generate::generate_video::providers::fal::veo_3p1::build::build_fal_veo_3p1;
 use crate::generate::generate_video::providers::fal::veo_3p1_fast::build::build_fal_veo_3p1_fast;
 use crate::generate::generate_video::providers::fal::veo_3p1_lite::build::build_fal_veo_3p1_lite;
+use crate::generate::generate_video::providers::fal::flux_3::build::build_fal_flux_3;
+use crate::generate::generate_video::providers::fal::flux_3_draft::build::build_fal_flux_3_draft;
+use crate::generate::generate_video::providers::fal::minimax_h3::build::build_fal_minimax_h3;
 use crate::generate::generate_video::providers::fal::vidu_q3::build::build_fal_vidu_q3;
 use crate::generate::generate_video::providers::fal::vidu_q3_turbo::build::build_fal_vidu_q3_turbo;
 use crate::generate::generate_video::providers::kinovi::seedance_2p0_fast::build::build_kinovi_seedance_2p0_fast;
 use crate::generate::generate_video::providers::kinovi::seedance_2p0_mini::build::build_kinovi_seedance_2p0_mini;
+use crate::generate::generate_video::providers::artcraft::seedance_2p5::build::build_artcraft_seedance_2p5;
+use crate::generate::generate_video::providers::artcraft::seedance_2p5_u::build::build_artcraft_seedance_2p5_u;
 use crate::generate::generate_video::providers::artcraft::seedance_2p5_preview::build::build_artcraft_seedance_2p5_preview;
+use crate::generate::generate_video::providers::kinovi::seedance_2p5::build::build_kinovi_seedance_2p5;
 use crate::generate::generate_video::providers::kinovi::seedance_2p5_preview::build::build_kinovi_seedance_2p5_preview;
 use crate::generate::generate_video::video_generation_draft_or_request::VideoGenerationDraftOrRequest;
 
@@ -132,6 +137,12 @@ pub struct GenerateVideoRequestBuilder {
   /// so it's best to be explicit.
   pub generate_audio: Option<bool>,
 
+  /// CALCULATION-ONLY (never sent to any provider): the total seconds of
+  /// reference video input, summed across all reference videos and rounded
+  /// up to whole seconds per file. Models that bill reference-video input
+  /// seconds (e.g. Seedance 2.5) add this to the billed duration.
+  pub total_reference_video_input_seconds: Option<u16>,
+
   /// If the request is a mismatch with the (model/provider), how to mitigate it.
   pub request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy,
 
@@ -160,6 +171,7 @@ impl Default for GenerateVideoRequestBuilder {
       duration_seconds: None,
       video_batch_count: None,
       generate_audio: None,
+      total_reference_video_input_seconds: None,
       idempotency_token: None,
     }
   }
@@ -172,6 +184,8 @@ impl GenerateVideoRequestBuilder {
       // Artcraft
       (RouterProvider::Artcraft, RouterVideoModel::GrokImagineVideo) => build_artcraft_grok_imagine_video(self),
       (RouterProvider::Artcraft, RouterVideoModel::GrokImagineVideo1p5) => build_artcraft_grok_imagine_video_1p5(self),
+      (RouterProvider::Artcraft, RouterVideoModel::Flux3) => build_artcraft_flux_3(self),
+      (RouterProvider::Artcraft, RouterVideoModel::Flux3Draft) => build_artcraft_flux_3_draft(self),
       (RouterProvider::Artcraft, RouterVideoModel::HappyHorse1p0) => build_artcraft_happy_horse_1p0(self),
       (RouterProvider::Artcraft, RouterVideoModel::Kling16Pro) => build_artcraft_kling_1_6_pro(self),
       (RouterProvider::Artcraft, RouterVideoModel::Kling21Master) => build_artcraft_kling_2_1_master(self),
@@ -180,10 +194,9 @@ impl GenerateVideoRequestBuilder {
       (RouterProvider::Artcraft, RouterVideoModel::Kling2p6Pro) => build_artcraft_kling_2_6_pro(self),
       (RouterProvider::Artcraft, RouterVideoModel::Kling3p0Pro) => build_artcraft_kling_3p0_pro(self),
       (RouterProvider::Artcraft, RouterVideoModel::Kling3p0Standard) => build_artcraft_kling_3p0_standard(self),
+      (RouterProvider::Artcraft, RouterVideoModel::MinimaxH3) => build_artcraft_minimax_h3(self),
       (RouterProvider::Artcraft, RouterVideoModel::Seedance2p0) => build_artcraft_seedance_2p0(self),
       (RouterProvider::Artcraft, RouterVideoModel::Seedance2p0Fast) => build_artcraft_seedance_2p0_fast(self),
-      (RouterProvider::Artcraft, RouterVideoModel::Seedance2p0Ultra) => build_artcraft_seedance_2p0_u(self),
-      (RouterProvider::Artcraft, RouterVideoModel::Seedance2p0UltraFast) => build_artcraft_seedance_2p0_u_fast(self),
       (RouterProvider::Artcraft, RouterVideoModel::Seedance2p0BytePlus) => build_artcraft_seedance_2p0_bp(self),
       (RouterProvider::Artcraft, RouterVideoModel::Seedance2p0BytePlusFast) => build_artcraft_seedance_2p0_bp_fast(self),
       (RouterProvider::Artcraft, RouterVideoModel::Seedance2p0BytePlusUltra) => build_artcraft_seedance_2p0_bpu(self),
@@ -192,6 +205,8 @@ impl GenerateVideoRequestBuilder {
       (RouterProvider::Artcraft, RouterVideoModel::Seedance2p0BytePlusMini) => build_artcraft_seedance_2p0_bp_mini(self),
       (RouterProvider::Artcraft, RouterVideoModel::Seedance2p0BytePlusUltraMini) => build_artcraft_seedance_2p0_bpu_mini(self),
       (RouterProvider::Artcraft, RouterVideoModel::Seedance2p5Preview) => build_artcraft_seedance_2p5_preview(self),
+      (RouterProvider::Artcraft, RouterVideoModel::Seedance2p5) => build_artcraft_seedance_2p5(self),
+      (RouterProvider::Artcraft, RouterVideoModel::Seedance2p5Ultra) => build_artcraft_seedance_2p5_u(self),
       (RouterProvider::Artcraft, RouterVideoModel::PreviewModel) => build_artcraft_preview_model(self),
       (RouterProvider::Artcraft, RouterVideoModel::PreviewModelFast) => build_artcraft_preview_model_fast(self),
       (RouterProvider::Artcraft, RouterVideoModel::Seedance10Lite) => build_artcraft_seedance_1p0_lite(self),
@@ -207,6 +222,8 @@ impl GenerateVideoRequestBuilder {
       (RouterProvider::Artcraft, RouterVideoModel::ViduQ3) => build_artcraft_vidu_q3(self),
       (RouterProvider::Artcraft, RouterVideoModel::ViduQ3Turbo) => build_artcraft_vidu_q3_turbo(self),
       // Fal
+      (RouterProvider::Fal, RouterVideoModel::Flux3) => build_fal_flux_3(self),
+      (RouterProvider::Fal, RouterVideoModel::Flux3Draft) => build_fal_flux_3_draft(self),
       (RouterProvider::Fal, RouterVideoModel::Kling16Pro) => build_fal_kling_1_6_pro(self),
       (RouterProvider::Fal, RouterVideoModel::Kling21Master) => build_fal_kling_2_1_master(self),
       (RouterProvider::Fal, RouterVideoModel::Kling21Pro) => build_fal_kling_2_1_pro(self),
@@ -214,6 +231,7 @@ impl GenerateVideoRequestBuilder {
       (RouterProvider::Fal, RouterVideoModel::Kling2p6Pro) => build_fal_kling_2_6_pro(self),
       (RouterProvider::Fal, RouterVideoModel::Kling3p0Pro) => build_fal_kling_3p0_pro(self),
       (RouterProvider::Fal, RouterVideoModel::Kling3p0Standard) => build_fal_kling_3p0_standard(self),
+      (RouterProvider::Fal, RouterVideoModel::MinimaxH3) => build_fal_minimax_h3(self),
       (RouterProvider::Fal, RouterVideoModel::Seedance10Lite) => build_fal_seedance_1p0_lite(self),
       (RouterProvider::Fal, RouterVideoModel::Seedance1p5Pro) => build_fal_seedance_1p5_pro(self),
       (RouterProvider::Fal, RouterVideoModel::Sora2) => build_fal_sora_2(self),
@@ -226,9 +244,6 @@ impl GenerateVideoRequestBuilder {
       (RouterProvider::Fal, RouterVideoModel::Veo3p1Lite) => build_fal_veo_3p1_lite(self),
       (RouterProvider::Fal, RouterVideoModel::ViduQ3) => build_fal_vidu_q3(self),
       (RouterProvider::Fal, RouterVideoModel::ViduQ3Turbo) => build_fal_vidu_q3_turbo(self),
-      // GmiCloud
-      (RouterProvider::GmiCloud, RouterVideoModel::Seedance2p0Ultra) => build_gmicloud_seedance_2p0_u(self),
-      (RouterProvider::GmiCloud, RouterVideoModel::Seedance2p0UltraFast) => build_gmicloud_seedance_2p0_u_fast(self),
       // Grok
       (RouterProvider::GrokApi, RouterVideoModel::GrokImagineVideo) => build_grok_api_grok_imagine_video(self),
       (RouterProvider::GrokApi, RouterVideoModel::GrokImagineVideo1p5) => build_grok_api_grok_imagine_video_1p5(self),
@@ -240,6 +255,7 @@ impl GenerateVideoRequestBuilder {
       (RouterProvider::KinoviWeb, RouterVideoModel::Seedance2p0BytePlusMini) => build_kinovi_seedance_2p0_mini(self),
       (RouterProvider::KinoviWeb, RouterVideoModel::Seedance2p0BytePlusUltraMini) => build_kinovi_seedance_2p0_mini(self),
       (RouterProvider::KinoviWeb, RouterVideoModel::Seedance2p5Preview) => build_kinovi_seedance_2p5_preview(self),
+      (RouterProvider::KinoviWeb, RouterVideoModel::Seedance2p5) => build_kinovi_seedance_2p5(self),
       _ => self.unsupported_provider_and_model(),
     }
   }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/providers/artcraft/build_common.rs

@@ -82,6 +82,7 @@ pub fn build_artcraft_omni_video_request(
     negative_prompt: None,
     generate_audio: None,
     quality: None,
+    estimate_only: None,
   })
 }
 
@@ -230,7 +231,7 @@ fn plan_output_resolution(
   }
 }
 
-/// Batch counts: 1, 2, 4.
+/// Batch counts: 1 through 4.
 pub fn plan_batch_count(
   video_batch_count: Option<u16>,
   strategy: RequestMismatchMitigationStrategy,
@@ -238,7 +239,8 @@ pub fn plan_batch_count(
   let count = video_batch_count.unwrap_or(1);
   match count {
     0 => Err(ArtcraftRouterError::Client(ClientError::UserRequestedZeroGenerations)),
-    1 | 2 | 4 => Ok(count),
+    1..=4 => Ok(count),
+    // 5 and above:
     _ => match strategy {
       RequestMismatchMitigationStrategy::ErrorOut => {
         Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
@@ -247,9 +249,31 @@ pub fn plan_batch_count(
         }))
       }
       RequestMismatchMitigationStrategy::PayMoreUpgrade => Ok(4),
-      RequestMismatchMitigationStrategy::PayLessDowngrade => {
-        Ok(if count < 4 { 2 } else { 4 })
+      RequestMismatchMitigationStrategy::PayLessDowngrade => Ok(4),
+    },
+  }
+}
+
+/// Batch counts for the Seedance 2.0 Mini family: 1-8 are all valid
+/// (wider than the shared 1/2/4 planning); higher counts clamp to 8 per the
+/// mitigation strategy.
+pub fn plan_mini_batch_count(
+  video_batch_count: Option<u16>,
+  strategy: RequestMismatchMitigationStrategy,
+) -> Result<u16, ArtcraftRouterError> {
+  let count = video_batch_count.unwrap_or(1);
+  match count {
+    0 => Err(ArtcraftRouterError::Client(ClientError::UserRequestedZeroGenerations)),
+    1..=8 => Ok(count),
+    _ => match strategy {
+      RequestMismatchMitigationStrategy::ErrorOut => {
+        Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
+          field: "video_batch_count",
+          value: format!("{}", count),
+        }))
       }
+      RequestMismatchMitigationStrategy::PayMoreUpgrade
+      | RequestMismatchMitigationStrategy::PayLessDowngrade => Ok(8),
     },
   }
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/providers/artcraft/flux_3/build.rs

@@ -0,0 +1,64 @@
+use enums::common::generation::common_video_model::CommonVideoModel as CommonVideoModelEnum;
+
+use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::errors::client_error::ClientError;
+use crate::generate::generate_video::generate_video_request_builder::GenerateVideoRequestBuilder;
+use crate::generate::generate_video::providers::artcraft::build_common::{
+  build_artcraft_omni_video_request, SupportedResolutions, UltraWideSupport,
+};
+use crate::generate::generate_video::providers::artcraft::flux_3::request::ArtcraftFlux3RequestState;
+use crate::generate::generate_video::video_generation_draft_or_request::VideoGenerationDraftOrRequest;
+use crate::generate::generate_video::video_generation_request::VideoGenerationRequest;
+
+pub fn build_artcraft_flux_3(builder: GenerateVideoRequestBuilder) -> Result<VideoGenerationDraftOrRequest, ArtcraftRouterError> {
+  let state = build_artcraft_flux_3_state(builder)?;
+  Ok(VideoGenerationDraftOrRequest::Request(VideoGenerationRequest::ArtcraftFlux3(state)))
+}
+
+pub(crate) fn build_artcraft_flux_3_state(mut builder: GenerateVideoRequestBuilder) -> Result<ArtcraftFlux3RequestState, ArtcraftRouterError> {
+  // Flux 3 accepts 5–20 seconds — wider than the generic helper's window —
+  // so pre-plan the duration and reapply it after (the helper would clamp
+  // 16–20s down). Also preserve generate_audio (the helper hardcodes None on
+  // its output).
+  let strategy = builder.request_mismatch_mitigation_strategy;
+  let final_duration = plan_flux_3_duration(builder.duration_seconds, strategy)?;
+  builder.duration_seconds = final_duration;
+
+  let generate_audio = builder.generate_audio;
+  let mut request = build_artcraft_omni_video_request(
+    builder,
+    CommonVideoModelEnum::Flux3,
+    SupportedResolutions::Full,
+    UltraWideSupport::Supported,
+  )?;
+  request.generate_audio = generate_audio;
+  request.duration_seconds = final_duration;
+
+  Ok(ArtcraftFlux3RequestState { request })
+}
+
+/// Flux 3 durations: 5–20 seconds (unset lets the model pick).
+pub(crate) fn plan_flux_3_duration(
+  duration_seconds: Option<u16>,
+  strategy: RequestMismatchMitigationStrategy,
+) -> Result<Option<u16>, ArtcraftRouterError> {
+  const MIN: u16 = 5;
+  const MAX: u16 = 20;
+  match duration_seconds {
+    None => Ok(None),
+    Some(d) if (MIN..=MAX).contains(&d) => Ok(Some(d)),
+    Some(other) => match strategy {
+      RequestMismatchMitigationStrategy::ErrorOut => {
+        Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
+          field: "duration_seconds",
+          value: format!("{}", other),
+        }))
+      }
+      RequestMismatchMitigationStrategy::PayMoreUpgrade
+      | RequestMismatchMitigationStrategy::PayLessDowngrade => {
+        Ok(Some(other.clamp(MIN, MAX)))
+      }
+    },
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/providers/artcraft/flux_3/cost.rs

@@ -0,0 +1,123 @@
+use enums::common::generation::common_resolution::CommonResolution as CommonResolutionEnum;
+
+use crate::generate::generate_video::providers::artcraft::flux_3::request::ArtcraftFlux3RequestState;
+use crate::generate::generate_video::video_generation_cost_estimate::VideoGenerationCostEstimate;
+
+/// Per-second rates in hundredths of a US cent.
+const LOW_RES_RATE_HUNDREDTH_CENTS_PER_SEC: u64 = 1_955;
+const HIGH_RES_RATE_HUNDREDTH_CENTS_PER_SEC: u64 = 3_335;
+
+#[derive(Clone, Debug)]
+pub struct ArtcraftFlux3CostState {
+  pub duration_seconds: u64,
+  pub is_1080p: bool,
+}
+
+impl ArtcraftFlux3CostState {
+  pub fn from_request(request: &ArtcraftFlux3RequestState) -> Self {
+    Self {
+      // Flux 3 defaults None → 5s (the shortest selectable duration).
+      duration_seconds: request.request.duration_seconds.map(u64::from).unwrap_or(5),
+      is_1080p: is_1080p(request.request.resolution),
+    }
+  }
+
+  pub fn estimate_cost(&self) -> VideoGenerationCostEstimate {
+    let rate = if self.is_1080p {
+      HIGH_RES_RATE_HUNDREDTH_CENTS_PER_SEC
+    } else {
+      LOW_RES_RATE_HUNDREDTH_CENTS_PER_SEC
+    };
+    // Round up to the next whole cent.
+    let cost_in_usd_cents = (rate * self.duration_seconds).div_ceil(100);
+
+    VideoGenerationCostEstimate {
+      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,
+      failures_are_refunded: None,
+    }
+  }
+}
+
+/// Flux 3 renders 720p or 1080p; 1080p and above land on the higher tier,
+/// while 720p and below render at 720p. The default (unset) resolution is
+/// 720p.
+fn is_1080p(resolution: Option<CommonResolutionEnum>) -> bool {
+  match resolution {
+    None => false, // defaults to 720p
+    Some(CommonResolutionEnum::TenEightyP)
+    | Some(CommonResolutionEnum::OneK)
+    | Some(CommonResolutionEnum::TwoK)
+    | Some(CommonResolutionEnum::ThreeK)
+    | Some(CommonResolutionEnum::FourK) => true,
+    Some(CommonResolutionEnum::HalfK)
+    | Some(CommonResolutionEnum::FourEightyP)
+    | Some(CommonResolutionEnum::SevenTwentyP) => false,
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use enums::common::generation::common_resolution::CommonResolution as CommonResolutionEnum;
+
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_resolution::RouterResolution;
+  use crate::api::router_video_model::RouterVideoModel;
+  use crate::generate::generate_video::generate_video_request_builder::GenerateVideoRequestBuilder;
+  use crate::generate::generate_video::providers::artcraft::flux_3::build::build_artcraft_flux_3_state;
+  use crate::generate::generate_video::providers::artcraft::flux_3::cost::ArtcraftFlux3CostState;
+
+  #[test]
+  fn default_settings_5s_is_98() { assert_eq!(cost_cents(Some(5), None), 98); }
+
+  #[test]
+  fn default_duration_is_5s() { assert_eq!(cost_cents(None, None), 98); }
+
+  #[test]
+  fn low_res_20s_is_391() { assert_eq!(cost_cents(Some(20), Some(RouterResolution::SevenTwentyP)), 391); }
+
+  #[test]
+  fn four_eighty_p_lands_on_low_tier() {
+    assert_eq!(cost_cents(Some(5), Some(RouterResolution::FourEightyP)), 98);
+  }
+
+  #[test]
+  fn high_res_5s_is_167() { assert_eq!(cost_cents(Some(5), Some(RouterResolution::TenEightyP)), 167); }
+
+  #[test]
+  fn high_res_10s_is_334() { assert_eq!(cost_cents(Some(10), Some(RouterResolution::TenEightyP)), 334); }
+
+  #[test]
+  fn odd_duration_rounds_up_to_whole_cents() {
+    // 7s low res: 1955 × 7 = 13685 hundredth-cents → 137 cents.
+    assert_eq!(cost_cents(Some(7), None), 137);
+  }
+
+  #[test]
+  fn resolution_classifier_defaults_720p() {
+    assert!(!super::is_1080p(None));
+    assert!(super::is_1080p(Some(CommonResolutionEnum::TenEightyP)));
+    assert!(!super::is_1080p(Some(CommonResolutionEnum::SevenTwentyP)));
+    assert!(!super::is_1080p(Some(CommonResolutionEnum::FourEightyP)));
+  }
+
+  fn cost_cents(
+    duration_seconds: Option<u16>,
+    resolution: Option<RouterResolution>,
+  ) -> u64 {
+    let b = GenerateVideoRequestBuilder {
+      model: RouterVideoModel::Flux3,
+      provider: RouterProvider::Artcraft,
+      prompt: Some("test".to_string()),
+      duration_seconds,
+      resolution,
+      ..Default::default()
+    };
+    let state = build_artcraft_flux_3_state(b).unwrap();
+    ArtcraftFlux3CostState::from_request(&state).estimate_cost().cost_in_usd_cents.unwrap()
+  }
+}

crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/providers/artcraft/flux_3/mod.rs

@@ -0,0 +1,3 @@
+pub mod build;
+pub mod cost;
+pub mod request;

crates/api_clients/artcraft/artcraft_router/src/generate/generate_video/providers/artcraft/flux_3/request.rs

@@ -0,0 +1,104 @@
+use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_video_cost_and_generate_request::OmniGenVideoCostAndGenerateRequest;
+
+use crate::client::router_artcraft_client::RouterArtcraftClient;
+use crate::errors::artcraft_router_error::ArtcraftRouterError;
+use crate::generate::generate_video::generate_video_response::GenerateVideoResponse;
+use crate::generate::generate_video::providers::artcraft::request_common::send_artcraft_omni_video_request;
+
+#[derive(Clone, Debug)]
+pub struct ArtcraftFlux3RequestState {
+  pub request: OmniGenVideoCostAndGenerateRequest,
+}
+
+impl ArtcraftFlux3RequestState {
+  pub async fn send(&self, client: &RouterArtcraftClient) -> Result<GenerateVideoResponse, ArtcraftRouterError> {
+    send_artcraft_omni_video_request(&self.request, client).await
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use tokens::tokens::media_files::MediaFileToken;
+
+  use artcraft_client::credentials::storyteller_credential_set::StorytellerCredentialSet;
+  use artcraft_client::utils::api_host::ApiHost;
+  use test_data::web::image_media_tokens::JUNO_AT_LAKE_PRODUCTION_MEDIA_TOKEN;
+
+  use crate::api::image_ref::ImageRef;
+  use crate::api::router_aspect_ratio::RouterAspectRatio;
+  use crate::api::router_provider::RouterProvider;
+  use crate::api::router_video_model::RouterVideoModel;
+  use crate::client::router_artcraft_client::RouterArtcraftClient;
+  use crate::client::router_client::RouterClient;
+  use crate::generate::generate_video::generate_video_request_builder::GenerateVideoRequestBuilder;
+  use crate::generate::generate_video::generate_video_response::GenerateVideoResponse;
+  use crate::generate::generate_video::video_generation_draft_or_request::VideoGenerationDraftOrRequest;
+
+  #[tokio::test]
+  #[ignore] // sends a real generation to the Artcraft backend, incurs cost
+  async fn text_to_video() {
+    let response = run_pipeline(GenerateVideoRequestBuilder {
+      prompt: Some("A red kite soaring over coastal cliffs, cinematic.".to_string()),
+      aspect_ratio: Some(RouterAspectRatio::WideSixteenByNine),
+      ..artcraft_builder()
+    }).await;
+    assert!(matches!(response, GenerateVideoResponse::Artcraft(_)));
+    assert_eq!(1, 2, "Inspect output above");
+  }
+
+  #[tokio::test]
+  #[ignore] // sends a real generation to the Artcraft backend, incurs cost
+  async fn keyframe_start_frame() {
+    let response = run_pipeline(GenerateVideoRequestBuilder {
+      prompt: Some("The dog stands up and walks toward the lake.".to_string()),
+      start_frame: Some(ImageRef::MediaFileToken(MediaFileToken::new(JUNO_AT_LAKE_PRODUCTION_MEDIA_TOKEN.to_string()))),
+      ..artcraft_builder()
+    }).await;
+    assert!(matches!(response, GenerateVideoResponse::Artcraft(_)));
+    assert_eq!(1, 2, "Inspect output above");
+  }
+
+  // ── Helpers ──
+
+  fn artcraft_builder() -> GenerateVideoRequestBuilder {
+    GenerateVideoRequestBuilder {
+      model: RouterVideoModel::Flux3,
+      provider: RouterProvider::Artcraft,
+      duration_seconds: Some(5),
+      video_batch_count: Some(1),
+      ..Default::default()
+    }
+  }
+
+  fn get_artcraft_client() -> RouterClient {
+    let cookies = std::fs::read_to_string("/Users/bt/Artcraft/credentials/artcraft_cookies.txt")
+      .expect("Failed to read artcraft cookies");
+    let cookies = cookies.trim().to_string();
+    let credentials = StorytellerCredentialSet::parse_multi_cookie_header(&cookies)
+      .expect("Failed to parse cookies")
+      .expect("No credentials found");
+    RouterClient::Artcraft(RouterArtcraftClient::new(ApiHost::Storyteller, credentials))
+  }
+
+  async fn run_pipeline(builder: GenerateVideoRequestBuilder) -> GenerateVideoResponse {
+    let client = get_artcraft_client();
+
+    let draft_or_request = builder.build2().expect("build2 should succeed");
+    let request = match draft_or_request {
+      VideoGenerationDraftOrRequest::Request(r) => r,
+      _ => panic!("expected Request variant (Artcraft skips draft)"),
+    };
+
+    let response = request.send_request(&client).await.expect("send_request should succeed");
+
+    match &response {
+      GenerateVideoResponse::Artcraft(p) => {
+        println!("inference_job_token={:?}", p.inference_job_token);
+        println!("all_inference_job_tokens={:?}", p.all_inference_job_tokens);
+      }
+      other => println!("response: {:?}", other),
+    }
+
+    response
+  }
+}