---
title: "Start a tool on files"
method: POST
path: "/api/v1/jobs"
tags: ["Jobs"]
---

# Start a tool on files

`POST /api/v1/jobs`

## Request

- Base URL: `https://audo.ai`
- URL: `https://audo.ai/api/v1/jobs`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Secure-audo.session_token`

The body is the tool's ID and its input in snake_case, such as {"tool": "remove_noise", "file_id": "file_8Kc2QmP4", "idempotency_key": "<a new UUID>"}. The price is reserved now and charged only if the job succeeds. Add max_credits to cap it, or "free": true for the free part. The Idempotency-Key header works in place of idempotency_key.

## Request body

- union
  - object
    - `file_id` string, required: The recording, audio or video, such as file_8Kc2QmP4.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `noise_reduction` integer: How much of the noise to turn down, as a percentage. 100 turns down all it can; lower values keep some of the background. Default 100.
    - `auto_volume` boolean: Sets the whole file to -16 LUFS with one gain, and limits peaks to -1 dBTP. It doesn't balance loud and quiet speakers. Default true.
    - `output_format` 'same' | 'wav' | 'mp3' | 'm4a' | 'flac': The result's format: same (as the input; a video stays a video), wav, mp3, m4a, or flac. Default same.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first minute, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first minute free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'remove_noise', required
  - object
    - `file_id` string, required: The recording, audio or video, such as file_8Kc2QmP4.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `noise_reduction` integer: How much of the regenerated voice to use, as a percentage. 100 uses all of it; lower values mix back some of the original sound. Default 100.
    - `auto_volume` boolean: Sets the whole file to -16 LUFS with one gain, and limits peaks to -1 dBTP. It doesn't balance loud and quiet speakers. Default true.
    - `output_format` 'same' | 'wav' | 'mp3' | 'm4a' | 'flac': The result's format: same (as the input; a video stays a video), wav, mp3, m4a, or flac. Default same.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first minute, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first minute free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'enhance_voice', required
  - object
    - `file_id` string, required: The recording, audio or video, such as file_8Kc2QmP4.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `language` string: The spoken language, as a code such as en or ja. Default: detected.
    - `verbatim` boolean: Keeps filler words such as um and uh, so they can be cut later. Default true.
    - `speaker_labels` boolean: Labels who speaks when: Speaker 1, Speaker 2, and so on, in the order they first speak, up to 8 people. No names. Default true.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first 2 minutes, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first 2 minutes free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'transcribe_audio', required
  - object
    - `file_id` string, required: The recording, audio or video, such as file_8Kc2QmP4.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `text` string: The script as plain text, SRT, or VTT, up to 2 MB, such as "Welcome back to the show." Pass text or script_file_id, not both.
    - `script_file_id` string: An uploaded script file (TXT, SRT, or VTT), such as file_3Jd9RtY2. Pass text or script_file_id, not both.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first 2 minutes, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first 2 minutes free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'align_script', required
  - object
    - `file_id` string, required: The recording, audio or video, such as file_8Kc2QmP4.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `mode` 'remove' | 'keep': remove deletes the ranges; keep keeps only the ranges. Default remove.
    - `output` 'joined' | 'separate': joined makes one file; separate makes one file per range. Default joined.
    - `crossfade_ms` integer: A crossfade at each cut, in milliseconds (0 to 200), such as 20. Default 20.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first hour, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first hour free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'cut_audio', required
  - object
    - `file_id` string, required: The recording, audio or video, such as file_8Kc2QmP4.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `min_pause_seconds` number: Shortens pauses at least this long, in seconds (0.3 to 5), such as 0.7. Default 0.7.
    - `keep_seconds` number: How much of each pause to keep, in seconds (0 to 1), such as 0.25. Default 0.25.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first hour, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first hour free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'remove_silence', required
  - object
    - `file_id` string, required: The recording, audio or video, such as file_8Kc2QmP4.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `target` 'podcast' | 'streaming' | 'broadcast' | 'audiobook' | 'custom': Where it's going: podcast (-16 LUFS), streaming (-14 LUFS), broadcast (-23 LUFS), audiobook (ACX checks), or custom (set custom_lufs). Default podcast.
    - `custom_lufs` number: The loudness for target custom, in LUFS (-30 to -5), such as -18.
    - `output_format` 'same' | 'wav' | 'mp3' | 'm4a' | 'flac': The result's format: same (as the input; a video stays a video), wav, mp3, m4a, or flac. Default same.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first hour, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first hour free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'adjust_loudness', required
  - object
    - `file_id` string, required: The file to convert, audio or video, such as file_8Kc2QmP4.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `format` 'mp3' | 'wav' | 'm4a' | 'flac' | 'ogg' | 'opus': The format to convert to: mp3, wav, m4a, flac, ogg, or opus. Default mp3.
    - `bitrate_kbps` integer: The bitrate for mp3, m4a, ogg, or opus, in kbps (16 to 320), such as 128. Default: chosen for the format.
    - `sample_rate` 8000 | 16000 | 22050 | 24000 | 32000 | 44100 | 48000: The sample rate in Hz, such as 44100. Default: the input's.
    - `channels` 'mono' | 'stereo': mono or stereo. Default: the input's.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first hour, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first hour free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'convert_audio', required
  - object
    - `file_ids` string[], required: The files to join, in order, such as ["file_8Kc2QmP4", "file_3Jd9RtY2"]. 2 to 20 files.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `crossfade_ms` integer: A crossfade between files, in milliseconds (0 to 5000), such as 500. Default 0.
    - `match_loudness` boolean: Matches the files' loudness before joining. Default true.
    - `output_format` 'same' | 'wav' | 'mp3' | 'm4a' | 'flac': The result's format: same (as the first file), wav, mp3, m4a, or flac. Default same.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first hour of the result, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first hour of the result free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'join_audio', required
  - object
    - `video_file_id` string, required: The video that gets the new soundtrack, such as file_8Kc2QmP4.
    - `audio_file_id` string, required: The new soundtrack, such as file_3Jd9RtY2.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `offset_seconds` number: When the new audio starts against the picture, in seconds, such as 0.5 (later) or -0.5 (earlier). Default 0.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first hour, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first hour free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'replace_audio', required
  - object
    - `file_id` string, required: The file to inspect, audio or video, such as file_8Kc2QmP4.
    - `detail` 'concise' | 'full': concise lists up to 50 silent stretches; full lists them all. Default concise.
    - `tool` 'analyze_audio', required
  - object
    - `file_id` string, required: The recording, audio or video, such as file_8Kc2QmP4.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `transcript_file_id` string: A verbatim transcript of this recording: the JSON file from transcribe_audio or an earlier remove_fillers run, such as file_3Jd9RtY2. It isn't transcribed again, so the job costs 1 credit a minute instead of 2. Needed with cut_ids.
    - `dry_run` boolean: true lists the cuts it would make, with their IDs, and makes no audio. Default false.
    - `cut_ids` string[]: Makes only these cuts, by ID from a dry run of the same transcript, such as ["c1", "c4"]. Needs transcript_file_id. Default: every cut.
    - `repeats` boolean: Also cuts a word or phrase of up to 3 words said twice in a row, keeping the second ("the the" becomes "the"). Default true.
    - `language` string: The spoken language, as a code such as en or de. It picks the filler words: en, de, fr, es, it, nl, ja, or ko. Default: detected.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first 2 minutes, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first 2 minutes free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'remove_fillers', required
  - object
    - `file_id` string: One recording with everyone in it, audio or video, such as file_8Kc2QmP4. Pass file_id or track_file_ids, not both.
    - `track_file_ids` string[]: Per-person tracks instead, one speaker each, such as ["file_8Kc2QmP4", "file_3Jd9RtY2"]. 2 to 10 tracks; each comes back leveled as its own file.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `target` 'podcast' | 'streaming' | 'broadcast' | 'custom': The loudness it finishes at: podcast (-16 LUFS), streaming (-14 LUFS), broadcast (-23 LUFS), or custom (set custom_lufs). Default podcast.
    - `custom_lufs` number: The loudness for target custom, in LUFS (-30 to -5), such as -18.
    - `within_speaker` boolean: Also evens out slow changes within each speaker, such as leaning away from the mic: up to 6 dB, measured on their speech only and held through pauses. Default false.
    - `output_format` 'same' | 'wav' | 'mp3' | 'm4a' | 'flac': The result's format: same (as the input; a video stays a video), wav, mp3, m4a, or flac. Default same.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first 3 minutes, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first 3 minutes free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'level_speakers', required
  - object
    - `tracks` object[], required: The tracks, such as [{"file_id": "file_8Kc2QmP4", "role": "voice"}, {"file_id": "file_3Jd9RtY2", "role": "music", "volume_db": -6}]. 2 to 20.
      - `file_id` string, required: The track, such as file_8Kc2QmP4.
      - `volume_db` number: The track's volume change in dB (-60 to 24), such as -12. Default 0.
      - `start_seconds` number: Where the track starts in the mix, in seconds, such as 4.5. Default 0. With align, only the earliest aligned track's is used.
      - `role` 'voice' | 'music': voice or music: align lines up voice tracks, and duck lowers music under voice. Default none.
    - `idempotency_key` string, required: A new random key for this request, such as a UUID. Reuse it only to retry the same request, so it's never charged twice.
    - `align` boolean: Lines up tracks recorded at the same time (the voice tracks, or every track when none has a role) by their sound, and corrects clock drift. Default false.
    - `duck` boolean: Lowers music tracks while a voice track speaks. Needs a voice and a music track. Default false.
    - `duck_gap_lu` number: With duck, how far under the speech the music sits, in LU (6 to 30), such as 12. Default 12.
    - `loudness` 'none' | 'podcast' | 'streaming' | 'broadcast': A loudness for the mix: none (the tracks as set, lowered only if it would clip), podcast (-16 LUFS), streaming (-14), or broadcast (-23). Default none.
    - `output_format` 'same' | 'wav' | 'mp3' | 'm4a' | 'flac': The mix's format: same (as the first track's audio), wav, mp3, m4a, or flac. Default same.
    - `max_credits` integer: The most this job may cost, in credits (1 credit is 1 US cent), such as 200. A job that would cost more doesn't start.
    - `free` boolean: true processes only the first 3 minutes of the mix, at no cost, a few times a day. false always processes the whole file with credits. Left out, the whole file when the balance covers it, otherwise the first 3 minutes of the mix free if quota is available (otherwise insufficient_balance / 402). true with exhausted quota returns free_limit_reached / 429; false with insufficient balance returns 402, without fallback.
    - `tool` 'mix_tracks', required

## Response `201`

OK

- object
  - `id` string, required
  - `tool` 'remove_noise' | 'enhance_voice' | 'transcribe_audio' | 'align_script' | 'cut_audio' | 'remove_silence' | 'adjust_loudness' | 'convert_audio' | 'join_audio' | 'replace_audio' | 'analyze_audio' | 'remove_fillers' | 'level_speakers' | 'mix_tracks', required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'held', required
  - `progress` integer, required: How much of the job is done, from 0 to 100. It never goes down, and its first part is the time a job usually takes to start
  - `stage` 'queued' | 'preparing' | 'processing' | 'finishing' | 'succeeded' | 'failed' | 'cancelled' | 'held', required: Where the job is: queued (not started yet, perhaps behind the account's other running jobs), preparing (getting the file ready), processing (the tool's work), finishing (saving the result), then succeeded, failed, or cancelled; or held (waiting for payment: see finishUrl)
  - `estimatedSecondsLeft` integer, nullable, required: About how many seconds the job has left, from the file's length and how fast the tool runs, refined as it goes. A rough guide. Null while it's queued, while Audo is busy (waitingForWorker), and once it has ended
  - `waitingForWorker` boolean, required: True while a running job has waited in line longer than a start usually takes: Audo is busy, and the job carries on as soon as there's room. A free job also waits behind paid ones, so it can wait longer; jobs with credits go first
  - `inputFileIds` string[], required: The main input first
  - `outputFileIds` string[], required: The main output first, once the job succeeds
  - `free` boolean, required: A free job processes only the first part of its input, at no cost
  - `processedSeconds` number, required: How much of the input the job processes
  - `quotedCredits` integer, required
  - `chargedCredits` integer, nullable, required: Set when the job succeeds
  - `result` object, nullable, required: The tool's details, such as loudness before and after
  - `error` object, nullable, required
    - `code` string, required
    - `message` string, required
  - `createdAt` string, required: ISO 8601 time
  - `startedAt` string, nullable, required: ISO 8601 time
  - `finishedAt` string, nullable, required: ISO 8601 time
  - `finishUrl` string, nullable: A job held for payment: the page where the whole file can run, or null once its files are gone

## Other responses

- `default`: An error, with what went wrong and what to do next

---

[API](https://skmtc.dev/audo/apis/audo-api.md) · [All operations](https://skmtc.dev/audo/apis/audo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/audo/apis/audo-api/revisions/0800e93224eb?raw)