Audio and images API
Base URL and authentication are on the REST API overview.
Audio (OpenAI-compatible)
POST /v1/audio/speech
A thin adapter over /v1/generations — same queue, same ownership, same limits. Point an OpenAI client at this base URL and audio.speech.create() works.
Body
{ "model": "qwen3-tts", "input": "Hello world", "voice": "warm" }model and input are required. Whether a speaker source is also required depends on the model — requires_speaker in capabilities answers it. Qwen3-TTS Base needs one: either a configured voice or speaker_artifact, the ID of an uploaded clip to clone. Orpheus and Qwen3-TTS CustomVoice need none, and refuse a clip if sent one; their voice names a speaker built into the checkpoint. IndicF5 needs speaker_artifact and reference_text, the clip's exact transcript — requires_reference_text in capabilities says so. language (a hint the model may ignore), instruct (a sentence of style direction, which only the instruction-tuned checkpoints act on) and max_duration_seconds (a ceiling on the finished audio, however long the text is) are the other DPPAN extensions.
Response 200 — the audio itself, not JSON.
content-type: audio/wav
x-dppan-artifact-id: 34c7dd29-...
x-dppan-job-id: 441b638c-...The artifact outlives the response, so you can re-fetch it from /v1/artifacts/:id instead of regenerating.
Where compatibility stops
| Field | Behaviour |
|---|---|
response_format | Only wav. Asking for mp3/opus/aac/flac returns 400 rather than WAV bytes labelled as mp3 — a client trusting the Content-Type would otherwise write a file that does not play. Omitting it gives wav. |
voice | Works, but names a voice this deployment configured or one built into the checkpoint — not OpenAI's alloy/echo/…, which do not exist here. An unknown name is refused, listing what does exist. With neither kind available there is nothing to select and any value is refused. GET /v1/generations/capabilities lists both. |
speed | Honoured by a generator that declares a speed_range in capabilities — IndicF5, 0.3–2.0 — where it divides the generated duration (2.0 is twice as fast); outside the range is a 400. Every other generator has no duration control and no resampling in this build, so for them it is accepted and ignored. max_duration_seconds truncates the finished audio, which is a different thing from speaking it faster. |
Errors — 400 bad request or unavailable format · 422 no generator · 429 queue full · 503 generation or artifact storage not configured · 504 the wait ran out
The 504 is not a lost request: the job keeps running and the message carries its ID, so poll GET /v1/generations/:id. The wait is bounded by DPPAN_SPEECH_SYNC_TIMEOUT_SECS (default 120). Anything genuinely long-running belongs on the native async API — this endpoint is a convenience over it.
POST /v1/audio/music
Generate a song. Same queue and same ownership as speech, and like speech it is an adapter over /v1/generations.
Body
{
"model": "minimax-music3",
"input": "warm lo-fi hip hop, dusty piano, vinyl crackle",
"lyrics": "[verse]\nlate night on an empty street\n",
"duration_seconds": 30
}| Field | |
|---|---|
model | required — the generator's name, from capabilities. This is the bundle directory's name, e.g. minimax-music3, not the pipeline |
input | required — the style prompt: genre, instruments, mood, tempo |
lyrics | optional for most models; required by some, which need [verse] / [chorus] headers to structure the song. Omit it for an instrumental |
duration_seconds | clamped to the deployment's ceiling rather than refused |
steps | solver steps. Higher is slower and cleaner; the default is the one the model was tuned for |
stems | mix (default), vocal, or instrumental. Only some models can separate — supports_stems in capabilities says which, and the rest refuse anything but mix |
response_format | wav only |
Response 200 — the audio itself, with the same x-dppan-artifact-id / x-dppan-job-id headers as speech, and the same re-fetch from /v1/artifacts/:id.
Sample rate and channel count are properties of the model, not of this API — read them from the WAV header rather than assuming; supported models differ.
Expect a 504, and treat it as normal. A song is minutes of compute, so the bounded wait will usually run out and hand back a job id. That is not a failed request — the job keeps running, and GET /v1/generations/:id reports its progress. DPPAN_MUSIC_SYNC_TIMEOUT_SECS bounds the wait. For anything but a short clip, use POST /v1/generations directly rather than holding a connection open.
Progress arrives as a named phase, not a percentage — a song writes, then solves, then decodes, and those cost very different amounts, so a single fraction would sit near the end for most of the wall clock. Show the phase name.
Errors — 400 bad request · 422 no music generator configured, or the model cannot do what was asked (stems it does not separate; lyrics it requires and did not get) · 429 queue full · 503 generation or artifact storage not configured · 504 the wait ran out
POST /v1/audio/transcriptions
Turn a clip into text. Multipart, as OpenAI specifies, and an adapter over the same understanding job the dashboard uses — so the decode runs on the node chain like any other inference, not on the orchestrator.
Body — multipart/form-data
curl -X POST http://localhost:8000/v1/audio/transcriptions \
-F "[email protected];type=audio/wav" \
-F "model=qwen3-asr:1.7b"| Field | |
|---|---|
file | required — the clip. Send a Content-Type on the part; it is what the container is decided from, and a part without one is refused |
model | required — an understanding generator whose input_modalities include audio, from capabilities |
response_format | json (default) or text |
prompt | optional. A dedicated ASR model ignores it; it is passed through for models that read it |
language | a hallucination filter, not a hint — a transcript the model reports as a different language comes back empty. Omit to keep whatever it detects |
temperature | accepted and ignored — transcription runs greedy |
Audio formats — audio/wav, audio/x-wav, audio/wave, audio/vnd.wave, audio/mpeg, audio/mp3. Anything else is refused before the upload rather than accepted and failed inside a job. Note that browser MediaRecorder output is audio/webm or audio/mp4, neither of which is on that list — encode to WAV client-side.
Response 200
{ "text": "With this, Matthew's companion stopped talking." }response_format=text returns the bare transcript as text/plain. Both carry x-dppan-artifact-id and x-dppan-job-id, so a caller can re-fetch the transcript from /v1/artifacts/:id without transcribing again.
verbose_json is refused, deliberately. It promises language, duration and per-segment timestamps. This path produces a flat transcript and has none of them, and returning the envelope with those fields missing or invented is worse than an error — a client keying on segments cannot tell the difference. srt and vtt are refused for the same reason.
Errors — 400 bad request (no model, no file, a container that cannot be decoded, an unsupported response_format) · 413 clip over 64 MiB · 429 queue full · 503 generation or artifact storage not configured · 504 the wait ran out, with the job id to poll
Images (OpenAI-compatible)
OpenAI's Images API over /v1/generations: an OpenAI client, or Open WebUI's image settings with this server as the base URL, makes images here unchanged. Each image is one image job with its seed recorded, so it appears in GET /v1/generations and can be made again. Errors come in OpenAI's envelope, {"error": {"message": …, "type": …}}.
POST /v1/images/generations
{ "model": "z-image-turbo", "prompt": "a red fox in fresh snow", "n": 2, "size": "1024x768" }prompt is required. Without model the first installed image model is used; an upscaler is not one. Response 200:
{ "created": 1793000000, "size": "1024x768", "output_format": "png",
"data": [ { "b64_json": "iVBORw0…" }, { "b64_json": "iVBORw0…" } ] }| Field | |
|---|---|
size | WIDTHxHEIGHT, or auto for the model's own size. The model's rules apply: a size off its grid is a 400 naming the nearest |
n | 1 to 10. That many jobs, which run on several machines at once when nodes hold the model |
response_format | b64_json (default) or url, the image's artifact on this server, fetched with the same credentials |
seed | DPPAN extension: the first image's seed, each next one the next. Absent, a random one, recorded on the job |
negative_prompt | DPPAN extension |
output_format | png only: jpeg and webp are a 400 |
background | auto or opaque; transparent is a 400, as no model here makes one |
quality, style, moderation, user, … | Accepted and ignored |
POST /v1/images/edits
Multipart, as OpenAI's: image (or image[], repeated), an optional mask, prompt, and the fields above. Images are PNG, JPEG or WebP, each with its Content-Type, up to 32 MiB.
- With a
mask, one image is changed where the mask allows (inpainting), at the mask's size, which must be the image's. As OpenAI's, the mask is transparent where the image changes; a mask with no alpha channel is read as white where it changes. - Without one, the images are references for a model that takes them (FLUX 3 Klein and FLUX.2 Klein, up to 4), at the model's size unless
sizesays otherwise. A model without references takes one image, its start image.
Errors — 400 bad request · 404 no such image model, listing those installed · 413 an image over 32 MiB · 429 queue full · 503 generation or artifact storage not configured · 504 the wait ran out, with a job's id to poll. The wait is bounded by DPPAN_IMAGES_SYNC_TIMEOUT_SECS (default 900).