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

[API reference](/docs/api/)

# 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](#object)
-   GET [List audio assets](#list_audio)
-   POST [Upload or securely import original audio](#upload_audio)
-   GET [Get audio metadata, access URL, and transcription status](#get_audio)
-   PATCH [Replace audio organization fields](#update_audio)
-   DELETE [Delete original audio, transcript artifacts, and metadata](#delete_audio)
-   POST [Generate transcript artifacts for an audio asset](#enrich_audio)
-   POST [Mint fresh audio and transcript bearer URLs](#sign_audio_url)

## 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

The Audio object properties

Property

Type

Description

`id`

string

Audio id (`aud_` prefix).

`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 `url`. PixelVault does not transcode audio.

`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

One of: `public`, `private`

`mime_type`

string

Canonical type derived from the inspected container.

One of: `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/ogg`

`size`

integer

Bytes; at most 25,000,000.

min 16

`container`

string nullable

One of: `mp3`, `wav`, `m4a`, `ogg`, `null`

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

One of: `mp3`, `pcm`, `pcm_float`, `aac`, `opus`, `vorbis`, `null`

`duration_seconds`

number nullable

min 0

`sample_rate`

integer nullable

min 8000

`channels`

integer nullable

min 1

`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 `enrichment`

Properties of enrichment

Property

Type

Description

`status`

string

Poll [`get_audio`](/docs/api/audio/#get_audio) until `complete` or `failed`.

One of: `not_requested`, `pending`, `processing`, `complete`, `failed`

`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 `transcript`

Properties of transcript

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

`error`

object

Present when status is `failed`. Call [`enrich_audio`](/docs/api/audio/#enrich_audio) again to retry with a new `job_id`.

Child properties of `error`

Properties of error

Property

Type

Description

`code`

string

`message`

string

`created_at`

string (date-time)

`expires_at`

string (date-time)

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

`temporary`

boolean

Present and true only when `expires_at` is set.

`replayed`

boolean

Present and true when an idempotent retry returns the committed asset.

`signed_expires`

integer

Unix timestamp when private original and transcript bearer URLs expire. Private audio only.

The Audio object

```
{
  "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

Query parameters

Name

Type

Required

Description

`page`

integer

Optional

Page number, from 1.

Default: `1`

min 1

`per_page`

integer

Optional

Assets per page (max 100).

Default: `20`

min 1 · max 100

`folder`

string

Optional

Exact logical-folder match.

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`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. `?meta[show]=42`; combines with `metadata`.

### Responses

-   200
    
    Paginated audio assets
    
-   400
    
    [`invalid_folder`](/docs/errors/#invalid_folder): bad folder name. [`validation_error`](/docs/errors/#validation_error): malformed or conflicting metadata filter.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    `no_project`: the signed-in account has no project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl "https://api.pixelvault.dev/v1/audio?per_page=20" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "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`](/docs/errors/#idempotency_key_reuse); a retry while the first request is still running returns 409 [`idempotency_in_progress`](/docs/errors/#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`](/docs/api/audio/#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](https://pixelvault.dev/tools/audio-to-url/) hosts public originals up to 25,000,000 bytes for 24 hours without an account (see [`playground_audio_upload`](/docs/api/playground/#playground_audio_upload)).

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Headers

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 `audio.<ext>`. A recognized extension must match `Content-Type` ([`container_mismatch`](/docs/errors/#container_mismatch)).

max length 255

`X-PixelVault-Visibility`

string

Optional

Direct uploads: `private` serves the original and transcripts only through signed URLs.

One of: `public`, `private`

Default: `public`

`X-PixelVault-Sign-Expires-In`

integer

Optional

Direct uploads: lifetime in seconds of the returned private URLs. Never deletes the asset.

Default: `3600`

min 60 · max 2592000

`X-PixelVault-Expires-In`

integer

Optional

Direct uploads: delete the asset and its transcripts after this many seconds.

min 60 · max 2592000

`X-PixelVault-Folder`

string

Optional

Direct uploads: logical folder (letters, numbers, hyphens, underscores; max 64).

pattern ^\[A-Za-z0-9\_-\]{1,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 [`idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse).

max length 255 · pattern ^\[\\x21-\\x7e\]+$

`X-PixelVault-Content-SHA256`

string

Optional

Hex SHA-256 of the bytes, verified while streaming. Required with `Idempotency-Key` for a direct upload.

pattern ^\[a-fA-F0-9\]{64}$

### Request body (application/json)

`application/json`, required

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 `Content-Length`.

`filename`

string

Optional

Original filename; defaults to the URL's last path segment.

max length 255

`visibility`

string

Optional

One of: `public`, `private`

Default: `public`

`sign_expires_in`

integer

Optional

Lifetime in seconds of the returned private URLs.

Default: `3600`

min 60 · max 2592000

`expires_in`

integer

Optional

Deletion TTL in seconds; distinct from `sign_expires_in`.

min 60 · max 2592000

`folder`

string nullable

Optional

Logical folder.

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`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`](/docs/errors/#invalid_audio) / [`unsupported_audio_codec`](/docs/errors/#unsupported_audio_codec): the bytes are not an accepted container and codec combination. [`container_mismatch`](/docs/errors/#container_mismatch): the filename extension conflicts with `Content-Type`. [`content_length_mismatch`](/docs/errors/#content_length_mismatch): the body length differs from `Content-Length`. [`checksum_mismatch`](/docs/errors/#checksum_mismatch): the bytes do not match `X-PixelVault-Content-SHA256`. [`idempotency_checksum_required`](/docs/errors/#idempotency_checksum_required): a direct upload with `Idempotency-Key` needs the checksum header. [`missing_file`](/docs/errors/#missing_file): empty body. [`invalid_json`](/docs/errors/#invalid_json) / [`missing_url`](/docs/errors/#missing_url): bad URL-import body. [`url_length_required`](/docs/errors/#url_length_required): the remote server sent no valid `Content-Length`. [`invalid_url`](/docs/errors/#invalid_url), [`unsupported_scheme`](/docs/errors/#unsupported_scheme), [`blocked_host`](/docs/errors/#blocked_host), [`url_fetch_failed`](/docs/errors/#url_fetch_failed): the URL could not be imported. [`invalid_upload`](/docs/errors/#invalid_upload): the stored upload was incomplete. [`invalid_folder`](/docs/errors/#invalid_folder), [`validation_error`](/docs/errors/#validation_error): a bad header or field.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   402
    
    [`upload_limit_reached`](/docs/errors/#upload_limit_reached), [`storage_limit_reached`](/docs/errors/#storage_limit_reached), [`private_limit_reached`](/docs/errors/#private_limit_reached): a plan quota is full.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`collection_not_found`](/docs/errors/#collection_not_found): no such collection in the project. `no_project`: the signed-in account has no project.
    
-   409
    
    [`idempotency_in_progress`](/docs/errors/#idempotency_in_progress): an upload with this `Idempotency-Key` is still running; the error also carries `upload_id`, `asset_id` and `expires_at`. Retry later.
    
-   410
    
    [`idempotency_result_deleted`](/docs/errors/#idempotency_result_deleted): the asset created with this `Idempotency-Key` was deleted; use a new key.
    
-   411
    
    [`length_required`](/docs/errors/#length_required): a direct upload needs a valid `Content-Length`.
    
-   413
    
    [`file_too_large`](/docs/errors/#file_too_large): larger than 25,000,000 bytes. [`request_too_large`](/docs/errors/#request_too_large): a direct request over 100 MB. [`url_too_large`](/docs/errors/#url_too_large): the remote file is too large.
    
-   415
    
    [`unsupported_media_type`](/docs/errors/#unsupported_media_type): `Content-Type` (or, for URL imports, the filename and remote type) is not MP3, WAV, M4A or OGG, or `application/json`.
    
-   422
    
    [`idempotency_key_reuse`](/docs/errors/#idempotency_key_reuse): the `Idempotency-Key` was already used with a different source, bytes, visibility, TTL, folder, collection or metadata. [`collection_visibility_mismatch`](/docs/errors/#collection_visibility_mismatch): the collection's visibility differs from the asset's.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    
-   503
    
    [`audio_policy_pending`](/docs/errors/#audio_policy_pending): audio hosting is disabled until its maximum file size is configured; nothing was stored.
    

Request

curlNode.jsPythonCLI

```
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
```

Response 201

```
{
  "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

Path parameters

Name

Type

Required

Description

`id`

string

Required

Audio id.

### Responses

-   200
    
    Audio asset
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`audio_not_found`](/docs/errors/#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`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPythonCLI

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

Response 200

```
{
  "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

Path parameters

Name

Type

Required

Description

`id`

string

Required

Audio id.

### Request body

`application/json`, required

Request body

Name

Type

Required

Description

`metadata`

object nullable

Optional

Replaces the stored metadata (not merged).

`folder`

string nullable

Optional

New logical folder.

pattern ^\[A-Za-z0-9\_-\]{1,64}$

`collection_id`

string nullable

Optional

An existing collection with the same visibility.

### Responses

-   200
    
    Updated audio asset
    
-   400
    
    [`validation_error`](/docs/errors/#validation_error): the body is not JSON, has none of `metadata`, `folder`, `collection_id`, or a value is invalid. [`invalid_folder`](/docs/errors/#invalid_folder): bad folder name.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`audio_not_found`](/docs/errors/#audio_not_found): no audio asset with this id in the project. [`collection_not_found`](/docs/errors/#collection_not_found): no such collection. `no_project`: the signed-in account has no project.
    
-   413
    
    [`payload_too_large`](/docs/errors/#payload_too_large): the request body is larger than 16 KB.
    
-   422
    
    [`collection_visibility_mismatch`](/docs/errors/#collection_visibility_mismatch): the collection's visibility differs from the asset's.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
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"}'
```

Response 200

```
{
  "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

Path parameters

Name

Type

Required

Description

`id`

string

Required

Audio id.

### Responses

-   200
    
    Deleted
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`audio_not_found`](/docs/errors/#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`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPythonCLI

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

Response 200

```
{
  "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`](/docs/api/audio/#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`](/docs/api/usage/#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

Path parameters

Name

Type

Required

Description

`id`

string

Required

Audio id.

### Responses

-   200
    
    Transcription already complete
    
-   202
    
    Transcription queued or processing
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   402
    
    [`enrichment_limit_reached`](/docs/errors/#enrichment_limit_reached): the shared monthly media-enrichment allowance cannot cover this duration.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`audio_not_found`](/docs/errors/#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`](/docs/errors/#enrichment_source_too_large): the source exceeds 25,000,000 bytes.
    
-   422
    
    [`audio_duration_unavailable`](/docs/errors/#audio_duration_unavailable): the duration is unknown, invalid or under 1 second. [`enrichment_duration_too_long`](/docs/errors/#enrichment_duration_too_long): longer than 10 minutes.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    
-   503
    
    [`enrichment_unavailable`](/docs/errors/#enrichment_unavailable): transcription is temporarily unavailable; nothing was charged.
    

Request

curlNode.jsPython

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

Response 200

```
{
  "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

Path parameters

Name

Type

Required

Description

`id`

string

Required

Audio id.

### Request body

`application/json`, optional

Request body

Name

Type

Required

Description

`expires_in`

integer

Optional

Lifetime of every URL, in seconds.

Default: `3600`

min 60 · max 2592000

### Responses

-   200
    
    Fresh signed URLs
    
-   400
    
    [`invalid_expires_in`](/docs/errors/#invalid_expires_in): `expires_in` is not an integer between 60 and 2592000.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`video_upload_forbidden`](/docs/errors/#video_upload_forbidden): publishable keys cannot use the video and audio endpoints. [`email_verification_required`](/docs/errors/#email_verification_required): verify the account email first. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`audio_not_found`](/docs/errors/#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`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPythonCLI

```
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}'
```

Response 200

```
{
  "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"
  }
}
```
