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.
Creating a project
Section titled “Creating a project”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 | |
|---|---|
files | The 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. |
submit | Submit it too: at once if its files are ready, otherwise as soon as they are. |
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. |
show | Optional: one of the account’s shows. The project starts with the show’s defaults. |
keep | Optional: keep its files past 30 days. Unsaid: the show’s default, else the account’s. |
deliveries | Optional: destination ids its files are sent to when it completes (Drive and Dropbox). Unsaid: the show’s. |
settings.mergeOutput | Two-track projects only: one merged file instead of two. |
While every file is ready, the draft’s creditsSeconds already says what it will cost.
Statuses
Section titled “Statuses”| Status | Meaning |
|---|---|
draft | Created. Its files, settings and name can change. Submit it when its files are in (or before: it waits). |
validating | Submitted, and waiting for its files to arrive (or be checked). |
rejected | Refused at validation; rejection says why. Change it and submit again. |
queued | Charged and 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. |
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.
Rejections
Section titled “Rejections”rejection.code | Fix |
|---|---|
upload_missing | A file didn’t arrive within 24 hours. Upload it and submit again. |
unreadable_file | We couldn’t read a file as audio or video. Replace it with a working file and submit again. |
file_too_large | Test mode only: a file is over 500 MB. Replace it with a smaller one. |
import_failed | An import couldn’t be downloaded; the file’s error.message says why. Replace it with a working link. |
file_expired | A file was deleted, or is more than 30 days old. Upload it again and put the new file in the project. |
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. |
test_limit_reached | Test mode only: today’s test limits are used up. |
spend_cap_reached, access_revoked | An AI assistant submitted it over its monthly cap, or after it was disconnected. |
Changing a project
Section titled “Changing a project”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).
| Status | name, metadata, clientRef | files, settings, show, testOutcome |
|---|---|---|
draft, rejected | yes | yes |
| anything else | yes | no: 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.
Processing again
Section titled “Processing again”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.
| Situation | What to do | Credits |
|---|---|---|
A wrong setting, still queued | Cancel it, then copy it with the change. | Refunded, then charged for the copy. |
| Other settings or files after it ran | Copy it with the change. | The copy is charged in full; the original’s charge stands. |
It failed | Copy it (or write to us). | The failure was refunded; the copy is charged. |
| The result is wrong because of us | Write to support@podsworth.com with the project id. | We reprocess the same project, free. |
What it costs
Section titled “What it costs”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.
Stereo files with a speaker on each side
Section titled “Stereo files with a speaker on each side”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.
Following a project
Section titled “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.
files: each file, with its status and length (anduploadUrlwhile 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;nullwhile the studio is offline.progress(processing):step(e.g. “Isolating and enhancing dialogue”),percent, andrate/capif you animate a progress bar between polls (move at mostratepercent per second, never pastcap).
Outputs
Section titled “Outputs”A completed project has:
downloadUrl: the whole delivery as one zip (a folder named after the project).outputs: each delivered file (kind:audio,videoortranscript, and itsvariant, below) with its ownurl, then the zip (zip). A live project finished before per-file outputs existed has none (and no manifest): usedownloadUrl.manifestUrl:manifest.json, describing the outputs (with the samevariant), 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:
| Ending | variant | What it is |
|---|---|---|
_pw_vs | vs | The 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_ae | ae | The 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.
Cancelling
Section titled “Cancelling”POST /v1/projects/{id}/cancel: before processing starts (draft, validating, rejected, queued). Charged
credits come back.
Deleting
Section titled “Deleting”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.