Skip to content

Projects

A project is one recording: one file, or two to eight tracks of the same recording (host, guest, …) that are processed together. You make it of files, change it as much as you like while it’s a draft, submit it, and follow it to a delivery.

POST /v1/projects
{
"name": "Episode 12",
"clientRef": "ep-12",
"metadata": { "show": "Acme Weekly" },
"settings": { "mergeOutput": false },
"files": ["file_8c1d4f0e2b7a49d1a3f0", { "fileName": "guest.wav" }],
"submit": true
}
Field
filesThe project’s files in track order. Each is a file’s id (one you already made, uploaded or used before), or a new file: {"fileName": "guest.wav"} to upload, which comes back with its uploadUrl, or {"fileName", "source"} to import (see Files). 1 file: processed alone. 2–8: tracks of one recording. Video files (MP4, AVI, …) can’t be grouped. May be empty while it’s a draft.
submitSubmit it too: at once if its files are ready, otherwise as soon as they are.
nameOptional; names the delivery’s zip and folder.
clientRefYour own id, unique within the account. Filter by it: GET /v1/projects?clientRef=ep-12.
metadataUp to 20 string keys and values, returned as given.
showOptional: one of the account’s shows. The project starts with the show’s defaults.
keepOptional: keep its files past 30 days. Unsaid: the show’s default, else the account’s.
deliveriesOptional: destination ids its files are sent to when it completes (Drive and Dropbox). Unsaid: the show’s.
settings.mergeOutputTwo-track projects only: one merged file instead of two.

While every file is ready, the draft’s creditsSeconds already says what it will cost.

StatusMeaning
draftCreated. Its files, settings and name can change. Submit it when its files are in (or before: it waits).
validatingSubmitted, and waiting for its files to arrive (or be checked).
rejectedRefused at validation; rejection says why. Change it and submit again.
queuedCharged and waiting for the studio. estimatedCompletionAt estimates when it’ll be done.
processingBeing processed; progress says the step and roughly how far along.
completedDone: download the outputs.
failedWe couldn’t process it after retrying; its credits were refunded.
stoppedHeld by our team (rare). It’s queued again or cancelled.
cancelledCancelled before processing; its credits were refunded.

POST /v1/projects/{id}/submit answers with the outcome when it can: if every file is already checked, the project it returns is queued or rejected. Otherwise it’s validating until the files are in (up to 24 hours), then queued or rejected. Either way the outcome is the project’s status and rejection, and every change is also a webhook event. A project can go back to queued (and processing) when we retry it.

rejection.codeFix
upload_missingA file didn’t arrive within 24 hours. Upload it and submit again.
unreadable_fileWe couldn’t read a file as audio or video. Replace it with a working file and submit again.
file_too_largeTest mode only: a file is over 500 MB. Replace it with a smaller one.
import_failedAn import couldn’t be downloaded; the file’s error.message says why. Replace it with a working link.
file_expiredA file was deleted, or is more than 30 days old. Upload it again and put the new file in the project.
insufficient_creditsThe account doesn’t have enough credits. Buy more (the message names a bundle that covers it) and submit again.
measurement_unavailableWe couldn’t check a file just now. Submit again in a minute.
test_limit_reachedTest mode only: today’s test limits are used up.
spend_cap_reached, access_revokedAn AI assistant submitted it over its monthly cap, or after it was disconnected.
PATCH /v1/projects/{id}
{ "files": ["file_8c1d4f0e2b7a49d1a3f0", { "fileName": "guest-take2.wav" }], "settings": { "mergeOutput": true } }

Send only what changes. files is the whole list, in track order: it replaces the project’s (the files taken out stay yours, to use elsewhere or delete).

Statusname, metadata, clientReffiles, settings, show, testOutcome
draft, rejectedyesyes
anything elseyesno: 409 invalid_transition

Once a project is submitted, what it processes doesn’t change. While it’s queued you can cancel it (its credits come back); to process it again, with the same or other settings and files, copy it. name names the outputs, so renaming a project once processing has started doesn’t rename files already made. keep and destinations have their own calls: POST /v1/projects/{id}/keep and POST /v1/projects/{id}/deliveries.

