Generation and artifacts API
Base URL and authentication are on the REST API overview.
Generation
Asynchronous media generation. Submit a job, poll it, then download the artifacts it produced. See Generation jobs for the model.
Ownership follows the same rule as artifacts: on your own orchestrator every request has the same owner, and a deployment with sign-in keeps each account's jobs apart. A missing job and another owner's job both return 404.
If generation is not configured, every endpoint here returns 503.
Which modalities work depends on what is configured. Speech is available when a speech model has been pulled with dppan pull --speech, or named explicitly with DPPAN_SPEECH_MODEL and DPPAN_SPEECH_MMPROJ (see Speech and voice). Images and video are available for each model installed with dppan pull --visual (see Images); without one, those modalities answer 422.
Rather than inferring what a deployment supports, ask it — GET /v1/generations/capabilities.
GET /v1/generations/capabilities
What this deployment can generate, and what each generator will honour. Answer this before composing a request: a client that assumes limits offers controls the deployment silently clamps.
Unauthenticated on purpose — it exposes only which generators are configured and reveals nothing about anyone's jobs.
{
"generators": [
{
"modality": "audio",
"model": "qwen3-tts",
"voices": ["warm", "clear"],
"requires_speaker": true,
"languages": ["de", "en", "es", "fr", "it", "ja", "ko", "pt", "ru", "zh"],
"limits": {
"max_duration_seconds": 40.96,
"default_temperature": 0.9,
"default_top_k": 50,
"default_top_p": 1.0,
"default_repetition_penalty": 1.05
}
},
{
"modality": "audio",
"model": "hf-PkmX-orpheus-3b-0.1-ft-Q8_0-GGUF-Q8_0-full",
"builtin_voices": ["tara", "leah", "jess", "leo", "dan", "mia", "zac", "zoe"],
"requires_speaker": false,
"limits": {
"max_duration_seconds": 43.69,
"default_temperature": 0.9,
"default_top_k": 50,
"default_top_p": 1.0,
"default_repetition_penalty": 1.05
}
},
{
"modality": "audio",
"model": "ai4bharat-IndicF5",
"requires_speaker": true,
"requires_reference_text": true,
"speed_range": { "min": 0.3, "max": 2.0 },
"languages": ["as", "bn", "gu", "hi", "kn", "ml", "mr", "or", "pa", "ta", "te"]
}
]
}voices, builtin_voices and languages are omitted when empty, requires_reference_text when false, and speed_range when the generator has no pace control.
voices and builtin_voices are both passed as voice, but they are not the same thing. voices are reference clips this deployment registered, and an operator can add or remove them; builtin_voices are speakers baked into the checkpoint's weights, and nobody can. Offer them under one control — the server knows which is which — but do not merge them in your own configuration, because only one of the two is yours to change.
requires_speaker says whether a request must carry a voice or speaker_artifact at all. It is a property of the checkpoint, not of speech or even of the codec — two Qwen3-TTS models on the same codec answer differently. Qwen3-TTS Base needs a voice or a clip; Qwen3-TTS CustomVoice takes no clip and offers nine builtin_voices instead; Orpheus has no clip conditioning whatsoever, and sending it one is refused with speaker_unsupported. Gate your submit control on this field: a client that assumes either answer disables the control for half the models it can see.
requires_reference_text says the clip must come with exactly what is said in it, as reference_text. It is true for F5 models (IndicF5), which continue the clip's speech rather than encoding a voice from it: a clip without its transcript is refused with 400, and so is a configured voice, which has no transcript. Every other speech model refuses reference_text with 400, so send it only where this field asks for it. An F5 generator reports no limits — it has no sampler and no frame ceiling to state; max_duration_seconds on the request still caps the result. See Speech and voice for what makes a good reference clip.
speed_range says the generator honours speed — in params, or OpenAI's speed on /v1/audio/speech — and within what bounds. It divides the generated duration: 2.0 is twice as fast, 0.5 half. A value outside the range is refused with 400. Show a speed control only where this is present: every other generator ignores the field, as it always has.
languages is read from the model's own vocabulary, so it is what this model can actually speak rather than what the library could translate; anything outside it fails the job. Empty means the model has no language tokens to select between — an Orpheus checkpoint is fine-tuned for one language, fixed when it was pulled — not that it speaks nothing, so render it as "no choice to make" rather than as an empty dropdown.
limits.max_duration_seconds is the longest single generation the frame budget allows, and differs between generators on the same budget because the frame rate is the codec's own. It is not a limit on how much you can have spoken: longer text is split and joined, so the finished audio can be many times this. To cap the result, send max_duration_seconds on the request — that one bounds the finished audio.
Image and video generators carry a visual block instead of limits — the model's own settings, which a request inherits by leaving a field out:
{
"modality": "image",
"kind": "image",
"model": "flux2-klein-4b",
"requires_speaker": false,
"ready": true,
"input_modalities": ["image"],
"visual": {
"width": 1024, "height": 1024, "max_side": 4096,
"locked": true, "steps": 4, "cfg": 1.0, "sampler": "euler",
"strength": 0.75, "start_image": true, "ref_images": 4
}
}| Field | |
|---|---|
width, height | The native size, and a request's default. max_side is the largest side a request may ask for |
size_multiple | The grid a request's width and height must be on, where it is coarser than usual: 64 for LTX-2.3. Absent: offer multiples of 64 for an image model, 32 for a video model |
frames, fps, max_frames | A video model's default length, frame rate and longest request. max_frames is the lower of what the model makes (a model that makes each clip in one go stops at the length it was trained on) and the deployment's DPPAN_VISUAL_MAX_FRAMES. Absent for images |
audio | The model makes a soundtrack with its video, kept in the file unless a request sends audio: false. Absent means it makes none. Any video model also takes a soundtrack from an artifact: see Video › Sound |
ranges | The highest value a request may set for steps (max_steps), cfg (max_cfg), flow_shift (max_flow_shift), fps (max_fps), a LoRA's strength (max_lora_strength, from minus it) and control_strength (max_control_strength); steps and fps start at 1, the others above 0. A value outside is refused with the range. Absent on an upscaler |
voice | The model makes the person in its start image speak a voice it is given (Wan 2.2 S2V): a request needs image_artifact (the portrait) and audio_artifact (the voice, also the clip's sound), and max_frames is that of one clip. input_modalities then includes audio. Absent otherwise: see Video › Making a person speak |
frame_step, min_frames | A video model whose lengths are fixed makes only min_frames, then every frame_step frames more: MiniMax-H3's are 5, 22, 39, 56… A request for another count is refused, so offer only these. Absent means any count |
locked | The model's schedule is fixed: a request that sets steps, cfg, sampler or flow_shift is refused. Hide those controls |
steps, cfg | What a job samples with when the request does not say |
sampler, flow_shift, negative_prompt | The model's defaults; absent means the model has no preset and its usual default applies |
loras | LoRA names a request may use. Absent when the model has none |
strength | The img2img default, present only on an image model that takes a start image |
start_image, end_image | A start image (an image to change, or a video's first frame) and a video's last frame are accepted. Absent means not |
ref_images | The most reference images the model edits from. Absent means none |
control | Wan VACE: how a control video may be followed — depth, canny, grey, plain — the default first. Absent means it follows none; present, input_modalities includes video |
default_loras | LoRAs the model applies to every job (a fast variant's distillation LoRA). Shown, not offered: a request may not name one |
Offer an input only where its field is present: a start image, last frame or reference the model would ignore is refused, not dropped. The request fields these map to are under Image and video settings › Parameters.
An empty generators list is the honest answer for a deployment with no generator, and a client should render it as such rather than offering a form whose submission cannot succeed.
POST /v1/generations
Body
{
"model": "qwen3-tts",
"modality": "audio",
"params": { "text": "Hello world" },
"seed": 42,
"input_artifacts": ["1deaf021-..."],
"idempotency_key": "submit-1",
"deadline_seconds": 120
}modality is audio, image, video, or text. text runs the arrow the other way — media in, an answer out — and is documented under Understanding below. params is generator-specific and passed through untouched; the image and video fields are under Image and video settings › Parameters. input_artifacts are artifact IDs consumed as input — a speaker reference for voice cloning, the clip an understanding job reads. Image and video jobs name their input images in params instead (image_artifact, ref_artifacts), because each image has a role; their params.node chooses the machine that makes them (see On other machines), and the job's node_name says which node did, absent when it was the orchestrator's own. Submitting the same idempotency_key twice returns the first job rather than queueing a second. deadline_seconds sets the job's deadline, counted from submission, at most 24 hours. Without it, image, video, music and f5 speech jobs get a time limit when they start running (for images and video, DPPAN_VISUAL_DEADLINE_MINUTES), and expires_at is empty until then; other jobs get DPPAN_JOB_DEADLINE_MINUTES from submission.
Response 202 — the job is durably queued, not finished.
{
"id": "9f1c...", "state": "queued", "modality": "audio", "model": "qwen3-tts",
"seed": 42, "input_artifacts": [], "output_artifacts": [],
"progress_stage": null, "progress_fraction": null,
"error_code": null, "error_message": null,
"created_at": "2026-08-06T09:14:22.981Z", "started_at": null,
"completed_at": null, "expires_at": "2026-08-06T09:24:22.981Z"
}Errors — 400 malformed request · 409 idempotency-key race · 422 no generator produces this · 429 queue full
Those last two are worth telling apart: 429 is retryable, 422 never will be.
Understanding: media in, text out
Every other generator turns a prompt into bytes. modality: "text" turns bytes into a prompt's answer — describe this photo, transcribe this clip, read this receipt. It is the same queue, the same job record and the same artifact store; only the direction changes.
It is worth knowing when to use this instead of a multimodal chat completion, which reads media too. Chat streams its answer and needs a connection held open. A job does not: it survives a restart, it can be polled or subscribed to later, and it is the right shape for a batch of receipts or a clip that takes a minute to read.
Discovering them. Understanding generators appear in GET /v1/generations/capabilities like any other, with kind: "understand":
{
"modality": "text",
"kind": "understand",
"model": "qwen3vl:4b",
"ready": true,
"input_modalities": ["image", "video"]
}input_modalities is what this model's projector handles, so a file picker can refuse a clip before it becomes a job that fails on load. An OCR checkpoint lists image and no audio; Ultravox lists audio and no image.
video appears only when the orchestrator host has ffmpeg on its PATH — the whole container is decoded server-side, because a job has no browser to extract frames the way the chat path does. A model that reads video on a host without ffmpeg simply does not advertise it.
ready says whether the model can serve right now. A model can be installed, multimodal and projector-ready and still be unservable, because nothing has loaded it or the nodes covering its layers are not all connected. Render an unready generator as visible-but-unselectable rather than hiding it: "that model exists and is not up" is a different problem from "not installed", and only one of them is fixed by pulling a model. voices, languages and limits are absent — understanding has no voice to pick and no duration budget.
Submitting one. The media goes in input_artifacts; the question goes in params.prompt. Upload first (POST /v1/files or POST /v1/artifacts), then:
curl -X POST http://localhost:8001/v1/generations \
-H 'Content-Type: application/json' \
-d '{"model":"qwen3vl:4b","modality":"text",
"input_artifacts":["66815206-..."],
"params":{"prompt":"What is the total on this receipt?","max_tokens":512}}'params field | ||
|---|---|---|
prompt | required | What to look for. An empty or absent prompt fails the job rather than guessing — no_prompt |
max_tokens | 1024 | Longest answer to generate |
thinking | model default | true or false. Absent leaves the model's own setting. Worth sending false to a reasoning model asked to read a receipt, which will otherwise spend much of the budget deciding how to read it |
More than one input artifact is allowed and order is preserved — the media is sent in the order given, with the prompt last, which is the order these templates render. Each input is capped at 64 MiB.
Response. A 202 with the usual job record, modality reading "text". When it completes, output_artifacts[0] is a single text/plain artifact (capped at 4 MiB) that you fetch from GET /v1/artifacts/:id. Progress reports three stages — reading input, understanding, publishing — over GET /v1/generations/:id/events.
The artifact holds the answer alone. A reasoning model's thinking is taken out, as it is from a chat reply, and not kept. If the model spends all of max_tokens thinking and gives no answer, the job fails with no_answer.
Job errors — reported in error_code on the job record, not as an HTTP status, because they happen after the 202:
| code | |
|---|---|
no_prompt | params.prompt was empty or absent |
no_input | no input_artifacts were given |
input_unreadable | an input artifact is gone, or its bytes could not be read |
input_too_large | an input exceeds 64 MiB |
unsupported_input | this model cannot read that media type, or a video was sent to a host with no ffmpeg |
inference_failed | the model is not loaded, its node chain is incomplete, or generation failed |
no_answer | the model spent all of max_tokens thinking and gave no answer: raise max_tokens, or send "thinking": false |
publish_failed | the answer could not be written to the artifact store |
GET /v1/generations
The caller's own jobs, newest first. ?limit= (default 100, max 1000), ?offset= (default 0).
output_artifacts here lists only artifacts that still exist. A job record outlives the bytes it produced — artifacts expire, and they can be deleted directly — so this endpoint resolves each one against the store and reports what is actually left, with artifacts_deleted counting what is not:
{ "id": "…", "state": "completed", "output_artifacts": [], "artifacts_deleted": 1,
"params": { "text": "hello world" } }That row is not a failure: error_code is null, the prompt is intact, and it can be regenerated. Distinguishing it from a job that never produced anything is the whole reason the field exists — a client that shows a player for a completed job without checking will render a dead control. The dashboard hides these rows on the Generate page and surfaces them under Admin → Storage, where they can be cleared.
Resolution happens on the LISTING only. GET /v1/generations/:id is polled once a second by every open tab, and a store lookup there would multiply the cost of watching a job by the number of watchers to answer a question that only matters once it has finished — so a single job's artifacts_deleted is always 0.
GET /v1/generations/:id
Poll one job. state is queued, running, completed, failed, cancelled, or expired; only completed populates output_artifacts, which are ordinary artifact IDs fetched through GET /v1/artifacts/:id. A finished job can carry notes: something worth knowing about how it ran though it succeeded, such as a video decoded in tiles, which is slower, and what avoids it. Absent when there is nothing to say.
GET /v1/generations/:id/events
Live progress as Server-Sent Events, instead of polling. Each data: line is the same JSON GET /v1/generations/:id returns, sent when something changes; the stream ends with data: [DONE].
curl -N http://localhost:9000/v1/generations/$JOB/eventsdata: {"state":"queued", ...}
data: {"state":"running","progress_stage":"loading","progress_fraction":0.0, ...}
data: {"state":"running","progress_stage":"generating","progress_fraction":0.57, ...}
data: {"state":"completed","progress_stage":"publishing","progress_fraction":1.0, ...}
data: [DONE]The current state is sent immediately on connect, so attaching to a job that already finished returns its outcome and closes rather than hanging.
Disconnecting does not cancel the job. Watching and controlling are separate: closing a tab or losing a connection leaves the work running, and you can re-attach later or fall back to GET /v1/generations/:id. Use DELETE to actually stop it.
Any peer can serve any job's stream — progress is read from the shared job store, not from an in-process subscription, so it does not matter which orchestrator is running the job.
Errors — 400 malformed id · 404 unknown or not yours · 503 generation not configured. These arrive as status codes before the stream opens, never as an event payload.
GET /v1/generations/:id/preview
The newest live preview of a running image or video job, as a PNG — for a video, its middle frame. It is refreshed after every sampling step, so fetch it again whenever the job's progress changes, on the event stream or by polling.
curl -s -D - -o preview.png http://localhost:9000/v1/generations/$JOB/preview| Header | |
|---|---|
Content-Type | image/png |
X-Preview-Step | The sampling step the preview shows |
Cache-Control | no-store |
Previews live in memory for a running job only. Once it ends, its output is the result, fetched through output_artifacts.
Errors — 400 malformed id · 404 unknown or not yours, or no preview right now (before the first step, after the job ends, or a generator that makes none) · 503 generation not configured
DELETE /v1/generations/:id
Cancel. Returns the job rather than 204, so the caller sees which state it settled in without polling again — a cancel racing a finishing job may land as completed.
Cancellation reaches a running generator: generators stop between frames rather than being killed, so nothing is left half-written.
Errors — 404 unknown or not yours · 409 already finished (the job is still readable via GET, which is why this is not a 404)
DELETE /admin/generations/:id (admin)
Destroy a job record, and by default the artifacts it produced.
Admin-gated while DELETE /v1/generations/:id on the same resource is not, and the asymmetry is the point: cancelling stops work the caller started and leaves the record; this erases the record itself — the prompt, the parameters, the fact that it ever ran. Nothing else in the API can do that, and nothing undoes it.
Query — artifacts (default true). artifacts=false keeps the bytes and removes only the record, which is the exact inverse of DELETE /v1/artifacts/:id. Between the two, either half of a generation can be dropped alone.
curl -X DELETE -H "X-Admin-Token: $TOKEN" \
"http://localhost:9000/admin/generations/$JOB?artifacts=false"Response 200
{ "id": "441b638c-…", "artifacts_deleted": 1 }A missing artifact is not an error — the caller asked for it gone and it is gone — so artifacts_deleted can be lower than the job's original output count.
Errors — 401 bad or missing token · 404 unknown or not yours · 409 the job is still queued or running (a worker is writing to that record; cancel it first) · 503 no admin token configured on this deployment · 500artifacts=true on a deployment with no artifact store, which is refused rather than silently reporting the bytes deleted
Artifacts
Durable blobs the orchestrator keeps beyond a single request — an upload you reference later by ID, or bytes a generator produced. Text nodes never receive them. See Artifacts for how they are kept.
Ownership follows the deployment: on your own orchestrator every request has the same owner; a deployment with sign-in keeps each account's artifacts apart, and answers a request without a session with 401. A missing artifact and another owner's artifact both return 404.
If artifact storage is not configured, every endpoint here returns 503.
POST /v1/artifacts
Upload an artifact. The body is streamed; Content-Type is recorded as the media type and defaults to application/octet-stream. A single upload is capped at 512 MiB.
Response 201
{
"id": "1deaf021-07a3-407c-9d6f-1af47c23db18",
"media_type": "audio/wav",
"size_bytes": 40000,
"digest": "5327345f0dc6d1c5dc69b1edbd486188bf47ee65bf3ecb4e6168e3072cc45b1b",
"state": "ready",
"created_at": "2026-08-06T09:14:22.981Z",
"expires_at": null
}digest is SHA-256 of the full object. state is pending, ready, or failed; only ready artifacts are readable.
Errors — 413 body over the per-request cap · 507 owner quota exhausted
GET /v1/artifacts
List the caller's own artifacts, newest first.
Query — limit (default 100, max 1000) · offset (default 0) · kind (generated | uploaded; absent lists both)
kind splits the store by origin, which each artifact records at creation: uploaded for anything a person sent — through either the Files API or POST /v1/artifacts — and generated for what a job produced. Pages, counts and totals all follow the filter. An unrecognised value lists both.
Response 200
{
"artifacts": [
{ "id": "1deaf021-...", "media_type": "audio/wav", "size_bytes": 40000,
"digest": "5327345f...", "state": "ready",
"created_at": "2026-08-06T09:14:22.981Z", "expires_at": null,
"filename": "my-voice.wav", "purpose": "user_data" }
],
"truncated": false
}filename and purpose are present only for artifacts uploaded through the Files API; anything created natively has neither. They are display metadata, not the origin discriminator — use kind for that.
truncated says the server had more than it returned — walk the rest with offset. Use GET /v1/artifacts/usage for totals: summing pages understates them, and is wrong the moment anything is deleted mid-walk.
Ordering is (created_at DESC, id DESC). The tie-break on id is what makes offset safe: two artifacts written in the same millisecond would otherwise be free to swap places between requests, showing one twice and hiding the other.
GET /v1/artifacts/usage
How much this caller is storing, and what it is measured against.
Response 200
{ "bytes": 43219872, "objects": 37, "max_bytes": 0, "max_objects": 0,
"generated": { "bytes": 42100000, "objects": 34 },
"uploaded": { "bytes": 1119872, "objects": 3 } }generated and uploaded are the same totals split by origin, and they sum to the top-level pair. They are here so each half of a management view can state its own size without walking its pages — and so a bulk delete can say what it will free before it starts, which is the difference between "delete everything" and "delete all 34 files (42.1 MB)".
max_bytes and max_objects are 0 when no ceiling is configured, which is the self-hosted default. default_ttl_hours is present only when DPPAN_ARTIFACT_TTL_HOURS is set; its absence means artifacts are kept until deleted explicitly and nothing is swept.
The counts cover all your artifacts, not just one page of the list.
GET /v1/artifacts/:id
Stream the bytes. Responds with Accept-Ranges: bytes.
Supply Range: bytes=<start>-<end> for a partial read; the response is 206 with a Content-Range header. Single ranges only — multi-range (bytes=0-9,20-29) and suffix (bytes=-500) requests return 416 rather than being partially honoured.
Errors — 400 malformed ID or range · 404 unknown or not yours · 409 artifact is not ready · 416 range outside the object
GET /v1/artifacts/:id/meta
Metadata only; same body shape as the upload response.
DELETE /v1/artifacts/:id
Remove bytes and metadata.
Response 204 — no body. 404 if it does not exist or is not yours.