Audio
Host original MP3, WAV, M4A and OGG files without transcoding (max 25,000,000 bytes), served with HTTP range support. Optional transcription produces plain-text, WebVTT and timestamped JSON transcripts.
The Audio object
A hosted original MP3, WAV, M4A or OGG file. Bytes are stored and served unchanged (no transcoding), with HEAD and single-range (206; unsatisfiable ranges 416) support on the CDN. Transcript artifacts inherit the asset's visibility, deletion TTL and signed-URL expiry.
Properties
| Property | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | string | Audio id ( | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
kind | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url | string (uri) | CDN URL of the original. Signed for private audio; unsigned private requests get 403 (no public fallback). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
original_url | string (uri) | The original uploaded bytes; equal to | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
branded_url | string (uri) | The original served from the project's active custom domain. Present only when a ready custom domain exists; signed query parameters are preserved. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
visibility | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mime_type | string | Canonical type derived from the inspected container. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
size | integer | Bytes; at most 25,000,000. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
container | string nullable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
codec | string nullable | Accepted combinations: MPEG Layer III in MP3, PCM integer or IEEE float in WAV, AAC in M4A, Opus or Vorbis in OGG. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
duration_seconds | number nullable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sample_rate | integer nullable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
channels | integer nullable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
filename | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
folder | string nullable | Logical folder used for organization and list filtering. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collection_id | string nullable | Collection membership; the collection's visibility matches the asset's. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadata | object nullable | Caller-managed custom metadata (max 50 top-level keys, 4 KB). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
enrichment | AudioEnrichment | State of the optional transcription job. Text, WebVTT, and timestamped JSON artifacts inherit the audio asset's visibility, deletion TTL, and signed-URL expiry. Audio enrichment does not create storyboards. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Child properties of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Property | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
status | string | Poll | |||||||||||||||||||||||||||
job_id | string | Stable identifier for this transcription attempt. Repeated requests while queued, running, or complete return the same job ID; retrying a failed job creates a new one. | |||||||||||||||||||||||||||
requested_at | string (date-time) | ||||||||||||||||||||||||||||
completed_at | string (date-time) nullable | ||||||||||||||||||||||||||||
transcript | object nullable | ||||||||||||||||||||||||||||
Child properties of | |||||||||||||||||||||||||||||
| Property | Type | Description |
|---|---|---|
status | string | |
text_url | string (uri) | Plain-text transcript. |
vtt_url | string (uri) | Timed WebVTT captions. |
segments_url | string (uri) | Timestamped JSON segments. |
language | string nullable | |
languages | array of string | |
model | string nullable | |
segment_count | integer |
errorPresent when status is failed. Call enrich_audio again to retry with a new job_id.
Child properties of error
| Property | Type | Description |
|---|---|---|
code | string | |
message | string |
created_atexpires_atDeletion time for a temporary audio asset. The hourly sweep can lag by about two hours; it fails an active transcription, returns its reserved seconds, and deletes the original plus transcripts. Signed-URL expiry is separate.
temporaryPresent and true only when expires_at is set.
replayedPresent and true when an idempotent retry returns the committed asset.
signed_expiresUnix timestamp when private original and transcript bearer URLs expire. Private audio only.
{
"id": "aud_abc123",
"kind": "audio",
"url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"original_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"branded_url": "https://media.example.com/aud_abc123.ogg",
"visibility": "public",
"mime_type": "audio/ogg",
"size": 1843200,
"container": "ogg",
"codec": "opus",
"duration_seconds": 42.4,
"sample_rate": 48000,
"channels": 2,
"filename": "episode.ogg",
"folder": "episodes",
"collection_id": "col_abc123",
"metadata": {
"show": "42"
},
"enrichment": {
"status": "complete",
"job_id": "aen_abc123",
"requested_at": "2026-11-16T12:00:00.000Z",
"completed_at": "2026-11-16T12:00:40.000Z",
"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",
"languages": [
"en"
],
"model": "@cf/openai/whisper-large-v3-turbo",
"segment_count": 12
},
"error": {
"code": "transcription_failed",
"message": "The audio could not be transcribed."
}
},
"created_at": "2026-11-16T12:00:00.000Z",
"expires_at": "2026-11-17T12:00:00.000Z",
"temporary": true,
"replayed": true,
"signed_expires": 1795449600
}List audio assets
GET /v1/audio
A page of the project's audio assets, newest first, with folder, collection and custom-metadata filters (combined with AND). Private assets carry fresh signed URLs (1 hour).
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | integer | Optional | Page number, from 1. |
per_page | integer | Optional | Assets per page (max 100). |
folder | string | Optional | Exact logical-folder match. |
collection_id | string | Optional | Only assets in this collection. |
metadata | string | Optional | JSON object; returns assets whose custom metadata contains every key/value pair. |
meta[key] | string | Optional | Shorthand string match on one metadata key, e.g. |
Responses
- 200
Paginated audio assets
- 400
invalid_folder: bad folder name.validation_error: malformed or conflicting metadata filter. - 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 403
video_upload_forbidden: publishable keys cannot use the video and audio endpoints.email_verification_required: verify the account email first.account_suspended: the account is suspended. - 404
no_project: the signed-in account has no project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl "https://api.pixelvault.dev/v1/audio?per_page=20" \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": [
{
"id": "aud_abc123",
"kind": "audio",
"url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"original_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"branded_url": "https://media.example.com/aud_abc123.ogg",
"visibility": "public",
"mime_type": "audio/ogg",
"size": 1843200,
"container": "ogg",
"codec": "opus",
"duration_seconds": 42.4,
"sample_rate": 48000,
"channels": 2,
"filename": "episode.ogg",
"folder": "episodes",
"collection_id": "col_abc123",
"metadata": {
"show": "42"
},
"enrichment": {
"status": "complete",
"job_id": "aen_abc123",
"requested_at": "2026-11-16T12:00:00.000Z",
"completed_at": "2026-11-16T12:00:40.000Z",
"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",
"languages": [
"en"
],
"model": "@cf/openai/whisper-large-v3-turbo",
"segment_count": 12
},
"error": {
"code": "transcription_failed",
"message": "The audio could not be transcribed."
}
},
"created_at": "2026-11-16T12:00:00.000Z",
"expires_at": "2026-11-17T12:00:00.000Z",
"temporary": true,
"replayed": true,
"signed_expires": 1795449600
}
],
"meta": {
"total": 42,
"page": 1,
"per_page": 20
}
} Upload or securely import original audio
POST /v1/audio
Host original MP3, WAV, M4A or OGG bytes without transcoding and get a stable aud_ id and CDN URL. Requires a secret API key or dashboard session and a verified email.
PixelVault inspects the bytes: MP3 must contain MPEG Layer III, WAV must be PCM integer or IEEE float, M4A must contain AAC, and OGG must contain Opus or Vorbis. Renaming a file or changing its MIME type does not bypass validation. The response includes canonical MIME type, size, container, codec, duration, sample rate and channels.
Limit: originals have one global maximum of 25,000,000 bytes. It is not a plan allowance or capacity reservation: audio uses the existing upload-count, storage, bandwidth, private-asset (100 on Free) and retention rules.
Direct upload: send the bytes with Content-Type: audio/mpeg|audio/wav|audio/mp4|audio/ogg, Content-Length, and optional X-PixelVault-* headers for filename, visibility, signed-URL lifetime, deletion TTL, folder, collection and metadata.
Import by URL: send application/json with an https url and the equivalent JSON fields. The SSRF-safe importer requires a valid remote Content-Length, identifies the format from the filename extension or Content-Type, streams and validates the bytes (5-minute timeout), and enforces the same maximum.
Retry safety: Idempotency-Key is scoped to the project and the audio endpoint for 24 hours. An exact retry returns the committed asset (200, replayed: true); conflicting source, bytes, visibility, TTL, folder, collection or metadata return 422 idempotency_key_reuse; a retry while the first request is still running returns 409 idempotency_in_progress. Direct uploads with a key must also send X-PixelVault-Content-SHA256. This is request idempotency, not cross-owner or cross-visibility content deduplication.
Lifecycle: signed-link expiry (sign_expires_in) never deletes the asset. Deletion TTL (expires_in) fails an active transcription, returns its reserved allowance, and removes the original plus every transcript artifact; the hourly sweep can lag by about two hours.
Transcribe with enrich_audio. Intentionally unsupported: audio editing, transcoding or conversion, HLS/DASH, streaming manifests, storyboards, summaries, show notes, chapters and promotional copy. The free Audio to URL tool hosts public originals up to 25,000,000 bytes for 24 hours without an account (see playground_audio_upload).
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
X-PixelVault-Filename | string | Optional | Direct uploads: original filename, 1–255 UTF-8 bytes (percent-encode non-ASCII). Defaults to |
X-PixelVault-Visibility | string | Optional | Direct uploads: |
X-PixelVault-Sign-Expires-In | integer | Optional | Direct uploads: lifetime in seconds of the returned private URLs. Never deletes the asset. |
X-PixelVault-Expires-In | integer | Optional | Direct uploads: delete the asset and its transcripts after this many seconds. |
X-PixelVault-Folder | string | Optional | Direct uploads: logical folder (letters, numbers, hyphens, underscores; max 64). |
X-PixelVault-Collection-Id | string | Optional | Direct uploads: an existing collection with the same visibility. |
X-PixelVault-Metadata | string | Optional | Direct uploads: custom metadata as a JSON object string (max 50 keys, 4 KB). |
Idempotency-Key | string | Optional | Up to 255 non-space printable ASCII characters; replays for 24 hours within this project. Conflicting inputs return 422 |
X-PixelVault-Content-SHA256 | string | Optional | Hex SHA-256 of the bytes, verified while streaming. Required with |
Request body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | Required | Public https URL of an MP3, WAV, M4A or OGG file. Must return |
filename | string | Optional | Original filename; defaults to the URL's last path segment. |
visibility | string | Optional | |
sign_expires_in | integer | Optional | Lifetime in seconds of the returned private URLs. |
expires_in | integer | Optional | Deletion TTL in seconds; distinct from |
folder | string nullable | Optional | Logical folder. |
collection_id | string nullable | Optional | An existing collection with the same visibility. |
metadata | object nullable | Optional | Custom metadata (max 50 keys, 4 KB). |
Request body (raw bytes)
The file bytes as the request body, with Content-Type set to
audio/mpeg, audio/wav, audio/mp4 or audio/ogg.
Responses
- 200
Committed idempotent upload replayed (
replayed: true) - 201
Audio hosted
- 400
invalid_audio/unsupported_audio_codec: the bytes are not an accepted container and codec combination.container_mismatch: the filename extension conflicts withContent-Type.content_length_mismatch: the body length differs fromContent-Length.checksum_mismatch: the bytes do not matchX-PixelVault-Content-SHA256.idempotency_checksum_required: a direct upload withIdempotency-Keyneeds the checksum header.missing_file: empty body.invalid_json/missing_url: bad URL-import body.url_length_required: the remote server sent no validContent-Length.invalid_url,unsupported_scheme,blocked_host,url_fetch_failed: the URL could not be imported.invalid_upload: the stored upload was incomplete.invalid_folder,validation_error: a bad header or field. - 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 402
upload_limit_reached,storage_limit_reached,private_limit_reached: a plan quota is full. - 403
video_upload_forbidden: publishable keys cannot use the video and audio endpoints.email_verification_required: verify the account email first.account_suspended: the account is suspended. - 404
collection_not_found: no such collection in the project.no_project: the signed-in account has no project. - 409
idempotency_in_progress: an upload with thisIdempotency-Keyis still running; the error also carriesupload_id,asset_idandexpires_at. Retry later. - 410
idempotency_result_deleted: the asset created with thisIdempotency-Keywas deleted; use a new key. - 411
length_required: a direct upload needs a validContent-Length. - 413
file_too_large: larger than 25,000,000 bytes.request_too_large: a direct request over 100 MB.url_too_large: the remote file is too large. - 415
unsupported_media_type:Content-Type(or, for URL imports, the filename and remote type) is not MP3, WAV, M4A or OGG, orapplication/json. - 422
idempotency_key_reuse: theIdempotency-Keywas already used with a different source, bytes, visibility, TTL, folder, collection or metadata.collection_visibility_mismatch: the collection's visibility differs from the asset's. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After. - 503
audio_policy_pending: audio hosting is disabled until its maximum file size is configured; nothing was stored.
curl -X POST https://api.pixelvault.dev/v1/audio \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "X-PixelVault-Filename: episode.ogg" \
-H "Content-Type: audio/mpeg" \
--data-binary @episode.mp3 {
"data": {
"id": "aud_abc123",
"kind": "audio",
"url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"original_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"branded_url": "https://media.example.com/aud_abc123.ogg",
"visibility": "public",
"mime_type": "audio/ogg",
"size": 1843200,
"container": "ogg",
"codec": "opus",
"duration_seconds": 42.4,
"sample_rate": 48000,
"channels": 2,
"filename": "episode.ogg",
"folder": "episodes",
"collection_id": "col_abc123",
"metadata": {
"show": "42"
},
"enrichment": {
"status": "complete",
"job_id": "aen_abc123",
"requested_at": "2026-11-16T12:00:00.000Z",
"completed_at": "2026-11-16T12:00:40.000Z",
"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",
"languages": [
"en"
],
"model": "@cf/openai/whisper-large-v3-turbo",
"segment_count": 12
},
"error": {
"code": "transcription_failed",
"message": "The audio could not be transcribed."
}
},
"created_at": "2026-11-16T12:00:00.000Z",
"expires_at": "2026-11-17T12:00:00.000Z",
"temporary": true,
"replayed": true,
"signed_expires": 1795449600
}
} Get audio metadata, access URL, and transcription status
GET /v1/audio/{id}
One audio asset: original metadata, organization fields and transcription state. Poll this while enrichment.status is pending or processing. Private assets return fresh signed URLs (1 hour) for the original and existing transcripts.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Audio id. |
Responses
- 200
Audio asset
- 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 403
video_upload_forbidden: publishable keys cannot use the video and audio endpoints.email_verification_required: verify the account email first.account_suspended: the account is suspended. - 404
audio_not_found: no audio asset with this id in the project.no_project: the signed-in account has no project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl https://api.pixelvault.dev/v1/audio/aud_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": {
"id": "aud_abc123",
"kind": "audio",
"url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"original_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"branded_url": "https://media.example.com/aud_abc123.ogg",
"visibility": "public",
"mime_type": "audio/ogg",
"size": 1843200,
"container": "ogg",
"codec": "opus",
"duration_seconds": 42.4,
"sample_rate": 48000,
"channels": 2,
"filename": "episode.ogg",
"folder": "episodes",
"collection_id": "col_abc123",
"metadata": {
"show": "42"
},
"enrichment": {
"status": "complete",
"job_id": "aen_abc123",
"requested_at": "2026-11-16T12:00:00.000Z",
"completed_at": "2026-11-16T12:00:40.000Z",
"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",
"languages": [
"en"
],
"model": "@cf/openai/whisper-large-v3-turbo",
"segment_count": 12
},
"error": {
"code": "transcription_failed",
"message": "The audio could not be transcribed."
}
},
"created_at": "2026-11-16T12:00:00.000Z",
"expires_at": "2026-11-17T12:00:00.000Z",
"temporary": true,
"replayed": true,
"signed_expires": 1795449600
}
} Replace audio organization fields
PATCH /v1/audio/{id}
Replace custom metadata, logical folder and/or collection membership. Send at least one field; omitted fields remain unchanged and null clears. The collection's visibility must match the asset's. The request body may be at most 16 KB.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Audio id. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
metadata | object nullable | Optional | Replaces the stored metadata (not merged). |
folder | string nullable | Optional | New logical folder. |
collection_id | string nullable | Optional | An existing collection with the same visibility. |
Responses
- 200
Updated audio asset
- 400
validation_error: the body is not JSON, has none ofmetadata,folder,collection_id, or a value is invalid.invalid_folder: bad folder name. - 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 403
video_upload_forbidden: publishable keys cannot use the video and audio endpoints.email_verification_required: verify the account email first.account_suspended: the account is suspended. - 404
audio_not_found: no audio asset with this id in the project.collection_not_found: no such collection.no_project: the signed-in account has no project. - 413
payload_too_large: the request body is larger than 16 KB. - 422
collection_visibility_mismatch: the collection's visibility differs from the asset's. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl -X PATCH https://api.pixelvault.dev/v1/audio/aud_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata":{"show":"42","season":"2"},"folder":"episodes"}' {
"data": {
"id": "aud_abc123",
"kind": "audio",
"url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"original_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"branded_url": "https://media.example.com/aud_abc123.ogg",
"visibility": "public",
"mime_type": "audio/ogg",
"size": 1843200,
"container": "ogg",
"codec": "opus",
"duration_seconds": 42.4,
"sample_rate": 48000,
"channels": 2,
"filename": "episode.ogg",
"folder": "episodes",
"collection_id": "col_abc123",
"metadata": {
"show": "42"
},
"enrichment": {
"status": "complete",
"job_id": "aen_abc123",
"requested_at": "2026-11-16T12:00:00.000Z",
"completed_at": "2026-11-16T12:00:40.000Z",
"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",
"languages": [
"en"
],
"model": "@cf/openai/whisper-large-v3-turbo",
"segment_count": 12
},
"error": {
"code": "transcription_failed",
"message": "The audio could not be transcribed."
}
},
"created_at": "2026-11-16T12:00:00.000Z",
"expires_at": "2026-11-17T12:00:00.000Z",
"temporary": true,
"replayed": true,
"signed_expires": 1795449600
}
} Delete original audio, transcript artifacts, and metadata
DELETE /v1/audio/{id}
Permanently delete an audio asset: the original, every transcript artifact and the record are removed and their storage freed; signed URLs stop working. An active transcription is failed and its reserved seconds returned. Emits media.deleted.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Audio id. |
Responses
- 200
Deleted
- 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 403
video_upload_forbidden: publishable keys cannot use the video and audio endpoints.email_verification_required: verify the account email first.account_suspended: the account is suspended. - 404
audio_not_found: no audio asset with this id in the project.no_project: the signed-in account has no project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl -X DELETE https://api.pixelvault.dev/v1/audio/aud_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"success": true
} Generate transcript artifacts for an audio asset
POST /v1/audio/{id}/enrich
Start or resume speech-to-text for an owned audio asset. Returns the asset with a stable aen_ job id immediately: 202 while queued or processing, 200 when complete. Poll get_audio until enrichment.status is complete or failed; a completed job exposes plain-text, timed WebVTT and timestamped JSON segment URLs.
Repeating the call while pending, processing or complete returns the same attempt without duplicate work; calling it after a failure starts a new attempt with a new job_id. A local polling timeout never cancels the server job. Emits audio.enrichment.completed or audio.enrichment.failed.
Sources are limited to 25,000,000 bytes and 1 second to 10 minutes. Audio and video jobs share the monthly media-enrichment allowance (2 minutes Free, 30 Starter, 120 Pro), reported by get_usage under the backward-compatible name video_enrichment; the remaining allowance must cover the whole source duration. Transcript files use ordinary storage and bandwidth quota and stay private for private audio (expiry-matched signed URLs). Audio enrichment does not create storyboards, summaries, show notes, chapters or promotional copy.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Audio id. |
Responses
- 200
Transcription already complete
- 202
Transcription queued or processing
- 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 402
enrichment_limit_reached: the shared monthly media-enrichment allowance cannot cover this duration. - 403
video_upload_forbidden: publishable keys cannot use the video and audio endpoints.email_verification_required: verify the account email first.account_suspended: the account is suspended. - 404
audio_not_found: no audio asset with this id in the project.no_project: the signed-in account has no project. - 413
enrichment_source_too_large: the source exceeds 25,000,000 bytes. - 422
audio_duration_unavailable: the duration is unknown, invalid or under 1 second.enrichment_duration_too_long: longer than 10 minutes. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After. - 503
enrichment_unavailable: transcription is temporarily unavailable; nothing was charged.
curl -X POST https://api.pixelvault.dev/v1/audio/aud_abc123/enrich \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": {
"id": "aud_abc123",
"kind": "audio",
"url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"original_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg",
"branded_url": "https://media.example.com/aud_abc123.ogg",
"visibility": "public",
"mime_type": "audio/ogg",
"size": 1843200,
"container": "ogg",
"codec": "opus",
"duration_seconds": 42.4,
"sample_rate": 48000,
"channels": 2,
"filename": "episode.ogg",
"folder": "episodes",
"collection_id": "col_abc123",
"metadata": {
"show": "42"
},
"enrichment": {
"status": "complete",
"job_id": "aen_abc123",
"requested_at": "2026-11-16T12:00:00.000Z",
"completed_at": "2026-11-16T12:00:40.000Z",
"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",
"languages": [
"en"
],
"model": "@cf/openai/whisper-large-v3-turbo",
"segment_count": 12
},
"error": {
"code": "transcription_failed",
"message": "The audio could not be transcribed."
}
},
"created_at": "2026-11-16T12:00:00.000Z",
"expires_at": "2026-11-17T12:00:00.000Z",
"temporary": true,
"replayed": true,
"signed_expires": 1795449600
}
} Mint fresh audio and transcript bearer URLs
POST /v1/audio/{id}/sign-url
Mint one expiry-matched set of bearer URLs: the original plus only the transcript artifacts that exist. Does not change the asset's visibility or deletion TTL. Use it when private links (including a webhook payload's) expire.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Audio id. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
expires_in | integer | Optional | Lifetime of every URL, in seconds. |
Responses
- 200
Fresh signed URLs
- 400
invalid_expires_in:expires_inis not an integer between 60 and 2592000. - 401
unauthorized: no Bearer token, or the dashboard session is invalid or expired.invalid_api_key: the API key is unknown or revoked. - 403
video_upload_forbidden: publishable keys cannot use the video and audio endpoints.email_verification_required: verify the account email first.account_suspended: the account is suspended. - 404
audio_not_found: no audio asset with this id in the project.no_project: the signed-in account has no project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl -X POST https://api.pixelvault.dev/v1/audio/aud_abc123/sign-url \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expires_in":3600}' {
"data": {
"url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg?token=3f9a…&expires=1795449600",
"original_url": "https://img.pixelvault.dev/proj_xyz789/aud_abc123.ogg?token=3f9a…&expires=1795449600",
"branded_url": "https://media.example.com/cp/a/aud_abc123.ogg?token=3f9a…&expires=1795449600",
"enrichment": {
"status": "complete",
"job_id": "aen_abc123",
"requested_at": "2026-11-16T12:00:00.000Z",
"completed_at": "2026-11-16T12:00:40.000Z",
"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",
"languages": [
"en"
],
"model": "@cf/openai/whisper-large-v3-turbo",
"segment_count": 12
},
"error": {
"code": "transcription_failed",
"message": "The audio could not be transcribed."
}
},
"expires": 1795449600,
"visibility": "private"
}
}