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.

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 a connection.

To browse the public catalog, call GET /public/napster-companions. 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/napster-companions?pageSize=10 \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Creating a custom companion

If you need full control, you can create your own companion by defining:

• 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.
• Visual appearance — provide an image URL to generate a custom avatar for your agent.
• Gender and ethnicity — optionally specify the companion's gender and ethnicity to influence the generated avatar's appearance.

To create a custom companion, call POST /public/companions:

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. Keeps a professional but approachable tone, occasionally uses light humor to put frustrated users at ease.",
    "pictureUrl": "https://example.com/images/alex-avatar.png",
    "gender": "male",
    "ethnicity": "Asian"
  }'

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"

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"