Video Recordings

Generate a pre-recorded video of your Omniagent speaking — video greetings, training clips, onboarding, and announcements

Recordings must be enabled for your organization before you can create them. Until then, creating a recording fails with a RecordingsApiNotEnabled error. To request access, contact us with your organization ID.

A recording is a pre-recorded video of your Omniagent's avatar speaking text you provide — a video greeting, a training or onboarding clip, or an announcement. Use it anywhere a fixed, pre-recorded clip works better than a live session, so you get the same polished delivery every time.

You supply either text and a voice, or an audio track; the API renders a lip-synced video of the companion that you can preview, download, and reuse. Recordings are generated asynchronously: each one starts as a job that moves through a few states before the video is ready.

Generating a recording

Create a recording job with voice and text

Generating from audio

Lip-sync the avatar to an audio file

Recording lifecycle

Status values from pending to completed

Retrieving a recording

Fetch one recording to check its status

Listing recordings

Paginated recording list with filters

Downloading a recording

Request a time-limited download URL

Deleting a recording

Permanently remove a recording

Errors

Why a recording request is rejected

Next steps

Related guides and the API reference

Generating a recording

Call POST /public/companions/{companionId}/recordings with a voice and the text for the avatar to speak.

curl -X POST https://companion-api.napster.com/public/companions/comp_abc123/recordings \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceId": "alloy",
    "text": "Welcome to Acme. In this short clip, I will walk you through everything you need to get started."
  }'

The response returns the recording with a status of pending — the video is rendered in the background.

{
  "id": "rec_xyz789",
  "provider": "openAi",
  "voiceId": "alloy",
  "text": "Welcome to Acme. In this short clip, I will walk you through everything you need to get started.",
  "audioUrl": null,
  "fromFile": false,
  "previewUrl": null,
  "status": "pending",
  "createdAt": 1721433600,
  "updatedAt": 1721433600,
  "tags": null,
  "companion": {
    "id": "comp_abc123",
    "firstName": "Ava",
    "lastName": "Reed"
  }
}

Request parameters

Parameter	Type	Required	Description
`text`	string	Conditional	The text for the avatar to speak, 84–30,000 characters. Required unless you pass `audioUrl`.
`voiceId`	string	Conditional	The voice to speak with — for example `alloy`, `echo`, or `shimmer`. Required with `text`, except for digital twins, which use their cloned voice when you omit it.
`provider`	string	No	The voice provider: `openAi` (default) or `elevenLabs`. Use `elevenLabs` to pick a digital twin's cloned voice explicitly, passing its `externalId` from the companion's `customVoices` as `voiceId`.
`audioUrl`	string	Conditional	An `http` or `https` URL of an audio file for the avatar to lip-sync to. Use instead of `text` — see Generating from audio.
`tags`	object	No	Arbitrary key–value metadata to attach to the recording. Useful for filtering later.

Pass exactly one of text or audioUrl.

Generating from audio

Instead of text, the avatar can lip-sync to audio you provide — a voice-over or a recorded message. The recording uses the audio as is, so voiceId and provider don't apply.

Pass a link to the file as audioUrl:

curl -X POST https://companion-api.napster.com/public/companions/comp_abc123/recordings \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audioUrl": "https://assets.acme.com/audio/welcome.mp3"
  }'

Or upload the file directly with POST /public/companions/{companionId}/recordings/from-file as multipart/form-data:

curl -X POST https://companion-api.napster.com/public/companions/comp_abc123/recordings/from-file \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -F "[email protected]" \
  -F "Tags[campaign]=onboarding"

Both return the recording with a status of pending. Uploaded recordings have fromFile set to true.

	`audioUrl`	Upload (`from-file`)
Maximum size	50 MB	2 MB
Formats	MP3, WAV, M4A, FLAC, OGG, WebM, MP4	MP3, WAV, M4A, FLAC, OGG, WebM, MP4

Recording lifecycle

A recording moves through these status values:

Status	Meaning
`pending`	The job is queued.
`processing`	The avatar video is being rendered.
`uploading`	Rendering finished; the video is being stored.
`completed`	The video is ready. `previewUrl` is populated and the download URL is available.
`failed`	Rendering did not succeed.

Poll the recording (see below) until status is completed, then use previewUrl to play it inline or request a download URL for the video file.

