Digital Twins

A digital twin is a companion based on a real person. It uses the person's actual voice recording and likeness to produce an avatar that looks and sounds like them. Once created, a digital twin returns a companion ID that you use the same way as any other companion — attach it to an agent, deploy to any channel.

For fictional or generated personas, use a companion instead.

Grant consent first. An admin must enable digital twins in the dashboard, or the API fails with DigitalTwinConsentRequired.

Creating a digital twin

Call POST /public/digital-twins with the person's identity, a voice recording, and a reference image or video for the avatar.

curl -X POST https://companion-api.napster.com/public/digital-twins \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Sarah",
    "lastName": "Johnson",
    "description": "VP of Customer Success at Acme Corp. Confident, warm, and knowledgeable. Speaks clearly and directly, with a focus on helping customers get the most out of the product.",
    "gender": "female",
    "ethnicity": "Caucasian",
    "voiceUrl": "https://example.com/recordings/sarah-voice-sample.wav",
    "videoUrl": "https://example.com/videos/sarah-speaking.mp4",
    "externalClientId": "sarah-johnson-001",
    "version": "v2"
  }'

Parameter reference

Parameter	Type	Required	Description
`firstName`	string	Yes	The person's first name.
`lastName`	string	Yes	The person's last name.
`description`	string	Yes	Role, personality, and communication style. Becomes the foundation of the agent's system prompt.
`gender`	string	Yes	One of `male`, `female`, or `nonBinary`.
`ethnicity`	string	Yes	Use the ethnicities endpoint to get supported values.
`voiceUrl`	string	Yes	URL of a voice recording of the person. Used to clone their voice. Must be publicly reachable over HTTPS.
`externalClientId`	string	Yes	A unique identifier for the person. See External client ID below.
`pictureUrl`	string	No	URL of a reference image for avatar generation (v1).
`videoUrl`	string	No	URL of a reference video of the person speaking (v2).
`version`	string	No	Avatar model. `"v1"` (default) or `"v2"`. See Avatar Models.
`tags`	object	No	Key-value string pairs for labeling.

All identity fields (firstName, lastName, gender, ethnicity) are required for digital twins, unlike custom companions where they are optional.

Voice recording requirements

The voiceUrl is what makes the digital twin sound like the real person. Provide a clear recording of the person speaking naturally — the longer and more natural the sample, the better the voice clone.

Requirement	Value
Supported formats	mp3, wav, m4a, flac, ogg, webm, mp4
Max file size	10 MB
Minimum duration	60 seconds
Maximum duration	300 seconds (5 minutes)

The URL must be publicly reachable over HTTPS.

External client ID

The externalClientId is your own unique identifier for the person this digital twin represents — an employee ID, CRM contact ID, or any stable ID from your system. It links the digital twin back to the real individual so you can correlate sessions, analytics, and updates across your platform. For example, if Sarah leaves the company and is replaced, you can create a new digital twin with a different externalClientId while keeping the old one for historical records.

Avatar models

Two avatar models are available — v1 (image input, fast) and v2 (video input, highest quality). Set the version field to "v1" or "v2". If omitted, it defaults to "v1". See Avatar Models for the full comparison.

Response

The response returns a companion object with an id:

{
  "id": "comp_abc123",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "description": "VP of Customer Success at Acme Corp...",
  "gender": "female",
  "ethnicity": "Caucasian"
}

Listing your digital twins

Digital twins are listed through the same companions endpoint. Use the personaType query parameter to filter:

curl https://companion-api.napster.com/public/companions?personaType=digitalTwin \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Using a digital twin in an agent

Use the returned id as the companionId when creating an agent — same as any other companion:

curl -X POST https://companion-api.napster.com/public/agents \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companionId": "comp_abc123",
    "name": "Sarah - Customer Success",
    "providerSettings": {
      "temperature": 0.7
    }
  }'

From here, follow the standard flow: configure the agent, add tools and knowledge, and deploy to a channel.

Digital Twins

On this page