add minimax to fal

This commit is contained in:
Hanashi committed 2026-08-04 04:42:27 -04:00
1 parent 60b4148179
commit 85d263cff8
15 files changed
+987

No files matched your search

@@ -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<String>,
/// Duration in seconds. Valid range 5–15; fal's default is `5` when `None`.
pub duration: Option<u8>,
/// Output resolution. fal's default is `2K` when `None`.
pub resolution: Option<MinimaxH3Resolution>,
}
impl FalEndpoint for MinimaxH3ImageToVideoRequest {
const ENDPOINT: &str = "minimax/h3/image-to-video";
type RawRequest = MinimaxH3ImageToVideoInput;
type RawResponse = MinimaxH3ImageToVideoOutput;
fn to_raw_request(&self) -> Result<Self::RawRequest, FalErrorPlus> {
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
}
@@ -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<u8>,
resolution: Option<MinimaxH3Resolution>,
) -> 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<u8>, Option<MinimaxH3Resolution>, 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);
}
}
}
@@ -0,0 +1,3 @@
pub mod api;
pub mod cost;
pub mod raw_request;
@@ -0,0 +1,37 @@
use serde::{Deserialize, Serialize};
/// Over-the-wire input shape for `minimax/h3/image-to-video`.
/// fal's schema: <https://fal.ai/models/minimax/h3/image-to-video/api>
#[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<String>,
/// Duration in seconds. Range 5–15. fal default: 5.
#[serde(skip_serializing_if = "Option::is_none")]
pub duration: Option<u8>,
/// Output resolution.
/// Possible values: "768P", "2K". fal default: "2K".
#[serde(skip_serializing_if = "Option::is_none")]
pub resolution: Option<String>,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct MinimaxH3ImageToVideoVideoFile {
pub url: String,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct MinimaxH3ImageToVideoOutput {
pub video: MinimaxH3ImageToVideoVideoFile,
}
@@ -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;
@@ -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<Vec<String>>,
/// URLs of motion/reference video clips (at most 3; 2–15 seconds each,
/// combined duration at most 15 seconds).
pub reference_video_urls: Option<Vec<String>>,
/// 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<Vec<String>>,
/// Duration in seconds. Valid range 5–15; fal's default is `5` when `None`.
pub duration: Option<u8>,
/// Output resolution. fal's default is `2K` when `None`.
pub resolution: Option<MinimaxH3Resolution>,
/// Aspect ratio. fal's default is `adaptive` when `None`.
pub aspect_ratio: Option<MinimaxH3ReferenceToVideoAspectRatio>,
}
/// 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<Self::RawRequest, FalErrorPlus> {
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
}
@@ -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<u8>,
resolution: Option<MinimaxH3Resolution>,
image_count: usize,
) -> MinimaxH3ReferenceToVideoRequest {
let images = (0..image_count)
.map(|i| format!("https://example.com/ref_{i}.png"))
.collect::<Vec<String>>();
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<u8>, Option<MinimaxH3Resolution>, 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);
}
}
}
@@ -0,0 +1,3 @@
pub mod api;
pub mod cost;
pub mod raw_request;
@@ -0,0 +1,51 @@
use serde::{Deserialize, Serialize};
/// Over-the-wire input shape for `minimax/h3/reference-to-video`.
/// fal's schema: <https://fal.ai/models/minimax/h3/reference-to-video/api>
#[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<Vec<String>>,
/// 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<Vec<String>>,
/// 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<Vec<String>>,
/// Duration in seconds. Range 5–15. fal default: 5.
#[serde(skip_serializing_if = "Option::is_none")]
pub duration: Option<u8>,
/// Output resolution.
/// Possible values: "768P", "2K". fal default: "2K".
#[serde(skip_serializing_if = "Option::is_none")]
pub resolution: Option<String>,
/// 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<String>,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct MinimaxH3ReferenceToVideoVideoFile {
pub url: String,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct MinimaxH3ReferenceToVideoOutput {
pub video: MinimaxH3ReferenceToVideoVideoFile,
}
@@ -1,3 +1,4 @@
pub mod minimax_h3;
pub mod veo_3p1;
pub mod veo_3p1_fast;
pub mod vidu_q3_reference_to_video;
@@ -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<u8>,
/// Output resolution. fal's default is `2K` when `None`.
pub resolution: Option<MinimaxH3Resolution>,
/// Aspect ratio. fal's default is `16:9` when `None`.
pub aspect_ratio: Option<MinimaxH3TextToVideoAspectRatio>,
}
/// 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<Self::RawRequest, FalErrorPlus> {
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
}
@@ -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<u8>,
resolution: Option<MinimaxH3Resolution>,
) -> 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<u8>, Option<MinimaxH3Resolution>, 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:?}");
}
}
}
}
@@ -0,0 +1,3 @@
pub mod api;
pub mod cost;
pub mod raw_request;
@@ -0,0 +1,33 @@
use serde::{Deserialize, Serialize};
/// Over-the-wire input shape for `minimax/h3/text-to-video`.
/// fal's schema: <https://fal.ai/models/minimax/h3/text-to-video/api>
#[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<u8>,
/// Output resolution.
/// Possible values: "768P", "2K". fal default: "2K".
#[serde(skip_serializing_if = "Option::is_none")]
pub resolution: Option<String>,
/// 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<String>,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct MinimaxH3TextToVideoVideoFile {
pub url: String,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct MinimaxH3TextToVideoOutput {
pub video: MinimaxH3TextToVideoVideoFile,
}
@@ -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;