POST /v1/projects/{id}/copy
{ "settings": { "mergeOutput": true }, "submit": true }

A copy is a new project with the same files, settings, name, metadata and show, with the changes you send (any field you’d create a project with, files included). It has copiedFrom, and the original stays exactly as it was: its outputs, its charge and its deliveries. It needs no upload while its files last (30 days after they were uploaded, or for good if the project was kept); after that, put new files in the copy’s files (409 file_expired otherwise). A copy starts without a clientRef, and its Keep and destinations follow the defaults like any new project, unless you send them.

SituationWhat to doCredits
A wrong setting, still queuedCancel it, then copy it with the change.Refunded, then charged for the copy.
Other settings or files after it ranCopy it with the change.The copy is charged in full; the original’s charge stands.
It failedCopy it (or write to us).The failure was refunded; the copy is charged.
The result is wrong because of usWrite to support@podsworth.com with the project id.We reprocess the same project, free.

creditsSeconds is the project’s price in credits (seconds of audio): the measured length of all its tracks, with a small per-project minimum. Every setting costs the same, and both versions of the outputs are included. A live project’s credits are taken when it’s validated and given back if it fails or is cancelled. Each run is charged: a copy costs what a new project would. See Credits.

Some recorders put each mic on its own side of a stereo file: one person on the left, the other on the right. When a file is checked we tell: such a file has twoSpeakers: true, and a project processes it as two tracks, its left side and its right, cleaned separately and mixed into one file. It’s priced as two tracks (twice its length), and a draft’s creditsSeconds already counts both. When you submit, the project’s tracks list them (channel 0 and 1, in the file’s place):

"files": [{ "id": "file_9f2c", "fileName": "interview.wav", "channels": 2, "twoSpeakers": true, … }],
"tracks": [
{ "fileId": "file_9f2c", "name": "interview (left).wav", "channel": 0 },
{ "fileId": "file_9f2c", "name": "interview (right).wav", "channel": 1 }
]

A file on its own becomes a merged 2-track project named after it. In a project with other files, both tracks join it and count toward its 8 tracks (over 8: rejected with too_many_tracks). A stereo file with the same audio on both sides, or one speaker on both, is one track and priced once (twoSpeakers: false); we process its louder side.

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.

  • files: each file, with its status and length (and uploadUrl while it’s waiting for its upload).
  • 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).

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, and its variant, below) with its own url, then the zip (zip). A live project finished before per-file outputs existed has none (and no manifest): use downloadUrl.
  • manifestUrl: manifest.json, describing the outputs (with the same variant), the inputs they came from and the settings.

Every link lasts an hour; read the project again for fresh ones.

Every project comes back in two versions, at no extra cost:

EndingvariantWhat it is
_pw_vsvsThe cleaned audio, its length kept so it lines up with the recording: use it under a video. A video file comes back as video with this audio in it.
_pw_aeaeThe audio edit: the same cleanup with filler words (“um”, “uh”), long pauses, coughs and music cut out. It’s shorter than the recording, so it’s always audio (.wav), even for a video.

A one-file project delivers <name>_pw_vs.<ext> and <name>_pw_ae.wav; a multi-track project delivers each track (or one merged file) in both versions. Each version has its own transcript, timed to its own audio, named after the project like its zip: <project name>_pw_vs_transcript.txt and <project name>_pw_ae_transcript.txt (a project without a name uses its first file’s). In a multi-track transcript each speaker is their track: Track 1 is the project’s first file, Track 2 its second, and so on. The zip and the manifest have no variant (null).

If the audio edit can’t be made for a project, it’s delivered with the _pw_vs files alone (and their transcript); we’re alerted and follow up.

POST /v1/projects/{id}/cancel: before processing starts (draft, validating, rejected, queued). Charged credits come back.

  • DELETE /v1/projects/{id}/outputs: deletes the project’s outputs (and their kept copies) from storage now. The project and its usage stay.
  • DELETE /v1/files/{id}: deletes one of its files (Files).

Everything is deleted after 30 days anyway, unless it’s kept.