Struct ChainRequest 

pub struct ChainRequest {

    pub model: String,
    pub stages: Vec<ChainStage>,
    pub motion_tail_frames: u32,
    pub width: u32,
    pub height: u32,
    pub fps: u32,
    pub seed: Option<u64>,
    pub steps: u32,
    pub guidance: f64,
    pub strength: f64,
    pub output_format: OutputFormat,
    pub placement: Option<DevicePlacement>,
    pub original_prompt: Option<String>,
    pub prompt_transform: Option<PromptTransformProvenance>,
    pub batch_id: Option<String>,
    pub batch_index: Option<u32>,
    pub batch_count: Option<u32>,
    pub prompt: Option<String>,
    pub total_frames: Option<u32>,
    pub clip_frames: Option<u32>,
    pub source_image: Option<Vec<u8>>,
    pub enable_audio: Option<bool>,
}

Chained generation request. Server accepts either the canonical form (stages non-empty) or the auto-expand form (prompt + total_frames + clip_frames); ChainRequest::normalise collapses the latter into the former so downstream code only deals with stages.

Fields

model: String

stages: Vec<ChainStage>

Canonical stages list. Empty triggers auto-expand from prompt/total_frames/clip_frames.

motion_tail_frames: u32

Pixel frames of motion-tail overlap between consecutive stages. 0 = no overlap (simple concat). >0 = the final K pixel frames of stage N’s latents are threaded into stage N+1’s conditioning, and stage N+1’s leading K output frames are dropped at stitch time.

Defaults to 17 (matches the CLI --motion-tail and SPA defaults): 1 + 16 lands on the LTX-2 VAE’s 1 + 8k causal-grid for a clean re-encode of the carryover RGB frames. Values that do not satisfy 1 + 8k will fail the receiving stage’s tail re-encode at the VAE. Must be strictly less than each stage’s frames.

width: u32

height: u32

fps: u32

seed: Option<u64>

Chain base seed. Per-stage seeds are derived as base_seed ^ ((stage_idx as u64) << 32) by the orchestrator so the whole chain is reproducible from a single seed value.

steps: u32

guidance: f64

strength: f64

Denoising strength for stages[0].source_image. Ignored when the first stage has no source image. Continuation stages are always full-strength conditioned via motion-tail latents.

output_format: OutputFormat

placement: Option<DevicePlacement>

original_prompt: Option<String>

Original source prompt shared by a client-prepared sibling batch.

prompt_transform: Option<PromptTransformProvenance>

batch_id: Option<String>

Durable prepared-batch identity and one-based sibling position.

batch_index: Option<u32>

batch_count: Option<u32>

prompt: Option<String>

Auto-expand: single prompt replicated across all stages.

total_frames: Option<u32>

Auto-expand: total pixel frames the stitched output should cover.

clip_frames: Option<u32>

Auto-expand: per-clip frame count. Defaults to 97 (LTX-2 19B/22B distilled cap). Must be 8k+1.

source_image: Option<Vec<u8>>

Auto-expand: starting image for stages[0].

enable_audio: Option<bool>

Generate per-stage audio and mux it into the final stitched output. Only meaningful for AV-capable families (LTX-2 / LTX-2.3); the server rejects Some(true) for non-AV models. None means “no preference” and resolves to off — chains opt in to audio explicitly so existing callers don’t suddenly start producing audio they didn’t ask for.

Implementations

impl ChainRequest

pub fn synthetic_generate_request( &self, actual_format: OutputFormat, frames: u32, fps: u32, ) -> GenerateRequest

Build a synthetic single-clip GenerateRequest describing the stitched output, so gallery rows and embedded metadata can reuse the existing single-clip schema. stages[0] supplies the prompt, negative prompt, and source image (the row only has one prompt field — continuation prompts are dropped, acceptable for v1).

Callers must pass a normalised request (stages non-empty). actual_format is the container after encode fallbacks (e.g. a WebP request that fell back to APNG records APNG).

pub fn stitched_output_metadata( &self, actual_format: OutputFormat, frame_count: u32, provenance: Option<&ChainProvenance<'_>>, ) -> OutputMetadata

Gallery/PNG metadata for the stitched chain output, derived from Self::synthetic_generate_request via OutputMetadata::from_generate_request so chain rows can never drift from the single-clip metadata semantics (e.g. strength is only recorded when the chain starts from a source image).

pub fn normalise(self) -> Result<Self>

Collapse the auto-expand form into a canonical Vec<ChainStage> and validate the result. Called once on the server side immediately after JSON parsing, before any engine work kicks off.

Post-conditions on a successful return:

• self.stages is non-empty.
• Each stage’s frames is 8k+1 and > 0.
• self.stages.len() <= MAX_CHAIN_STAGES.
• All auto-expand fields are None (caller must use self.stages).

pub fn normalise_with_family(self, family_hint: Option<&str>) -> Result<Self>

normalise with the family already resolved.

The manifest cannot classify an installed cv: / hf: id, so a manifest-only lookup fell back to the LTX 8k+1 grid and rejected a 53-frame wan stage as “this family requires 8k+1” — immediately after the server had resolved it as wan from the sidecar overlay (#783). Callers holding a resolved family pass it; None keeps the historical manifest-only behaviour for callers that do not.

pub fn estimated_total_frames(&self) -> u32

Predicted stitched frame count before any top-level total_frames trim. Used by UIs for the footer summary and by the server to size the final buffer.

Per-boundary rule:

• smooth: drop leading motion_tail_frames of the incoming clip
• cut: no trim
• fade: replace 2 * fade_len frames (trailing of prior + leading of next) with fade_len blended frames → net -fade_len

Sums stage_contributed_frames so the per-stage boundary math exists in exactly one place (the chain-job runner persists the same values as frames_emitted).

Trait Implementations

impl Clone for ChainRequest

fn clone(&self) -> ChainRequest

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ComposeSchema for ChainRequest

fn compose(generics: Vec<RefOr<Schema>>) -> RefOr<Schema>

impl Debug for ChainRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ChainRequest

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&ChainRequest> for ChainScript

fn from(req: &ChainRequest) -> Self

Converts to this type from the input type.

impl PartialEq for ChainRequest

fn eq(&self, other: &ChainRequest) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for ChainRequest

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ChainRequest

impl ToSchema for ChainRequest

fn name() -> Cow<'static, str>

Return name of the schema.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference utoipa::openapi::schema::Schemas for this type.