Image and video settings
Every parameter an image or video job takes, how locked models behave, how to follow and cancel a job, how to tune a model for your machine, and the settings and limits these models share. To make something, start with Images or Video.
Image and video parameters
Every field but prompt is optional; anything left out comes from the model's visual block. Unknown fields are ignored. The upscaler takes its own two fields instead: see Upscaling.
| Field | |
|---|---|
prompt | What to make. Text past the first few hundred tokens is not read |
negative_prompt | What to steer away from. Only used above CFG 1, so at CFG 1 it is refused |
width, height | 16 to 4096 each, and a multiple of the model's grid (32 on Wan 2.2, 64 on SDXL, LTX-2.3 and LTX-2.5): a size off it is refused with the nearest two. Quality falls away from the model's native size |
steps | Sampling steps, 1 to 150. More is slower, and past the model's own count rarely better |
cfg | Guidance, above 0 and at most 30. At 1 each step takes half the time |
sampler | euler, euler_a, heun, dpm++2m, lcm, ddim_trailing and others. An unknown name is refused |
flow_shift | For flow-matching video models (Wan), above 0 and at most 30 |
frames, fps | Video only: length in frames, from 1 to the model's max_frames in capabilities, and frame rate (1 to 60). max_frames is the lower of what the model makes (81 for Wan 2.2 A14B, Wan 2.1 VACE and Wan 2.2 S2V, 1024 for the others) and DPPAN_VISUAL_MAX_FRAMES (481 by default). MiniMax-H3 makes 24 fps only, and refuses another. See Longer videos |
extend_artifact | A video you made, to continue; frames then counts what is added. See Longer videos |
prompts, color_match | A longer video: a prompt per part, and how closely each holds the first's look. See Longer videos |
keyframe_artifacts, keyframe_spacing | A video through keyframes, and the frames between them. See Longer videos |
audio, audio_artifact | A video's sound: see Sound |
loras | [{"name": "…", "strength": 1.0}], from the model's loras/ folder. Strength from -2 to 2; below 0 pushes the other way |
image_artifact, strength, fit, ref_artifacts, end_image_artifact | See Starting from an image |
mask_artifact | See Changing part of an image |
control_artifact, control, control_strength | Wan VACE only: see Following a video |
node | Where it runs: local, or a node's name or id. See On other machines |
scale | The upscaler only: see Upscaling |
A refused request fails the job as soon as it starts, with error_codebad_params and a message naming the field. A number outside its range is refused with the range ("steps must be between 1 and 150, got 500"), never clamped. The dashboard holds its fields to the same ranges: a value outside one turns the field red, says what it takes, and Generate waits until it is fixed.
Locked models
Distilled models — Z-Image Turbo, Krea-2 Turbo, FLUX 3 Klein, FLUX.2 Klein, FLUX.1 schnell, SD3.5 Large Turbo, HiDream-O1 Dev, Wan 2.2 TI2V Turbo, LTX-2.3, LTX-2.5, MiniMax-H3 with Hyperflow, Pika H3 Flex, and the fast Wan 2.2 A14B, Wan 2.2 S2V, Wan VACE, Wan 2.2 VACE-Fun, Qwen-Image 2.1 and HunyuanVideo 1.5 — work well only with their own few steps at CFG 1. Their visual block says locked, and a request that sets steps, cfg, sampler or flow_shift is refused. Size, length, seed, input images and LoRAs still apply.
Progress, previews and cancelling
| Stage | |
|---|---|
loading | The model starts. Only on its first job, or after it was unloaded |
preparing | The prompt is encoded and the model's weights read in |
sampling | The model works step by step. The only stage with a fraction |
decoding | The result becomes pixels. Long for a video |
publishing | The PNG or MP4 is saved |
waiting | The node running the job left, and the job waits for another machine with the model |
While a job samples, GET /v1/generations/:id/preview returns its newest preview as a PNG (a video's middle frame), updated every step; X-Preview-Step says which. It answers 404 before the first step and after the job ends.
DELETE /v1/generations/:id stops a job within a few seconds and keeps the model loaded for the next one.
What to expect
Times from one machine, an Apple M5 Pro with 24 GB; yours will differ with its GPU and memory:
| Model | Job | Time |
|---|---|---|
| SDXL base 1.0 | 1024×1024, 20 steps, CFG 7 | 54 s |
| Z-Image Turbo | 1024×1024, 8 steps, first job (includes loading) | 69 s |
| Real-ESRGAN x4plus | a 1024×1024 image, either scale | 90 s |
| Wan 2.2 TI2V Turbo | 832×480, 33 frames, from a first frame | 111 s |
| LTX-2.3 | 1024×576, 49 frames (2 s), with its sound | 2.3 min |
| LTX-2.3 | 1024×576, 97 frames (4 s), with its sound | 3.9 min |
| Wan VACE 1.3B fast | 832×480, 33 frames, following a video | 4 min |
| Wan 2.2 TI2V | 832×480, 33 frames, 20 steps, CFG 6, from a first frame | 5.2 min |
| LTX-2.3 | 1024×576, 97 frames, from a first frame, or a first and a last | 6–6.5 min |
| MiniMax-H3 | 864×480, 22 frames, 20 steps, from a first and a last frame | 8.8 min |
| Wan VACE 1.3B | 832×480, 33 frames, following a video | 16 min |
Longer and larger takes longer: the Wan 2.2 TI2V models' default is 1280×704 at 49 frames, MiniMax-H3's 39 frames, and the LTX models' 1024×576 at 97 frames. MiniMax-H3 and Wan VACE 14B need about 16 GB of free memory, LTX-2.3, LTX-2.5 and Wan 2.2 T2V A14B fast about 20 GB, Wan VACE 1.3B under 10 GB.
Tuning a model for this machine
An installed model's settings are the visual block of bundle.dppan.json in its directory. They are the defaults every request inherits — change them for a shorter default video, say, or to trade speed for memory:
"visual": {
"kind": "video", "width": 1280, "height": 704, "frames": 49, "fps": 24,
"sampler": "lcm", "sigmas": [1.0, 0.9375, 0.833333, 0.625, 0.0], "cfg": 1.0,
"locked": true, "start_image": true, "params_backend": "te=disk,diffusion=disk"
}| Key | |
|---|---|
kind | image or video |
width, height | The native size, and a request's default |
frames, fps | A video's default length and frame rate |
frame_step, min_frames | The only lengths a model makes, when it has fixed ones: MiniMax-H3's 17 and 5 give 5, 22, 39… frames |
max_frames | A model that makes each clip in one go: the longest clip it was trained for (Wan: 81). A longer request is refused |
steps, cfg, sampler, flow_shift | Sampling defaults. 0 or absent: 20 steps, CFG 7 |
sigmas | A distilled model's noise schedule, ending in 0. It sets the step count |
refine_sigmas | LTX-2.3 and LTX-2.5: the second stage's schedule, run after the video is enlarged |
negative_prompt | The default negative prompt |
guidance | A guidance-distilled model's guidance (FLUX.1 Kontext: 2.5). Absent takes 3.5 |
skip_layer_guidance | Skip Layer Guidance: layers, scale, start and end (SD3.5 Medium: layers 7, 8 and 9 at 2.5, from 0.01 to 0.2) |
locked | Refuse requests that change the schedule |
start_image, end_image, ref_images | Which images a request may send |
params_backend | Which parts are read in for each job, instead of kept in memory |
Restart the orchestrator to apply a change. An unknown key stops the model from loading, and startup logs ignoring visual bundle … with the reason.
params_backend trades time for memory. The video models read their text encoder and video model in for each job (te=disk,diffusion=disk), about 10 s more a job, so less is held between jobs and the decode has room. LTX-2.3 and LTX-2.5 add vae=disk, so each of their jobs reads over 20 GB from disk. With plenty of memory, remove it.
Your changes survive a re-pull: dppan pull --visual keeps every value you changed and updates the rest.
LoRAs
A model's LoRAs go in the loras/ folder of its directory, as .safetensors or .gguf files. A request names one by its file name without the extension. The SDXL install includes sd_xl_offset_example-lora_1.0, for deeper darks and brighter lights. The folder is read at startup; capabilities lists what it found.
Memory and the worker process
Each image or video model runs in a process of its own. If one crashes, only its job fails, and the next job starts it again. Between jobs it stays loaded, a cancelled job included, so the next job starts sooner. After DPPAN_VISUAL_IDLE_MINUTES (10 minutes) with no job, its process stops and returns all its memory; the next job loads it again. Stopping the orchestrator stops every model's process with it.
Image, video, speech and music models share one memory budget (DPPAN_SPEECH_MEMORY_BUDGET_MB). When a job needs room, the least recently used idle model is unloaded and loads again on its next request — a small budget costs time, not failures. On a Mac, an image or video model that is loading keeps the speech models loaded, so a spoken reply during a render starts at once, unless it needs their memory.
DPPAN_VISUAL_MAX_VRAM_GIB caps the GPU memory each image or video model uses. The default, 0, takes what is free when the model starts, less 512 MiB. Set it on a machine doing other work. A negative value leaves that much free instead.
A text node on this machine, joined through localhost, is such work: with the setting unset, each image or video model here leaves room for two chat sessions on the layers that node serves, plus 1 GB, at most half the memory its model runs in. dppan join prints how much; a shorter DPPAN_CTX on the node makes each session smaller. A value set in DPPAN_VISUAL_MAX_VRAM_GIB, 0 included, is used as it is instead.
Configuration
| Variable | Default | |
|---|---|---|
DPPAN_MODELS_DIR | ~/.dppan/models | Where pull installs and the orchestrator looks, in bundles/ |
DPPAN_VISUAL_MAX_VRAM_GIB | 0 (what is free) | GPU memory per image or video model, in GiB |
DPPAN_SPEECH_MEMORY_BUDGET_MB | half of RAM | Memory all loaded generators may hold together |
HF_TOKEN | unset | Hugging Face token for gated repositories |
DPPAN_VISUAL_NODES | off | on accepts nodes' image and video models (On other machines) |
DPPAN_VISUAL_PREFER_NODES | on | Jobs that name no place try nodes serving only image and video models before this machine. off tries this machine first |
DPPAN_IMAGES_SYNC_TIMEOUT_SECS | 900 | How long /v1/images/generations and /v1/images/edits wait before returning a job ID to poll |
DPPAN_VISUAL_MAX_FRAMES | 481 (20 s at 24 fps) | Longest video a request may ask for, 1 to 1024. A model trained on shorter clips stops at its own length |
DPPAN_VISUAL_DEADLINE_MINUTES | 240 (4 h) | How long an image job may run, and a video for each part it is made in, 1 to 1440 |
DPPAN_VISUAL_IDLE_MINUTES | 10 | How long an image or video model stays loaded with no job, 1 to 1440. Then its process stops and the next job loads it again |
An image or video job's time limit counts from when it starts running, so time spent waiting behind another job does not use it up. A job past it is stopped and marked expired. A request's deadline_seconds sets its own deadline instead, counted from when it is submitted. Both settings are listed under Settings → Limits in the dashboard.
Known limitations
- One music, image or video job at a time on each machine. Transcriptions run beside one; spoken replies and voice cloning do on a Mac when their model fits in the memory left, and otherwise wait for it;
/v1/audio/speechmay then return a job ID to poll. Running image and video work on a node keeps this machine free. - LTX-2.3, LTX-2.5 and Wan 2.2 T2V A14B fast need about 20 GB free. On a machine short of that, run them on a node with more memory.
- A node serving a text model and image or video models at once shares its GPU between them.
- Only a Mac makes and reads H.264. A node that is not a Mac cannot Restyle or Extend a video made on a Mac: run that job on a Mac (Run on).
- No watermark or signed content credentials, only the metadata label. Label generated media where you publish it; some jurisdictions require that.
- No content filter: the model makes what the prompt asks for.
- Wan VACE is 480p at 16 fps and follows a video from its start; it cannot extend a clip or change one region. Preparing a control video in the dashboard needs Chrome, Edge or Firefox; elsewhere, Restyle a video made here.