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.

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

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.

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 (fast) and v2 (highest quality). Set the version field to "v1" or "v2"; if omitted, it defaults to "v1". v1 takes a still image (pictureUrl). v2 takes a reference video (videoUrl) for the best results, or a still image (pictureUrl) when you don't have video. 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.