Create a separation job
https://api.dev.developers.gaudiolab.io/v1/jobsSubmits one asset for separation. List the tracks you want in targets — for example dme_dialogue_v1, dme_music_v1, karaoke_vocal_v1, and stem_bass_v1 in one request. Each target is processed independently and may finish at a different time. The job returns immediately with a jobId; results arrive via webhook or polling.
/jobscurl -X POST "https://api.dev.developers.gaudiolab.io/v1/jobs" \
-H "x-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assetId": "as_7f3a9c",
"targets": [
{
"model": "dme_dialogue_v1",
"tier": "premium",
"formats": [
"wav"
],
"inputs": {
"lyricsAssetId": "as_2b81de"
},
"params": {
"language": "ja",
"syncLevel": "word"
}
}
],
"webhookUrl": "https://..."
}'{
"jobId": "job_91b2e0",
"status": "queued",
"targets": [
{
"model": "dme_dialogue_v1",
"tier": "premium",
"status": "queued"
},
{
"model": "karaoke_vocal_v1",
"status": "queued"
},
{
"model": "stem_bass_v1",
"status": "queued"
}
]
}Headers
x-api-keyRequiredYour project API key, sent on every request. Create and manage keys in the dashboard under Settings → API Keys.
Idempotency-KeystringOptionalA unique key you generate to safely retry this request. If a job was already created with the same key, the original job is returned instead of creating a duplicate.
Request body
assetIdstringRequiredIdentifier of a ready asset to process.
targetsTargetRequest[]RequiredThe separation outputs to produce. Each target runs independently and can complete at a different time.
modelstringRequiredModel alias to run. Examples: dme_dialogue_v1 for DME, stem_vocal_v1 for multi-stem separation, or karaoke_vocal_v1 for instrumental-track separation. See GET /models.
tierenumOptionalProcessing tier for DME separation only. Supported values depend on the selected model; check the model's tiers list in GET /models. Non-DME models reject tier. A tier can also narrow what the model accepts — see tier_overrides in GET /models.
Allowed values: premiumstandardlive
formatsenum[]RequiredFormats to render this output in. Each format is returned as a separate downloadable file. Which formats a model supports is listed in GET /models: separation models render wav; text_sync models return a single json document.
inputsTargetInputsOptionalAdditional assets this target consumes, beyond the job's assetId. Target-scoped rather than job-scoped: a job can hold targets that need none of these, and the same audio can carry two lyric targets in different languages. Which roles a model requires is declared in GET /models. Each referenced asset must be ready and owned by the caller, and is re-checked when the job leaves the queue.
lyricsAssetIdstringOptionalPlain-text lyric asset, required by text_sync models. UTF-8, one lyric line per line.
paramsobjectOptionalModel-specific parameters. Which keys are valid, their allowed values and any defaults are declared per model in GET /models; unknown keys are rejected. Defaults are applied when the job is accepted, so the job records what it will actually run.
languageenumOptionalLanguage of the lyric. Required by text_sync models.
Allowed values: enkoja
syncLevelenumOptionalword returns per-word timings for karaoke highlighting; line returns line timings only, and its words carry no times.
Allowed values: lineword
webhookUrlstring (uri)OptionalHTTPS endpoint that receives a POST as each target completes. If omitted, poll GET /jobs/{jobId} for results instead.
Response
jobIdstringRequiredUnique identifier for the job.
statusenumRequiredAggregate status across all targets. completed once every target has finished — note an individual target may still have failed.
Allowed values: queuedprocessingcompletedfailed
progressintegerOptionalOverall completion percentage, a rollup across all targets. Only reaches 100 once the job is terminal (completed or failed).
phaseenumOptionalPipeline phase while status is processing: the least-advanced phase across the job's unfinished targets. pending means the job was handed to a worker that has not started reporting yet (capacity placement / cold start). null while queued and once terminal.
Allowed values: pendingstartingdownloadingpreparingprocessinguploadingfinalizing
dispatchedAtstring (date-time)OptionalISO 8601 timestamp when the job left the queue and was handed to a worker. null while queued. Use it to show elapsed processing time.
progressUpdatedAtstring (date-time)OptionalISO 8601 timestamp of the last progress report from the worker. null until the first report. A value that stops advancing while status is processing indicates a worker that is not responding.
estimatedProcessingSecondsintegerOptionalEstimated worker time for this job (seconds), from the source length and recent jobs on the same backend. Advisory; null when the source length is unknown or the job is terminal.
estimatedStartSecondsintegerOptionalFor a queued job, estimated seconds until a worker slot frees on the backend it will run on (global capacity, running jobs' remaining time, queued jobs ahead). Advisory; null unless queued.
linksExpireAtstring (date-time)OptionalISO 8601 timestamp when the download links stop working. Re-fetch the job to refresh them. Links are valid for 48 hours.
targetsTargetResult[]RequiredPer-target results, in the order they were requested.
modelstringRequiredThe model alias this result corresponds to.
tierenumOptionalThe processing tier this target was processed with. Present for DME targets only.
Allowed values: premiumstandardlive
statusenumRequiredStatus of this individual target.
Allowed values: queuedprocessingcompletedfailed
progressintegerOptionalCompletion percentage for this target. A completed target reports 100.
phaseenumOptionalPipeline phase reported by the worker for this target while the job is processing (see Job.phase). pending until the worker's first report; null while queued and once the target is terminal.
Allowed values: pendingstartingdownloadingpreparingprocessinguploadingfinalizing
outputmap<string, map<string, string (uri)>>OptionalDownload links, keyed by stem name and then by format (for example output.dialogue.wav). Present once status is completed.
errorTargetErrorOptionalFailure details. Present only when status is failed.
codeenumRequiredA stable, machine-readable code. New codes may be added over time — treat an unrecognised one as a generic failure and fall back to retryable.
Allowed values: PROCESSING_FAILEDPROCESSING_TIMEOUTQUEUE_TIMEOUTSOURCE_EXPIREDJOB_CANCELLED
messagestringRequiredA human-readable explanation. Fixed per code — safe to show to an end user, but do not parse it or branch on its wording.
retryablebooleanRequiredWhether resubmitting the same source can succeed. true means the failure was transient (an interrupted run, a timeout, or no capacity in time) — retry with backoff. false means retrying changes nothing.
codestringRequiredA stable, machine-readable error code you can branch on.
messagestringRequiredA human-readable explanation of what went wrong.
detailsobjectOptionalMachine-readable specifics for the errors that carry them — for example FEATURE_NOT_ENABLED reports the model that was refused and the feature it belongs to. Absent for errors that add nothing beyond code and message.
codestringRequiredA stable, machine-readable error code you can branch on.
messagestringRequiredA human-readable explanation of what went wrong.
detailsobjectOptionalMachine-readable specifics for the errors that carry them — for example FEATURE_NOT_ENABLED reports the model that was refused and the feature it belongs to. Absent for errors that add nothing beyond code and message.
FEATURE_NOT_ENABLED). details.feature names the model's category. Contact your Gaudio representative to enable it. Entitlements are checked when a job is accepted: a job already accepted before a feature was disabled still runs to completion.codestringRequiredA stable, machine-readable error code you can branch on.
messagestringRequiredA human-readable explanation of what went wrong.
detailsobjectOptionalMachine-readable specifics for the errors that carry them — for example FEATURE_NOT_ENABLED reports the model that was refused and the feature it belongs to. Absent for errors that add nothing beyond code and message.
assetId does not exist or has expired.codestringRequiredA stable, machine-readable error code you can branch on.
messagestringRequiredA human-readable explanation of what went wrong.
detailsobjectOptionalMachine-readable specifics for the errors that carry them — for example FEATURE_NOT_ENABLED reports the model that was refused and the feature it belongs to. Absent for errors that add nothing beyond code and message.
UNSUPPORTED_CHANNELS). Returned when the input is neither mono, stereo, nor an authoritative 5.1 PCM WAV/RF64, or when a 5.1 input is sent to a target that does not accept 5.1.codestringRequiredA stable, machine-readable error code you can branch on.
messagestringRequiredA human-readable explanation of what went wrong.
detailsobjectOptionalMachine-readable specifics for the errors that carry them — for example FEATURE_NOT_ENABLED reports the model that was refused and the feature it belongs to. Absent for errors that add nothing beyond code and message.