Prerequisites

Before you start, have these ready.

• A Diffio API key with read and write permissions.
• A speech focused audio file, for example sample.wav.
• Python 3.8 or later, or Node 18 or later.

Workflow overview

Projects hold your media. Each project can have one or more generations, and you can download each result.

Using the Diffio SDK

Follow these steps in order, and add each block to the same file. You will create a project, run a generation, wait for completion, and download the restored audio.

1. 1

   Create an API key

   Create an API key in the developer dashboard and store it as a secret. Pass the key on every request using the Authorization header (X-Api-Key and Xi-Api-Key also work).

   Create API key

   .env

   Copy

   DIFFIO_API_KEY=diffio_live_...

   Tip

   Store your API key as a managed secret instead of committing it to source control.

2. 2

   Install the SDK

   Install the Diffio Python or Node SDK, then load your API key from an environment file.

   PythonNode.js

   Python

   Copy

   pip install diffio python-dotenv

   Node.js

   Copy

   npm install diffio dotenv

   SDK source code

   Browse the SDK repositories on GitHub: diffio-js and diffio-python .

   Note

   Use Node 18 or later so fetch is available without extra packages.

3. 3

   Configure the client

   Create a file named full_guide.py or full_guide.mjs. Then initialize the client and set global request options like timeouts and retries.

   PythonNode.js

   Python

   Copy

   from dotenv import load_dotenvfrom diffio import DiffioClient, RequestOptionsimport osload_dotenv()client = DiffioClient(    apiKey=os.getenv("DIFFIO_API_KEY"),    requestOptions=RequestOptions(        timeoutInSeconds=60,        maxRetries=2,    ),)

   Node.js

   Copy

   import "dotenv/config"import { DiffioClient } from "diffio"const client = new DiffioClient({  apiKey: process.env.DIFFIO_API_KEY,  timeoutInSeconds: 60,  maxRetries: 2,})

   Per call overrides

   Every SDK call accepts requestOptions so you can override timeouts, retries, headers, or the API key for a single request.

4. 4

   Create a project

   Create a project for your media file. The SDK uploads the file as part of project creation. You can attach optional metadata through params.

   PythonNode.js

   Python

   Copy

   file_path = "sample.wav"project = client.create_project(    filePath=file_path,    fileFormat="wav",    params={        "source": "full-guide",        "notes": "First upload from docs",    },)

   Node.js

   Copy

   const filePath = "./sample.wav"const project = await client.createProject({  filePath,  fileFormat: "wav",  params: {    source: "full-guide",    notes: "First upload from docs",  },})

5. 5

   Create a generation

   Start a generation with the model you want. Use sampling or params for model specific settings.

   PythonNode.js

   Python

   Copy

   generation = client.generations.create(    apiProjectId=project.apiProjectId,    model="diffio-3.4",    sampling={"preset": "balanced"},    params={"tag": "docs"},)

   Node.js

   Copy

   const generation = await client.generations.create({  apiProjectId: project.apiProjectId,  model: "diffio-3.4",  sampling: { preset: "balanced" },  params: { tag: "docs" },})

6. 6

   Wait for completion

   Poll until the generation completes. The wait helper returns the full progress object.

   PythonNode.js

   Python

   Copy

   progress = client.generations.wait_for_complete(    generationId=generation.generationId,    apiProjectId=project.apiProjectId,    pollInterval=3.0,    timeout=900.0,    showProgress=True,)print("Final status:", progress.status)

   Node.js

   Copy

   const progress = await client.generations.waitForComplete({  generationId: generation.generationId,  apiProjectId: project.apiProjectId,  pollInterval: 3,  timeoutInSeconds: 900,  showProgress: true,})console.log("Final status:", progress.status)

   Shortcut

   You can combine creation and polling with client.generations.create_and_wait in Python or client.generations.createAndWait in Node.

7. 7

   Download results

   Fetch the download URL, then save the restored audio. Signed URLs expire, so request a new URL if needed.

   PythonNode.js

   Python

   Copy

   client.generations.download(    generationId=generation.generationId,    apiProjectId=project.apiProjectId,    downloadFilePath="restored.mp3",    downloadType="mp3",)

   Node.js

   Copy

   import fs from "node:fs"const download = await client.generations.getDownload({  generationId: generation.generationId,  apiProjectId: project.apiProjectId,  downloadType: "audio",})const audioResponse = await fetch(download.downloadUrl)const audioBuffer = Buffer.from(await audioResponse.arrayBuffer())fs.writeFileSync("restored.mp3", audioBuffer)

   Troubleshooting

   If you receive 401Unauthorized, treated as auth error. or 403Forbidden, treated as permission error., confirm the API key is valid and has read and write permissions. A 402Payment required, billing issue such as paymentFailed. API usage can be blocked until billing is updated. error indicates a billing issue such as a spend limit or a paymentFailed billing hold. API usage can be blocked until billing is updated. A 409Conflict, treated as not ready yet. error indicates the generation is not complete yet, poll progress and retry the download.

Manage projects and generations

Use list endpoints to build dashboards, resume work, or review past generations.

1. 1

   List projects

   PythonNode.js

   Python

   Copy

   projects = client.projects.list()for project in projects.projects:    print(project.apiProjectId, project.status, project.originalFileName)

   Node.js

   Copy

   const projects = await client.projects.list()for (const project of projects.projects) {  console.log(project.apiProjectId, project.status, project.originalFileName)}

