Projects

A project is one recording: one file, or two to eight tracks of the same recording (host, guest, …) that are processed together. You create it, put its files in place (upload or import), submit it, and follow it to a delivery.

Creating a project

POST /v1/projects

{
  "name": "Episode 12",
  "clientRef": "ep-12",
  "metadata": { "show": "Acme Weekly" },
  "settings": { "noiseLevel": "n2", "plosivesLevel": "p2", "mergeOutput": false },
  "files": [{ "fileName": "host.wav" }, { "fileName": "guest.wav" }]
}

Field
`files`	1 file: processed alone. 2–8: tracks of one recording. Video files (MP4, AVI, …) can’t be grouped. Each file is an upload (the default) or an import: see Uploads and imports.
`name`	Optional; names the delivery’s zip and folder.
`clientRef`	Your own id, unique within the account. Filter by it: `GET /v1/projects?clientRef=ep-12`.
`metadata`	Up to 20 string keys and values, returned as given.
`settings.noiseLevel`	`n1` light, `n2` medium (default), `n3` strong noise reduction.
`settings.plosivesLevel`	`p1` light, `p2` medium (default), `p3` strong plosive reduction.
`settings.mergeOutput`	Two-track projects only: one merged file instead of two.

Statuses

Status	Meaning
`draft`	Created. Upload (or wait for the imports of) its files, then submit.
`validating`	Submitted: we check every file is in, measure it, apply the rules and charge the credits.
`rejected`	Refused at validation; `rejection` says why. Fix it and submit again.
`queued`	Waiting for the studio. `estimatedCompletionAt` estimates when it’ll be done.
`processing`	Being processed; `progress` says the step and roughly how far along.
`completed`	Done: download the outputs.
`failed`	We couldn’t process it after retrying; its credits were refunded.
`stopped`	Held by our team (rare). It’s queued again or cancelled.
`cancelled`	Cancelled before processing; its credits were refunded.

A project can go back to queued (and processing) when we retry it. Every change is also a webhook event.

Rejections

`rejection.code`	Fix
`upload_missing`	A file wasn’t uploaded. Upload it and submit again.
`unreadable_file`	We couldn’t read a file as audio or video. That file gets a new upload location: upload it again and submit.
`insufficient_credits`	The account doesn’t have enough credits. Buy more (the message names a bundle that covers it) and submit again.
`measurement_unavailable`	We couldn’t check a file just now. Submit again in a minute.
`file_too_large`	Test mode only: a file is over 500 MB.
`test_limit_reached`	Test mode only: today’s test limits are used up.
`import_failed`	An import couldn’t be downloaded; the file’s `importError` says why. Create the project again with a working link.

What it costs

creditsSeconds is the project’s price in credits (seconds of audio): the measured length of all its files, with a small per-project minimum. Every setting costs the same. A live project’s credits are taken when it’s validated and given back if it fails or is cancelled. See Credits.

Following a project

GET /v1/projects/{id}
GET /v1/projects?status=queued&limit=50&cursor=…

Lists are newest first, at most 100 per page; pass nextCursor as cursor for the next page.

estimatedCompletionAt (queued and processing): when we expect it done, from the queue ahead of it and the studio’s capacity. An estimate, refreshed on every read; null while the studio is offline.
progress (processing): step (e.g. “Isolating and enhancing dialogue”), percent, and rate/cap if you animate a progress bar between polls (move at most rate percent per second, never past cap).

Outputs

A completed project has:

downloadUrl: the whole delivery as one zip (a folder named after the project).
outputs: each delivered file (kind: audio, video or transcript) with its own url. Test projects list them today; live projects will shortly (until then, use the zip).
manifestUrl: manifest.json, describing the outputs, the inputs they came from and the settings.

Every link lasts an hour; read the project again for fresh ones. A one-file project delivers <name>_pw_vs.<ext> and <name>_transcript.txt; a multi-track project delivers each track (or one merged file) and a transcript.

Cancelling and deleting files

POST /v1/projects/{id}/cancel: before processing starts (draft, validating, rejected, queued). Charged credits come back.
DELETE /v1/projects/{id}/files: deletes the project’s inputs and outputs from storage now. The project and its usage stay. Everything is deleted after 30 days anyway.