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},
idempotencyKey="restore-job-2026-001",
)
print(generation.generationId)
print(generation.idempotentReplay)
Use one stable idempotencyKey for every retry of the same logical generation request.
The response's optional idempotentReplay value is True when the API returns the
result of an earlier request with that key. Use a new key for a different generation.
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
1 maintainer
Release files for diffio 0.1.46
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| diffio-0.1.46.tar.gz | 26.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| diffio-0.1.46-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 45.5 kB
Release files / diffio-0.1.46.tar.gz
| Download URL | diffio-0.1.46.tar.gz |
|---|---|
| Size | 26.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c5a6a70150e45da2398f898eb0248d29124f9e8d01743b4980766092af01611a
|
|
BLAKE2b-256 checksum How to use checksums |
c50c03980a1e14a5a6de3d0aeaa0affb47675492d5849c3b3dcc5c2be51bd4bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / diffio-0.1.46-py3-none-any.whl
| Download URL | diffio-0.1.46-py3-none-any.whl |
|---|---|
| Size | 19.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
56f5a33af2d984da0803a2b27b4d8a970c59a5653b97a10f3fe5f39f1914bfa6
|
|
BLAKE2b-256 checksum How to use checksums |
d47a35d2a28e4acb2595171f623fddead331920c5b31a37bce1364ed81731cc0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency log
