Quickstart

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 multiple generations, often one per model, and you can download each result.

Using the Diffio SDK

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_...

2. 2

   Install the SDK

   Install the Diffio SDK for Python or Node, then load the API key from the environment.

   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 .

3. 3

   Create a project

   Create a file named example.py or example.mjs. Then create a project for your media file. The SDK uploads the file as part of project creation.

   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"project = client.create_project(    filePath=file_path,)

   Node.js

   Copy

   import "dotenv/config"import { DiffioClient } from "diffio"const client = new DiffioClient({ apiKey: process.env.DIFFIO_API_KEY })const filePath = "./sample.wav"const project = await client.createProject({  filePath})

4. 4

   Run multiple generations

   Create three generations, one per model, so you can compare the results.

   PythonNode.js

   Python

   Copy

   models = ["diffio-2", "diffio-3.5"]generations = []for model in models:    generation = client.create_generation(        apiProjectId=project.apiProjectId,        model=model,    )    generations.append({"model": model, "generation": generation})

   Node.js

   Copy

   const models = ["diffio-2", "diffio-3.5"]const generations = []for (const model of models) {  const generation = await client.createGeneration({    apiProjectId: project.apiProjectId,    model,  })  generations.push({ model, generation })}

5. 5

   Download each result

   Add this block near the end of the file, then poll each generation and download restored audio plus transcript JSON. Move the node:fs import to the top of the file with the other imports.

   PythonNode.js

   Python

   Copy

   import timefor item in generations:    status = "queued"    while status not in ("complete", "failed"):        progress = client.generations.get_progress(            generationId=item["generation"].generationId,            apiProjectId=project.apiProjectId,        )        status = progress.status        print(item["model"], "status:", status)        if status not in ("complete", "failed"):            time.sleep(5)    if status != "complete":        raise SystemExit(f"Generation failed for {item['model']}")    output_name = f"restored-{item['model']}.mp3"    client.generations.download(        generationId=item["generation"].generationId,        apiProjectId=project.apiProjectId,        downloadFilePath=output_name,        downloadType="mp3",    )    transcript_name = f"transcript-{item['model']}.json"    client.generations.download(        generationId=item["generation"].generationId,        apiProjectId=project.apiProjectId,        downloadFilePath=transcript_name,        downloadType="transcript",    )

   Node.js

   Copy

   import fs from "node:fs"for (const item of generations) {  let status = "queued"  while (!["complete", "failed"].includes(status)) {    const progress = await client.generations.getProgress({      generationId: item.generation.generationId,      apiProjectId: project.apiProjectId,    })    status = progress.status    console.log(item.model, "status:", status)    if (!["complete", "failed"].includes(status)) {      await new Promise((resolve) => setTimeout(resolve, 5000))    }  }  if (status !== "complete") {    throw new Error(`Generation failed for ${item.model}`)  }  const download = await client.generations.getDownload({    generationId: item.generation.generationId,    apiProjectId: project.apiProjectId,    downloadType: "audio",  })  const audioResponse = await fetch(download.downloadUrl)  const audioBuffer = Buffer.from(await audioResponse.arrayBuffer())  const outputName = `restored-${item.model}.mp3`  fs.writeFileSync(outputName, audioBuffer)  const transcript = await client.generations.getDownload({    generationId: item.generation.generationId,    apiProjectId: project.apiProjectId,    downloadType: "transcript",  })  const transcriptResponse = await fetch(transcript.downloadUrl)  const transcriptText = await transcriptResponse.text()  const transcriptName = `transcript-${item.model}.json`  fs.writeFileSync(transcriptName, transcriptText)}

   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.