diff --git a/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/api.rs b/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/api.rs new file mode 100644 index 0000000000..0834146607 --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/api.rs @@ -0,0 +1,139 @@ +use crate::error::fal_error_plus::FalErrorPlus; +use crate::requests::api::video::image::minimax_h3::raw_request::{ + MinimaxH3ImageToVideoInput, MinimaxH3ImageToVideoOutput, +}; +use crate::requests::api::video::text::minimax_h3::api::MinimaxH3Resolution; +use crate::requests::traits::fal_endpoint_trait::FalEndpoint; + +#[derive(Clone, Debug)] +pub struct MinimaxH3ImageToVideoRequest { + /// Text prompt (1 to 7000 characters). + pub prompt: String, + + /// URL of the image to use as the first frame. The output aspect ratio + /// follows this image. + pub image_url: String, + + /// Optional URL of the image to use as the last frame, for first-to-last + /// keyframe generation. + pub end_image_url: Option, + + /// Duration in seconds. Valid range 5–15; fal's default is `5` when `None`. + pub duration: Option, + + /// Output resolution. fal's default is `2K` when `None`. + pub resolution: Option, +} + +impl FalEndpoint for MinimaxH3ImageToVideoRequest { + const ENDPOINT: &str = "minimax/h3/image-to-video"; + + type RawRequest = MinimaxH3ImageToVideoInput; + type RawResponse = MinimaxH3ImageToVideoOutput; + + fn to_raw_request(&self) -> Result { + Ok(Self::RawRequest { + prompt: self.prompt.clone(), + image_url: self.image_url.clone(), + end_image_url: self.end_image_url.clone(), + duration: self.duration, + resolution: self.resolution.map(|r| r.to_str().to_string()), + }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::creds::fal_api_key::FalApiKey; + use crate::requests::traits::fal_endpoint_trait::FalEndpoint; + use errors::AnyhowResult; + use std::fs::read_to_string; + + const EXAMPLE_IMAGE_URL: &str = + "https://storage.googleapis.com/falserverless/example_inputs/hailuo23/pro_i2v_in.jpg"; + + // ── Real requests (manually run; require a live key and cost money) ── + + #[tokio::test] + #[ignore] // manually run — fires a real API request and incurs cost + async fn test_image_to_video_webhook() -> AnyhowResult<()> { + let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?; + let api_key = FalApiKey::from_str(&secret); + + let request = MinimaxH3ImageToVideoRequest { + prompt: "the camera slowly pulls back, revealing the full landscape".to_string(), + image_url: EXAMPLE_IMAGE_URL.to_string(), + end_image_url: None, + duration: Some(5), + resolution: Some(MinimaxH3Resolution::SevenSixtyEightP), + }; + + let result = request.send_webhook_request(&api_key, "https://example.com/webhook").await?; + println!("Webhook result: {:?}", result); + assert!(result.request_id.is_some() || result.gateway_request_id.is_some()); + Ok(()) + } + + #[tokio::test] + #[ignore] // manually run — fires a real API request and incurs cost + async fn test_image_to_video_queue() -> AnyhowResult<()> { + let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?; + let api_key = FalApiKey::from_str(&secret); + + let request = MinimaxH3ImageToVideoRequest { + prompt: "gentle wind moves through the scene as clouds drift overhead".to_string(), + image_url: EXAMPLE_IMAGE_URL.to_string(), + end_image_url: None, + duration: Some(5), + resolution: Some(MinimaxH3Resolution::SevenSixtyEightP), + }; + + let result = request.send_queue_request(&api_key).await?; + println!("Queue result — request_id: {}", result.request_id); + assert!(!result.request_id.is_empty()); + Ok(()) + } + + // ── Wire-shape sanity (no API calls) ── + + #[test] + fn raw_request_maps_all_fields() { + let request = MinimaxH3ImageToVideoRequest { + prompt: "p".to_string(), + image_url: "https://example.com/first.png".to_string(), + end_image_url: Some("https://example.com/last.png".to_string()), + duration: Some(12), + resolution: Some(MinimaxH3Resolution::TwoK), + }; + let raw = request.to_raw_request().unwrap(); + assert_eq!(raw.prompt, "p"); + assert_eq!(raw.image_url, "https://example.com/first.png"); + assert_eq!(raw.end_image_url.as_deref(), Some("https://example.com/last.png")); + assert_eq!(raw.duration, Some(12)); + assert_eq!(raw.resolution.as_deref(), Some("2K")); + } + + #[test] + fn raw_request_omits_unset_optionals() { + let request = MinimaxH3ImageToVideoRequest { + prompt: "minimal".to_string(), + image_url: "https://example.com/first.png".to_string(), + end_image_url: None, + duration: None, + resolution: None, + }; + let json = serde_json::to_value(request.to_raw_request().unwrap()).unwrap(); + assert_eq!(json, serde_json::json!({ + "prompt": "minimal", + "image_url": "https://example.com/first.png", + })); + } + + #[test] + fn endpoint_path_is_canonical() { + assert_eq!(MinimaxH3ImageToVideoRequest::ENDPOINT, "minimax/h3/image-to-video"); + } + + // NB: Pricing tests are in cost.rs +} diff --git a/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/cost.rs b/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/cost.rs new file mode 100644 index 0000000000..dff1dca483 --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/cost.rs @@ -0,0 +1,78 @@ +use crate::requests::api::video::image::minimax_h3::api::MinimaxH3ImageToVideoRequest; +use crate::requests::api::video::text::minimax_h3::api::MinimaxH3Resolution; +use crate::requests::api::video::text::minimax_h3::cost::{ + minimax_h3_rate_cents_per_sec, minimax_h3_video_cost_cents, +}; +use crate::requests::traits::fal_request_cost_calculator_trait::{FalRequestCostCalculator, UsdCents}; + +// Image-to-video shares the MiniMax H3 per-second pricing (see the text module +// for the canonical rate table): +// 768P: $0.16/sec +// 2K: $0.26/sec +// Pricing depends on resolution and duration only (start/end frames are free). + +impl FalRequestCostCalculator for MinimaxH3ImageToVideoRequest { + fn calculate_cost_in_cents(&self) -> UsdCents { + // fal defaults when unset: duration = 5s, resolution = 2K. + let duration_secs = u64::from(self.duration.unwrap_or(5)); + let is_2k = self.resolution + .unwrap_or(MinimaxH3Resolution::TwoK) + .is_2k(); + + let rate = minimax_h3_rate_cents_per_sec(is_2k); + minimax_h3_video_cost_cents(rate, duration_secs) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn make_request( + duration: Option, + resolution: Option, + ) -> MinimaxH3ImageToVideoRequest { + MinimaxH3ImageToVideoRequest { + prompt: "test".to_string(), + image_url: "https://example.com/first.png".to_string(), + end_image_url: None, + duration, + resolution, + } + } + + mod cost_table { + use super::*; + + // (duration, resolution, expected_cents) + const COST_TABLE: &[(Option, Option, u64)] = &[ + // 768P → $0.16/s + (Some(5), Some(MinimaxH3Resolution::SevenSixtyEightP), 80), + (Some(15), Some(MinimaxH3Resolution::SevenSixtyEightP), 240), + // 2K → $0.26/s + (Some(5), Some(MinimaxH3Resolution::TwoK), 130), + (Some(15), Some(MinimaxH3Resolution::TwoK), 390), + // Defaults: duration=None→5s, resolution=None→2K + (None, None, 130), + ]; + + #[test] + fn matches_cost_table() { + for &(duration, resolution, expected) in COST_TABLE { + let got = make_request(duration, resolution).calculate_cost_in_cents(); + assert_eq!(got, expected, "duration={duration:?} resolution={resolution:?}"); + } + } + + /// The end frame does not affect the bill (only resolution + duration do). + #[test] + fn cost_ignores_end_image() { + let without = make_request(Some(8), Some(MinimaxH3Resolution::TwoK)).calculate_cost_in_cents(); + let with = MinimaxH3ImageToVideoRequest { + end_image_url: Some("https://example.com/last.png".to_string()), + ..make_request(Some(8), Some(MinimaxH3Resolution::TwoK)) + }.calculate_cost_in_cents(); + assert_eq!(with, without); + } + } +} diff --git a/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/mod.rs b/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/mod.rs new file mode 100644 index 0000000000..3bfb6c86db --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/mod.rs @@ -0,0 +1,3 @@ +pub mod api; +pub mod cost; +pub mod raw_request; diff --git a/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/raw_request.rs b/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/raw_request.rs new file mode 100644 index 0000000000..7772259df9 --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/image/minimax_h3/raw_request.rs @@ -0,0 +1,37 @@ +use serde::{Deserialize, Serialize}; + +/// Over-the-wire input shape for `minimax/h3/image-to-video`. +/// fal's schema: +#[derive(Debug, Serialize, Deserialize, Default)] +pub struct MinimaxH3ImageToVideoInput { + /// Text prompt (1 to 7000 characters). + pub prompt: String, + + /// URL of the image to use as the first frame. The output aspect ratio + /// follows this image. + pub image_url: String, + + /// Optional URL of the image to use as the last frame, for first-to-last + /// keyframe generation. + #[serde(skip_serializing_if = "Option::is_none")] + pub end_image_url: Option, + + /// Duration in seconds. Range 5–15. fal default: 5. + #[serde(skip_serializing_if = "Option::is_none")] + pub duration: Option, + + /// Output resolution. + /// Possible values: "768P", "2K". fal default: "2K". + #[serde(skip_serializing_if = "Option::is_none")] + pub resolution: Option, +} + +#[derive(Debug, Serialize, Deserialize)] +pub struct MinimaxH3ImageToVideoVideoFile { + pub url: String, +} + +#[derive(Debug, Serialize, Deserialize)] +pub struct MinimaxH3ImageToVideoOutput { + pub video: MinimaxH3ImageToVideoVideoFile, +} diff --git a/crates/api_clients/fal_client/src/requests/api/video/image/mod.rs b/crates/api_clients/fal_client/src/requests/api/video/image/mod.rs index b41bd9b17f..e869d88a37 100644 --- a/crates/api_clients/fal_client/src/requests/api/video/image/mod.rs +++ b/crates/api_clients/fal_client/src/requests/api/video/image/mod.rs @@ -2,6 +2,7 @@ pub mod kling_1p6_pro_image_to_video; pub mod kling_2p5_turbo_pro_image_to_video; pub mod kling_2p6_pro_image_to_video; pub mod kling_3p0_standard_image_to_video; +pub mod minimax_h3; pub mod veo_2; pub mod veo_3; pub mod veo_3_fast; diff --git a/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/api.rs b/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/api.rs new file mode 100644 index 0000000000..6766db26dc --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/api.rs @@ -0,0 +1,200 @@ +use crate::error::fal_error_plus::FalErrorPlus; +use crate::requests::api::video::reference::minimax_h3::raw_request::{ + MinimaxH3ReferenceToVideoInput, MinimaxH3ReferenceToVideoOutput, +}; +use crate::requests::api::video::text::minimax_h3::api::MinimaxH3Resolution; +use crate::requests::traits::fal_endpoint_trait::FalEndpoint; + +#[derive(Clone, Debug)] +pub struct MinimaxH3ReferenceToVideoRequest { + /// Text prompt (1 to 7000 characters). Refer to reference assets by their + /// modality and order in the reference lists: Image 1, Image 2, Video 1, + /// Audio 1, and so on. + pub prompt: String, + + /// URLs of subject/style reference images (at most 9). Reference images, + /// videos, and audio clips must add up to at most 12 files. + pub reference_image_urls: Option>, + + /// URLs of motion/reference video clips (at most 3; 2–15 seconds each, + /// combined duration at most 15 seconds). + pub reference_video_urls: Option>, + + /// URLs of reference audio clips (at most 3; 2–15 seconds each, combined + /// duration at most 15 seconds). Audio cannot be the only reference input. + pub reference_audio_urls: Option>, + + /// Duration in seconds. Valid range 5–15; fal's default is `5` when `None`. + pub duration: Option, + + /// Output resolution. fal's default is `2K` when `None`. + pub resolution: Option, + + /// Aspect ratio. fal's default is `adaptive` when `None`. + pub aspect_ratio: Option, +} + +/// Reference-to-video aspect ratios. Unlike the text modality, `adaptive` +/// (derive the ratio from the reference assets) is supported and is fal's +/// default. +#[derive(Copy, Clone, Debug, Eq, PartialEq)] +pub enum MinimaxH3ReferenceToVideoAspectRatio { + Adaptive, + TwentyOneByNine, + SixteenByNine, + FourByThree, + Square, + ThreeByFour, + NineBySixteen, +} + +impl MinimaxH3ReferenceToVideoAspectRatio { + fn to_str(&self) -> &'static str { + match self { + Self::Adaptive => "adaptive", + Self::TwentyOneByNine => "21:9", + Self::SixteenByNine => "16:9", + Self::FourByThree => "4:3", + Self::Square => "1:1", + Self::ThreeByFour => "3:4", + Self::NineBySixteen => "9:16", + } + } +} + +impl FalEndpoint for MinimaxH3ReferenceToVideoRequest { + const ENDPOINT: &str = "minimax/h3/reference-to-video"; + + type RawRequest = MinimaxH3ReferenceToVideoInput; + type RawResponse = MinimaxH3ReferenceToVideoOutput; + + fn to_raw_request(&self) -> Result { + Ok(Self::RawRequest { + prompt: self.prompt.clone(), + reference_image_urls: self.reference_image_urls.clone(), + reference_video_urls: self.reference_video_urls.clone(), + reference_audio_urls: self.reference_audio_urls.clone(), + duration: self.duration, + resolution: self.resolution.map(|r| r.to_str().to_string()), + aspect_ratio: self.aspect_ratio.map(|ar| ar.to_str().to_string()), + }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::creds::fal_api_key::FalApiKey; + use crate::requests::traits::fal_endpoint_trait::FalEndpoint; + use errors::AnyhowResult; + use std::fs::read_to_string; + + const EXAMPLE_IMAGE_URL: &str = + "https://storage.googleapis.com/falserverless/example_inputs/hailuo23/pro_i2v_in.jpg"; + + // ── Real requests (manually run; require a live key and cost money) ── + + #[tokio::test] + #[ignore] // manually run — fires a real API request and incurs cost + async fn test_reference_to_video_webhook() -> AnyhowResult<()> { + let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?; + let api_key = FalApiKey::from_str(&secret); + + let request = MinimaxH3ReferenceToVideoRequest { + prompt: "Image 1 is the subject. Keep the subject consistent while the camera slowly orbits.".to_string(), + reference_image_urls: Some(vec![EXAMPLE_IMAGE_URL.to_string()]), + reference_video_urls: None, + reference_audio_urls: None, + duration: Some(5), + resolution: Some(MinimaxH3Resolution::SevenSixtyEightP), + aspect_ratio: Some(MinimaxH3ReferenceToVideoAspectRatio::Adaptive), + }; + + let result = request.send_webhook_request(&api_key, "https://example.com/webhook").await?; + println!("Webhook result: {:?}", result); + assert!(result.request_id.is_some() || result.gateway_request_id.is_some()); + Ok(()) + } + + #[tokio::test] + #[ignore] // manually run — fires a real API request and incurs cost + async fn test_reference_to_video_queue() -> AnyhowResult<()> { + let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?; + let api_key = FalApiKey::from_str(&secret); + + let request = MinimaxH3ReferenceToVideoRequest { + prompt: "Image 1 is the subject. The subject walks through a sunlit garden.".to_string(), + reference_image_urls: Some(vec![EXAMPLE_IMAGE_URL.to_string()]), + reference_video_urls: None, + reference_audio_urls: None, + duration: Some(5), + resolution: Some(MinimaxH3Resolution::SevenSixtyEightP), + aspect_ratio: None, + }; + + let result = request.send_queue_request(&api_key).await?; + println!("Queue result — request_id: {}", result.request_id); + assert!(!result.request_id.is_empty()); + Ok(()) + } + + // ── Wire-shape sanity (no API calls) ── + + #[test] + fn raw_request_maps_all_fields() { + let request = MinimaxH3ReferenceToVideoRequest { + prompt: "p".to_string(), + reference_image_urls: Some(vec!["https://example.com/a.png".to_string()]), + reference_video_urls: Some(vec!["https://example.com/b.mp4".to_string()]), + reference_audio_urls: Some(vec!["https://example.com/c.mp3".to_string()]), + duration: Some(12), + resolution: Some(MinimaxH3Resolution::TwoK), + aspect_ratio: Some(MinimaxH3ReferenceToVideoAspectRatio::Adaptive), + }; + let raw = request.to_raw_request().unwrap(); + assert_eq!(raw.prompt, "p"); + assert_eq!(raw.reference_image_urls.as_deref(), Some(&["https://example.com/a.png".to_string()][..])); + assert_eq!(raw.reference_video_urls.as_deref(), Some(&["https://example.com/b.mp4".to_string()][..])); + assert_eq!(raw.reference_audio_urls.as_deref(), Some(&["https://example.com/c.mp3".to_string()][..])); + assert_eq!(raw.duration, Some(12)); + assert_eq!(raw.resolution.as_deref(), Some("2K")); + assert_eq!(raw.aspect_ratio.as_deref(), Some("adaptive")); + } + + #[test] + fn raw_request_omits_unset_optionals() { + let request = MinimaxH3ReferenceToVideoRequest { + prompt: "minimal".to_string(), + reference_image_urls: None, + reference_video_urls: None, + reference_audio_urls: None, + duration: None, + resolution: None, + aspect_ratio: None, + }; + let json = serde_json::to_value(request.to_raw_request().unwrap()).unwrap(); + assert_eq!(json, serde_json::json!({ "prompt": "minimal" })); + } + + #[test] + fn every_aspect_ratio_maps_to_wire_string() { + for (variant, expected) in [ + (MinimaxH3ReferenceToVideoAspectRatio::Adaptive, "adaptive"), + (MinimaxH3ReferenceToVideoAspectRatio::TwentyOneByNine, "21:9"), + (MinimaxH3ReferenceToVideoAspectRatio::SixteenByNine, "16:9"), + (MinimaxH3ReferenceToVideoAspectRatio::FourByThree, "4:3"), + (MinimaxH3ReferenceToVideoAspectRatio::Square, "1:1"), + (MinimaxH3ReferenceToVideoAspectRatio::ThreeByFour, "3:4"), + (MinimaxH3ReferenceToVideoAspectRatio::NineBySixteen, "9:16"), + ] { + assert_eq!(variant.to_str(), expected); + } + } + + #[test] + fn endpoint_path_is_canonical() { + assert_eq!(MinimaxH3ReferenceToVideoRequest::ENDPOINT, "minimax/h3/reference-to-video"); + } + + // NB: Pricing tests are in cost.rs +} diff --git a/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/cost.rs b/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/cost.rs new file mode 100644 index 0000000000..7149c1b620 --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/cost.rs @@ -0,0 +1,127 @@ +use crate::requests::api::video::reference::minimax_h3::api::MinimaxH3ReferenceToVideoRequest; +use crate::requests::api::video::text::minimax_h3::api::MinimaxH3Resolution; +use crate::requests::api::video::text::minimax_h3::cost::{ + minimax_h3_rate_cents_per_sec, minimax_h3_video_cost_cents, +}; +use crate::requests::traits::fal_request_cost_calculator_trait::{FalRequestCostCalculator, UsdCents}; + +// Reference-to-video shares the MiniMax H3 per-second pricing (see the text +// module for the canonical rate table): +// 768P: $0.16/sec +// 2K: $0.26/sec +// On top of that, the first 5 reference images are free and each additional +// image costs $0.08. Reference videos and audio clips are free. +const FREE_REFERENCE_IMAGES: u64 = 5; +const EXTRA_REFERENCE_IMAGE_CENTS: u64 = 8; // $0.08 per image beyond the first 5 + +impl FalRequestCostCalculator for MinimaxH3ReferenceToVideoRequest { + fn calculate_cost_in_cents(&self) -> UsdCents { + // fal defaults when unset: duration = 5s, resolution = 2K. + let duration_secs = u64::from(self.duration.unwrap_or(5)); + let is_2k = self.resolution + .unwrap_or(MinimaxH3Resolution::TwoK) + .is_2k(); + + let rate = minimax_h3_rate_cents_per_sec(is_2k); + let video_cents = minimax_h3_video_cost_cents(rate, duration_secs); + + let image_count = self.reference_image_urls.as_ref().map_or(0, |urls| urls.len() as u64); + let extra_image_cents = image_count.saturating_sub(FREE_REFERENCE_IMAGES) + * EXTRA_REFERENCE_IMAGE_CENTS; + + video_cents + extra_image_cents + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn make_request( + duration: Option, + resolution: Option, + image_count: usize, + ) -> MinimaxH3ReferenceToVideoRequest { + let images = (0..image_count) + .map(|i| format!("https://example.com/ref_{i}.png")) + .collect::>(); + MinimaxH3ReferenceToVideoRequest { + prompt: "test".to_string(), + reference_image_urls: if images.is_empty() { None } else { Some(images) }, + reference_video_urls: None, + reference_audio_urls: None, + duration, + resolution, + aspect_ratio: None, + } + } + + mod cost_table { + use super::*; + + // (duration, resolution, image_count, expected_cents) + // Math: rate × secs + 8¢ × max(0, images − 5), where rate (cents) = 16 + // (768P) or 26 (2K). + const COST_TABLE: &[(Option, Option, usize, u64)] = &[ + // 768P → $0.16/s; up to 5 reference images are free + (Some(5), Some(MinimaxH3Resolution::SevenSixtyEightP), 0, 80), + (Some(5), Some(MinimaxH3Resolution::SevenSixtyEightP), 1, 80), + (Some(5), Some(MinimaxH3Resolution::SevenSixtyEightP), 5, 80), + (Some(15), Some(MinimaxH3Resolution::SevenSixtyEightP), 5, 240), + // 2K → $0.26/s + (Some(5), Some(MinimaxH3Resolution::TwoK), 5, 130), + (Some(15), Some(MinimaxH3Resolution::TwoK), 5, 390), + // Each image beyond the 5th adds 8¢ + (Some(5), Some(MinimaxH3Resolution::SevenSixtyEightP), 6, 88), + (Some(5), Some(MinimaxH3Resolution::SevenSixtyEightP), 9, 112), // 80 + 4×8 + (Some(5), Some(MinimaxH3Resolution::TwoK), 6, 138), + (Some(5), Some(MinimaxH3Resolution::TwoK), 9, 162), // 130 + 4×8 + // Defaults: duration=None→5s, resolution=None→2K + (None, None, 0, 130), + (None, None, 9, 162), + ]; + + #[test] + fn matches_cost_table() { + for &(duration, resolution, image_count, expected) in COST_TABLE { + let got = make_request(duration, resolution, image_count).calculate_cost_in_cents(); + assert_eq!( + got, expected, + "duration={duration:?} resolution={resolution:?} images={image_count}"); + } + } + + #[test] + fn first_five_images_are_free() { + let none = make_request(Some(5), Some(MinimaxH3Resolution::TwoK), 0).calculate_cost_in_cents(); + for image_count in 1..=5 { + let cost = make_request(Some(5), Some(MinimaxH3Resolution::TwoK), image_count).calculate_cost_in_cents(); + assert_eq!(cost, none, "images={image_count} should not change the bill"); + } + } + + #[test] + fn each_extra_image_adds_eight_cents() { + let five = make_request(Some(5), Some(MinimaxH3Resolution::TwoK), 5).calculate_cost_in_cents(); + for (image_count, extra) in [(6, 8), (7, 16), (8, 24), (9, 32)] { + let cost = make_request(Some(5), Some(MinimaxH3Resolution::TwoK), image_count).calculate_cost_in_cents(); + assert_eq!(cost, five + extra, "images={image_count}"); + } + } + + /// Reference videos and audio clips do not affect the bill. + #[test] + fn cost_ignores_reference_videos_and_audio() { + let baseline = make_request(Some(5), Some(MinimaxH3Resolution::TwoK), 2).calculate_cost_in_cents(); + let with_extras = MinimaxH3ReferenceToVideoRequest { + reference_video_urls: Some(vec![ + "https://example.com/a.mp4".to_string(), + "https://example.com/b.mp4".to_string(), + ]), + reference_audio_urls: Some(vec!["https://example.com/a.mp3".to_string()]), + ..make_request(Some(5), Some(MinimaxH3Resolution::TwoK), 2) + }.calculate_cost_in_cents(); + assert_eq!(with_extras, baseline); + } + } +} diff --git a/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/mod.rs b/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/mod.rs new file mode 100644 index 0000000000..3bfb6c86db --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/mod.rs @@ -0,0 +1,3 @@ +pub mod api; +pub mod cost; +pub mod raw_request; diff --git a/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/raw_request.rs b/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/raw_request.rs new file mode 100644 index 0000000000..5c6c9dd9a3 --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/reference/minimax_h3/raw_request.rs @@ -0,0 +1,51 @@ +use serde::{Deserialize, Serialize}; + +/// Over-the-wire input shape for `minimax/h3/reference-to-video`. +/// fal's schema: +#[derive(Debug, Serialize, Deserialize, Default)] +pub struct MinimaxH3ReferenceToVideoInput { + /// Text prompt (1 to 7000 characters). Refer to reference assets by their + /// modality and order in the reference lists: Image 1, Image 2, Video 1, + /// Audio 1, and so on. + pub prompt: String, + + /// URLs of subject/style reference images (at most 9). Reference images, + /// videos, and audio clips must add up to at most 12 files. + #[serde(skip_serializing_if = "Option::is_none")] + pub reference_image_urls: Option>, + + /// URLs of motion/reference video clips (at most 3; 2–15 seconds each, + /// combined duration at most 15 seconds). + #[serde(skip_serializing_if = "Option::is_none")] + pub reference_video_urls: Option>, + + /// URLs of reference audio clips (at most 3; 2–15 seconds each, combined + /// duration at most 15 seconds). Audio cannot be the only reference input. + #[serde(skip_serializing_if = "Option::is_none")] + pub reference_audio_urls: Option>, + + /// Duration in seconds. Range 5–15. fal default: 5. + #[serde(skip_serializing_if = "Option::is_none")] + pub duration: Option, + + /// Output resolution. + /// Possible values: "768P", "2K". fal default: "2K". + #[serde(skip_serializing_if = "Option::is_none")] + pub resolution: Option, + + /// Aspect ratio. + /// Possible values: "adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16". + /// fal default: "adaptive". + #[serde(skip_serializing_if = "Option::is_none")] + pub aspect_ratio: Option, +} + +#[derive(Debug, Serialize, Deserialize)] +pub struct MinimaxH3ReferenceToVideoVideoFile { + pub url: String, +} + +#[derive(Debug, Serialize, Deserialize)] +pub struct MinimaxH3ReferenceToVideoOutput { + pub video: MinimaxH3ReferenceToVideoVideoFile, +} diff --git a/crates/api_clients/fal_client/src/requests/api/video/reference/mod.rs b/crates/api_clients/fal_client/src/requests/api/video/reference/mod.rs index ef70095d19..fb4e8110f8 100644 --- a/crates/api_clients/fal_client/src/requests/api/video/reference/mod.rs +++ b/crates/api_clients/fal_client/src/requests/api/video/reference/mod.rs @@ -1,3 +1,4 @@ +pub mod minimax_h3; pub mod veo_3p1; pub mod veo_3p1_fast; pub mod vidu_q3_reference_to_video; diff --git a/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/api.rs b/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/api.rs new file mode 100644 index 0000000000..cf9e9f3d20 --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/api.rs @@ -0,0 +1,192 @@ +use crate::error::fal_error_plus::FalErrorPlus; +use crate::requests::api::video::text::minimax_h3::raw_request::{ + MinimaxH3TextToVideoInput, MinimaxH3TextToVideoOutput, +}; +use crate::requests::traits::fal_endpoint_trait::FalEndpoint; + +#[derive(Clone, Debug)] +pub struct MinimaxH3TextToVideoRequest { + /// Text prompt (1 to 7000 characters). + pub prompt: String, + + /// Duration in seconds. Valid range 5–15; fal's default is `5` when `None`. + pub duration: Option, + + /// Output resolution. fal's default is `2K` when `None`. + pub resolution: Option, + + /// Aspect ratio. fal's default is `16:9` when `None`. + pub aspect_ratio: Option, +} + +/// MiniMax H3 (Hailuo-03) resolutions. 2K bills at a higher per-second rate +/// than 768P (see the cost module). Shared by the text + image + reference +/// modalities. +#[derive(Copy, Clone, Debug, Eq, PartialEq)] +pub enum MinimaxH3Resolution { + SevenSixtyEightP, + TwoK, +} + +impl MinimaxH3Resolution { + /// 2K is billed at the higher per-second rate. + pub fn is_2k(&self) -> bool { + matches!(self, Self::TwoK) + } + + pub(crate) fn to_str(&self) -> &'static str { + match self { + Self::SevenSixtyEightP => "768P", + Self::TwoK => "2K", + } + } +} + +#[derive(Copy, Clone, Debug, Eq, PartialEq)] +pub enum MinimaxH3TextToVideoAspectRatio { + TwentyOneByNine, + SixteenByNine, + FourByThree, + Square, + ThreeByFour, + NineBySixteen, +} + +impl MinimaxH3TextToVideoAspectRatio { + fn to_str(&self) -> &'static str { + match self { + Self::TwentyOneByNine => "21:9", + Self::SixteenByNine => "16:9", + Self::FourByThree => "4:3", + Self::Square => "1:1", + Self::ThreeByFour => "3:4", + Self::NineBySixteen => "9:16", + } + } +} + +impl FalEndpoint for MinimaxH3TextToVideoRequest { + const ENDPOINT: &str = "minimax/h3/text-to-video"; + + type RawRequest = MinimaxH3TextToVideoInput; + type RawResponse = MinimaxH3TextToVideoOutput; + + fn to_raw_request(&self) -> Result { + Ok(Self::RawRequest { + prompt: self.prompt.clone(), + duration: self.duration, + resolution: self.resolution.map(|r| r.to_str().to_string()), + aspect_ratio: self.aspect_ratio.map(|ar| ar.to_str().to_string()), + }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::creds::fal_api_key::FalApiKey; + use crate::requests::traits::fal_endpoint_trait::FalEndpoint; + use errors::AnyhowResult; + use std::fs::read_to_string; + + // ── Real requests (manually run; require a live key and cost money) ── + + #[tokio::test] + #[ignore] // manually run — fires a real API request and incurs cost + async fn test_text_to_video_webhook() -> AnyhowResult<()> { + let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?; + let api_key = FalApiKey::from_str(&secret); + + let request = MinimaxH3TextToVideoRequest { + prompt: "a white kitten chases a butterfly across a sunlit garden".to_string(), + duration: Some(5), + resolution: Some(MinimaxH3Resolution::SevenSixtyEightP), + aspect_ratio: Some(MinimaxH3TextToVideoAspectRatio::SixteenByNine), + }; + + let result = request.send_webhook_request(&api_key, "https://example.com/webhook").await?; + println!("Webhook result: {:?}", result); + assert!(result.request_id.is_some() || result.gateway_request_id.is_some()); + Ok(()) + } + + #[tokio::test] + #[ignore] // manually run — fires a real API request and incurs cost + async fn test_text_to_video_queue() -> AnyhowResult<()> { + let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?; + let api_key = FalApiKey::from_str(&secret); + + let request = MinimaxH3TextToVideoRequest { + prompt: "a wave crashes against a rocky shoreline at sunset".to_string(), + duration: Some(5), + resolution: Some(MinimaxH3Resolution::SevenSixtyEightP), + aspect_ratio: Some(MinimaxH3TextToVideoAspectRatio::SixteenByNine), + }; + + let result = request.send_queue_request(&api_key).await?; + println!("Queue result — request_id: {}", result.request_id); + assert!(!result.request_id.is_empty()); + Ok(()) + } + + // ── Wire-shape sanity (no API calls) ── + + #[test] + fn raw_request_maps_all_fields() { + let request = MinimaxH3TextToVideoRequest { + prompt: "p".to_string(), + duration: Some(12), + resolution: Some(MinimaxH3Resolution::TwoK), + aspect_ratio: Some(MinimaxH3TextToVideoAspectRatio::FourByThree), + }; + let raw = request.to_raw_request().unwrap(); + assert_eq!(raw.prompt, "p"); + assert_eq!(raw.duration, Some(12)); + assert_eq!(raw.resolution.as_deref(), Some("2K")); + assert_eq!(raw.aspect_ratio.as_deref(), Some("4:3")); + } + + #[test] + fn raw_request_omits_unset_optionals() { + let request = MinimaxH3TextToVideoRequest { + prompt: "minimal".to_string(), + duration: None, + resolution: None, + aspect_ratio: None, + }; + let json = serde_json::to_value(request.to_raw_request().unwrap()).unwrap(); + assert_eq!(json, serde_json::json!({ "prompt": "minimal" })); + } + + #[test] + fn every_resolution_maps_to_wire_string() { + for (variant, expected, is_2k) in [ + (MinimaxH3Resolution::SevenSixtyEightP, "768P", false), + (MinimaxH3Resolution::TwoK, "2K", true), + ] { + assert_eq!(variant.to_str(), expected); + assert_eq!(variant.is_2k(), is_2k); + } + } + + #[test] + fn every_aspect_ratio_maps_to_wire_string() { + for (variant, expected) in [ + (MinimaxH3TextToVideoAspectRatio::TwentyOneByNine, "21:9"), + (MinimaxH3TextToVideoAspectRatio::SixteenByNine, "16:9"), + (MinimaxH3TextToVideoAspectRatio::FourByThree, "4:3"), + (MinimaxH3TextToVideoAspectRatio::Square, "1:1"), + (MinimaxH3TextToVideoAspectRatio::ThreeByFour, "3:4"), + (MinimaxH3TextToVideoAspectRatio::NineBySixteen, "9:16"), + ] { + assert_eq!(variant.to_str(), expected); + } + } + + #[test] + fn endpoint_path_is_canonical() { + assert_eq!(MinimaxH3TextToVideoRequest::ENDPOINT, "minimax/h3/text-to-video"); + } + + // NB: Pricing tests are in cost.rs +} diff --git a/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/cost.rs b/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/cost.rs new file mode 100644 index 0000000000..c48efaa965 --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/cost.rs @@ -0,0 +1,118 @@ +use crate::requests::api::video::text::minimax_h3::api::{ + MinimaxH3Resolution, MinimaxH3TextToVideoRequest, +}; +use crate::requests::traits::fal_request_cost_calculator_trait::{FalRequestCostCalculator, UsdCents}; + +// MiniMax H3 (Hailuo-03) pricing (see https://fal.ai/models/minimax/h3/text-to-video): +// 768P: $0.16 per video second +// 2K: $0.26 per video second +// +// Pricing depends on resolution and duration only (aspect ratio is free). +// Both rates are exact whole cents. Shared by the text + image + reference +// modalities (reference additionally bills extra reference images; see the +// reference cost module). +const RATE_768P_CENTS_PER_SEC: u64 = 16; // $0.16/sec +const RATE_2K_CENTS_PER_SEC: u64 = 26; // $0.26/sec + +/// Per-second rate in whole cents for MiniMax H3. `is_2k` selects the 2K tier. +pub(crate) fn minimax_h3_rate_cents_per_sec(is_2k: bool) -> u64 { + if is_2k { RATE_2K_CENTS_PER_SEC } else { RATE_768P_CENTS_PER_SEC } +} + +/// Per-second rate × duration → whole cents (both rates are exact cents, so no +/// rounding is needed). +pub(crate) fn minimax_h3_video_cost_cents(rate_cents_per_sec: u64, duration_secs: u64) -> UsdCents { + rate_cents_per_sec * duration_secs +} + +impl FalRequestCostCalculator for MinimaxH3TextToVideoRequest { + fn calculate_cost_in_cents(&self) -> UsdCents { + // fal defaults when unset: duration = 5s, resolution = 2K. + let duration_secs = u64::from(self.duration.unwrap_or(5)); + let is_2k = self.resolution + .unwrap_or(MinimaxH3Resolution::TwoK) + .is_2k(); + + let rate = minimax_h3_rate_cents_per_sec(is_2k); + minimax_h3_video_cost_cents(rate, duration_secs) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::requests::api::video::text::minimax_h3::api::MinimaxH3TextToVideoAspectRatio; + + fn make_request( + duration: Option, + resolution: Option, + ) -> MinimaxH3TextToVideoRequest { + MinimaxH3TextToVideoRequest { + prompt: "test".to_string(), + duration, + resolution, + aspect_ratio: Some(MinimaxH3TextToVideoAspectRatio::SixteenByNine), + } + } + + mod cost_table { + use super::*; + + // (duration, resolution, expected_cents) + // Math: rate × secs where rate (cents) = 16 (768P) or 26 (2K). + const COST_TABLE: &[(Option, Option, u64)] = &[ + // 768P → $0.16/s + (Some(5), Some(MinimaxH3Resolution::SevenSixtyEightP), 80), + (Some(10), Some(MinimaxH3Resolution::SevenSixtyEightP), 160), + (Some(15), Some(MinimaxH3Resolution::SevenSixtyEightP), 240), + // 2K → $0.26/s + (Some(5), Some(MinimaxH3Resolution::TwoK), 130), + (Some(10), Some(MinimaxH3Resolution::TwoK), 260), + (Some(15), Some(MinimaxH3Resolution::TwoK), 390), + // Defaults: duration=None→5s, resolution=None→2K + (None, None, 130), + (Some(8), None, 208), + (None, Some(MinimaxH3Resolution::SevenSixtyEightP), 80), + ]; + + #[test] + fn matches_cost_table() { + for &(duration, resolution, expected) in COST_TABLE { + let got = make_request(duration, resolution).calculate_cost_in_cents(); + assert_eq!(got, expected, "duration={duration:?} resolution={resolution:?}"); + } + } + + #[test] + fn two_k_is_more_expensive_than_768p() { + let low = make_request(Some(8), Some(MinimaxH3Resolution::SevenSixtyEightP)).calculate_cost_in_cents(); + let high = make_request(Some(8), Some(MinimaxH3Resolution::TwoK)).calculate_cost_in_cents(); + assert!(high > low, "2K={high}¢ should exceed 768P={low}¢"); + } + + #[test] + fn cost_scales_linearly_with_duration() { + let five = make_request(Some(5), Some(MinimaxH3Resolution::SevenSixtyEightP)).calculate_cost_in_cents(); + let ten = make_request(Some(10), Some(MinimaxH3Resolution::SevenSixtyEightP)).calculate_cost_in_cents(); + assert_eq!(ten, five * 2); + } + + /// Aspect ratio does not affect the bill (only resolution + duration do). + #[test] + fn cost_ignores_aspect_ratio() { + let baseline = make_request(Some(8), Some(MinimaxH3Resolution::TwoK)).calculate_cost_in_cents(); + for ar in [ + None, + Some(MinimaxH3TextToVideoAspectRatio::TwentyOneByNine), + Some(MinimaxH3TextToVideoAspectRatio::Square), + Some(MinimaxH3TextToVideoAspectRatio::NineBySixteen), + ] { + let cost = MinimaxH3TextToVideoRequest { + aspect_ratio: ar, + ..make_request(Some(8), Some(MinimaxH3Resolution::TwoK)) + }.calculate_cost_in_cents(); + assert_eq!(cost, baseline, "ar={ar:?}"); + } + } + } +} diff --git a/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/mod.rs b/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/mod.rs new file mode 100644 index 0000000000..3bfb6c86db --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/mod.rs @@ -0,0 +1,3 @@ +pub mod api; +pub mod cost; +pub mod raw_request; diff --git a/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/raw_request.rs b/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/raw_request.rs new file mode 100644 index 0000000000..413c92eafd --- /dev/null +++ b/crates/api_clients/fal_client/src/requests/api/video/text/minimax_h3/raw_request.rs @@ -0,0 +1,33 @@ +use serde::{Deserialize, Serialize}; + +/// Over-the-wire input shape for `minimax/h3/text-to-video`. +/// fal's schema: +#[derive(Debug, Serialize, Deserialize, Default)] +pub struct MinimaxH3TextToVideoInput { + /// Text prompt (1 to 7000 characters). + pub prompt: String, + + /// Duration in seconds. Range 5–15. fal default: 5. + #[serde(skip_serializing_if = "Option::is_none")] + pub duration: Option, + + /// Output resolution. + /// Possible values: "768P", "2K". fal default: "2K". + #[serde(skip_serializing_if = "Option::is_none")] + pub resolution: Option, + + /// Aspect ratio. + /// Possible values: "21:9", "16:9", "4:3", "1:1", "3:4", "9:16". fal default: "16:9". + #[serde(skip_serializing_if = "Option::is_none")] + pub aspect_ratio: Option, +} + +#[derive(Debug, Serialize, Deserialize)] +pub struct MinimaxH3TextToVideoVideoFile { + pub url: String, +} + +#[derive(Debug, Serialize, Deserialize)] +pub struct MinimaxH3TextToVideoOutput { + pub video: MinimaxH3TextToVideoVideoFile, +} diff --git a/crates/api_clients/fal_client/src/requests/api/video/text/mod.rs b/crates/api_clients/fal_client/src/requests/api/video/text/mod.rs index a69e090fdb..bd756098da 100644 --- a/crates/api_clients/fal_client/src/requests/api/video/text/mod.rs +++ b/crates/api_clients/fal_client/src/requests/api/video/text/mod.rs @@ -2,6 +2,7 @@ pub mod kling_1p6_pro_text_to_video; pub mod kling_2p5_turbo_pro_text_to_video; pub mod kling_2p6_pro_text_to_video; pub mod kling_3p0_standard_text_to_video; +pub mod minimax_h3; pub mod veo_2; pub mod veo_3; pub mod veo_3_fast;