<!-- Markdown twin of https://pixelvault.dev/docs/guides/audio/ -->

# Host & transcribe audio

**Goal:** host an audio original at a stable CDN URL and get a transcript, without transcoding anything. PixelVault stores MP3, WAV, M4A, or OGG bytes exactly as uploaded.

## 1\. Upload the original

[`POST /v1/audio`](/docs/api/audio/#upload_audio) takes the raw bytes. A secret API key (or dashboard session) and a verified email are required.

Upload

curlCLINode.jsPython

```
SIZE=$(wc -c < episode.ogg)
SHA256=$(shasum -a 256 episode.ogg | awk '{print $1}')
curl -X POST https://api.pixelvault.dev/v1/audio \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: audio/ogg" \
  -H "Content-Length: $SIZE" \
  -H "X-PixelVault-Filename: episode.ogg" \
  -H "X-PixelVault-Content-SHA256: $SHA256" \
  -H "Idempotency-Key: episode-v1" \
  --data-binary @episode.ogg
```

```
{ "data": {
  "id": "aud_abc123",
  "kind": "audio",
  "original_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
  "visibility": "public",
  "mime_type": "audio/ogg",
  "size": 1843200,
  "container": "ogg",
  "codec": "opus",
  "duration_seconds": 42.4,
  "sample_rate": 48000,
  "channels": 2
} }
```

PixelVault inspects the file itself: accepted combinations are MPEG Layer III in MP3, PCM integer or IEEE-float WAV, AAC in M4A, and Opus or Vorbis in OGG. Renaming a file or changing its MIME type does not bypass validation.

**Limit:** audio originals have one approved global maximum of **25,000,000 bytes**. This byte ceiling is not a plan allowance or capacity reservation. Audio uses the existing upload count, storage, bandwidth, private-asset, and retention rules; no audio-specific pricing or transformation allowance was added.

**Retry safety:** `Idempotency-Key` is scoped to the authenticated project and audio endpoint for 24 hours. Exact retries return the committed asset; conflicting source, bytes, visibility, TTL, folder, collection, or metadata return `422 idempotency_key_reuse`. Direct byte uploads with a key also require `X-PixelVault-Content-SHA256`. This is request idempotency, not cross-owner or cross-visibility content deduplication. Details: [Idempotency](/docs/idempotency/).

### Import by URL

Send `application/json` with a `url` and optional `filename`. PixelVault applies the same SSRF-safe importer, requires a valid remote `Content-Length`, validates downloaded bytes, and enforces the same 25,000,000-byte maximum.

```
curl -X POST https://api.pixelvault.dev/v1/audio \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://media.example/episode.m4a","filename":"episode.m4a"}'
```

## 2\. Transcribe it

Call [`POST /v1/audio/:id/enrich`](/docs/api/audio/#enrich_audio) for owned audio up to 25,000,000 bytes and 10 minutes. The idempotent call returns 202 while queued or processing and 200 when complete. Poll [`GET /v1/audio/:id`](/docs/api/audio/#get_audio) until `enrichment.status` is `complete` or `failed` (see [Async jobs](/docs/async-jobs/)), or subscribe to `audio.enrichment.*` [webhooks](/docs/webhooks/) (runnable receiver: [`audio-enrichment-webhook.mjs`](/examples/audio-enrichment-webhook.mjs)). A failed job may be retried; the new attempt gets a new `aen_` job ID. A local polling timeout never cancels the server job.

```
curl -X POST https://api.pixelvault.dev/v1/audio/aud_abc123/enrich \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

→ { "data": {
     "id": "aud_abc123",
     "original_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
     "enrichment": {
       "job_id": "aen_abc123",
       "status": "complete",
       "transcript": {
         "status": "complete",
         "text_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.transcript.txt",
         "vtt_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.transcript.vtt",
         "segments_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.transcript.json",
         "language": "en"
       }
     }
   } }
```

Audio transcription uses the existing monthly _media enrichment_ allowance shared with video transcript/storyboard jobs: 2 minutes on Free, 30 minutes on Starter, and 120 minutes on Pro. The remaining allowance must cover the whole source duration. `GET /v1/usage` reports this legacy-named shared counter as `video_enrichment`. Transcript files use ordinary storage and bandwidth quota. No separate audio price or entitlement was added.

## 3\. Privacy, expiry and organization

Use `X-PixelVault-Visibility: private`, `X-PixelVault-Sign-Expires-In`, `X-PixelVault-Expires-In`, `X-PixelVault-Folder`, `X-PixelVault-Collection-Id` (same-visibility collection), and `X-PixelVault-Metadata` headers on direct uploads; URL imports use equivalent JSON fields. Signed-link expiry never deletes the asset. Deletion TTL fails an active transcription job, returns its reserved allowance, and removes the original plus every completed transcript artifact. The hourly sweep can lag by up to about two hours.

```
# Secure server-side URL import with replay safety
npx pixelvault-cli audio upload https://media.example/episode.ogg --idempotency-key episode-v1 --json
# Resume lifecycle work from the stable aud_ ID
npx pixelvault-cli audio get aud_abc --json
npx pixelvault-cli audio sign aud_abc --expires 1h
npx pixelvault-cli audio delete aud_abc
```

[`GET /v1/audio`](/docs/api/audio/#list_audio) lists audio with pagination and folder/collection/metadata filters. `GET`, [`PATCH`](/docs/api/audio/#update_audio), and [`DELETE /v1/audio/:id`](/docs/api/audio/#delete_audio) read, organize, or delete one owned asset. [`POST /v1/audio/:id/sign-url`](/docs/api/audio/#sign_audio_url) mints one expiry-matched set containing the private original and only transcript artifacts that exist, without changing privacy or deletion TTL. Public and correctly signed private originals support `HEAD` and one HTTP byte range (`206` or `416`); unsigned private requests return `403`.

## Not supported

Intentionally unsupported: audio editing, transcoding or conversion, HLS/DASH, streaming manifests, storyboards, summaries, show notes, chapters, and promotional-copy generation. Audio has no resumable multipart upload. The [free browser tool](/tools/audio-to-url/) hosts public MP3, WAV, M4A, and OGG originals up to 25,000,000 bytes; anonymous links last up to 24 hours and can be saved to an account without re-uploading. Transcription requires an owned asset and authentication.

## Next steps

-   [Share private audio](/docs/guides/signed-urls/) with signed URLs.
-   [Transcribe video](/docs/guides/video-transcripts/) with the same allowance.
-   [MCP](/docs/mcp/): `upload_audio` and `enrich_audio` for agents.
