Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

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 takes the raw bytes. A secret API key (or dashboard session) and a verified email are required.

Upload
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.

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 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 until enrichment.status is complete or failed (see Async jobs), or subscribe to audio.enrichment.* webhooks (runnable receiver: 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 lists audio with pagination and folder/collection/metadata filters. GET, PATCH, and DELETE /v1/audio/:id read, organize, or delete one owned asset. POST /v1/audio/:id/sign-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 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