moderator endpoints

## Summary

- Regression from PR #1492. After the refactor, `useFeaturedObjects`
auto-fetch effect was racing the `EngineContext` editor instance: on
AssetModal's first mount `editor` is `null`, the effect synchronously
flipped `firstFetch.current` to `IN_PROGRESS` and then called
`fetchFeaturedObjects()` which immediately bailed at `if (!editor)
return`. When the editor became available the effect re-fired (editor is
in the `useCallback` deps), but the `IN_PROGRESS` guard then blocked it
— so **the network request never fired** for any featured category.
- Visible only on Sets and Creatures tabs because
Characters/Objects/Memes are merged with local demo arrays in
`assetTabs` and looked populated despite the same fetch breakage.
- Fix: gate the auto-fetch effect on `editor` (early-return when null,
add `editor` to deps) so `IN_PROGRESS` isn't burned on the no-op call.

## Test plan

- [ ] Open `/edit-3d` in artcraft-webapp with DevTools Network panel +
"Disable cache" on.
- [ ] Open the AssetModal — confirm exactly 5 GETs to
`/v1/media_files/list_featured` (one each for `character`, `object`,
`location`, `creature`, `image_plane`).
- [ ] Switch to Sets and Creatures tabs — items render.
- [ ] Drag a Set into the 3D scene — loads via `addObject` (LOCATION
maps to `AssetType.OBJECT` in `responseMapping`).
- [ ] Tauri smoke: open the 3D page in the desktop app, AssetModal
Sets/Creatures tabs populate.
- [ ] `nx typecheck @storyteller/ui-pagescene` (no new errors).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

.sqlx/query-01a0bf33e8331c19dc73f064c54eaa863bec158ef7713450a06c75e246f5f08c.json

@@ -1,12 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "\n    INSERT INTO tasks (\n      id,\n      task_status,\n      task_type,\n      model_type,\n      provider,\n      provider_job_id,\n      frontend_caller,\n      frontend_subscriber_id,\n      frontend_subscriber_payload\n    )\n    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)\n  ",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Right": 9
-    },
-    "nullable": []
-  },
-  "hash": "01a0bf33e8331c19dc73f064c54eaa863bec158ef7713450a06c75e246f5f08c"
-}

.sqlx/query-35677894f7b02f32a1bf6396fa6d10caba69bb0f3f03ee7ffbfa1437689d42df.json

@@ -1,6 +1,6 @@
 {
   "db_name": "SQLite",
-  "query": "\n    SELECT\n      id,\n      task_status,\n      task_type,\n      model_type,\n      provider,\n      provider_job_id,\n      frontend_caller,\n      frontend_subscriber_id,\n      frontend_subscriber_payload\n    FROM tasks\n    WHERE\n      provider = ?\n      AND provider_job_id = ?\n  ",
+  "query": "\n    SELECT\n      id,\n      task_status,\n      task_type,\n      model_type,\n      provider,\n      provider_job_id,\n      frontend_caller,\n      queue_status_url,\n      queue_response_url,\n      prompt_token,\n      frontend_subscriber_id,\n      frontend_subscriber_payload\n    FROM tasks\n    WHERE\n      provider = ?\n      AND provider_job_id = ?\n  ",
   "describe": {
     "columns": [
       {
@@ -39,14 +39,29 @@
         "type_info": "Text"
       },
       {
-        "name": "frontend_subscriber_id",
+        "name": "queue_status_url",
         "ordinal": 7,
         "type_info": "Text"
       },
       {
-        "name": "frontend_subscriber_payload",
+        "name": "queue_response_url",
         "ordinal": 8,
         "type_info": "Text"
+      },
+      {
+        "name": "prompt_token",
+        "ordinal": 9,
+        "type_info": "Text"
+      },
+      {
+        "name": "frontend_subscriber_id",
+        "ordinal": 10,
+        "type_info": "Text"
+      },
+      {
+        "name": "frontend_subscriber_payload",
+        "ordinal": 11,
+        "type_info": "Text"
       }
     ],
     "parameters": {
@@ -61,8 +76,11 @@
       true,
       true,
       true,
+      true,
+      true,
+      true,
       true
     ]
   },
-  "hash": "38ff2df237b16f077865711dd81261de1b5fa05a9787679ce9ccd4ac576b1069"
+  "hash": "35677894f7b02f32a1bf6396fa6d10caba69bb0f3f03ee7ffbfa1437689d42df"
 }

.sqlx/query-4fc9674ae39abaadc36054c200290ec95d0e2c7765336f0fa97805a2265f5c4c.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "\n    INSERT INTO tasks (\n      id,\n      task_status,\n      task_type,\n      model_type,\n      provider,\n      provider_job_id,\n      queue_status_url,\n      queue_response_url,\n      prompt_token,\n      frontend_caller,\n      frontend_subscriber_id,\n      frontend_subscriber_payload\n    )\n    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n  ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 12
+    },
+    "nullable": []
+  },
+  "hash": "4fc9674ae39abaadc36054c200290ec95d0e2c7765336f0fa97805a2265f5c4c"
+}

.sqlx/query-507a60f98f6da63620abc28a5a83772f29ffcfdfcc8d30bfa7c611d73073ca16.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  ur.id as `id: u64`,\n  ur.invited_user_token as `invited_user_token: UserToken`,\n  invited.username as `invited_username: String`,\n  invited.display_name as `invited_display_name: String`,\n  invited.email_address as `invited_email_address: String`,\n  ur.referrer_user_token as `referrer_user_token: UserToken`,\n  referrer.username as `referrer_username: String`,\n  referrer.display_name as `referrer_display_name: String`,\n  ur.maybe_referral_code_token as `maybe_referral_code_token: UserReferralCodeToken`,\n  ur.maybe_referral_url,\n  ur.maybe_landing_url,\n  ur.created_at\nFROM user_referrals ur\nJOIN users invited ON invited.token = ur.invited_user_token\nJOIN users referrer ON referrer.token = ur.referrer_user_token\nORDER BY ur.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id: u64",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "invited_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "invited_username: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "invited_display_name: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "invited_email_address: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "referrer_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "referrer_username: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "referrer_display_name: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "maybe_referral_code_token: UserReferralCodeToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "maybe_referral_url",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "maybe_landing_url",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "created_at",
+        "type_info": {
+          "type": "Datetime",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true,
+      true,
+      true,
+      false
+    ]
+  },
+  "hash": "507a60f98f6da63620abc28a5a83772f29ffcfdfcc8d30bfa7c611d73073ca16"
+}

.sqlx/query-56462cb07d49a001095ff118bfdf4fab4c30d1c7e6dca09a11e82f5956508e0b.json

@@ -0,0 +1,58 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `token: UserReferralCodeToken`,\n  owner_user_token as `owner_user_token: UserToken`,\n  code,\n  code_lowercase\nFROM user_referral_codes\nWHERE code_lowercase = ?\n  AND deleted_at IS NULL\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token: UserReferralCodeToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "owner_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "code",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "code_lowercase",
+        "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
+    ]
+  },
+  "hash": "56462cb07d49a001095ff118bfdf4fab4c30d1c7e6dca09a11e82f5956508e0b"
+}

.sqlx/query-566a2d56735180e0f17484789d0debd03c68bda20354882e111476bab6132723.json

@@ -0,0 +1,25 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `token: tokens::tokens::users::UserToken`\nFROM users\n  WHERE username = ?\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token: tokens::tokens::users::UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "566a2d56735180e0f17484789d0debd03c68bda20354882e111476bab6132723"
+}

.sqlx/query-5e2e68267e858b449de90dbf0d5b20d60b8cb82c4a4ddf56a49200ac92912817.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO user_referral_codes (\n  token,\n  code,\n  code_lowercase,\n  owner_user_token\n)\nVALUES (?, ?, ?, ?)\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 4
+    },
+    "nullable": []
+  },
+  "hash": "5e2e68267e858b449de90dbf0d5b20d60b8cb82c4a4ddf56a49200ac92912817"
+}

.sqlx/query-7369b2f3fd9e7c1e968dc5501ef9bea7e1610fd7a044a0f9ad8b908dfada2b6a.json

@@ -1,12 +1,12 @@
 {
   "db_name": "MySQL",
-  "query": "\nINSERT INTO media_files\nSET\n  token = ?,\n\n  media_class = ?,\n  media_type = ?,\n\n  origin_category = ?,\n  origin_product_category = ?,\n\n  maybe_engine_category = ?,\n  maybe_animation_type = ?,\n\n  maybe_mime_type = ?,\n  file_size_bytes = ?,\n\n  checksum_sha2 = ?,\n\n  maybe_prompt_token = ?,\n  maybe_batch_token = ?,\n\n  maybe_title = ?,\n  maybe_duration_millis = ?,\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  creator_ip_address = ?,\n\n  creator_set_visibility = ?,\n\n  maybe_scene_source_media_file_token = ?,\n  is_intermediate_system_file = ?,\n\n  maybe_creator_file_synthetic_id = ?,\n  maybe_creator_category_synthetic_id = ?,\n\n  is_user_upload = TRUE,\n\n  maybe_origin_model_type = NULL,\n  maybe_origin_model_token = NULL\n        ",
+  "query": "\nINSERT INTO media_files\nSET\n  token = ?,\n\n  media_class = ?,\n  media_type = ?,\n\n  origin_category = ?,\n  origin_product_category = ?,\n\n  maybe_engine_category = ?,\n  maybe_animation_type = ?,\n\n  maybe_mime_type = ?,\n  file_size_bytes = ?,\n\n  checksum_sha2 = ?,\n\n  maybe_prompt_token = ?,\n  maybe_batch_token = ?,\n\n  maybe_title = ?,\n  maybe_duration_millis = ?,\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  creator_ip_address = ?,\n\n  creator_set_visibility = ?,\n\n  maybe_scene_source_media_file_token = ?,\n\n  is_intermediate_system_file = ?,\n  is_user_upload = ?,\n\n  maybe_generation_provider = ?,\n\n  maybe_creator_file_synthetic_id = ?,\n  maybe_creator_category_synthetic_id = ?,\n\n  maybe_origin_model_type = NULL,\n  maybe_origin_model_token = NULL\n        ",
   "describe": {
     "columns": [],
     "parameters": {
-      "Right": 25
+      "Right": 27
     },
     "nullable": []
   },
-  "hash": "8d6c1f608ec25a74dddf375d525c3e30467c5eba5389094401b74b7dc74552d7"
+  "hash": "7369b2f3fd9e7c1e968dc5501ef9bea7e1610fd7a044a0f9ad8b908dfada2b6a"
 }

.sqlx/query-867b22640ae6c49c26973a32d36439933dceef881313a7f3385d61ebe5faeb34.json

