Video Recordings
Generate a pre-recorded video of your Omniagent speaking — video greetings, training clips, onboarding, and announcements
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 the text and a voice; the API renders a lip-synced, voiced 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
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
Next steps
Related guides and the API reference
Generating a recording
Call POST /public/companions/{companionId}/recordings with the OpenAI voice provider, 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 '{
"provider": "openAi",
"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.",
"previewUrl": null,
"status": "pending",
"createdAt": 1721433600,
"updatedAt": 1721433600,
"tags": null
}Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | Voice provider used for the avatar's speech. Use openAi. |
voiceId | string | Yes | The OpenAI voice name — for example alloy, echo, or shimmer. |
text | string | Yes | The text for the avatar to speak in the video. |
tags | object | No | Arbitrary key–value metadata to attach to the recording. Useful for filtering later. |
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.",
"previewUrl": "https://cdn.napster.com/recordings/rec_xyz789.mp4",
"status": "completed",
"createdAt": 1721433600,
"updatedAt": 1721433742,
"tags": null
}Listing recordings
List all 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
}
],
"filteredCount": 1,
"totalCount": 1,
"pageIndex": 0,
"pageSize": 20,
"search": null
}Query parameters
| Parameter | Type | Description |
|---|---|---|
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.
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