2. 2

   List generations in a project

   PythonNode.js

   Python

   Copy

   generations = client.projects.list_generations(    apiProjectId=project.apiProjectId,)for generation in generations.generations:    print(generation.generationId, generation.status, generation.modelKey)

   Node.js

   Copy

   const generations = await client.projects.listGenerations({  apiProjectId: project.apiProjectId,})for (const generation of generations.generations) {  console.log(generation.generationId, generation.status, generation.modelKey)}

Restore audio in one call

The audio isolation helper creates the project, starts a generation, waits for completion, and downloads the restored audio in one call.

1. 1

   Restore in one call

   PythonNode.js

   Python

   Copy

   from dotenv import load_dotenvfrom diffio import DiffioClientimport osload_dotenv()client = DiffioClient(apiKey=os.getenv("DIFFIO_API_KEY"))file_path = "sample.wav"audio_bytes, info = client.audio_isolation.restore_audio(    filePath=file_path,    model="diffio-3.4",    downloadType="mp3",)if info["error"]:    raise SystemExit(info["error"])with open("restored-one-call.mp3", "wb") as handle:    handle.write(audio_bytes)

   Node.js

   Copy

   import "dotenv/config"import { DiffioClient } from "diffio"import fs from "node:fs"const client = new DiffioClient({ apiKey: process.env.DIFFIO_API_KEY })const filePath = "./sample.wav"const [audioBytes, info] = await client.audioIsolation.restore({  filePath,  model: "diffio-3.4",  downloadType: "audio",})if (info.error) {  throw new Error(info.error)}fs.writeFileSync("restored-one-call.mp3", Buffer.from(audioBytes))

   Metadata

   The helper returns a metadata object with status, errors, and download info you can log or store alongside the result.

Use webhooks for status updates

Webhooks let Diffio notify your service when a generation changes status. This is a condensed walkthrough. For full details, see the Webhooks guide.

1. 1

   Create a webhook endpoint

   Follow the webhook creation steps in the docs, then open the developer dashboard to add your endpoint URL and choose events. Save the signing secret for verification.

   Endpoint scope

   Each API key owns its own webhook endpoints and signing secrets.

2. 2

   Verify webhook signatures

   Use the Diffio SDK helpers to verify signatures against the raw request body, not a parsed JSON object.

   Node.jsPython

   Node.js

   Copy

   import express from "express"import { DiffioClient } from "diffio"const app = express()const client = new DiffioClient({ apiKey: process.env.DIFFIO_API_KEY })app.post("/webhooks/diffio", express.raw({ type: "application/json" }), (req, res) => {  try {    const event = client.webhooks.verifySignature({      payload: req.body,      headers: req.headers,      secret: process.env.DIFFIO_WEBHOOK_SECRET    })    console.log("Webhook received", event.eventType)    res.status(200).send("ok")  } catch (err) {    res.status(400).send("Invalid signature")  }})app.listen(3000)

   Python

   Copy

   from fastapi import FastAPI, Request, HTTPExceptionfrom diffio import DiffioClientimport osapp = FastAPI()client = DiffioClient(apiKey=os.environ["DIFFIO_API_KEY"])@app.post("/webhooks/diffio")async def diffio_webhook(request: Request):    payload = await request.body()    try:        event = client.webhooks.verify_signature(            payload=payload,            headers=request.headers,            secret=os.environ["DIFFIO_WEBHOOK_SECRET"],        )    except Exception:        raise HTTPException(status_code=400, detail="Invalid signature")    print("Webhook received", event.eventType)    return {"ok": True}

3. 3

   Send a test event

   Use the SDKs to send a test event and confirm delivery in the portal.

   PythonNode.js

   Python

   Copy

   from dotenv import load_dotenvfrom diffio import DiffioClientimport osload_dotenv()client = DiffioClient(apiKey=os.getenv("DIFFIO_API_KEY"))result = client.webhooks.send_test_event(    eventType="generation.completed",    mode="live",)print(result.svixMessageId)

   Node.js

   Copy

   import "dotenv/config"import { DiffioClient } from "diffio"const client = new DiffioClient({ apiKey: process.env.DIFFIO_API_KEY })const result = await client.webhooks.sendTestEvent({  eventType: "generation.completed",  mode: "live",})console.log(result.svixMessageId)

4. 4

   Handle webhook events

   When you receive generation.completed, fetch the download URL and queue any heavy work.

   PythonNode.js

   Python

   Copy

   from dotenv import load_dotenvfrom diffio import DiffioClientimport osload_dotenv()client = DiffioClient(apiKey=os.getenv("DIFFIO_API_KEY"))def handle_event(event):    if event.eventType != "generation.completed":        return    download = client.generations.get_download(        generationId=event.generationId,        apiProjectId=event.apiProjectId,        downloadType="audio",    )    print("Download URL:", download.downloadUrl)

   Node.js

   Copy

   import "dotenv/config"import { DiffioClient } from "diffio"const client = new DiffioClient({ apiKey: process.env.DIFFIO_API_KEY })const handleEvent = async (event) => {  if (event.eventType !== "generation.completed") {    return  }  const download = await client.generations.getDownload({    generationId: event.generationId,    apiProjectId: event.apiProjectId,    downloadType: "audio",  })  console.log("Download URL:", download.downloadUrl)}

   Respond quickly

   Return a 200Success, treated as complete. response fast and push heavy work to a queue or background job.