Full API guide

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.5",    sampling={"preset": "balanced"},    params={"tag": "docs"},)

   Node.js

   Copy

   const generation = await client.generations.create({  apiProjectId: project.apiProjectId,  model: "diffio-3.5",  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 and transcript JSON. 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",)client.generations.download(    generationId=generation.generationId,    apiProjectId=project.apiProjectId,    downloadFilePath="transcript.json",    downloadType="transcript",)

   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)const transcript = await client.generations.getDownload({  generationId: generation.generationId,  apiProjectId: project.apiProjectId,  downloadType: "transcript",})const transcriptResponse = await fetch(transcript.downloadUrl)fs.writeFileSync("transcript.json", await transcriptResponse.text())

   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)}

Account, keys, and usage

Agent keys and scoped keys can read account settings, manage API keys, and inspect usage when their scopes allow it.

1. 1

   Read account settings

   PythonNode.js

   Python

   Copy

   settings = client.account.get_settings()print(settings.account.get("billingPolicy"))

   Node.js

   Copy

   const settings = await client.account.getSettings()console.log(settings.account.billingPolicy)

2. 2

   Manage API keys

   PythonNode.js

   Python

   Copy

   created_key = client.api_keys.create(    label="worker-key",    scopes=["projects:read", "projects:write", "generations:read", "generations:write"],)keys = client.api_keys.list()print(created_key.keyId, len(keys.keys))

   Node.js

   Copy

   const createdKey = await client.apiKeys.create({  label: "worker-key",  scopes: ["projects:read", "projects:write", "generations:read", "generations:write"],})const keys = await client.apiKeys.list()console.log(createdKey.keyId, keys.keys.length)

3. 3

   Read usage summary

   PythonNode.js

   Python

   Copy

   usage = client.usage.summary()print(usage.usage, usage.billing)

   Node.js

   Copy

   const usage = await client.usage.summary()console.log(usage.usage, usage.billing)

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.5",    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.5",  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.

   PythonNode.js

   Python

   Copy

   result = client.webhooks.configure(    mode="live",    url="https://example.com/webhooks/diffio",    eventTypes=["generation.completed", "generation.failed"],    apiKeyId=os.getenv("DIFFIO_API_KEY_ID"),)print(result.webhook)

   Node.js

   Copy

   const result = await client.webhooks.configure({  mode: "live",  url: "https://example.com/webhooks/diffio",  eventTypes: ["generation.completed", "generation.failed"],  apiKeyId: process.env.DIFFIO_API_KEY_ID,})console.log(result.webhook)

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 an Agent key or a scoped key with webhooks:write to send a test event and confirm delivery in the portal. If you use an Agent key, pass the target apiKeyId.

   PythonNode.js

   Python

   Copy

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

   Node.js

   Copy

   import "dotenv/config"import { DiffioClient } from "diffio"const client = new DiffioClient({ apiKey: process.env.DIFFIO_WEBHOOK_KEY })const result = await client.webhooks.sendTestEvent({  eventType: "generation.completed",  mode: "live",  apiKeyId: process.env.DIFFIO_API_KEY_ID,})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.