Skip to content

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

json
{ "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

FieldBehaviour
response_formatOnly 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.
voiceWorks, 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.
speedHonoured 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

json
{
  "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
modelrequired — the generator's name, from capabilities. This is the bundle directory's name, e.g. minimax-music3, not the pipeline
inputrequired — the style prompt: genre, instruments, mood, tempo
lyricsoptional for most models; required by some, which need [verse] / [chorus] headers to structure the song. Omit it for an instrumental
duration_secondsclamped to the deployment's ceiling rather than refused
stepssolver steps. Higher is slower and cleaner; the default is the one the model was tuned for
stemsmix (default), vocal, or instrumental. Only some models can separate — supports_stems in capabilities says which, and the rest refuse anything but mix
response_formatwav 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

bash
curl -X POST http://localhost:8000/v1/audio/transcriptions \
  -F "[email protected];type=audio/wav" \
  -F "model=qwen3-asr:1.7b"
Field
filerequired — the clip. Send a Content-Type on the part; it is what the container is decided from, and a part without one is refused
modelrequired — an understanding generator whose input_modalities include audio, from capabilities
response_formatjson (default) or text
promptoptional. A dedicated ASR model ignores it; it is passed through for models that read it
languagea hallucination filter, not a hint — a transcript the model reports as a different language comes back empty. Omit to keep whatever it detects
temperatureaccepted 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

json
{ "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 ​

json
{ "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:

json
{ "created": 1793000000, "size": "1024x768", "output_format": "png",
  "data": [ { "b64_json": "iVBORw0…" }, { "b64_json": "iVBORw0…" } ] }
Field
sizeWIDTHxHEIGHT, or auto for the model's own size. The model's rules apply: a size off its grid is a 400 naming the nearest
n1 to 10. That many jobs, which run on several machines at once when nodes hold the model
response_formatb64_json (default) or url, the image's artifact on this server, fetched with the same credentials
seedDPPAN extension: the first image's seed, each next one the next. Absent, a random one, recorded on the job
negative_promptDPPAN extension
output_formatpng only: jpeg and webp are a 400
backgroundauto 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 size says 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).

Free to run · Proprietary