Film
Docs / CLI reference / start
CLI reference

film start

film start --prompt TEXT --allow-provider-cost --pipeline NAME
           [--reference-image-url URL] [--duration SECONDS] [--frames N] [--fps N]
           [--width PX] [--height PX] [--resolution NAME] [--json]
           [--mode MODE] [--audio-url URL] [--driving-video-url URL] [--aspect-ratio RATIO]
           [--sound BOOL] [--n-frames VALUE] [--size VALUE] [--lora FILE=STRENGTH ...]

Starts one render through the Film at FILM_URL, authenticated with the secret FILM_SECRET_ROLE names (see configuration), and prints the job Film answered. A render is billed by its renderer, so the command refuses without --allow-provider-cost.

  • --pipeline: hedra, kling, sora, veo, wavespeed or wisent. Without it Film refuses the request with HTTP 400 and names the configured pipelines; it does not choose a renderer.
  • --mode: explicitly selects text_to_video, image_to_video, scail or lipsync. Without it, --reference-image-url selects image-to-video and its absence selects text-to-video.
  • --reference-image-url: the source still. --audio-url supplies the voice for lipsync; --driving-video-url supplies scail's motion reference.
  • --duration: clip length in seconds, as the renderer spells it.
  • --sound: whether Kling renders sound, stated as true or false. Kling requires this and duration.
  • --n-frames and --size: Sora clip length and quality, using KIE's values.
  • --frames, --fps, --width, --height: what the wisent pipeline renders. That pipeline assumes none of them: a render without all four is refused.
  • --lora FILE=STRENGTH: an adapter the wisent pipeline applies at that strength; repeat it for each. None is a render with the base model. No other pipeline loads adapters, so Film refuses a LoRA sent to one instead of rendering without it.
  • --resolution: the output resolution as the renderer spells it. Scail and lipsync require it; Film does not choose a tier.
  • --aspect-ratio: the output proportions as the renderer spells them. Veo and Sora require it, as does Kling text-to-video. Hedra requires this as well as resolution before media staging, and refuses either output value when empty. Unsupported provider values retain the renderer’s refusal rather than selecting another output.

Render a talking portrait

film start --pipeline hedra --mode lipsync --prompt "$PROMPT" \
  --reference-image-url "$PORTRAIT_URL" --audio-url "$VOICE_URL" \
  --resolution "$RESOLUTION" --aspect-ratio "$ASPECT_RATIO" --allow-provider-cost

Use URLs the renderer can fetch and choose output values it supports. For InfiniteTalk use --pipeline wavespeed --mode lipsync with an explicit resolution. Echo's avatar configuration asks for these same values instead of selecting a hidden default.

job_id: <id>
pipeline: <pipeline>
status: processing
url: -
error: -
completed_at: -

With --json the same job as JSON; fields with no value are left out. Read it back with film status.

Refusals

Exit 2, nothing sent:

refusing a billable render without explicit --allow-provider-cost

`<name>` is not a pipeline: hedra, kling, sora, veo, wavespeed or wisent

invalid value '<value>' for '--lora <LORA>': --lora `<value>` is not FILE=STRENGTH

The service answers 422 pipeline `<name>` cannot apply a LoRA; only `wisent` loads the adapters a request names for a --lora sent to any other pipeline; nothing is rendered.

Exit 1: the configuration refusals; film at <url> — <cause> when the service cannot be reached; film refused (<status>): <reason> with the service's own reason; and a job whose status is failed, after it is printed.