Skip to content

For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/developers/guides/clean-up-a-back-catalogue.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Clean up a back catalogue

Restore every recording in a folder, a few at a time, pick up where a stopped run left off, and total what it used.

How it works

  1. State file → Your script: done files, skipped if digest and output match
  2. Your script → Diffio API: POST /projects, Idempotency-Key from path and content, 3 at a time
  3. Diffio API → Your script: upload or upload: null, null: it already arrived
  4. Your script → Diffio API: GET …/generations/{id}, until complete
  5. Your script → Diffio API: GET …/media, download the restored MP3
  6. Your script → State file: done, after each file
  7. Your script → Diffio API: GET /usage?start=…, the run's total
Stop the script at any point; the next run picks up from the state file and the same keys.

Build it

  1. 1

    One Idempotency-Key per file

    The key hashes the file's relative path with a SHA-256 of its content, under a batch name. Running again finds the same project instead of creating and billing a second one; a changed file gets a new key. Keys belong to your account (and end user, if you send one).

  2. 2

    Skip what already arrived

    A repeated POST /projects answers upload: null once the file has arrived: skip the upload and wait for the project's first generation (latest_generation).

  3. 3

    A few at a time

    Three workers keep uploads and downloads moving without flooding your network; restores queue on Diffio's side (see queue on a generation). Each worker waits at most 2 hours for one file.

  4. 4

    Resume from the state file

    The state file is named after BATCH and the source and target folders, so another batch or folder pair never reuses it (give each source its own target). A file counts as done only when its stored digest matches its content and its output exists; outputs are written to a .part file and renamed. A failed generation fails again with the same key; a new BATCH name starts over with new keys and restores every file again.

  5. 5

    Total the usage

    GET /usage from the first run's start time. It counts the whole account's generations in that period; send Diffio-End-User on the run to count only its own.

The complete script

Pass the folder to read and the folder to write; ep01.wav becomes ep01.wav.restored.mp3 at the same relative path.

What you get

The state after a stopped run and a second run (example)
FileRun 1Run 2
ep01.wavdoneskipped
ep02.wavdoneskipped
ep03.mp3uploaded, then stoppeddone (no second upload)
ep04.mp3not starteddone
ep01.mp3not starteddone (its own output)
  • One .restored.mp3 per recording, named after the whole original file name, so ep.wav and ep.mp3 never collide.
  • No file billed twice: a rerun reuses each unchanged file's project; a changed file is restored again.
  • The run's generations, billable seconds and list price from GET /usage.
Output of python catalogue.py ./archive ./restored (second run)
Terminal
skipped ep01.wav
skipped ep02.wav
done ep03.mp3
done ep01.mp3
done ep04.mp3
since 2026-11-13T09:00:00Z: 5 generations, 14400 s, $20.00 at list price

API reference

  • POSTCreate a project (/projects): Idempotency-Key, generation and upload.
  • GETGet a generation (/projects/{project_id}/generations/{generation_id}): status, stage and queue.
  • GETGet a playback grant (/projects/{project_id}/generations/{generation_id}/media): The restored file.
  • GETGet usage (/usage): Generations, billable seconds and list price.

Report an issue with this page