200Success, treated as complete.: Test webhook sent.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, eventType is required, eventType is not supported, mode must be test or live, samplePayload must be an object.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: API key is not active, missing read permission, or does not match apiKeyId.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: Svix is not configured, failed to initialize webhook app, or failed to send test webhook.
Notes
eventType must be one of generation.queued, generation.processing, generation.failed, or generation.completed.
mode controls whether the test event is delivered to test or live endpoints.
samplePayload can override payload fields, but eventType, eventId, createdAt, apiKeyId, and status are always set by Diffio.
Diffio documentation
Documentation
Guides and references for restoring speech audio, reviewing transcripts, and integrating Diffio.
Speech focused restorationAudio and video supportTranscripts and A/B review
Diffio offers three speech restoration models, each tuned for a different balance of speed, cost, and clarity. Choose a model for every generation, and run multiple generations on the same project to compare results.
Model lineup
Use the model id in the SDK model field or call the matching REST endpoint. Each model focuses on speech, with different performance and fidelity targets.
Diffio 2.0 Flash
diffio-2-flash
Fast
Fastest turnaround for previews and quick cleanups.
Best for: Rapid previews, high volume queues.
Low latency option for high volume queues.
Great for rapid iterations and early reviews.
Balanced cleanup for shorter clips.
Diffio 2.0
diffio-2
Balanced
Reliable baseline model for consistent cleanup.
Best for: Production cleanup with balanced speed and fidelity.
Steady results for interviews and podcasts.
Good balance of speed and quality.
Stable output across large batches.
Diffio 3.4
diffio-3.4
Best
Best quality reconstruction for demanding speech.
Best for: Critical clarity work and detailed transcripts.
Improved clarity in noisy rooms.
Sharper consonants and tighter detail.
Stronger alignment for transcript review.
Choosing a model
Start with a fast preview, then move to higher fidelity for final delivery. Keep the same project and create a new generation each time you change models.
diffio-2-flash for rapid previews or high volume queues.
diffio-2 for balanced speed and clarity when throughput matters.
diffio-3.4 for the highest clarity on noisy or distant speech.
Plan access
Diffio 2.0 and Diffio 3.4 require a paid plan. Review billing details for plan options.
Endpoint mapping
Model ids map to specific generation endpoints. Use these paths when calling the REST API directly.
Outline the intent of this section, the key audience, and the most important takeaways.
Examples
Show a realistic request and response, plus any required headers.
Next steps
Link to related guides, or point to the API reference when it is ready.
Answers to common billing questions for Diffio API plans, including upgrades, billing thresholds, and invoices.
Upgrading to the Developer tier
What happens when I upgrade to the Developer tier?
When you upgrade, there is no immediate charge. You are billed for usage at month end or when you reach progressive billing thresholds, which are listed below.
Usage is billed per second based on processing time, with a minimum billable duration of 60 seconds per generation request.
Example: a 30 second request is billed as 60 seconds. An 80 second request is billed as 80 seconds.
To upgrade from the Free tier to the Developer tier, add a valid payment method, including a credit card, a United States bank account, or a SEPA debit account.
Your upgrade takes effect immediately. Billing occurs at the end of your monthly billing cycle or when you cross the progressive thresholds of $1, $10, $100, $500, and $1,000.
What are the benefits of upgrading?
The Developer tier is designed for developers and teams who need more capacity with pay as you go pricing.
Usage based billing for production workloads
Spend limits with budget alerts
Audit logs with 7 day retention
Can I downgrade back to the Free tier after I upgrade?
Yes, you can downgrade to the Free tier at any time from your account settings under Billing.
When you downgrade, we issue a final invoice for any outstanding usage that has not yet been billed. You will need to pay this invoice before the downgrade is complete.
After downgrading:
Your account returns to Free tier rate limits and restrictions
You lose access to Developer tier benefits
Usage based charges stop immediately
You can upgrade again whenever you need more capacity
Understanding the Diffio billing model
How does the billing cycle work?
Diffio uses a monthly billing cycle. You receive an invoice in arrears for usage. New Developer tier accounts also follow progressive billing thresholds to ease into pay as you go usage.
How does progressive billing work?
During the progressive billing phase, an invoice is triggered and payment is deducted when your cumulative usage reaches $1, $10, $100, $500, and $1,000.
Special billing for customers in India
Customers with a billing address in India have different thresholds. For India customers, the thresholds are $1, $10, and then every $100 thereafter. The $500 and $1,000 thresholds do not apply.
These thresholds are one time for most customers. Once you cross the $1,000 lifetime usage threshold, only monthly billing continues. For India customers, billing continues at each $100 increment.
What if I do not reach the next threshold?
If you do not reach the next threshold, your usage is billed on your regular end of month invoice.
Example
You cross $1, you are charged immediately.
You then use $2 more for the month. Lifetime usage is $3, still below $10.
The $2 is invoiced at the end of your monthly billing cycle, not immediately.
When is payment withdrawn from my account?
Payment is withdrawn automatically from your connected payment method each time an invoice is issued. This can happen during the progressive billing phase or at the end of each monthly billing cycle.
We only bill you once your usage reaches at least $0.50. If you see a total charge under $0.50, there is no action required on your end.
Monitoring your spending and usage
How can I view my current usage and spending in near real time?
You can monitor usage in the Diffio dashboard. Visit the Usage page to track usage across models and see how consumption aligns with pricing.
Can I set spending limits or receive budget alerts?
Yes. Developer tier accounts can set spend limits and receive budget alerts. Once billing is enabled, configure limits in the dashboard to keep costs on track.
Invoices, billing info, and credits
Where can I find my past invoices and payment history?
You can view and download invoices in the Diffio dashboard under Settings, then Billing. If billing is not yet enabled for your account, this area will appear once it is available.
Can I change my billing info and payment method?
Yes, update billing details anytime from Settings, then Billing in the Diffio dashboard.
What payment methods do you accept?
Diffio accepts credit cards (Visa, MasterCard, American Express, Discover), United States bank accounts, and SEPA debit accounts.
Are there promotional credits or trial offers?
New API Developer upgrades receive a one time $5 usage credit after you add a payment method. The credit applies to future API invoices once checkout completes.
Common billing questions and troubleshooting
How are refunds handled, if applicable?
Refunds are handled on a case by case basis. Contact our support team at support@diffio.ai for assistance.
What if I believe there is an error in my bill?
Check your Usage and Billing pages first. If you still believe there is an issue, contact support at support@diffio.ai.
Under what conditions can my account be suspended due to billing issues?
Account suspension or restriction can occur after prolonged non payment or consistently failed payment attempts. We handle each case individually. If your account is impacted, contact support for guidance.
What happens if my payment fails?
Update your payment method to ensure successful processing. We may retry payments, and failed payments can result in service suspension. We will email you if an invoice is unpaid.
What should I do if my billing question is not answered here?
Restore speech audio by creating a project with your media file, running multiple generations, and downloading results. This quickstart sets your API key, installs the SDK, and walks through each step.
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.
A project contains your media. Create multiple generations under it, then download each restored file.
Add this block near the end of the file, then poll each generation and download results. Move the node:fs import to the top of the file with the other imports.
Python
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", )
Node.js
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)}
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.
This guide expands on the quickstart and walks through most of the Diffio SDK surface. You will create projects, run generations, track progress, download results, list resources, and set up webhooks so your app can react to status changes. If you want the shortest path, start with the 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 one or more generations, and you can download each result.
A project contains your media. Create multiple generations under it, then download each restored file.
Prefer webhooks in production
Polling works for quick tests. For production, use webhooks so Diffio can notify you when a generation completes. See the Webhooks guide.
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.
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
List projects
Python
projects = client.projects.list()for project in projects.projects: print(project.apiProjectId, project.status, project.originalFileName)
Return a 200Success, treated as complete. response fast and push heavy work to a queue or background job.
Webhooks let Diffio notify your system when a generation changes status, so you do not need to poll. This guide walks through opening the portal, adding an endpoint, testing delivery, verifying signatures, and recovering from failures.
Intro
A webhook is a POST request that Diffio sends to a URL you control. Use one endpoint per service, and let that endpoint handle every event type you subscribe to. Respond with a 200Success, treated as complete. response quickly so delivery is marked successful. If your framework enables CSRF protection, disable it for this endpoint.
Each API key maps to its own webhook application, and each endpoint has its own signing secret. Webhook events are scoped to the API key that created the endpoint.
SDK support
The Diffio SDKs expose a webhooks client. In Python use send_test_event. In JavaScript use sendTestEvent. These call POST /v1/webhooks/send_test_event under the hood.
Events and payloads
Diffio emits events only when a generation status changes.
generation.queued when a generation is queued.
generation.processing when processing begins.
generation.failed when processing fails.
generation.completed when processing finishes.
Each webhook payload includes eventType, eventId, createdAt, apiKeyId, apiProjectId, generationId, status, hasVideo, modelKey, error, and errorDetails. The status values are queued, processing, error, and complete.
Create an API key before you set up webhooks. Webhook endpoints and events are tied to the API key that creates them. Use the developer dashboard to create your key.
Open the webhook portal from the developer dashboard and use Add endpoint to get started.
No server yet
If you do not have a webhook receiver, use the portal to generate a temporary test URL. It lets you inspect payloads before you build your own endpoint. If you use a no code tool that gives you a webhook URL, paste that URL into the portal.
3
Add your endpoint URL and events
In the portal, click Add endpoint, paste your URL, then choose the events you want. If you do not select events, your endpoint receives every event type.
Choose the events, add your destination URL, and use Create test link to get a temporary receiver URL.
4
Save the signing secret
After you create the endpoint, copy the signing secret from the endpoint details and store it in your secret manager. You will use it to verify signatures.
After creation, open the endpoint details and copy the signing secret.
Test endpoints
Use the portal Testing tab to send example events, or send a test event from the SDKs. Test events return a message id so you can locate the delivery in the portal.
You can pass samplePayload to override fields like apiProjectId and generationId for testing.
Verify signatures
Signature verification ensures the webhook really came from Diffio. Use the Diffio SDK helpers and always verify against the raw request body, not a parsed JSON object.
The verifier expects svix-id, svix-timestamp, and svix-signature headers.
Retries
Diffio retries failed deliveries with exponential backoff. A typical schedule looks like this, starting immediately after the first failure.
Immediately
After 5 seconds
After 5 minutes
After 30 minutes
After 2 hours
After 5 hours
After 10 hours
After 10 more hours
You can also retry messages manually from the portal, or recover all failed messages from a chosen time window.
Troubleshooting and recovery
Troubleshooting tips
Verify the raw payload, not a reserialized JSON string. Changing formatting breaks signature verification.
Confirm the signing secret matches the endpoint you are verifying. Secrets are unique to each endpoint.
Return a 200Success, treated as complete. response for success and any other status for failure. A 200Success, treated as complete. response always marks the delivery successful.
Respond quickly and queue heavy work. Slow responses lead to timeouts and retries.
Failure recovery
If an endpoint is disabled after repeated failures, enable it again in the portal. To replay messages, open the endpoint, choose Options, then Recover failed messages for a time window. You can also resend a single message from its attempt list.
Use this reference to plan Diffio API requests and responses. All endpoints use JSON over HTTPS at https://api.diffio.ai/v1.
API reference essentials
1
Base URL
Use the production base URL for all API requests.
https://api.diffio.ai/v1
Append the endpoint path to the base URL when calling the REST API directly.
2
Authentication
Send the API key on every request using one of the supported headers.
Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>
Use API keys with read and write permissions that match the endpoint.
3
Request conventions
All /v1 endpoints use POST with JSON bodies.
OPTIONS is accepted for CORS preflight.
Send Content-Type: application/json for JSON payloads.
Request fields use camelCase, for example apiProjectId.
create_project returns uploadUrl and uploadMethod. Use the returned method and set Content-Type to match contentType.
Download URLs from get_generation_download are signed and expire after about two hours.
4
Error responses
Errors return JSON with an error message. Some errors include additional fields such as code or billing metadata.
Example error response
{ "error": "Payment failed. Update your payment method in the billing portal.", "code": "paymentFailed"}
Billing holds return 402Payment required, billing issue such as paymentFailed. API usage can be blocked until billing is updated. with code paymentFailed. API usage can be blocked until billing is updated. Spend limit errors use spendLimitExceeded.
5
Rate limits
Rate limits and spend limits depend on your plan and API key settings. Review the API pricing page for current limits and use the developer dashboard to monitor usage.
Endpoints
Use these endpoints to create projects, run generations, and send test webhooks.
200Success, treated as complete.: Project created, upload URL returned.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, fileName must be provided as a string, contentType must be a string, contentLength must be a number, contentLength must be zero or higher, params must be an object.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: API key is not active, or missing write permission.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: API key missing userId, failed to create upload record, or failed to generate upload URL.
Notes
fileName is required.
contentLength is coerced to an integer, send whole bytes to avoid truncation.
params can be null, it is treated as an empty object.
fileFormat is expected to be a string, when provided and params.fileFormat is missing it is copied as is.
objectPath uses a sanitized basename of fileName, characters outside letters, digits, period, underscore, and hyphen are replaced with underscores, empty names fall back to upload.bin.
Upload the file to uploadUrl using uploadMethod and set Content-Type to match contentType.
uploadUrl expires at expiresAt, request a new URL if it expires.
List projects owned by the API key.
POST/v1/list_projectsPermissions: read
Endpoint
HTTP request
https://api.diffio.ai/v1/list_projects
Use POST with a JSON body.
Permissions
read
API keys must be active.
Authentication
Send the API key on every request using one of the supported headers.
Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>
Request
Send a JSON object to list projects for the API key. Additional fields are ignored.
200Success, treated as complete.: Generation queued and stored.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, apiProjectId must be provided as a string, sampling must be an object, params must be an object.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
402Payment required, billing issue such as paymentFailed. API usage can be blocked until billing is updated.: Spend limit exceeded for this API key.
403Forbidden, treated as permission error.: API key is not active, missing write permission, or does not own the project.
404Not found, treated as missing resource.: API project not found.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: Pricing is not configured, or failed to create generation record.
Example error response
Error response
{ "error": "Spend limit exceeded for this API key.", "code": "spendLimitExceeded", "currency": "USD", "spendLimitUsd": 10, "estimatedCostUsd": 1.5, "usedUsd": 9.2, "pendingUsd": 0, "periodStart": "2026-01-15T00:00:00Z", "periodEnd": "2026-02-15T00:00:00Z"}
Notes
apiProjectId is required.
sampling and params are optional objects. null is treated as an empty object.
sampling and params are passed through without schema validation. Nested fields are not validated.
modelKey is always set to diffio-2.
Use /v1/get_generation_progress to track progress after queuing.
Queue a generation for a project using the diffio-2-flash model.
200Success, treated as complete.: Generation queued and stored.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, apiProjectId must be provided as a string, sampling must be an object, params must be an object.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
402Payment required, billing issue such as paymentFailed. API usage can be blocked until billing is updated.: Spend limit exceeded for this API key.
403Forbidden, treated as permission error.: API key is not active, missing write permission, or does not own the project.
404Not found, treated as missing resource.: API project not found.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: Pricing is not configured, or failed to create generation record.
Example error response
Error response
{ "error": "Spend limit exceeded for this API key.", "code": "spendLimitExceeded", "currency": "USD", "spendLimitUsd": 10, "estimatedCostUsd": 1.5, "usedUsd": 9.2, "pendingUsd": 0, "periodStart": "2026-01-15T00:00:00Z", "periodEnd": "2026-02-15T00:00:00Z"}
Notes
apiProjectId is required.
sampling and params are optional objects. null is treated as an empty object.
sampling and params are passed through without schema validation. Nested fields are not validated.
modelKey is always set to diffio-2-flash.
Use /v1/get_generation_progress to track progress after queuing.
Queue a generation for a project using the diffio-3.4 model.
POST/v1/diffio-3.4-generationPermissions: write
Endpoint
HTTP request
https://api.diffio.ai/v1/diffio-3.4-generation
Use POST with a JSON body.
Permissions
write
API keys must be active.
Authentication
Send the API key on every request using one of the supported headers.
Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>
Request
Provide the project id and optional sampling or params overrides.
200Success, treated as complete.: Generation queued and stored.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, apiProjectId must be provided as a string, sampling must be an object, params must be an object.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
402Payment required, billing issue such as paymentFailed. API usage can be blocked until billing is updated.: Spend limit exceeded for this API key.
403Forbidden, treated as permission error.: API key is not active, missing write permission, or does not own the project.
404Not found, treated as missing resource.: API project not found.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: Pricing is not configured, or failed to create generation record.
Example error response
Error response
{ "error": "Spend limit exceeded for this API key.", "code": "spendLimitExceeded", "currency": "USD", "spendLimitUsd": 10, "estimatedCostUsd": 1.5, "usedUsd": 9.2, "pendingUsd": 0, "periodStart": "2026-01-15T00:00:00Z", "periodEnd": "2026-02-15T00:00:00Z"}
Notes
apiProjectId is required.
sampling and params are optional objects. null is treated as an empty object.
sampling and params are passed through without schema validation. Nested fields are not validated.
modelKey is always set to diffio-3.4.
Use /v1/get_generation_progress to track progress after queuing.
Fetch progress and stage details for a generation.
POST/v1/get_generation_progressPermissions: read
Endpoint
HTTP request
https://api.diffio.ai/v1/get_generation_progress
Use POST with a JSON body.
Permissions
read
API keys must be active.
Authentication
Send the API key on every request using one of the supported headers.
Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>
Request
Provide a generation id and optionally the project id.
Body fields
Field
Type
Required
Description
generationId
string
Yes
Generation identifier returned by a generation request.
200Success, treated as complete.: Download URL returned.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, generationId and apiProjectId must be strings, downloadType must be a string, downloadType must be audio or video, video downloads are only available for video projects.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: API key is not active, missing read permission, not permitted to download generations, or does not own the project or generation.
404Not found, treated as missing resource.: Generation not found, restored audio path is not available, restored audio file not found, restored video path is not available.
405Client error, treated as fix required.: Method is not POST.
409Conflict, treated as not ready yet.: Generation is not ready yet because processing is not complete or the generation is not marked complete, restored video is not ready yet because the restored job has not succeeded or the blob does not exist.
Notes
downloadType defaults to video for video projects, otherwise audio.
downloadUrl expires after about two hours, request a new one if it expires.
Audio downloads require the generation to be complete and the restored audio file to exist.
Video downloads require a video project, the generation to be complete, and the restored video job to be complete.
API keys must have read permission and downloadGenerations must be true when present.
List generations for a project.
POST/v1/list_project_generationsPermissions: read
Endpoint
HTTP request
https://api.diffio.ai/v1/list_project_generations
Use POST with a JSON body.
Permissions
read
API keys must be active.
Authentication
Send the API key on every request using one of the supported headers.
200Success, treated as complete.: Test webhook sent.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, eventType is required, eventType is not supported, mode must be test or live, samplePayload must be an object.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: API key is not active, missing read permission, or does not match apiKeyId.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: Svix is not configured, failed to initialize webhook app, or failed to send test webhook.
Notes
eventType must be one of generation.queued, generation.processing, generation.failed, or generation.completed.
mode controls whether the test event is delivered to test or live endpoints.
samplePayload can override payload fields, but eventType, eventId, createdAt, apiKeyId, and status are always set by Diffio.