Retrieving a recording

Fetch a single recording by ID to check its status or read back its details.

curl https://companion-api.napster.com/public/companions/comp_abc123/recordings/rec_xyz789 \
  -H "X-Api-Key: $NAPSTER_API_KEY"

{
  "id": "rec_xyz789",
  "provider": "openAi",
  "voiceId": "alloy",
  "text": "Welcome to Acme. In this short clip, I will walk you through everything you need to get started.",
  "audioUrl": null,
  "fromFile": false,
  "previewUrl": "https://cdn.napster.com/recordings/rec_xyz789.mp4",
  "status": "completed",
  "createdAt": 1721433600,
  "updatedAt": 1721433742,
  "tags": null,
  "companion": {
    "id": "comp_abc123",
    "firstName": "Ava",
    "lastName": "Reed"
  }
}

Listing recordings

List the recordings for a companion. The response is paginated and supports several filters.

curl "https://companion-api.napster.com/public/companions/comp_abc123/recordings?pageSize=20" \
  -H "X-Api-Key: $NAPSTER_API_KEY"

{
  "items": [
    {
      "id": "rec_xyz789",
      "provider": "openAi",
      "voiceId": "alloy",
      "previewUrl": "https://cdn.napster.com/recordings/rec_xyz789.mp4",
      "status": "completed",
      "createdAt": 1721433600,
      "updatedAt": 1721433742,
      "tags": null,
      "companion": {
        "id": "comp_abc123",
        "firstName": "Ava",
        "lastName": "Reed"
      }
    }
  ],
  "filteredCount": 1,
  "totalCount": 1,
  "pageIndex": 0,
  "pageSize": 20,
  "search": null
}

To list recordings across every companion in your project, call GET /public/recordings. It returns the same shape and accepts the same filters, plus companionId:

curl "https://companion-api.napster.com/public/recordings?companionId=comp_abc123&pageSize=20" \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Query parameters

Parameter	Type	Description
`companionId`	string	`GET /public/recordings` only. Filter to one companion's recordings.
`provider`	string	Filter by voice provider: `openAi` or `elevenLabs`.
`voiceId`	string	Filter to recordings made with a specific voice.
`search`	string	Free-text search across the recording text.
`tags`	object	Filter by tag values — a map of tag name to a list of matching values, e.g. `tags[campaign]=onboarding`.
`pageIndex`	integer	Zero-based page number.
`pageSize`	integer	Number of results per page.

Downloading a recording

Once a recording is completed, request a download URL for the video file. The URL is time-limited, so fetch it when you need it rather than storing it.

curl https://companion-api.napster.com/public/companions/comp_abc123/recordings/rec_xyz789/download-url \
  -H "X-Api-Key: $NAPSTER_API_KEY"

{
  "url": "https://cdn.napster.com/recordings/rec_xyz789.mp4?token=..."
}

Deleting a recording

Remove a recording you no longer need.

curl -X DELETE https://companion-api.napster.com/public/companions/comp_abc123/recordings/rec_xyz789 \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Deleting a recording is permanent. Any content referencing its video URL stops resolving.

Errors

A rejected request returns 400 with one of these codes:

Code	When
`InvalidRecordingTextLength`	`text` is shorter than 84 or longer than 30,000 characters.
`VoiceIdRequired`	You sent `text` without a `voiceId` for a companion that isn't a digital twin.
`ClonedVoiceNotAvailable`	The digital twin's cloned voice isn't ready yet.
`AudioUnsupportedFormat`	The audio isn't in one of the supported formats.
`AudioTooLarge`	The audio is over 50 MB (`audioUrl`) or 2 MB (upload).
`AudioValidationFailed`	The audio couldn't be read, or has no audio track.
`NoAvailableConnections`	No rendering capacity is free right now. Retry later.

Sending both text and audioUrl, neither of them, or an audioUrl that isn't an http or https URL returns a 400 validation error.

Next steps

Digital Twins — build a companion from a real person's voice and likeness
Avatar Models — configure the visual avatar for your companion
API reference: Recordings — full request and response schemas

Video Recordings

Generating a recording

Generating from audio

Recording lifecycle

Retrieving a recording

Listing recordings

Downloading a recording

Deleting a recording

Errors

Next steps

On this page