Text-to-Video

This guide covers deploying FastVideo text-to-video generation on Dynamo using a custom worker (worker.py) exposed through the /v1/videos endpoint.

Overview

• Default model: FastVideo/FastWan2.1-T2V-1.3B-Diffusers.
• Typed API: The worker builds GeneratorConfig once at startup and creates a GenerationRequest for each /v1/videos request.
• Optimized inference: torch.compile and NVFP4 transformer quantization are available through --torch-compile and --fp4-quantization; the legacy --enable-optimizations flag remains as a shortcut for both.
• Response format: Returns one complete MP4 payload per request as data[0].b64_json (non-streaming).
• Concurrency: One request at a time per worker (VideoGenerator is not re-entrant). Scale throughput by running multiple workers.

Kubernetes Deployment

Kubernetes is the recommended path for running FastVideo on Dynamo. The steps below build and push the runtime image, deploy the aggregated worker, and send a first request. For a single-node development workflow, see Local Deployment at the bottom of this page.

Deployment Files

Prerequisites

• Dynamo Kubernetes Platform installed
• GPU-enabled Kubernetes cluster
• A container registry you can push the FastVideo runtime image to
• Optional HF token secret (for gated models)

docker build examples/diffusers/ -t <my-registry/fastvideo-runtime:my-tag>
docker push <my-registry/fastvideo-runtime:my-tag>

export NAMESPACE=<your-namespace>
export HF_TOKEN=<your-hf-token>
kubectl create secret generic hf-token-secret \
  --from-literal=HF_TOKEN=${HF_TOKEN} \
  -n ${NAMESPACE}

cd <dynamo-root>/examples/diffusers/deploy
export NAMESPACE=<your-namespace>
kubectl apply -f huggingface-cache-pvc.yaml -n ${NAMESPACE}
kubectl apply -f agg.yaml -n ${NAMESPACE}

kubectl apply -f huggingface-cache-pvc.yaml -n ${NAMESPACE}
kubectl apply -f agg_user_workload.yaml -n ${NAMESPACE}

export DEPLOYMENT_FILE=agg.yaml
export FASTVIDEO_IMAGE=<my-registry/fastvideo-runtime:my-tag>
yq '(.spec.components[].podTemplate.spec.containers[] | select(.name == "main") | .image) = env(FASTVIDEO_IMAGE)' \
  ${DEPLOYMENT_FILE} > ${DEPLOYMENT_FILE}.generated
kubectl apply -f ${DEPLOYMENT_FILE}.generated -n ${NAMESPACE}

kubectl get dgd -n ${NAMESPACE}
kubectl get pods -n ${NAMESPACE}
kubectl logs -n ${NAMESPACE} -l nvidia.com/dynamo-component=FastVideoWorker

kubectl port-forward -n ${NAMESPACE} svc/fastvideo-agg-frontend 8000:8000

curl -s -X POST http://localhost:8000/v1/videos \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "FastVideo/FastWan2.1-T2V-1.3B-Diffusers",
    "prompt": "A cinematic drone shot over a snowy mountain range at sunrise",
    "size": "256x256",
    "response_format": "b64_json",
    "nvext": {
      "fps": 8,
      "num_frames": 8,
      "num_inference_steps": 1,
      "guidance_scale": 1.0,
      "seed": 10
    }
  }' > response.json
# Linux
jq -r '.data[0].b64_json' response.json | base64 --decode > output.mp4
# macOS
jq -r '.data[0].b64_json' response.json | base64 -D > output.mp4

cd <dynamo-root>/examples/diffusers/local
MODEL=FastVideo/LTX2-Distilled-Diffusers \
WORKER_EXTRA_ARGS="--attention-backend TORCH_SDPA --fp4-quantization" \
./run_local.sh

curl -s -X POST http://localhost:8000/v1/videos \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "FastVideo/LTX2-Distilled-Diffusers",
    "prompt": "A waterfall cascading into a forest pool, birds singing",
    "size": "1920x1088",
    "response_format": "b64_json",
    "nvext": {
      "fps": 24,
      "num_frames": 121,
      "num_inference_steps": 5,
      "guidance_scale": 1.0,
      "seed": 42
    }
  }'

Warmup Time

On first start, workers download model weights. When --torch-compile is enabled, compile/warmup steps can push the first ready time to roughly 10–20 minutes (hardware-dependent). After the first successful compiled response, the second request can still take around 35 seconds while runtime caches finish warming up; steady-state performance is typically reached from the third request onward.

Worker Configuration Reference

Troubleshooting

Hardware Support

The worker checks the GPU compute capability at startup and fails fast when the selected attention backend cannot run on the detected hardware:

Local Deployment

For single-node development you can run FastVideo directly with Docker Compose or a host-local script instead of Kubernetes.

Prerequisites

For Docker Compose:

• Docker Engine 26.0+
• Docker Compose v2
• NVIDIA Container Toolkit

For host-local script:

• Python environment with Dynamo + FastVideo dependencies installed
• CUDA-compatible GPU runtime available on host

Option 1: Docker Compose

The Compose file builds from the same Dockerfile used for the Kubernetes runtime image and exposes the API on http://localhost:8000.

cd <dynamo-root>/examples/diffusers/local
# Start 4 workers on GPUs 0..3
COMPOSE_PROFILES=4 docker compose up --build

Option 2: Host-Local Script

cd <dynamo-root>/examples/diffusers/local
./run_local.sh

Environment variables:

Example:

MODEL=FastVideo/FastWan2.1-T2V-1.3B-Diffusers \
NUM_GPUS=1 \
DYN_HTTP_PORT=8000 \
WORKER_EXTRA_ARGS="--attention-backend VIDEO_SPARSE_ATTN --vsa-sparsity 0.8" \
./run_local.sh

Validated B300 smoke-test worker configurations:

The script writes logs to:

• .runtime/logs/worker.log
• .runtime/logs/frontend.log

Source Code

The example source lives at examples/diffusers/ in the Dynamo repository.

See Also

• Text-to-Video with vLLM-Omni — vLLM-Omni video generation via /v1/videos
• Text-to-Video with SGLang — SGLang video generation worker
• Text-to-Video with TensorRT-LLM — TensorRT-LLM diffusion quick start
• Diffusion Overview — Full backend support matrix