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.

A companion is a separate, reusable resource: the same companion can front multiple agents with different tools and knowledge, and because the generated avatar lives here, you can reconfigure those agents freely without ever regenerating it.

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

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"