Companion

The companion is the core identity of your agent — how it looks and behaves. You can choose from an existing companion in the catalog, or create a custom one from scratch.

Looking to recreate a real person with their actual appearance and voice? See Digital Twins.

Using an existing companion

Napster provides a catalog of pre-built companions with ready-made avatars, voices, and personalities. Catalog companions can be used immediately when creating an agent.

To browse the public catalog, call GET /public/companions/napster-stock. You can filter results by search, gender, and ethnicity, and paginate with pageIndex and pageSize. See the API reference for the full list of query parameters.

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

Creating a custom companion

To create your own companion, define:

Personality — use the description field to describe the companion's role, personality, tone, and communication style. This shapes how the agent behaves and interacts with users.
Headline — a short tagline or subtitle for the companion (e.g. "Senior Tech Support Specialist"). Set via update after creation.
Visual appearance — provide an image or video as the reference input to generate a custom avatar. See avatar models for the difference between v1 (image) and v2 (video).
Gender and ethnicity — optionally specify the companion's gender and ethnicity to influence the generated avatar's appearance.

Creating with v1 (image input)

Provide a pictureUrl — a publicly reachable HTTPS URL of a reference image.

curl -X POST https://companion-api.napster.com/public/companions \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alex",
    "lastName": "Chen",
    "description": "A senior tech support specialist who has been helping customers for over a decade. Warm, patient, and detail-oriented. Explains technical concepts in plain language and always walks users through solutions step by step.",
    "pictureUrl": "https://example.com/images/alex-avatar.png",
    "gender": "male",
    "ethnicity": "Asian"
  }'

Creating with v2 (video input)

Provide a videoUrl and set version to "v2".

curl -X POST https://companion-api.napster.com/public/companions \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alex",
    "lastName": "Chen",
    "description": "A senior tech support specialist who has been helping customers for over a decade. Warm, patient, and detail-oriented. Explains technical concepts in plain language and always walks users through solutions step by step.",
    "videoUrl": "https://example.com/videos/alex-speaking.mp4",
    "gender": "male",
    "ethnicity": "Asian",
    "version": "v2"
  }'

Parameter reference

Parameter	Type	Required	Description
`description`	string	Yes	The companion's role, personality, and communication style. This becomes the foundation of the agent's system prompt.
`firstName`	string	No	The companion's first name.
`lastName`	string	No	The companion's last name.
`pictureUrl`	string	No	URL of a reference image for avatar generation (v1).
`videoUrl`	string	No	URL of a reference video of the person speaking for avatar generation (v2).
`version`	string	No	Avatar model. `"v1"` (default) or `"v2"`. See Avatar Models.
`gender`	string	No	One of `male`, `female`, or `nonBinary`.
`ethnicity`	string	No	Use the ethnicities endpoint to get supported values.
`tags`	object	No	Key-value string pairs for labeling the companion.

After creating a companion, you can add a headline — a short tagline or subtitle (e.g. "Senior Tech Support Specialist") — by updating it with PATCH /public/companions/{companionId}.

Ethnicity

The ethnicity field accepts a string value from a dynamic list maintained by the API. To retrieve the available ethnicities, call GET /public/companions/ethnicities:

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

Using a companion in an agent

Use the companion's id as the companionId when creating an agent:

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": "Support Agent",
    "voiceId": "alloy",
    "providerSettings": {
      "temperature": 0.7
    }
  }'

From here, configure the agent, add tools and knowledge, and deploy to a channel.

Listing your companions

To list your companions, call GET /public/companions. This returns all companions created under the project your API key is scoped to.

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

To filter by type, use the personaType query parameter. Use companion for custom companions or digitalTwin for digital twins:

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

Companion

On this page