vercel/ai · error · InvalidArgumentError

FLUX 3 video requires an explicit duration when ${UNTIMED_KE

Error message

FLUX 3 video requires an explicit duration when ${UNTIMED_KEYFRAMES_NEEDING_DURATION} or more keyframes are sent without a timestamp.

What it means

Thrown by getArgs() of the Black Forest Labs video model when generating FLUX 3 video with multiple string keyframes (image URLs/ids without per-keyframe timestamps) but no explicit `duration` option. The BFL API cannot infer a coherent timeline for >= UNTIMED_KEYFRAMES_NEEDING_DURATION untimed keyframes, so the SDK fails fast client-side with InvalidArgumentError instead of sending a doomed request. Providing a duration, or timestamped keyframes, resolves it.

Source

Thrown at packages/black-forest-labs/src/black-forest-labs-video-model.ts:521

        });
        duration = MAX_DURATION_SECONDS;
      } else if (duration < MIN_DURATION_SECONDS) {
        warnings.push({
          type: 'unsupported',
          feature: 'duration',
          details: `FLUX 3 video requires at least ${MIN_DURATION_SECONDS} seconds. The requested duration of ${options.duration} was clamped to ${MIN_DURATION_SECONDS}.`,
        });
        duration = MIN_DURATION_SECONDS;
      }
    }

    const untimedKeyframeCount =
      keyframes?.filter(keyframe => typeof keyframe === 'string').length ?? 0;
    if (
      duration == null &&
      untimedKeyframeCount >= UNTIMED_KEYFRAMES_NEEDING_DURATION
    ) {
      throw new InvalidArgumentError({
        argument: 'duration',
        message:
          `FLUX 3 video requires an explicit duration when ${UNTIMED_KEYFRAMES_NEEDING_DURATION} or more ` +
          'keyframes are sent without a timestamp.',
      });
    }

    const mode = keyframes != null ? 'i2v' : startVideo != null ? 'v2v' : 't2v';

    const body: Record<string, unknown> = {
      mode,
      prompt: options.prompt ?? '',
      aspect_ratio: aspectRatio,
      duration,
      resolution,
      version: bflOptions?.version,
      generate_audio: options.generateAudio,
      safety_tolerance: bflOptions?.safetyTolerance,

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Add an explicit whole-number `duration` (5-20 seconds) to the video generation options.
2. Provide timestamps for the keyframes so they are no longer 'untimed' string entries.
3. Reduce the number of keyframes below the threshold if a fixed duration is not desired.

Example fix

// before
await generateVideo({ model: bfl.video('flux-3'), prompt, keyframes: [img1, img2, img3] });
// after
await generateVideo({ model: bfl.video('flux-3'), prompt, keyframes: [img1, img2, img3], duration: 10 });

const untimed = keyframes?.filter(k => typeof k === 'string').length ?? 0;
if (duration == null && untimed >= 2) {
  throw new Error('Provide an explicit duration (5-20s) or timestamped keyframes.');
}

try {
  await generateVideo({ model, prompt, keyframes, duration });
} catch (e) {
  if (InvalidArgumentError.isInstance?.(e) && /duration/.test(e.message)) {
    // re-run with a default duration
  }
  throw e;
}

When it happens

Trigger: Calling generateVideo/doGenerate on a black-forest-labs FLUX 3 video model with `keyframes` containing at least UNTIMED_KEYFRAMES_NEEDING_DURATION plain string entries and options.duration left undefined.

Common situations: Passing an array of image URLs as keyframes to stitch a multi-shot video without specifying duration; copying a single-keyframe example (where duration is optional) and adding more keyframes; assuming the API will auto-pick duration as it does for text-to-video.

Related errors

• Invalid argument for parameter output: Invalid output type.
• Invalid argument for parameter schema: Schema is not support
• Invalid argument for parameter schemaDescription: Schema des
• Invalid argument for parameter schemaName: Schema name is no
• Invalid argument for parameter enumValues: Enum values are n

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/4ae40ea27ef2927b. Report an issue: GitHub.