> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/developers/quick-start/.

# Quickstart: restore audio in Python or Node

Create an API key, install the SDK and restore a speech recording in one call with Python, Node.js or cURL.

## Prerequisites

- A Diffio API key with Write permission enabled
- A speech audio or video file up to 2 GB, such as `interview.mp3`
- Python 3.8+, Node 18+, or `curl` and `jq`

## Restore your first file

### 1. Create an API key

[Create an API key in the developer dashboard](https://diffio.ai/developers/api-keys/) with Write permission enabled, then copy it right away (the secret is shown once). Pass it as `Authorization: Bearer <key>` on API requests, or set `DIFFIO_API_KEY` so the SDK reads it automatically.

**Terminal**

```bash
export DIFFIO_API_KEY="diffio_live_..."
```

### 2. Install the SDK

Install the Diffio SDK for Python or Node.js, or use `curl` and `jq` directly.

**Python**

```bash
pip install diffio
```

**Node.js**

```bash
npm install diffio
```

**cURL**

```bash
# Uses curl and jq (no SDK install needed)
curl --version && jq --version
```

> **SDK source code**
>
> Browse the SDK repositories on GitHub: [diffio-python](https://github.com/Diffio-AI/diffio-python) and [diffio-js](https://github.com/Diffio-AI/diffio-js).

### 3. Restore a file in one call

Run a restore on `interview.mp3` with `diffio-flash` (the alias for `diffio-4.7-flash`). The SDK helper creates the project with a queued generation, uploads the file via `upload.requests`, marks the upload complete, polls until `status` is `complete` and saves the restored MP3.

**Python**

```python
from diffio import DiffioClient

client = DiffioClient()  # reads DIFFIO_API_KEY

result = client.restore_audio(
    "interview.mp3",
    model="diffio-flash",
    output_path="interview-restored.mp3",
    on_progress=lambda generation: print(generation.status, generation.stage),
)
print(result.project.id, result.generation.id, result.output_path)
```

**Node.js**

```javascript
import { DiffioClient } from "diffio";

const client = new DiffioClient(); // reads DIFFIO_API_KEY

const result = await client.restoreAudio({
  file: "interview.mp3",
  model: "diffio-flash",
  outputPath: "interview-restored.mp3",
  onProgress: (generation) => console.log(generation.status, generation.stage),
});

console.log(result.project.id, result.generation.id, result.output_path);
```

**cURL**

```bash
set -euo pipefail
API="https://api.diffio.ai/v2"
FILE="interview.mp3"
AUTH="Authorization: Bearer $DIFFIO_API_KEY"
# Every request gets a time limit: 60 s for API calls, 15 min per upload part or download
API_CURL=(curl -fsS --connect-timeout 10 --max-time 60)
BULK_CURL=(curl -fsS --connect-timeout 10 --max-time 900)
WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT

# 1) Create the project and queue a Flash restore in one call
"${API_CURL[@]}" -X POST "$API/projects" -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"file_name\": \"$FILE\", \"content_type\": \"audio/mpeg\", \"size_bytes\": $(wc -c < "$FILE"), \"generation\": {\"model\": \"diffio-flash\"}}" \
  > "$WORK/project.json"
PROJECT_ID=$(jq -er .id "$WORK/project.json")
GEN_ID=$(jq -er .latest_generation.id "$WORK/project.json")
UPLOAD_TOKEN=$(jq -er .upload.upload_token "$WORK/project.json")
START_URL=$(jq -er .upload.requests.start.url "$WORK/project.json")
PART_URL_TEMPLATE=$(jq -er .upload.requests.part.url "$WORK/project.json")
COMPLETE_URL=$(jq -er .upload.requests.complete.url "$WORK/project.json")
PART_SIZE=$(jq -er .upload.part_size_bytes "$WORK/project.json")

# 2) Upload the bytes by following upload.requests, then mark complete
UPLOAD_ID=$("${API_CURL[@]}" -X POST "$START_URL" -H "Authorization: Bearer $UPLOAD_TOKEN" | jq -er .uploadId)
split -b "$PART_SIZE" -d -a 5 "$FILE" "$WORK/part."
N=1; PARTS="[]"
for P in "$WORK"/part.*; do
  PART_URL="${PART_URL_TEMPLATE/\{part_number\}/$N}"
  PART_URL="${PART_URL/\{upload_id\}/$UPLOAD_ID}"
  ETAG=$("${BULK_CURL[@]}" -X PUT "$PART_URL" -H "Authorization: Bearer $UPLOAD_TOKEN" --data-binary @"$P" | jq -er .etag)
  PARTS=$(jq -c --argjson n "$N" --arg e "$ETAG" '. + [{partNumber: $n, etag: $e}]' <<<"$PARTS")
  N=$((N + 1))
done
"${API_CURL[@]}" -X POST "$COMPLETE_URL" -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -H "Content-Type: application/json" -d "{\"uploadId\": \"$UPLOAD_ID\", \"parts\": $PARTS}" > /dev/null
"${API_CURL[@]}" -X POST "$API/projects/$PROJECT_ID/upload/complete" -H "$AUTH" > /dev/null

# 3) Poll for up to 30 minutes, stop on failure, then download the restored MP3
DEADLINE=$((SECONDS + 1800))
while :; do
  LEFT=$((DEADLINE - SECONDS))
  [ "$LEFT" -gt 0 ] || { echo "timed out waiting for the restore" >&2; exit 1; }
  # Each status call gets at most 60 s, and never more than the time left
  curl -fsS --connect-timeout 10 --max-time $((LEFT < 60 ? LEFT : 60)) \
    "$API/projects/$PROJECT_ID/generations/$GEN_ID" -H "$AUTH" > "$WORK/generation.json"
  STATUS=$(jq -er .status "$WORK/generation.json")
  [ "$STATUS" = "complete" ] && break
  if [ "$STATUS" = "failed" ]; then jq .error "$WORK/generation.json" >&2; exit 1; fi
  sleep $((LEFT < 3 ? LEFT : 3))
done
MEDIA_URL=$("${API_CURL[@]}" "$API/projects/$PROJECT_ID/generations/$GEN_ID/media" -H "$AUTH" | jq -er .files.audio)
"${BULK_CURL[@]}" -o interview-restored.mp3 "$MEDIA_URL"
echo "$PROJECT_ID $GEN_ID interview-restored.mp3"
```

Expected result

The generation reaches `status: "complete"` on `diffio-4.7-flash` and writes the restored recording to `interview-restored.mp3`; each tab prints the project id, the generation id and the file. To fetch the word-timed transcript too, call [Get a generation's transcript](https://diffio.ai/docs/api-reference/get-transcript/) with the returned project and generation ids.

## How it fits together

[Projects](https://diffio.ai/docs/api-reference/create-project/) hold your uploaded audio or video. Each project can run one or more [generations](https://diffio.ai/docs/api-reference/create-generation/) across [Diffio models](https://diffio.ai/docs/overview/models/), and you fetch temporary URLs from [generation media](https://diffio.ai/docs/api-reference/get-generation-media/) to stream or download restored files.

Create a project with a media file, run multiple generations with different models, then download the results.

1. **Create project**: with your audio or video file
2. **Generations** `diffio-4.7-flash` `diffio-4.7-pro`
3. **Download results**: restored audio, video or transcript

## Troubleshooting

- **`401` `403` Pass `Authorization: Bearer <key>` with an active key that has Write permission.**

  The key is missing (`missing_api_key`), invalid (`invalid_api_key`), inactive, or lacks Write permission (`permission_denied`).
- **`402` `insufficient_credit` Add credit on the Billing page of the developer dashboard.**

  Your API credit is used up, or cannot cover the file.
- **`409` `not_ready` Poll the generation until `status` is `complete`, or finish uploading first.**

  The generation, transcript, or separated tracks are still processing (`not_ready`), or `upload/complete` ran before the upload arrived (`upload_missing`).

Every error response includes `error.code`, `error.message` and `error.request_id`. Full error handling and retry rules are in the [Full API guide](https://diffio.ai/docs/developers/full-api-guide/#errors).

## Next steps

[**Full API guide** Create projects, follow upload descriptors, poll stages, paginate lists and scope end users.](https://diffio.ai/docs/developers/full-api-guide/) [**Webhooks guide** Open the webhook portal, subscribe to events and verify Svix signatures.](https://diffio.ai/docs/developers/webhooks/) [**Podcast cleanup in a SaaS app** A complete build: browser uploads, one project list per user and signed webhooks.](https://diffio.ai/docs/developers/guides/saas-podcast-cleanup/) [**API reference** Every endpoint, parameter, request field and response schema.](https://diffio.ai/docs/api-reference/introduction/)

Working with a coding agent? [Build with AI agents](https://diffio.ai/docs/developers/ai-agents/) gives it every docs page as plain text, with a ready prompt.

New releases, and which SDK version talks to which API version, are listed in the [Changelog](https://diffio.ai/docs/overview/changelog/).