@@ -1,12 +1,12 @@
 {
   "db_name": "MySQL",
-  "query": "\nINSERT INTO users\nSET\n  token = ?,\n  \n  is_temporary = ?,\n  \n  username = ?,\n  display_name = ?,\n\n  username_is_generated = ?,\n  username_is_not_customized = ?,\n\n  email_address = ?,\n  email_gravatar_hash = ?,\n\n  email_confirmed = FALSE,\n  email_confirmed_by_google = ?,\n  email_is_synthetic = ?,\n  \n  was_eagerly_provisioned = ?,\n\n  profile_markdown = ?,\n  profile_rendered_html = ?,\n  user_role_slug = ?,\n\n  password_hash = ?,\n  is_without_password = ?,\n\n  maybe_feature_flags = ?,\n\n  ip_address_creation = ?,\n  ip_address_last_login = ?,\n  ip_address_last_update = ?,\n\n  maybe_source = ?,\n\n  maybe_signup_method = ?,\n\n  maybe_referral_url = ?,\n  maybe_landing_url = ?\n        ",
+  "query": "\nINSERT INTO users\nSET\n  token = ?,\n  \n  is_temporary = ?,\n  \n  username = ?,\n  display_name = ?,\n\n  username_is_generated = ?,\n  username_is_not_customized = ?,\n\n  email_address = ?,\n  email_gravatar_hash = ?,\n\n  email_confirmed = FALSE,\n  email_confirmed_by_google = ?,\n  email_is_synthetic = ?,\n  \n  was_eagerly_provisioned = ?,\n\n  profile_markdown = ?,\n  profile_rendered_html = ?,\n  user_role_slug = ?,\n\n  password_hash = ?,\n  is_without_password = ?,\n\n  maybe_feature_flags = ?,\n\n  ip_address_creation = ?,\n  ip_address_last_login = ?,\n  ip_address_last_update = ?,\n\n  maybe_source = ?,\n\n  maybe_signup_method = ?,\n\n  maybe_referral_url = ?,\n  maybe_landing_url = ?,\n\n  maybe_referral_partner = ?,\n  maybe_referral_user_token = ?\n        ",
   "describe": {
     "columns": [],
     "parameters": {
-      "Right": 24
+      "Right": 26
     },
     "nullable": []
   },
-  "hash": "3aacc0d270a9073ee5a38595cc32ab7793e0e8b9ce3ad81f554e7198fd0fd509"
+  "hash": "867b22640ae6c49c26973a32d36439933dceef881313a7f3385d61ebe5faeb34"
 }

.sqlx/query-a4901f904aa1c00d9afc23faa7008816c6e1b653bd6ad9f0b6772e32000be544.json

@@ -1,12 +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            is_batch_generated = ?,\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_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        ",
+  "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            is_batch_generated = ?,\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            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": 40
+      "Right": 41
     },
     "nullable": []
   },
-  "hash": "87d5511700985daaabfc9f2972f018d56b6672c07be082daa7c1a782400cb18d"
+  "hash": "a4901f904aa1c00d9afc23faa7008816c6e1b653bd6ad9f0b6772e32000be544"
 }

.sqlx/query-acd6e67603ca687686513b080bbfa642d3e2ffe8c97b0f9dd646f3ef2f8d92df.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO user_referrals (\n  invited_user_token,\n  referrer_user_token,\n  maybe_referral_code_token,\n  maybe_referral_url,\n  maybe_landing_url\n)\nVALUES (?, ?, ?, ?, ?)\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 5
+    },
+    "nullable": []
+  },
+  "hash": "acd6e67603ca687686513b080bbfa642d3e2ffe8c97b0f9dd646f3ef2f8d92df"
+}

.sqlx/query-b2049fa1c9f76c73a9a22144de716b47dccdd35caeefb3721e75ec9aaf4614f0.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  ur.id as `id: u64`,\n  ur.invited_user_token as `invited_user_token: UserToken`,\n  invited.username as `invited_username: String`,\n  invited.display_name as `invited_display_name: String`,\n  invited.email_address as `invited_email_address: String`,\n  ur.referrer_user_token as `referrer_user_token: UserToken`,\n  referrer.username as `referrer_username: String`,\n  referrer.display_name as `referrer_display_name: String`,\n  ur.maybe_referral_code_token as `maybe_referral_code_token: UserReferralCodeToken`,\n  ur.maybe_referral_url,\n  ur.maybe_landing_url,\n  ur.created_at\nFROM user_referrals ur\nJOIN users invited ON invited.token = ur.invited_user_token\nJOIN users referrer ON referrer.token = ur.referrer_user_token\nWHERE ur.id < ?\nORDER BY ur.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id: u64",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "invited_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "invited_username: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "invited_display_name: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "invited_email_address: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "referrer_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "referrer_username: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "referrer_display_name: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "maybe_referral_code_token: UserReferralCodeToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "maybe_referral_url",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "maybe_landing_url",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "created_at",
+        "type_info": {
+          "type": "Datetime",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true,
+      true,
+      true,
+      false
+    ]
+  },
+  "hash": "b2049fa1c9f76c73a9a22144de716b47dccdd35caeefb3721e75ec9aaf4614f0"
+}

.sqlx/query-b5ce1dffc1d6e1762844f3a040a9a9cba2a608931824d99eebba67a7d718719e.json

@@ -0,0 +1,69 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token as `token: UserReferralCodeToken`,\n  code,\n  code_lowercase,\n  created_at,\n  updated_at\nFROM user_referral_codes\nWHERE owner_user_token = ?\n  AND deleted_at IS NULL\nORDER BY created_at ASC\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token: UserReferralCodeToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "code",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "code_lowercase",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "created_at",
+        "type_info": {
+          "type": "Datetime",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Datetime",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "b5ce1dffc1d6e1762844f3a040a9a9cba2a608931824d99eebba67a7d718719e"
+}

.sqlx/query-b8254ed110147c66fbeef783283ff4b2565b60c9443572c67091ecd60c9d97d6.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE user_referral_codes\nSET\n  deleted_at = CURRENT_TIMESTAMP,\n  code_lowercase = ?\nWHERE token = ?\n  AND owner_user_token = ?\n  AND deleted_at IS NULL\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "b8254ed110147c66fbeef783283ff4b2565b60c9443572c67091ecd60c9d97d6"
+}

.sqlx/query-e73dfa3af6a1a8f510f084435da86571e096f3d7e597fb01d6397d380b135341.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  ur.id as `id: u64`,\n  ur.invited_user_token as `invited_user_token: UserToken`,\n  invited.username as `invited_username: String`,\n  invited.display_name as `invited_display_name: String`,\n  invited.email_address as `invited_email_address: String`,\n  ur.referrer_user_token as `referrer_user_token: UserToken`,\n  referrer.username as `referrer_username: String`,\n  referrer.display_name as `referrer_display_name: String`,\n  ur.maybe_referral_code_token as `maybe_referral_code_token: UserReferralCodeToken`,\n  ur.maybe_referral_url,\n  ur.maybe_landing_url,\n  ur.created_at\nFROM user_referrals ur\nJOIN users invited ON invited.token = ur.invited_user_token\nJOIN users referrer ON referrer.token = ur.referrer_user_token\nWHERE referrer.username = ?\nORDER BY ur.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id: u64",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "invited_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "invited_username: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "invited_display_name: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "invited_email_address: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "referrer_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "referrer_username: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "referrer_display_name: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "maybe_referral_code_token: UserReferralCodeToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "maybe_referral_url",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "maybe_landing_url",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "created_at",
+        "type_info": {
+          "type": "Datetime",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true,
+      true,
+      true,
+      false
+    ]
+  },
+  "hash": "e73dfa3af6a1a8f510f084435da86571e096f3d7e597fb01d6397d380b135341"
+}

.sqlx/query-fb021a5fe7a6c0e284968d917f9d612953629d20a06efccc3fce3d930a7fe266.json

@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  ur.id as `id: u64`,\n  ur.invited_user_token as `invited_user_token: UserToken`,\n  invited.username as `invited_username: String`,\n  invited.display_name as `invited_display_name: String`,\n  invited.email_address as `invited_email_address: String`,\n  ur.referrer_user_token as `referrer_user_token: UserToken`,\n  referrer.username as `referrer_username: String`,\n  referrer.display_name as `referrer_display_name: String`,\n  ur.maybe_referral_code_token as `maybe_referral_code_token: UserReferralCodeToken`,\n  ur.maybe_referral_url,\n  ur.maybe_landing_url,\n  ur.created_at\nFROM user_referrals ur\nJOIN users invited ON invited.token = ur.invited_user_token\nJOIN users referrer ON referrer.token = ur.referrer_user_token\nWHERE referrer.username = ?\n  AND ur.id < ?\nORDER BY ur.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id: u64",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "invited_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "invited_username: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "invited_display_name: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "invited_email_address: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "referrer_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "referrer_username: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "referrer_display_name: String",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "maybe_referral_code_token: UserReferralCodeToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "maybe_referral_url",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "maybe_landing_url",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY",
+          "char_set": 224,
+          "max_size": 1020
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "created_at",
+        "type_info": {
+          "type": "Datetime",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      true,
+      true,
+      true,
+      false
+    ]
+  },
+  "hash": "fb021a5fe7a6c0e284968d917f9d612953629d20a06efccc3fce3d930a7fe266"
+}

.sqlx/query-ff9690b62bcc93212ecf9698d9ae1d12e6284fd4a8259986f6967bf5c29462f1.json

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

Cargo.lock

