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/saas-podcast-cleanup.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Podcast cleanup in a SaaS app

Your users upload episodes from the browser straight to Diffio, your server keeps the API key and each user's projects apart, and a signed webhook tells you when the cleaned audio is ready to play.

How it works

  1. Browser → Your server: POST /api/uploads, file name and size
  2. Your server → Diffio API: POST /projects, Diffio-End-User from your session
  3. Diffio API → Your server: upload, upload_token, upload.requests
  4. Your server → Browser: upload, never the API key
  5. Browser → Media host: start, parts, complete, Bearer upload_token
  6. Browser → Your server: POST …/{id}/complete, your route
  7. Your server → Diffio API: POST …/upload/complete, the restore starts
  8. Diffio API → Your server: generation.completed, signed; matched to one job
  9. Browser → Your server: GET /api/uploads/{id}, your route
  10. Your server → Diffio API: GET …/media, as the signed-in user, 6 hour URLs
Solid arrows are requests and webhook deliveries; dashed arrows are answers.

Build it

  1. 1

    Set up

    Install the SDK and a web framework. Set the API key, the endpoint's whsec_ signing secret (step 4) and a session secret, on the server only.

    Terminal
    pip install diffio flask                     # Python
    npm install diffio express express-session   # or Node.js
    export DIFFIO_API_KEY="diffio_..."
    export DIFFIO_WEBHOOK_SECRET="whsec_..."
    export SESSION_SECRET="..."
  2. 2

    Create the project for the signed-in user

    create_upload takes the user id from your session, never from the request body, and sends it as Diffio-End-User. generation queues the restore now; it starts once the file lands. The browser's upload_key becomes the Idempotency-Key, so a retried request returns the same project. The job row keeps the project, its first generation_id and the user.

  3. 3

    Upload from the browser

    The server returns only upload. The browser follows upload.requests (start, parts, complete) with the upload_token as a bearer token; the media host accepts these four requests from any origin. The token is scoped to this one project's file and works for 24 hours (upload.expires_at); POST .../upload gives a new one. Keep the uploadKey with the file: a retry with the same key gets the same project, and upload: null when its file already arrived.

  4. 4

    Verify and record the webhook

    Open the portal with python app.py portal or node app.mjs portal (an account-wide client, no end user) and add https://your-app.example/webhooks/diffio for generation.completed and generation.failed.

    • Verify the signature with the SDK, on the raw body.
    • One transaction: record event.id (a repeat changes nothing) and update the job.
    • Match the job on data.id = its generation_id and data.end_user = its user. A second restore or an edit of the same project, or another user's event, changes nothing.
    • Answer 204 after the commit, with no API calls in the delivery; an error answers 500 and the delivery is retried.

    Payloads and retries: Webhooks.

  5. 5

    Fetch media on read

    GET /api/uploads/<id> asks Diffio for media as the signed-in user once the job is complete, and again when the stored URL has less than 5 minutes of its 6 hours left.

The complete server

Run it locally: the example folder adds a development sign-in for two users, a page with a file input and player, and a signed sample webhook, with the commands and results to expect.

What you get

A finished Diffio project: the project title, the restored waveform, the play control, the Restored switch and the Background amount slider

Restored by Diffio 4.7 Flash

What a user uploads and gets back: the first 60 seconds of an archival lecture, and the finished project in the Diffio app. How this recording was restored.
  • Each customer's projects live under their own end user: another customer's project id answers 404Not found..
  • Files go from the browser to Diffio; your server never handles the audio.
  • A restored MP3 URL for each finished episode, renewed before its 6 hours run out.
Response of GET /api/uploads/<project_id>
JSON
{
  "status": "complete",
  "error_code": null,
  "audio_url": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3",
  "expires_at": "2026-11-13T06:33:47Z"
}

API reference

  • POSTCreate a project (/projects): Project, first generation and upload descriptors.
  • POSTGet new upload instructions (/projects/{project_id}/upload): A new upload token when the old one expired.
  • POSTComplete a project's upload (/projects/{project_id}/upload/complete): Check the file now instead of waiting.
  • GETGet a playback grant (/projects/{project_id}/generations/{generation_id}/media): Fresh playback and download URLs.
  • POSTOpen the webhook portal (/webhooks/portal): Add endpoints and copy the signing secret.

Report an issue with this page