diffio 0.1.7

Python SDK for the Diffio API.

Diffio Python SDK

The Diffio Python SDK helps you call the Diffio API from Python. This version covers project creation, upload, generation, progress checks, and download URLs. Requires Python 3.8 or later.

Install

pip install diffio

For local development:

cd diffio-python
pip install -e .

Configuration

Set the API key with DIFFIO_API_KEY. If you need to set the base URL explicitly, use the production endpoint with DIFFIO_API_BASE_URL.

export DIFFIO_API_KEY="diffio_live_..."
export DIFFIO_API_BASE_URL="https://api.diffio.ai/v1"

Request options

Use request options to override headers, timeouts, retries, or the API key per request. You can also pass timeoutInSeconds as an alias for timeout.

from diffio import DiffioClient, RequestOptions

client = DiffioClient(apiKey="diffio_live_...")
projects = client.list_projects(
    requestOptions=RequestOptions(
        headers={"X-Debug": "1"},
        timeout=30.0,
        maxRetries=2,
        retryBackoff=0.5,
    )
)

Create a project and generation

create_project uploads the file and returns the project metadata.

from diffio import DiffioClient

client = DiffioClient(apiKey="diffio_live_...")
file_path = "sample.wav"
project = client.create_project(
    filePath=file_path,
)

generation = client.create_generation(
    apiProjectId=project.apiProjectId,
    model="diffio-3.5",
    sampling={"steps": 12, "guidance": 1.5},
)

print(generation.generationId)

Audio isolation helper

from diffio import DiffioClient

client = DiffioClient(apiKey="diffio_live_...")
result = client.audio_isolation.isolate(
    filePath="sample.wav",
    model="diffio-3.5",
    sampling={"steps": 12, "guidance": 1.5},
)

print(result.generation.generationId)

Restore audio in one call

This helper runs the full flow and returns the downloaded bytes plus a metadata dict.

from diffio import DiffioClient

client = DiffioClient(apiKey="diffio_live_...")
audio_bytes, info = client.restore_audio(
    filePath="sample.wav",
    model="diffio-3.5",
    sampling={"steps": 12, "guidance": 1.5},
    onProgress=lambda progress: print(progress.status),
)

if info["error"]:
    print(info["error"])
else:
    with open("restored.mp3", "wb") as handle:
        handle.write(audio_bytes)

print(info["apiProjectId"], info["generationId"])

Generation progress

from diffio import DiffioClient

client = DiffioClient(apiKey="diffio_live_...")
progress = client.generations.get_progress(
    generationId="gen_123",
    apiProjectId="proj_123",
)

print(progress.status)

Generation download

from diffio import DiffioClient

client = DiffioClient(apiKey="diffio_live_...")
download = client.generations.download(
    generationId="gen_123",
    apiProjectId="proj_123",
    downloadType="mp3",
    downloadFilePath="restored.mp3",
)

print(download.downloadUrl)

If you only need the URL, use client.generations.get_download.

Set downloadType="transcript" to download the transcript JSON artifact when the generation has one.

transcript = client.generations.download(
    generationId="gen_123",
    apiProjectId="proj_123",
    downloadType="transcript",
    downloadFilePath="word_timestamps.json",
)

Account, keys, usage, and webhook configuration

Agent keys can manage account settings, scoped keys, usage, and webhook endpoints.

settings = client.account.get_settings()
key = client.api_keys.create(
    label="Backend worker",
    scopes=["projects:read", "projects:write", "generations:read", "generations:write", "artifacts:read"],
)
usage = client.usage.summary(apiKeyId=key.keyId)
webhook = client.webhooks.configure(
    mode="live",
    url="https://example.com/webhooks/diffio",
    eventTypes=["generation.completed", "generation.failed"],
    apiKeyId=key.keyId,
)

List projects

from diffio import DiffioClient

client = DiffioClient(apiKey="diffio_live_...")
projects = client.projects.list()

for project in projects.projects:
    print(project.apiProjectId, project.status)

List project generations

from diffio import DiffioClient

client = DiffioClient(apiKey="diffio_live_...")
generations = client.projects.list_generations(apiProjectId="proj_123")

for generation in generations.generations:
    print(generation.generationId, generation.status)

Send a test webhook event

from diffio import DiffioClient

client = DiffioClient(apiKey="diffio_live_...")
event = client.webhooks.send_test_event(
    eventType="generation.completed",
    mode="live",
    samplePayload={"apiProjectId": "proj_123"},
)

print(event.svixMessageId)

Verify webhook signatures

Use the raw request body (bytes) plus the svix-* headers and your webhook signing secret.

from fastapi import FastAPI, Request, HTTPException
from diffio import DiffioClient
import os

app = FastAPI()
client = DiffioClient(apiKey=os.environ["DIFFIO_API_KEY"])

@app.post("/webhooks/diffio")
async def diffio_webhook(request: Request):
    payload = await request.body()
    headers = request.headers
    try:
        event = client.webhooks.verify_signature(
            payload=payload,
            headers=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}

Tutorials

• Audio restoration CLI tutorial: tutorials/audio-restoration-cli/README.md

Runtime compatibility

Use Python 3.8 or later.

Tests

cd diffio-python
python -m pip install -r requirements-dev.txt
python -m pytest