@@ -679,6 +679,7 @@ dependencies = [
  "discord-rich-presence",
  "enums",
  "errors",
+ "fal_client",
  "filesys",
  "futures 0.3.32",
  "grok_client",

_database/sql/artcraft_migrations/20250708000000_create_tasks_table.sql

@@ -19,6 +19,10 @@
 --   tasks_v6.sqlite - added two fields:
 --      on_failure_type
 --      on_failure_message
+--   tasks_v7.sqlite - added prompt token + two fields (for fal):
+--      prompt_token
+--      queue_status_url
+--      queue_response_url
 
 CREATE TABLE tasks (
     -- Task auto-incrementing primary key.
@@ -46,6 +50,11 @@ CREATE TABLE tasks (
     -- The primary key for the job in the provider's system.
     provider_job_id TEXT,
 
+    -- OPTIONAL.
+    -- For third party jobs, we need to record the prompt details upfront.
+    -- We create a prompt record and store the token to associate once the task completes.
+    prompt_token TEXT,
+
     -- OPTIONAL.
     -- Tell the job system which caller initiated the task.
     -- e.g. 'canvas'
@@ -63,6 +72,16 @@ CREATE TABLE tasks (
     -- Whether the user has dismissed the task from view.
     is_dismissed_by_user INTEGER NOT NULL DEFAULT 0,
 
+    -- OPTIONAL.
+    -- For some third party systems (eg. FAL), the URL to check the status of the
+    -- job in the queue.
+    queue_status_url TEXT,
+
+    -- OPTIONAL.
+    -- For some third party systems (eg. FAL), the URL to check the
+    -- results (when the job completes)
+    queue_response_url TEXT,
+
     -- OPTIONAL.
     -- When the generation completes, the batch token (if any).
     -- This will point to a collection of multiple files.

_database/sql/migrations/2026-05-13-131719-0000_alter_users_add_maybe_referral_partner/down.sql

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

_database/sql/migrations/2026-05-13-131719-0000_alter_users_add_maybe_referral_partner/up.sql

@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE users
+  ADD COLUMN maybe_referral_partner VARCHAR(32) DEFAULT NULL;

_database/sql/migrations/2026-05-13-131733-0000_alter_users_add_maybe_referral_user_token/down.sql

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

_database/sql/migrations/2026-05-13-131733-0000_alter_users_add_maybe_referral_user_token/up.sql

@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE users
+  ADD COLUMN maybe_referral_user_token VARCHAR(32) DEFAULT NULL;

_database/sql/migrations/2026-05-13-225030-0000_user_referrals/down.sql

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

_database/sql/migrations/2026-05-13-225030-0000_user_referrals/up.sql

@@ -0,0 +1,31 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_referrals (
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- The user who was invited/referred.
+  invited_user_token VARCHAR(32) NOT NULL,
+
+  -- The user who referred the invited user.
+  referrer_user_token VARCHAR(32) NOT NULL,
+
+  -- OPTIONAL. The referral code token used, if any.
+  maybe_referral_code_token VARCHAR(32) DEFAULT NULL,
+
+  -- OPTIONAL. The referral URL the invited user arrived from.
+  maybe_referral_url VARCHAR(255) DEFAULT NULL,
+
+  -- OPTIONAL. The landing URL the invited user first visited.
+  maybe_landing_url VARCHAR(255) DEFAULT NULL,
+
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY unique_invited_user_token (invited_user_token),
+  KEY index_referrer_user_token (referrer_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations/2026-05-13-225037-0000_user_referral_codes/down.sql

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

_database/sql/migrations/2026-05-13-225037-0000_user_referral_codes/up.sql

@@ -0,0 +1,34 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_referral_codes (
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Unique token identifier for this referral code record.
+  token VARCHAR(32) NOT NULL,
+
+  -- The human-readable referral code (e.g. a username or custom code).
+  -- This can be changed.
+  code VARCHAR(32) NOT NULL,
+
+  -- Lowercased version of `code` for case-insensitive uniqueness lookups.
+  code_lowercase VARCHAR(32) NOT NULL,
+
+  -- The user who owns this referral code.
+  owner_user_token VARCHAR(32) NOT NULL,
+
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- Soft delete.
+  deleted_at DATETIME NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY unique_token (token),
+  UNIQUE KEY unique_code_lowercase (code_lowercase),
+  KEY index_owner_user_token (owner_user_token),
+  KEY index_deleted_at (deleted_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations_squashed/media_files.sql

@@ -28,6 +28,7 @@ CREATE TABLE media_files (
   -- There is an index on this column.
   -- Broad "category" for where the file came from:
   --   * 'inference' for inference output
+  --   * 'inference_third' for inference output
   --   * 'processed' for processed file (eg. mp3 encoding, stem splitting, etc.)
   --   * 'upload' for direct user upload (from the filesystem)
   --   * 'device_api' for direct user uploads recorded using Browser/Device APIs.

_database/sql/migrations_squashed/user_tables/user_referral_codes.sql

@@ -0,0 +1,33 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_referral_codes (
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Unique token identifier for this referral code record.
+  token VARCHAR(32) NOT NULL,
+
+  -- The human-readable referral code (e.g. a username or custom code).
+  code VARCHAR(32) NOT NULL,
+
+  -- Lowercased version of `code` for case-insensitive uniqueness lookups.
+  code_lowercase VARCHAR(32) NOT NULL,
+
+  -- The user who owns this referral code.
+  owner_user_token VARCHAR(32) NOT NULL,
+
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- Soft delete.
+  deleted_at DATETIME NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY unique_token (token),
+  UNIQUE KEY unique_code_lowercase (code_lowercase),
+  KEY index_owner_user_token (owner_user_token),
+  KEY index_deleted_at (deleted_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations_squashed/user_tables/user_referrals.sql

@@ -0,0 +1,31 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_referrals (
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- The user who was invited/referred.
+  invited_user_token VARCHAR(32) NOT NULL,
+
+  -- The user who referred the invited user.
+  referrer_user_token VARCHAR(32) NOT NULL,
+
+  -- OPTIONAL. The referral code token used, if any.
+  maybe_referral_code_token VARCHAR(32) DEFAULT NULL,
+
+  -- OPTIONAL. The referral URL the invited user arrived from.
+  maybe_referral_url VARCHAR(255) DEFAULT NULL,
+
+  -- OPTIONAL. The landing URL the invited user first visited.
+  maybe_landing_url VARCHAR(255) DEFAULT NULL,
+
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY unique_invited_user_token (invited_user_token),
+  KEY index_referrer_user_token (referrer_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;

_database/sql/migrations_squashed/user_tables/users.sql

@@ -202,9 +202,20 @@ CREATE TABLE users (
 
   -- ========== TRACKING ==========
 
-  -- Where the user signed up from (NOT NECESSARILY AN ENUM!)
-  -- For now this will be "artcraft", "fakeyou", or "storyteller", 
-  -- though we may extend or overload this to handle other cases or metadata.
+  -- Where the user signed up from
+  --
+  -- ArtCraft Values:
+  --  - "artcraft"         - (deprecated)
+  --  - "artcraft_app"     - Signup with the ArtCraft app
+  --  - "artcraft_get_web" - Signup with ArtCraft website signup flow
+  --  - "artcraft_get_s"   - Signup with ArtCraft website Stripe Checkout Flow
+  --  - "artcraft_ai_s"    - Signup with Artcraft.ai website Stripe checkout flow
+  --  - "artcraft_get_web" - Signup with ArtCraft.ai website signup flow
+  --
+  -- Other Sources:
+  --  - "fakeyou" - FakeYou signup
+  --  - "storyteller" - Storyteller.ai signup
+  --
   maybe_source VARCHAR(255) DEFAULT NULL,
 
   -- How users created their account
@@ -229,6 +240,13 @@ CREATE TABLE users (
   -- This helps us know what marketing is effective.
   maybe_landing_url VARCHAR(255) DEFAULT NULL,
 
+  -- If a user referred this user, this is either the raw username or raw "referral code"
+  -- that this user used to sign up. This is not verified and can be used for debugging.
+  maybe_referral_partner VARCHAR(32) DEFAULT NULL,
+
+  -- If a user referred this user, we record the user token of the referrer.
+  maybe_referral_user_token VARCHAR(32) DEFAULT NULL,
+
   -- ========== MODERATION DETAILS ==========
 
   -- Different than deleted.

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

@@ -10,6 +10,7 @@ pub mod omni_gen;
 pub mod prompts;
 pub mod stripe_artcraft;
 pub mod subscriptions;
+pub mod user_referral_codes;
 pub mod users;
 pub mod utils;
 pub mod web_referrals;

crates/api_clients/artcraft/artcraft_api_defs/src/stripe_artcraft/create_create_new_user_account_and_subscription_checkout.rs

@@ -20,6 +20,13 @@ pub struct StripeArtcraftCreateSubscriptionCheckoutWithUserSignupRequest {
   /// Optional: The URL where the user landed when they first arrived, prior to navigation and signing up.
   /// The browser can send `window.location.href` to the backend so we know how people are finding us.
   pub maybe_landing_url: Option<String>,
+
+  /// Optional: A referral username or code from a referring user.
+  pub maybe_referral_username: Option<String>,
+
+  /// Optional: A referral code created by another user. If present, takes priority over
+  /// `maybe_referral_username` for resolving the referring user.
+  pub maybe_referral_code: Option<String>,
 }
 
 #[derive(Serialize, Deserialize, ToSchema, Debug, Copy, Clone)]

crates/api_clients/artcraft/artcraft_api_defs/src/user_referral_codes/create_referral_code.rs

@@ -0,0 +1,17 @@
+use serde_derive::{Deserialize, Serialize};
+use tokens::tokens::user_referral_codes::UserReferralCodeToken;
+use utoipa::ToSchema;
+
+#[derive(Deserialize, ToSchema)]
+pub struct CreateReferralCodeRequest {
+  /// The referral code string. Alphanumeric plus underscore, period, dash.
+  pub code: String,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct CreateReferralCodeResponse {
+  pub success: bool,
+  pub token: UserReferralCodeToken,
+  pub code: String,
+  pub code_lowercase: String,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/user_referral_codes/delete_referral_code.rs

@@ -0,0 +1,13 @@
+use serde_derive::{Deserialize, Serialize};
+use tokens::tokens::user_referral_codes::UserReferralCodeToken;
+use utoipa::ToSchema;
+
+#[derive(Deserialize, ToSchema)]
+pub struct DeleteReferralCodePathInfo {
+  pub token: UserReferralCodeToken,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct DeleteReferralCodeResponse {
+  pub success: bool,
+}

crates/api_clients/artcraft/artcraft_api_defs/src/user_referral_codes/list_referral_codes.rs

@@ -0,0 +1,19 @@
+use chrono::{DateTime, Utc};
+use serde_derive::{Deserialize, Serialize};
+use tokens::tokens::user_referral_codes::UserReferralCodeToken;
+use utoipa::ToSchema;
+
+#[derive(Serialize, ToSchema)]
+pub struct ListReferralCodesResponse {
+  pub success: bool,
+  pub referral_codes: Vec<ReferralCodeEntry>,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct ReferralCodeEntry {
+  pub token: UserReferralCodeToken,
+  pub code: String,
+  pub code_lowercase: String,
+  pub created_at: DateTime<Utc>,
+  pub updated_at: DateTime<Utc>,
+}

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

@@ -0,0 +1,3 @@
+pub mod create_referral_code;
+pub mod delete_referral_code;
+pub mod list_referral_codes;

crates/api_clients/artcraft/artcraft_client/src/endpoints/media_files/legacy_upload_media_file_from_file.rs

@@ -34,10 +34,9 @@ pub struct LegacyUploadMediaFileFromFileArgs<'a, P: AsRef<Path>> {
   // /// NOTE: Cannot set `is_intermediate_system_file = true` if this is set.
   // pub maybe_prompt_token: Option<&'a PromptToken>,
 
-  // /// If provided, this is the service provider that created the image.
-  // /// NOTE: Cannot set `is_intermediate_system_file = true` if this is set.
-  // pub maybe_generation_provider: Option<GenerationProvider>,
-  
+  /// If provided, the third-party provider that generated this file.
+  pub maybe_generation_provider: Option<GenerationProvider>,
+
   // /// If provided, this groups the file into a batch
   // /// TODO: This shouldn't be set clientside without the backend generating the token 
   // ///  and cryptographically securing it. But we need to go fast here.
@@ -82,6 +81,10 @@ pub async fn legacy_upload_media_file_from_file<P: AsRef<Path>>(
   //  form = form.text("maybe_batch_token", batch_token.to_string());
   //}
 
+  if let Some(provider) = &args.maybe_generation_provider {
+    form = form.text("maybe_generation_provider", provider.to_str().to_string());
+  }
+
   let mut request_builder = client.post(url)
       .header("User-Agent", USER_AGENT)
       .header("Accept", APPLICATION_JSON);

crates/api_clients/artcraft/artcraft_client/src/endpoints/media_files/upload_image_media_file_from_bytes.rs

@@ -6,6 +6,7 @@ use crate::utils::api_host::ApiHost;
 use crate::utils::constants::{APPLICATION_JSON, USER_AGENT};
 use crate::utils::filter_bad_response::filter_bad_response;
 use crate::utils::http_get_anonymous::http_get_anonymous;
+use enums::common::generation_provider::GenerationProvider;
 use chrono::{DateTime, Utc};
 use uuid_utils::uuid::generate_random_uuid;
 use log::debug;
@@ -31,6 +32,9 @@ pub struct UploadImageBytesArgs<'a> {
   
   /// If true, we should hide the image from the user's gallery.
   pub is_intermediate_system_file: bool,
+
+  /// If provided, the third-party provider that generated this file.
+  pub maybe_generation_provider: Option<GenerationProvider>,
 }
 
 #[derive(Clone, Copy, Debug)]
@@ -86,6 +90,10 @@ pub async fn upload_image_media_file_from_bytes(
     form = form.text("is_intermediate_system_file", "true");
   }
 
+  if let Some(provider) = &args.maybe_generation_provider {
+    form = form.text("maybe_generation_provider", provider.to_str().to_string());
+  }
+
   let mut request_builder = client.post(url)
       .header("User-Agent", USER_AGENT)
       .header("Accept", APPLICATION_JSON);

crates/api_clients/artcraft/artcraft_client/src/endpoints/media_files/upload_image_media_file_from_file.rs

@@ -34,10 +34,9 @@ pub struct UploadImageFromFileArgs<'a, P: AsRef<Path>> {
   /// NOTE: Cannot set `is_intermediate_system_file = true` if this is set.
   pub maybe_prompt_token: Option<&'a PromptToken>,
 
-  // /// If provided, this is the service provider that created the image.
-  // /// NOTE: Cannot set `is_intermediate_system_file = true` if this is set.
-  // pub maybe_generation_provider: Option<GenerationProvider>,
-  
+  /// If provided, the third-party provider that generated this file.
+  pub maybe_generation_provider: Option<GenerationProvider>,
+
   /// If provided, this groups the file into a batch
   /// TODO: This shouldn't be set clientside without the backend generating the token 
   ///  and cryptographically securing it. But we need to go fast here.
@@ -82,6 +81,10 @@ pub async fn upload_image_media_file_from_file<P: AsRef<Path>>(
     form = form.text("maybe_batch_token", batch_token.to_string());
   }
 
+  if let Some(provider) = &args.maybe_generation_provider {
+    form = form.text("maybe_generation_provider", provider.to_str().to_string());
+  }
+
   let mut request_builder = client.post(url)
       .header("User-Agent", USER_AGENT)
       .header("Accept", APPLICATION_JSON);

crates/api_clients/artcraft/artcraft_client/src/endpoints/media_files/upload_new_engine_asset_from_file.rs

@@ -4,6 +4,7 @@ use crate::utils::api_host::ApiHost;
 use crate::utils::constants::{APPLICATION_JSON, USER_AGENT};
 use crate::utils::filter_bad_response::filter_bad_response;
 use crate::utils::http_get_anonymous::http_get_anonymous;
+use enums::common::generation_provider::GenerationProvider;
 use chrono::{DateTime, Utc};
 use uuid_utils::uuid::generate_random_uuid;
 use log::debug;
@@ -24,6 +25,7 @@ pub async fn upload_new_engine_asset_from_file<P: AsRef<Path>>(
   api_host: &ApiHost,
   maybe_creds: Option<&StorytellerCredentialSet>,
   path: P,
+  maybe_generation_provider: Option<GenerationProvider>,
 ) -> Result<UploadImageMediaFileSuccessResponse, ApiError> {
 
   let url = get_route(api_host);
@@ -37,11 +39,15 @@ pub async fn upload_new_engine_asset_from_file<P: AsRef<Path>>(
   let file_bytes = std::fs::read(path.as_ref())?;
   let file_name = path.as_ref().file_name()
       .and_then(|n| n.to_str()).unwrap_or("file").to_string();
-  let form = Form::new()
+  let mut form = Form::new()
       .text("uuid_idempotency_token", generate_random_uuid())
       .text("engine_category", "object") // TODO: Which type should we use?
       .part("file", Part::bytes(file_bytes).file_name(file_name));
 
+  if let Some(provider) = &maybe_generation_provider {
+    form = form.text("maybe_generation_provider", provider.to_str().to_string());
+  }
+
   let mut request_builder = client.post(url)
       .header("User-Agent", USER_AGENT)
       .header("Accept", APPLICATION_JSON);

crates/api_clients/artcraft/artcraft_client/src/endpoints/media_files/upload_video_media_file_from_file.rs

@@ -4,6 +4,7 @@ use crate::utils::api_host::ApiHost;
 use crate::utils::constants::{APPLICATION_JSON, USER_AGENT};
 use crate::utils::filter_bad_response::filter_bad_response;
 use crate::utils::http_get_anonymous::http_get_anonymous;
+use enums::common::generation_provider::GenerationProvider;
 use chrono::{DateTime, Utc};
 use uuid_utils::uuid::generate_random_uuid;
 use log::debug;
@@ -31,9 +32,8 @@ pub struct UploadVideoFromFileArgs<'a, P: AsRef<Path>> {
   /// NOTE: Cannot set `is_intermediate_system_file = true` if this is set.
   pub maybe_prompt_token: Option<&'a PromptToken>,
 
-  // /// If provided, this is the service provider that created the image.
-  // /// NOTE: Cannot set `is_intermediate_system_file = true` if this is set.
-  // pub maybe_generation_provider: Option<GenerationProvider>,
+  /// If provided, the third-party provider that generated this file.
+  pub maybe_generation_provider: Option<GenerationProvider>,
 
   // /// If provided, this groups the file into a batch
   // /// TODO: This shouldn't be set clientside without the backend generating the token 
@@ -73,6 +73,10 @@ pub async fn upload_video_media_file_from_file<P: AsRef<Path>>(
     form = form.text("maybe_prompt_token", prompt_token.to_string());
   }
 
+  if let Some(provider) = &args.maybe_generation_provider {
+    form = form.text("maybe_generation_provider", provider.to_str().to_string());
+  }
+
   let mut request_builder = client.post(url)
       .header("User-Agent", USER_AGENT)
       .header("Accept", APPLICATION_JSON);

crates/api_clients/artcraft/artcraft_client/src/recipes/upload_media_file_from_file.rs

@@ -33,7 +33,7 @@ pub async fn upload_media_file_from_file<P: AsRef<Path>>(
   
   match maybe_type {
     Some(FileExtension::Glb) => {
-      match upload_new_engine_asset_from_file(api_host, maybe_creds, path).await {
+      match upload_new_engine_asset_from_file(api_host, maybe_creds, path, None).await {
         Ok(result) => Ok(UploadMediaFileSuccessResponse {
           success: result.success,
           media_file_token: result.media_file_token,
@@ -46,7 +46,8 @@ pub async fn upload_media_file_from_file<P: AsRef<Path>>(
         api_host,
         maybe_creds, 
         path,
-        maybe_prompt_token
+        maybe_prompt_token,
+        maybe_generation_provider: None,
       }).await {
         Ok(result) => Ok(UploadMediaFileSuccessResponse {
           success: result.success,
@@ -63,6 +64,7 @@ pub async fn upload_media_file_from_file<P: AsRef<Path>>(
         is_intermediate_system_file: false,
         maybe_prompt_token,
         maybe_batch_token: None,
+        maybe_generation_provider: None,
       }).await;
       match result {
         Ok(result) => Ok(UploadMediaFileSuccessResponse {

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

@@ -5,5 +5,6 @@ pub mod request_mismatch_mitigation_strategy;
 pub mod router_artcraft_client;
 pub mod router_client;
 pub mod router_fal_client;
+pub mod router_fal_webhook_optional_client;
 pub mod router_muapi_client;
 pub mod router_seedance2pro_client;

crates/api_clients/artcraft/artcraft_router/src/client/multi_router_client.rs

@@ -1,5 +1,6 @@
 use crate::client::router_artcraft_client::RouterArtcraftClient;
 use crate::client::router_fal_client::RouterFalClient;
+use crate::client::router_fal_webhook_optional_client::RouterFalWebhookOptionalClient;
 use crate::client::router_muapi_client::RouterMuapiClient;
 use crate::client::router_seedance2pro_client::RouterSeedance2ProClient;
 use crate::errors::client_error::{ClientError, ClientType};
@@ -7,6 +8,7 @@ use crate::errors::client_error::{ClientError, ClientType};
 pub struct MultiRouterClient {
   pub(crate) artcraft_client: Option<RouterArtcraftClient>,
   pub(crate) fal_client: Option<RouterFalClient>,
+  pub(crate) fal_webhook_optional_client: Option<RouterFalWebhookOptionalClient>,
   pub(crate) muapi_client: Option<RouterMuapiClient>,
   pub(crate) seedance2pro_client: Option<RouterSeedance2ProClient>,
 }
@@ -21,6 +23,10 @@ impl MultiRouterClient {
     self.fal_client.as_ref()
       .ok_or(ClientError::ClientNotConfigured(ClientType::Fal))
   }
+  pub fn get_fal_webhook_optional_client_ref(&self) -> Result<&RouterFalWebhookOptionalClient, ClientError> {
+    self.fal_webhook_optional_client.as_ref()
+      .ok_or(ClientError::ClientNotConfigured(ClientType::FalWebhookOptional))
+  }
 
   pub fn get_muapi_client_ref(&self) -> Result<&RouterMuapiClient, ClientError> {
     self.muapi_client.as_ref()

crates/api_clients/artcraft/artcraft_router/src/client/multi_router_client_builder.rs

@@ -1,12 +1,14 @@
 use crate::client::multi_router_client::MultiRouterClient;
 use crate::client::router_artcraft_client::RouterArtcraftClient;
 use crate::client::router_fal_client::RouterFalClient;
+use crate::client::router_fal_webhook_optional_client::RouterFalWebhookOptionalClient;
 use crate::client::router_muapi_client::RouterMuapiClient;
 use crate::client::router_seedance2pro_client::RouterSeedance2ProClient;
 
 pub struct MultiRouterClientBuilder {
   artcraft_client: Option<RouterArtcraftClient>,
   fal_client: Option<RouterFalClient>,
+  fal_webhook_optional_client: Option<RouterFalWebhookOptionalClient>,
   muapi_client: Option<RouterMuapiClient>,
   seedance2pro_client: Option<RouterSeedance2ProClient>,
 }
@@ -16,6 +18,7 @@ impl MultiRouterClientBuilder {
     Self {
       artcraft_client: None,
       fal_client: None,
+      fal_webhook_optional_client: None,
       muapi_client: None,
       seedance2pro_client: None,
     }
@@ -30,6 +33,11 @@ impl MultiRouterClientBuilder {
     self.fal_client = Some(client);
     self
   }
+  
+  pub fn set_fal_webhook_optional_client(mut self, client: RouterFalWebhookOptionalClient) -> Self {
+    self.fal_webhook_optional_client = Some(client);
+    self
+  }
 
   pub fn set_muapi_client(mut self, client: RouterMuapiClient) -> Self {
     self.muapi_client = Some(client);
@@ -45,6 +53,7 @@ impl MultiRouterClientBuilder {
     MultiRouterClient {
       artcraft_client: self.artcraft_client,
       fal_client: self.fal_client,
+      fal_webhook_optional_client: self.fal_webhook_optional_client,
       muapi_client: self.muapi_client,
       seedance2pro_client: self.seedance2pro_client,
     }

crates/api_clients/artcraft/artcraft_router/src/client/router_client.rs

@@ -1,6 +1,7 @@
 use crate::client::multi_router_client::MultiRouterClient;
 use crate::client::router_artcraft_client::RouterArtcraftClient;
 use crate::client::router_fal_client::RouterFalClient;
+use crate::client::router_fal_webhook_optional_client::RouterFalWebhookOptionalClient;
 use crate::client::router_muapi_client::RouterMuapiClient;
 use crate::client::router_seedance2pro_client::RouterSeedance2ProClient;
 use crate::errors::client_error::{ClientError, ClientType};
@@ -9,6 +10,7 @@ pub enum RouterClient {
   Multi(MultiRouterClient),
   Artcraft(RouterArtcraftClient),
   Fal(RouterFalClient),
+  FalWebhookOptional(RouterFalWebhookOptionalClient),
   Muapi(RouterMuapiClient),
   Seedance2Pro(RouterSeedance2ProClient),
 }
@@ -30,6 +32,14 @@ impl RouterClient {
     }
   }
 
+  pub fn get_fal_webhook_optional_client_ref(&self) -> Result<&RouterFalWebhookOptionalClient, ClientError> {
+    match self {
+      RouterClient::FalWebhookOptional(client) => Ok(client),
+      RouterClient::Multi(multi) => multi.get_fal_webhook_optional_client_ref(),
+      _ => Err(ClientError::ClientNotConfigured(ClientType::Fal)),
+    }
+  }
+
   pub fn get_muapi_client_ref(&self) -> Result<&RouterMuapiClient, ClientError> {
     match self {
       RouterClient::Muapi(client) => Ok(client),

crates/api_clients/artcraft/artcraft_router/src/client/router_fal_client.rs

@@ -9,4 +9,11 @@ impl RouterFalClient {
   pub fn new(api_key: FalApiKey, webhook_url: String) -> Self {
     Self { api_key, webhook_url }
   }
+
+  pub fn new_from_raw_key(api_key: &str, webhook_url: String) -> Self {
+    Self {
+      api_key: FalApiKey::from_str(api_key),
+      webhook_url,
+    }
+  }
 }

crates/api_clients/artcraft/artcraft_router/src/client/router_fal_webhook_optional_client.rs

@@ -0,0 +1,22 @@
+use fal_client::creds::fal_api_key::FalApiKey;
+
+pub struct RouterFalWebhookOptionalClient {
+  pub(crate) api_key: FalApiKey,
+  pub(crate) webhook_url: Option<String>,
+}
+
+impl RouterFalWebhookOptionalClient {
+  pub fn new(api_key: FalApiKey) -> Self {
+    Self { api_key, webhook_url: None }
+  }
+  pub fn from_str(api_key: &str) -> Self {
+    Self::new(FalApiKey::from_str(api_key))
+  }
+
+  pub fn new_with_webhook(api_key: FalApiKey, webhook_url: String) -> Self {
+    Self { 
+      api_key, 
+      webhook_url: Some(webhook_url)
+    }
+  }
+}

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

@@ -1,8 +1,13 @@
 use crate::errors::client_error::ClientError;
 use crate::errors::download_error::DownloadError;
 use crate::errors::provider_error::ProviderError;
+use fal_client::error::fal_error_plus::FalErrorPlus;
+use seedance2pro_client::error::seedance2pro_error::Seedance2ProError;
+use seedance2pro_client::error::seedance2pro_specific_api_error::Seedance2ProSpecificApiError;
 use std::error::Error;
 use std::fmt::{Display, Formatter};
+use artcraft_client::error::api_error::ApiError;
+use artcraft_client::error::storyteller_error::StorytellerError;
 
 #[derive(Debug)]
 pub enum ArtcraftRouterError {
@@ -23,6 +28,9 @@ pub enum ArtcraftRouterError {
 
   /// An error from an underlying provider.
   Provider(ProviderError),
+  
+  /// A billing error from an underlying provider.
+  ProviderBillingError(ProviderError),
 }
 
 impl Error for ArtcraftRouterError {}
@@ -36,6 +44,7 @@ impl Display for ArtcraftRouterError {
       Self::UnsupportedProviderAndModelForNewApi(msg) => write!(f, "Unsupported provider/model (for new API during migration): {}", msg),
       Self::InvalidInput(msg) => write!(f, "Invalid input: {}", msg),
       Self::Provider(e) => write!(f, "Provider error: {}", e),
+      Self::ProviderBillingError(e) => write!(f, "Provider billing error: {}", e),
     }
   }
 }
@@ -54,6 +63,25 @@ impl From<DownloadError> for ArtcraftRouterError {
 
 impl From<ProviderError> for ArtcraftRouterError {
   fn from(error: ProviderError) -> Self {
-    Self::Provider(error)
+    let is_billing_error = match &error {
+      ProviderError::Fal(FalErrorPlus::FalBillingError(_)) => true,
+      ProviderError::Seedance2Pro(Seedance2ProError::ApiSpecific(Seedance2ProSpecificApiError::BillingError { .. })) => true,
+      ProviderError::Storyteller(StorytellerError::Api(ApiError::PaymentRequired(_))) => true,
+      _ => false,
+    };
+    if is_billing_error {
+      Self::ProviderBillingError(error)
+    } else {
+      Self::Provider(error)
+    }
+  }
+}
+
+impl From<FalErrorPlus> for ArtcraftRouterError {
+  fn from(error: FalErrorPlus) -> Self {
+    match &error {
+      FalErrorPlus::FalBillingError(e) => ArtcraftRouterError::ProviderBillingError(ProviderError::Fal(error)),
+      _ => ArtcraftRouterError::Provider(ProviderError::Fal(error)),
+    }
   }
 }

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

@@ -7,6 +7,7 @@ use tokens::tokens::media_files::MediaFileToken;
 pub enum ClientType {
   Artcraft,
   Fal,
+  FalWebhookOptional,
   Muapi,
   Seedance2Pro,
 }
@@ -16,6 +17,7 @@ impl Display for ClientType {
     match self {
       Self::Artcraft => write!(f, "Artcraft"),
       Self::Fal => write!(f, "Fal"),
+      Self::FalWebhookOptional => write!(f, "FalWebhookOptional"),
       Self::Muapi => write!(f, "Muapi"),
       Self::Seedance2Pro => write!(f, "Seedance2Pro"),
     }

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

@@ -33,10 +33,10 @@ mod tests {
   use crate::api::common_image_model::CommonImageModel;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::Flux1Dev,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -20,11 +20,11 @@ mod tests {
   use crate::api::common_image_model::CommonImageModel;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   #[test]
   fn test_estimate_cost_is_none() {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::Flux1Schnell,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -34,12 +34,12 @@ mod tests {
   use crate::api::image_list_ref::ImageListRef;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use tokens::tokens::media_files::MediaFileToken;
 
   fn estimate_usd_cents(image_batch_count: u16) -> u64 {
     let tokens = vec![MediaFileToken::new_from_str("test_token")];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::Flux2LoraAngles,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -36,10 +36,10 @@ mod tests {
   use crate::api::common_image_model::CommonImageModel;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::FluxPro11,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -33,10 +33,10 @@ mod tests {
   use crate::api::common_image_model::CommonImageModel;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::FluxPro11Ultra,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -59,11 +59,11 @@ mod tests {
   use crate::api::image_list_ref::ImageListRef;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use tokens::tokens::media_files::MediaFileToken;
 
-  fn base() -> GenerateImageRequest {
-    GenerateImageRequest {
+  fn base() -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
       model: CommonImageModel::GptImage1,
       provider: Provider::Artcraft,
       prompt: None,
@@ -86,7 +86,7 @@ mod tests {
     aspect_ratio: Option<CommonAspectRatio>,
     batch: u16,
   ) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       quality,
       aspect_ratio,
       image_batch_count: Some(batch),
@@ -105,7 +105,7 @@ mod tests {
     let tokens: Vec<MediaFileToken> = (0..num_input_images)
       .map(|i| MediaFileToken::new_from_str(&format!("mf_test{:028}", i)))
       .collect();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       quality,
       aspect_ratio,
       image_batch_count: Some(batch),

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

@@ -64,14 +64,14 @@ mod tests {
   use crate::api::common_quality::CommonQuality;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate(
     quality: Option<CommonQuality>,
     aspect_ratio: Option<CommonAspectRatio>,
     batch: u16,
   ) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::GptImage1p5,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -33,10 +33,10 @@ mod tests {
   use crate::api::common_image_model::CommonImageModel;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::NanoBanana,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -46,10 +46,10 @@ mod tests {
   use crate::api::common_resolution::CommonResolution;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(resolution: Option<CommonResolution>, image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::NanoBanana2,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -40,10 +40,10 @@ mod tests {
   use crate::api::common_resolution::CommonResolution;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(resolution: Option<CommonResolution>, image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::NanoBananaPro,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -34,12 +34,12 @@ mod tests {
   use crate::api::image_list_ref::ImageListRef;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use tokens::tokens::media_files::MediaFileToken;
 
   fn estimate_usd_cents(image_batch_count: u16) -> u64 {
     let tokens = vec![MediaFileToken::new_from_str("test_token")];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::QwenEdit2511Angles,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -33,10 +33,10 @@ mod tests {
   use crate::api::common_image_model::CommonImageModel;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::Seedream4,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -33,10 +33,10 @@ mod tests {
   use crate::api::common_image_model::CommonImageModel;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::Seedream4p5,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -33,10 +33,10 @@ mod tests {
   use crate::api::common_image_model::CommonImageModel;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::Seedream5Lite,
       provider: Provider::Artcraft,
       prompt: None,

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

@@ -38,10 +38,10 @@ mod tests {
   use crate::api::common_resolution::CommonResolution;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 
   fn estimate_usd_cents(resolution: Option<CommonResolution>, image_batch_count: u16) -> u64 {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       model: CommonImageModel::NanoBananaPro,
       provider: Provider::Fal,
       prompt: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_flux_1_dev.rs

@@ -36,7 +36,7 @@ pub async fn execute_artcraft_flux_1_dev(
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_flux_1_dev_image_request, get_artcraft_client};
   use strum::IntoEnumIterator;
@@ -45,7 +45,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_flux_1_dev() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       quality: None,
       image_batch_count: Some(1),
@@ -68,7 +68,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_flux_1_dev_batch_four() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       quality: None,
       image_batch_count: Some(4),
@@ -94,7 +94,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- text-to-image aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(ar),
         quality: None,
         image_batch_count: Some(1),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_flux_1_schnell.rs

@@ -36,7 +36,7 @@ pub async fn execute_artcraft_flux_1_schnell(
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::test_helpers::{base_flux_1_schnell_image_request, get_artcraft_client};
   use strum::IntoEnumIterator;
 
@@ -44,7 +44,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_flux_1_schnell() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       quality: None,
       image_batch_count: Some(1),
@@ -67,7 +67,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_flux_1_schnell_batch_four() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       quality: None,
       image_batch_count: Some(4),
@@ -93,7 +93,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- text-to-image aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(ar),
         quality: None,
         image_batch_count: Some(1),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_flux_2_lora_angles.rs

@@ -39,7 +39,7 @@ pub async fn execute_artcraft_flux_2_lora_angles(
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::image_list_ref::ImageListRef;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_flux_2_lora_angles_image_request, get_artcraft_client};
   use tokens::tokens::media_files::MediaFileToken;
@@ -49,7 +49,7 @@ mod tests {
   async fn test_angle_edit_flux_2_lora() {
     let client = get_artcraft_client();
     let tokens = vec![MediaFileToken::new_from_str("m_r45apt2swza6wp8j2z10237t92kkr8")];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::SquareHd),
       quality: None,
       image_batch_count: Some(1),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_flux_pro_1p1.rs

@@ -36,7 +36,7 @@ pub async fn execute_artcraft_flux_pro_1p1(
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_flux_pro_1p1_image_request, get_artcraft_client};
   use strum::IntoEnumIterator;
@@ -45,7 +45,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_flux_pro_1p1() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       quality: None,
       image_batch_count: Some(1),
@@ -68,7 +68,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_flux_pro_1p1_batch_four() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       quality: None,
       image_batch_count: Some(4),
@@ -94,7 +94,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- text-to-image aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(ar),
         quality: None,
         image_batch_count: Some(1),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_flux_pro_1p1_ultra.rs

@@ -36,7 +36,7 @@ pub async fn execute_artcraft_flux_pro_1p1_ultra(
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_flux_pro_1p1_ultra_image_request, get_artcraft_client};
   use strum::IntoEnumIterator;
@@ -45,7 +45,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_flux_pro_1p1_ultra() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       quality: None,
       image_batch_count: Some(1),
@@ -68,7 +68,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_flux_pro_1p1_ultra_batch_four() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       quality: None,
       image_batch_count: Some(4),
@@ -94,7 +94,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- text-to-image aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(ar),
         quality: None,
         image_batch_count: Some(1),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_gpt_image_1.rs

@@ -64,7 +64,7 @@ pub async fn execute_artcraft_gpt_image_1(
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::image_list_ref::ImageListRef;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_gpt_image_1_image_request, get_artcraft_client};
   use tokens::tokens::media_files::MediaFileToken;
@@ -73,7 +73,7 @@ mod tests {
   // (no network I/O — we never call generate_image).
   #[test]
   fn build_text_to_image_plan_smoke() {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       image_batch_count: Some(1),
       ..base_gpt_image_1_image_request()
@@ -88,7 +88,7 @@ mod tests {
   #[test]
   fn build_edit_image_plan_smoke() {
     let tokens = vec![MediaFileToken::new_from_str("mf_test00000000000000000000000000")];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       ..base_gpt_image_1_image_request()
     };
@@ -103,7 +103,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_gpt_image_1() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       image_batch_count: Some(1),
       prompt: Some("a horse walking through a cyberpunk city at night".to_string()),
@@ -128,7 +128,7 @@ mod tests {
       MediaFileToken::new_from_str("m_r45apt2swza6wp8j2z10237t92kkr8"),
     ];
 
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       prompt: Some("Change the background to a desert with cacti".to_string()),
       image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
       aspect_ratio: Some(CommonAspectRatio::Square),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_gpt_image_1p5.rs

@@ -43,7 +43,7 @@ mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::image_list_ref::ImageListRef;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_gpt_image_1p5_image_request, get_artcraft_client};
   use strum::IntoEnumIterator;
@@ -53,7 +53,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_gpt_image_1p5() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       image_batch_count: Some(1),
       prompt: Some("a horse walking through a cyberpunk city at night".to_string()),
@@ -80,7 +80,7 @@ mod tests {
       MediaFileToken::new_from_str("m_r45apt2swza6wp8j2z10237t92kkr8"),
     ];
 
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       prompt: Some("Change the background to a desert with cacti".to_string()),
       image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
       aspect_ratio: Some(CommonAspectRatio::Auto),
@@ -106,7 +106,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- text-to-image aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(ar),
         image_batch_count: Some(1),
         prompt: Some("a bear walking through a abandoned desert city at night".to_string()),
@@ -139,7 +139,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- image-edit aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         prompt: Some("Change the background to an alien world".to_string()),
         image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
         aspect_ratio: Some(ar),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_gpt_image_2.rs

@@ -48,13 +48,13 @@ mod tests {
   use crate::api::common_quality::CommonQuality;
   use crate::api::image_list_ref::ImageListRef;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{get_artcraft_client, get_artcraft_client_for_env};
   use tokens::tokens::media_files::MediaFileToken;
 
-  fn base_gpt_image_2_request() -> GenerateImageRequest {
-    GenerateImageRequest {
+  fn base_gpt_image_2_request() -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
       model: crate::api::common_image_model::CommonImageModel::GptImage2,
       provider: crate::api::provider::Provider::Artcraft,
       prompt: Some("a t-rex walking through a cyberpunk city at night".to_string()),
@@ -76,7 +76,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_gpt_image_2() {
     let client = get_artcraft_client_for_env(ApiHost::Localhost { port: 12345 });
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       image_batch_count: Some(1),
       ..base_gpt_image_2_request()
@@ -102,7 +102,7 @@ mod tests {
       MediaFileToken::new_from_str("m_r45apt2swza6wp8j2z10237t92kkr8"),
     ];
 
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       prompt: Some("Change the background to a desert with cacti".to_string()),
       image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens)),
       aspect_ratio: Some(CommonAspectRatio::Auto),
@@ -125,7 +125,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_gpt_image_2_high_quality() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       quality: Some(CommonQuality::High),
       image_batch_count: Some(1),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_nano_banana.rs

@@ -38,7 +38,7 @@ mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::image_list_ref::ImageListRef;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_nano_banana_image_request, get_artcraft_client};
   use strum::IntoEnumIterator;
@@ -48,7 +48,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_nano_banana() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       quality: None,
       image_batch_count: Some(1),
@@ -76,7 +76,7 @@ mod tests {
       MediaFileToken::new_from_str("m_r45apt2swza6wp8j2z10237t92kkr8"),
     ];
 
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       prompt: Some("Change the background to a sunny beach".to_string()),
       image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
       aspect_ratio: Some(CommonAspectRatio::Auto),
@@ -103,7 +103,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- text-to-image aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(ar),
         quality: None,
         image_batch_count: Some(1),
@@ -137,7 +137,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- image-edit aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         prompt: Some("Change the background to a sunny beach".to_string()),
         image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
         aspect_ratio: Some(ar),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_nano_banana_2.rs

@@ -38,7 +38,7 @@ pub async fn execute_artcraft_nano_banana_2(
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::common_resolution::CommonResolution;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_nano_banana_2_image_request, get_artcraft_client};
 
@@ -46,7 +46,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_nano_banana_2() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       resolution: Some(CommonResolution::OneK),
       quality: None,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_nano_banana_pro.rs

@@ -39,7 +39,7 @@ mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::common_resolution::CommonResolution;
   use crate::api::image_list_ref::ImageListRef;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_image_request, get_artcraft_client};
   use tokens::tokens::media_files::MediaFileToken;
@@ -48,7 +48,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_nano_banana_pro() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       resolution: Some(CommonResolution::OneK),
       quality: None,
@@ -72,7 +72,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_nano_banana_pro_batch_four() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       resolution: Some(CommonResolution::OneK),
       quality: None,
@@ -103,7 +103,7 @@ mod tests {
       MediaFileToken::new_from_str("m_2220d5we3masng5hvzg5zz68ywbdqd"),
     ];
 
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       prompt: Some("Add the man in the first image into the fantasy scene in the second image. Keep his hoodie and attire, but match the vibe of the fantasy scene.".to_string()),
       image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
       aspect_ratio: Some(CommonAspectRatio::Auto), // edit mode: preserve source dimensions

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_qwen_edit_2511_angles.rs

@@ -40,7 +40,7 @@ pub async fn execute_artcraft_qwen_edit_2511_angles(
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::image_list_ref::ImageListRef;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_qwen_edit_2511_angles_image_request, get_artcraft_client};
   use tokens::tokens::media_files::MediaFileToken;
@@ -50,7 +50,7 @@ mod tests {
   async fn test_angle_edit_qwen_edit_2511() {
     let client = get_artcraft_client();
     let tokens = vec![MediaFileToken::new_from_str("m_r45apt2swza6wp8j2z10237t92kkr8")];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::SquareHd),
       quality: None,
       image_batch_count: Some(1),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_seedream_4.rs

@@ -39,7 +39,7 @@ mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::image_list_ref::ImageListRef;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_seedream_4_image_request, get_artcraft_client};
   use strum::IntoEnumIterator;
@@ -49,7 +49,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_seedream_4() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       quality: None,
       image_batch_count: Some(1),
@@ -77,7 +77,7 @@ mod tests {
       MediaFileToken::new_from_str("m_r45apt2swza6wp8j2z10237t92kkr8"),
     ];
 
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       prompt: Some("Change the background to a sunny beach".to_string()),
       image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
       aspect_ratio: Some(CommonAspectRatio::Auto),
@@ -104,7 +104,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- text-to-image aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(ar),
         quality: None,
         image_batch_count: Some(1),
@@ -138,7 +138,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- image-edit aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         prompt: Some("Change the background to a sunny beach".to_string()),
         image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
         aspect_ratio: Some(ar),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_seedream_4p5.rs

@@ -39,7 +39,7 @@ mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::image_list_ref::ImageListRef;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_seedream_4p5_image_request, get_artcraft_client};
   use strum::IntoEnumIterator;
@@ -49,7 +49,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_seedream_4p5() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       quality: None,
       image_batch_count: Some(1),
@@ -77,7 +77,7 @@ mod tests {
       MediaFileToken::new_from_str("m_r45apt2swza6wp8j2z10237t92kkr8"),
     ];
 
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       prompt: Some("Change the background to a spooky haunted house".to_string()),
       image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
       aspect_ratio: Some(CommonAspectRatio::Auto2k),
@@ -104,7 +104,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- text-to-image aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(ar),
         quality: None,
         image_batch_count: Some(1),
@@ -138,7 +138,7 @@ mod tests {
 
     for ar in CommonAspectRatio::iter() {
       println!("--- image-edit aspect ratio: {:?} ---", ar);
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         prompt: Some("Change the background to a spooky haunted house".to_string()),
         image_inputs: Some(ImageListRef::MediaFileTokens(image_tokens.clone())),
         aspect_ratio: Some(ar),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/artcraft/generate_image_artcraft_seedream_5_lite.rs

@@ -37,7 +37,7 @@ pub async fn execute_artcraft_seedream_5_lite(
 #[cfg(test)]
 mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_seedream_5_lite_image_request, get_artcraft_client};
 
@@ -45,7 +45,7 @@ mod tests {
   #[ignore] // manually run — fires a real API request and incurs cost
   async fn test_text_to_image_seedream_5_lite() {
     let client = get_artcraft_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       quality: None,
       image_batch_count: Some(1),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_flux_1_dev.rs

@@ -58,6 +58,8 @@ pub async fn execute_fal_flux_1_dev(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_flux_1_schnell.rs

@@ -58,6 +58,8 @@ pub async fn execute_fal_flux_1_schnell(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_flux_pro_1p1.rs

@@ -35,6 +35,8 @@ pub async fn execute_fal_flux_pro_1p1(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_flux_pro_1p1_ultra.rs

@@ -35,6 +35,8 @@ pub async fn execute_fal_flux_pro_1p1_ultra(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_gpt_image_1.rs

@@ -67,6 +67,8 @@ pub async fn execute_fal_gpt_image_1(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }
@@ -79,12 +81,12 @@ mod tests {
   use crate::api::image_list_ref::ImageListRef;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::get_fal_client;
 
-  fn base_fal_request() -> GenerateImageRequest {
-    GenerateImageRequest {
+  fn base_fal_request() -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
       model: CommonImageModel::GptImage1,
       provider: Provider::Fal,
       prompt: Some("a cat in space".to_string()),
@@ -105,7 +107,7 @@ mod tests {
   // Build-only smoke test (no network I/O).
   #[test]
   fn build_text_to_image_plan_smoke() {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       image_batch_count: Some(1),
       ..base_fal_request()
@@ -121,7 +123,7 @@ mod tests {
   #[test]
   fn build_edit_image_plan_smoke() {
     let urls = vec!["https://example.com/img.jpg".to_string()];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::Urls(urls.clone())),
       ..base_fal_request()
     };
@@ -136,7 +138,7 @@ mod tests {
   #[ignore] // manually run — fires a real fal API request and incurs cost
   async fn test_text_to_image_gpt_image_1_fal() {
     let client = get_fal_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       image_batch_count: Some(1),
       prompt: Some("a horse walking through a cyberpunk city at night".to_string()),
@@ -158,7 +160,7 @@ mod tests {
     let urls = vec![
       TREX_SKELETON_IMAGE_URL.to_string(),
     ];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::Urls(urls.clone())),
       aspect_ratio: Some(CommonAspectRatio::Square),
       image_batch_count: Some(1),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_gpt_image_1p5.rs

@@ -67,6 +67,8 @@ pub async fn execute_fal_gpt_image_1p5(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_gpt_image_2.rs

@@ -64,6 +64,8 @@ pub async fn execute_fal_gpt_image_2(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }
@@ -76,7 +78,7 @@ mod tests {
   use crate::api::image_list_ref::ImageListRef;
   use crate::api::provider::Provider;
   use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::get_fal_client;
 
@@ -87,7 +89,7 @@ mod tests {
 
     #[test]
     fn text_to_image_plan() {
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(CommonAspectRatio::Square),
         image_batch_count: Some(1),
         ..base_request()
@@ -105,7 +107,7 @@ mod tests {
         JUNO_AT_LAKE_IMAGE_URL.to_string(),
         GHOST_IMAGE_URL.to_string(),
       ];
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         prompt: Some("dog running from a scary ghost".to_string()),
         image_inputs: Some(ImageListRef::Urls(urls.clone())),
         ..base_request()
@@ -127,7 +129,7 @@ mod tests {
     #[ignore] // manually run — fires a real fal API request and incurs cost
     async fn text_to_image() {
       let client = get_fal_client();
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
         image_batch_count: Some(1),
         prompt: Some("a horse walking through a cyberpunk city at night".to_string()),
@@ -147,7 +149,7 @@ mod tests {
     #[ignore] // manually run — fires a real fal API request and incurs cost
     async fn edit_image() {
       let client = get_fal_client();
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         prompt: Some("dog running from a scary ghost".to_string()),
         image_inputs: Some(ImageListRef::Urls(vec![
           JUNO_AT_LAKE_IMAGE_URL.to_string(),
@@ -170,8 +172,8 @@ mod tests {
 
   // ── Helpers ──
 
-  fn base_request() -> GenerateImageRequest {
-    GenerateImageRequest {
+  fn base_request() -> GenerateImageRequestBuilder {
+    GenerateImageRequestBuilder {
       model: CommonImageModel::GptImage2,
       provider: Provider::Fal,
       prompt: Some("a cat in space".to_string()),

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_nano_banana.rs

@@ -63,6 +63,8 @@ pub async fn execute_fal_nano_banana(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_nano_banana_2.rs

@@ -67,6 +67,8 @@ pub async fn execute_fal_nano_banana_2(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_nano_banana_pro.rs

@@ -66,6 +66,8 @@ pub async fn execute_fal_nano_banana_pro(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }
@@ -109,7 +111,7 @@ mod tests {
   use crate::api::common_aspect_ratio::CommonAspectRatio;
   use crate::api::common_resolution::CommonResolution;
   use crate::api::image_list_ref::ImageListRef;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
   use crate::test_helpers::{base_fal_image_request, get_fal_client};
   use test_data::web::image_urls::{GHOST_IMAGE_URL, TREX_SKELETON_IMAGE_URL};
@@ -118,7 +120,7 @@ mod tests {
   #[ignore] // manually run — fires a real Fal API request
   async fn test_text_to_image_fal_nano_banana_pro() {
     let client = get_fal_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::WideSixteenByNine),
       resolution: Some(CommonResolution::TwoK),
       quality: None,
@@ -143,7 +145,7 @@ mod tests {
   #[ignore] // manually run — fires a real Fal API request
   async fn test_text_to_image_fal_nano_banana_pro_batch_four() {
     let client = get_fal_client();
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       resolution: Some(CommonResolution::OneK),
       quality: None,
@@ -174,7 +176,7 @@ mod tests {
       TREX_SKELETON_IMAGE_URL.to_string(),
     ];
 
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       prompt: Some("Add the ghost from the first image hovering above the T-Rex skeleton in the second image, make it look spooky but friendly".to_string()),
       image_inputs: Some(ImageListRef::Urls(image_urls.clone())),
       aspect_ratio: Some(CommonAspectRatio::Auto), // edit mode: preserve source dimensions

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_seedream_4.rs

@@ -61,6 +61,8 @@ pub async fn execute_fal_seedream_4(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_seedream_4p5.rs

@@ -61,6 +61,8 @@ pub async fn execute_fal_seedream_4p5(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/execute/fal/generate_image_fal_seedream_5_lite.rs

@@ -61,6 +61,8 @@ pub async fn execute_fal_seedream_5_lite(
   Ok(GenerateImageResponse::Fal(FalImageResponsePayload {
     request_id: webhook_response.request_id,
     gateway_request_id: webhook_response.gateway_request_id,
+    maybe_status_url: None,
+    maybe_response_url: None,
     maybe_outbound_request: Some(outbound_request),
   }))
 }

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

@@ -9,6 +9,11 @@ use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigati
 use crate::errors::artcraft_router_error::ArtcraftRouterError;
 use crate::errors::client_error::ClientError;
 use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
+use crate::generate::generate_image_v2::image_generation_draft_or_request::ImageGenerationDraftOrRequest;
+use crate::generate::generate_image_v2::providers::fal::flux_1_dev::build::build_fal_flux_1_dev;
+use crate::generate::generate_image_v2::providers::fal::flux_1_schnell::build::build_fal_flux_1_schnell;
+use crate::generate::generate_image_v2::providers::fal::nano_banana_2::build::build_fal_nano_banana_2;
+use crate::generate::generate_image_v2::providers::fal::nano_banana_pro::build::build_fal_nano_banana_pro;
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_flux_1_dev::plan_generate_image_artcraft_flux_1_dev;
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_flux_1_schnell::plan_generate_image_artcraft_flux_1_schnell;
 use crate::generate::generate_image::plan::artcraft::plan_generate_image_artcraft_flux_2_lora_angles::plan_generate_image_artcraft_flux_2_lora_angles;
@@ -39,7 +44,7 @@ use crate::generate::generate_image::plan::fal::plan_generate_image_fal_nano_ban
 use crate::generate::generate_image::plan::fal::plan_generate_image_fal_nano_banana_pro::plan_generate_image_fal_nano_banana_pro;
 
 #[derive(Clone, Debug)]
-pub struct GenerateImageRequest {
+pub struct GenerateImageRequestBuilder {
   /// Which model to use.
   pub model: CommonImageModel,
 
@@ -88,7 +93,28 @@ pub struct GenerateImageRequest {
   pub idempotency_token: Option<String>,
 }
 
-impl GenerateImageRequest {
+impl GenerateImageRequestBuilder {
+
+  pub fn use_new_builder(&self) -> bool {
+    match (self.provider, self.model) {
+      (Provider::Fal, CommonImageModel::Flux1Dev) => true,
+      (Provider::Fal, CommonImageModel::Flux1Schnell) => true,
+      (Provider::Fal, CommonImageModel::NanoBanana2) => true,
+      (Provider::Fal, CommonImageModel::NanoBananaPro) => true,
+      _ => false,
+    }
+  }
+
+  pub fn build2(self) -> Result<ImageGenerationDraftOrRequest, ArtcraftRouterError> {
+    match (self.provider, self.model) {
+      (Provider::Fal, CommonImageModel::Flux1Dev) => build_fal_flux_1_dev(self),
+      (Provider::Fal, CommonImageModel::Flux1Schnell) => build_fal_flux_1_schnell(self),
+      (Provider::Fal, CommonImageModel::NanoBanana2) => build_fal_nano_banana_2(self),
+      (Provider::Fal, CommonImageModel::NanoBananaPro) => build_fal_nano_banana_pro(self),
+      _ => self.unsupported_provider_and_model(),
+    }
+  }
+
   /// Read the image generation request, construct a plan, then yield a means to execute it.
   pub fn build(&self) -> Result<ImageGenerationPlan, ArtcraftRouterError> {
     match self.provider {
@@ -149,6 +175,12 @@ impl GenerateImageRequest {
     ))
   }
 
+  fn unsupported_provider_and_model(&self) -> Result<ImageGenerationDraftOrRequest, ArtcraftRouterError> {
+    Err(ArtcraftRouterError::UnsupportedProviderAndModelForNewApi(
+      format!("Image generation for model `{:?}` is not supported for provider {:?} using the new API", self.model, self.provider)
+    ))
+  }
+
   pub fn get_or_generate_idempotency_token(&self) -> String {
     self.idempotency_token.clone()
         .unwrap_or_else(|| uuid::Uuid::new_v4().to_string())

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

@@ -13,6 +13,12 @@ pub struct FalImageResponsePayload {
   pub request_id: Option<String>,
   pub gateway_request_id: Option<String>,
 
+  /// The queue status URL (for polling job progress).
+  pub maybe_status_url: Option<String>,
+
+  /// The queue response URL (for fetching completed results).
+  pub maybe_response_url: Option<String>,
+
   /// The outbound request that was sent to Fal.
   /// Stored as a trait object so any Request type can be captured.
   /// Use `format!("{:?}", ...)` or `format!("{:#?}", ...)` to print.

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

@@ -1,6 +1,6 @@
 pub mod cost;
 pub mod execute;
-pub mod generate_image_request;
+pub mod generate_image_request_builder;
 pub mod generate_image_response;
 pub mod image_generation_cost_estimate;
 pub mod image_generation_plan;

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/plan/artcraft/plan_generate_image_artcraft_flux_1_dev.rs

@@ -3,7 +3,7 @@ use crate::client::generation_mode_mismatch_strategy::GenerationModeMismatchStra
 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::GenerateImageRequest;
+use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
 use artcraft_api_defs::generate::image::text::generate_flux_1_dev_text_to_image::{
   GenerateFlux1DevTextToImageAspectRatio, GenerateFlux1DevTextToImageNumImages,
@@ -18,7 +18,7 @@ pub struct PlanArtcraftFlux1Dev {
 }
 
 pub fn plan_generate_image_artcraft_flux_1_dev(
-  request: &GenerateImageRequest,
+  request: &GenerateImageRequestBuilder,
 ) -> Result<ImageGenerationPlan, ArtcraftRouterError> {
   // Flux 1 Dev is text-to-image only. Abort if image inputs are provided and
   // the caller has opted into strict mode.
@@ -134,7 +134,7 @@ mod tests {
   use crate::client::generation_mode_mismatch_strategy::GenerationModeMismatchStrategy;
   use crate::errors::artcraft_router_error::ArtcraftRouterError;
   use crate::errors::client_error::ClientError;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::test_helpers::base_flux_1_dev_image_request;
   use artcraft_api_defs::generate::image::text::generate_flux_1_dev_text_to_image::{
     GenerateFlux1DevTextToImageAspectRatio as FlAr,
@@ -146,7 +146,7 @@ mod tests {
   #[test]
   fn image_inputs_with_abort_returns_error() {
     let tokens = vec![];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       generation_mode_mismatch_strategy: Some(GenerationModeMismatchStrategy::AbortGeneration),
       ..base_flux_1_dev_image_request()
@@ -161,7 +161,7 @@ mod tests {
   #[test]
   fn image_inputs_with_generate_anyway_succeeds() {
     let tokens = vec![];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       generation_mode_mismatch_strategy: Some(GenerationModeMismatchStrategy::GenerateAnyway),
       ..base_flux_1_dev_image_request()
@@ -172,7 +172,7 @@ mod tests {
   #[test]
   fn image_inputs_with_none_strategy_succeeds() {
     let tokens = vec![];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       generation_mode_mismatch_strategy: None,
       ..base_flux_1_dev_image_request()
@@ -184,7 +184,7 @@ mod tests {
 
   #[test]
   fn aspect_ratio_none_is_none() {
-    let request = GenerateImageRequest { aspect_ratio: None, ..base_flux_1_dev_image_request() };
+    let request = GenerateImageRequestBuilder { aspect_ratio: None, ..base_flux_1_dev_image_request() };
     let ImageGenerationPlan::ArtcraftFlux1Dev(plan) = request.build().unwrap() else { panic!("expected ArtcraftFlux1Dev") };
     assert!(plan.aspect_ratio.is_none());
   }
@@ -192,7 +192,7 @@ mod tests {
   #[test]
   fn aspect_ratio_auto_falls_back_to_square() {
     for ar in [CommonAspectRatio::Auto, CommonAspectRatio::Auto2k, CommonAspectRatio::Auto4k] {
-      let request = GenerateImageRequest { aspect_ratio: Some(ar), ..base_flux_1_dev_image_request() };
+      let request = GenerateImageRequestBuilder { aspect_ratio: Some(ar), ..base_flux_1_dev_image_request() };
       let ImageGenerationPlan::ArtcraftFlux1Dev(plan) = request.build().unwrap() else { panic!("expected ArtcraftFlux1Dev") };
       assert!(matches!(plan.aspect_ratio, Some(FlAr::Square)), "expected Square for {:?}", ar);
     }
@@ -216,7 +216,7 @@ mod tests {
       (CommonAspectRatio::TallNineByTwentyOne, FlAr::PortraitNineBySixteen),
     ];
     for (common, expected) in cases {
-      let request = GenerateImageRequest { aspect_ratio: Some(common), ..base_flux_1_dev_image_request() };
+      let request = GenerateImageRequestBuilder { aspect_ratio: Some(common), ..base_flux_1_dev_image_request() };
       let ImageGenerationPlan::ArtcraftFlux1Dev(plan) = request.build().unwrap() else { panic!("expected ArtcraftFlux1Dev") };
       assert!(
         matches!(plan.aspect_ratio, Some(ar) if std::mem::discriminant(&ar) == std::mem::discriminant(&expected)),
@@ -227,7 +227,7 @@ mod tests {
 
   #[test]
   fn aspect_ratio_unsupported_error_out() {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::TallFourByFive),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       ..base_flux_1_dev_image_request()
@@ -245,7 +245,7 @@ mod tests {
       RequestMismatchMitigationStrategy::PayMoreUpgrade,
       RequestMismatchMitigationStrategy::PayLessDowngrade,
     ] {
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(CommonAspectRatio::TallFourByFive),
         request_mismatch_mitigation_strategy: strategy,
         ..base_flux_1_dev_image_request()
@@ -267,7 +267,7 @@ mod tests {
       RequestMismatchMitigationStrategy::PayMoreUpgrade,
       RequestMismatchMitigationStrategy::PayLessDowngrade,
     ] {
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         quality: None,
         image_batch_count: Some(0),
         request_mismatch_mitigation_strategy: strategy,
@@ -284,7 +284,7 @@ mod tests {
   fn num_images_direct_mapping() {
     let cases = [(1, FlN::One), (2, FlN::Two), (3, FlN::Three), (4, FlN::Four)];
     for (count, expected) in cases {
-      let request = GenerateImageRequest { image_batch_count: Some(count), ..base_flux_1_dev_image_request() };
+      let request = GenerateImageRequestBuilder { image_batch_count: Some(count), ..base_flux_1_dev_image_request() };
       let ImageGenerationPlan::ArtcraftFlux1Dev(plan) = request.build().unwrap() else { panic!("expected ArtcraftFlux1Dev") };
       assert!(
         std::mem::discriminant(&plan.num_images) == std::mem::discriminant(&expected),
@@ -295,7 +295,7 @@ mod tests {
 
   #[test]
   fn num_images_out_of_range_error_out() {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       quality: None,
       image_batch_count: Some(5),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
@@ -313,7 +313,7 @@ mod tests {
       RequestMismatchMitigationStrategy::PayMoreUpgrade,
       RequestMismatchMitigationStrategy::PayLessDowngrade,
     ] {
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         quality: None,
         image_batch_count: Some(5),
         request_mismatch_mitigation_strategy: strategy,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/plan/artcraft/plan_generate_image_artcraft_flux_1_schnell.rs

@@ -3,7 +3,7 @@ use crate::client::generation_mode_mismatch_strategy::GenerationModeMismatchStra
 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::GenerateImageRequest;
+use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
 use artcraft_api_defs::generate::image::text::generate_flux_1_schnell_text_to_image::{
   GenerateFlux1SchnellTextToImageAspectRatio, GenerateFlux1SchnellTextToImageNumImages,
@@ -18,7 +18,7 @@ pub struct PlanArtcraftFlux1Schnell {
 }
 
 pub fn plan_generate_image_artcraft_flux_1_schnell(
-  request: &GenerateImageRequest,
+  request: &GenerateImageRequestBuilder,
 ) -> Result<ImageGenerationPlan, ArtcraftRouterError> {
   // Flux 1 Schnell is text-to-image only. Abort if image inputs are provided and
   // the caller has opted into strict mode.
@@ -134,7 +134,7 @@ mod tests {
   use crate::client::generation_mode_mismatch_strategy::GenerationModeMismatchStrategy;
   use crate::errors::artcraft_router_error::ArtcraftRouterError;
   use crate::errors::client_error::ClientError;
-  use crate::generate::generate_image::generate_image_request::GenerateImageRequest;
+  use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
   use crate::test_helpers::base_flux_1_schnell_image_request;
   use artcraft_api_defs::generate::image::text::generate_flux_1_schnell_text_to_image::{
     GenerateFlux1SchnellTextToImageAspectRatio as FlAr,
@@ -146,7 +146,7 @@ mod tests {
   #[test]
   fn image_inputs_with_abort_returns_error() {
     let tokens = vec![];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       generation_mode_mismatch_strategy: Some(GenerationModeMismatchStrategy::AbortGeneration),
       ..base_flux_1_schnell_image_request()
@@ -161,7 +161,7 @@ mod tests {
   #[test]
   fn image_inputs_with_generate_anyway_succeeds() {
     let tokens = vec![];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       generation_mode_mismatch_strategy: Some(GenerationModeMismatchStrategy::GenerateAnyway),
       ..base_flux_1_schnell_image_request()
@@ -172,7 +172,7 @@ mod tests {
   #[test]
   fn image_inputs_with_none_strategy_succeeds() {
     let tokens = vec![];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       generation_mode_mismatch_strategy: None,
       ..base_flux_1_schnell_image_request()
@@ -184,7 +184,7 @@ mod tests {
 
   #[test]
   fn aspect_ratio_none_is_none() {
-    let request = GenerateImageRequest { aspect_ratio: None, ..base_flux_1_schnell_image_request() };
+    let request = GenerateImageRequestBuilder { aspect_ratio: None, ..base_flux_1_schnell_image_request() };
     let ImageGenerationPlan::ArtcraftFlux1Schnell(plan) = request.build().unwrap() else { panic!("expected ArtcraftFlux1Schnell") };
     assert!(plan.aspect_ratio.is_none());
   }
@@ -192,7 +192,7 @@ mod tests {
   #[test]
   fn aspect_ratio_auto_falls_back_to_square() {
     for ar in [CommonAspectRatio::Auto, CommonAspectRatio::Auto2k, CommonAspectRatio::Auto4k] {
-      let request = GenerateImageRequest { aspect_ratio: Some(ar), ..base_flux_1_schnell_image_request() };
+      let request = GenerateImageRequestBuilder { aspect_ratio: Some(ar), ..base_flux_1_schnell_image_request() };
       let ImageGenerationPlan::ArtcraftFlux1Schnell(plan) = request.build().unwrap() else { panic!("expected ArtcraftFlux1Schnell") };
       assert!(matches!(plan.aspect_ratio, Some(FlAr::Square)), "expected Square for {:?}", ar);
     }
@@ -216,7 +216,7 @@ mod tests {
       (CommonAspectRatio::TallNineByTwentyOne, FlAr::PortraitNineBySixteen),
     ];
     for (common, expected) in cases {
-      let request = GenerateImageRequest { aspect_ratio: Some(common), ..base_flux_1_schnell_image_request() };
+      let request = GenerateImageRequestBuilder { aspect_ratio: Some(common), ..base_flux_1_schnell_image_request() };
       let ImageGenerationPlan::ArtcraftFlux1Schnell(plan) = request.build().unwrap() else { panic!("expected ArtcraftFlux1Schnell") };
       assert!(
         matches!(plan.aspect_ratio, Some(ar) if std::mem::discriminant(&ar) == std::mem::discriminant(&expected)),
@@ -227,7 +227,7 @@ mod tests {
 
   #[test]
   fn aspect_ratio_unsupported_error_out() {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::TallFourByFive),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
       ..base_flux_1_schnell_image_request()
@@ -244,7 +244,7 @@ mod tests {
       RequestMismatchMitigationStrategy::PayMoreUpgrade,
       RequestMismatchMitigationStrategy::PayLessDowngrade,
     ] {
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         aspect_ratio: Some(CommonAspectRatio::TallFourByFive),
         request_mismatch_mitigation_strategy: strategy,
         ..base_flux_1_schnell_image_request()
@@ -263,7 +263,7 @@ mod tests {
       RequestMismatchMitigationStrategy::PayMoreUpgrade,
       RequestMismatchMitigationStrategy::PayLessDowngrade,
     ] {
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         quality: None,
         image_batch_count: Some(0),
         request_mismatch_mitigation_strategy: strategy,
@@ -280,7 +280,7 @@ mod tests {
   fn num_images_direct_mapping() {
     let cases = [(1, FlN::One), (2, FlN::Two), (3, FlN::Three), (4, FlN::Four)];
     for (count, expected) in cases {
-      let request = GenerateImageRequest { image_batch_count: Some(count), ..base_flux_1_schnell_image_request() };
+      let request = GenerateImageRequestBuilder { image_batch_count: Some(count), ..base_flux_1_schnell_image_request() };
       let ImageGenerationPlan::ArtcraftFlux1Schnell(plan) = request.build().unwrap() else { panic!("expected ArtcraftFlux1Schnell") };
       assert!(
         std::mem::discriminant(&plan.num_images) == std::mem::discriminant(&expected),
@@ -291,7 +291,7 @@ mod tests {
 
   #[test]
   fn num_images_out_of_range_error_out() {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       quality: None,
       image_batch_count: Some(5),
       request_mismatch_mitigation_strategy: RequestMismatchMitigationStrategy::ErrorOut,
@@ -309,7 +309,7 @@ mod tests {
       RequestMismatchMitigationStrategy::PayMoreUpgrade,
       RequestMismatchMitigationStrategy::PayLessDowngrade,
     ] {
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         quality: None,
         image_batch_count: Some(5),
         request_mismatch_mitigation_strategy: strategy,

crates/api_clients/artcraft/artcraft_router/src/generate/generate_image/plan/artcraft/plan_generate_image_artcraft_flux_2_lora_angles.rs

@@ -3,7 +3,7 @@ use crate::api::image_list_ref::ImageListRef;
 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::GenerateImageRequest;
+use crate::generate::generate_image::generate_image_request_builder::GenerateImageRequestBuilder;
 use crate::generate::generate_image::image_generation_plan::ImageGenerationPlan;
 use artcraft_api_defs::generate::image::angle::flux_2_lora_edit_image_angle::{
   Flux2LoraEditImageAngleImageSize,
@@ -23,7 +23,7 @@ pub struct PlanArtcraftFlux2LoraAngles {
 }
 
 pub fn plan_generate_image_artcraft_flux_2_lora_angles(
-  request: &GenerateImageRequest,
+  request: &GenerateImageRequestBuilder,
 ) -> Result<ImageGenerationPlan, ArtcraftRouterError> {
   let strategy = request.request_mismatch_mitigation_strategy;
 
@@ -153,7 +153,7 @@ mod tests {
 
   #[test]
   fn requires_image_input() {
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: None,
       ..base_flux_2_lora_angles_image_request()
     };
@@ -164,7 +164,7 @@ mod tests {
   #[test]
   fn rejects_urls() {
     let urls = vec!["https://example.com/img.png".to_string()];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::Urls(urls.clone())),
       ..base_flux_2_lora_angles_image_request()
     };
@@ -175,7 +175,7 @@ mod tests {
   #[test]
   fn accepts_single_media_token() {
     let tokens = vec![make_token()];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       ..base_flux_2_lora_angles_image_request()
     };
@@ -186,7 +186,7 @@ mod tests {
   #[test]
   fn rejects_multiple_media_tokens() {
     let tokens = vec![make_token(), make_token()];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       ..base_flux_2_lora_angles_image_request()
     };
@@ -197,7 +197,7 @@ mod tests {
   #[test]
   fn image_size_none_is_none() {
     let tokens = vec![make_token()];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: None,
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       ..base_flux_2_lora_angles_image_request()
@@ -209,7 +209,7 @@ mod tests {
   #[test]
   fn image_size_square_maps_directly() {
     let tokens = vec![make_token()];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       aspect_ratio: Some(CommonAspectRatio::Square),
       image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
       ..base_flux_2_lora_angles_image_request()
@@ -223,7 +223,7 @@ mod tests {
     let tokens = vec![make_token()];
     let cases = [(1, N::One), (2, N::Two), (3, N::Three), (4, N::Four)];
     for (count, expected) in cases {
-      let request = GenerateImageRequest {
+      let request = GenerateImageRequestBuilder {
         quality: None,
         image_batch_count: Some(count),
         image_inputs: Some(ImageListRef::MediaFileTokens(tokens.clone())),
@@ -240,7 +240,7 @@ mod tests {
   #[test]
   fn angle_fields_are_passed_through() {
     let tokens = vec![make_token()];
-    let request = GenerateImageRequest {
+    let request = GenerateImageRequestBuilder {
       horizontal_angle: Some(45.0),
       vertical_angle: Some(-30.0),
       zoom: Some(1.5),