Quickstart

Create your own Interactive Avatar Agent using the Perso Platform Context.

Get your API Key

List the Resources

You’ll need a valid tts_type (voice) name and model_style (avatar) name for the next step. Replace PersoPlatform-APIKey with your own API Key.Fetch the list of options your account is allowed to use:

curl 'https://platform.perso.ai/api/console/b2c/form-resources/' \
  -H 'PersoPlatform-APIKey: <YOUR-KEY>'

Example response:

  "tts_types": [
    {
      "id": "61f2d0b0-71fc-4b66-9bbd-caf70fa00d7f",
      "name": "openai-nova"
    },
  ],
  "model_styles": [
    {
      "id": "7a1c5211-ffdd-4c0d-acac-e5903b268e86",
      "name": "chaehee_livechat-front-white_suit-natural_loop"
    },
  ]

Note the name values for the voice and avatar you want — use them when creating a context.

Create a Context

A context is the session template for your avatar agent. Replace PersoPlatform-APIKey with your own API Key.

curl -X POST 'https://platform.perso.ai/api/console/b2c/contexts/' \
  -H 'PersoPlatform-APIKey: <YOUR-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Tour Guide",
    "greeting": "Hi! Want a quick tour of our product?",
    "instructions": "You are a friendly product tour guide.",
    "tts_type": "openai-nova",
    "model_style": "chaehee_livechat-front-white_suit-natural_loop",
    "background_image": "default",
    "max_session_sec": 600
  }'

Example Response:context_id is the public token you put on your website.

{
  "id": "4e6f8c2a-1234-4abc-9def-0123456789ab",
  "context_id": "plctx_8f9a0bdc1e2f3a4b5c6d7e8f",
  "name": "Tour Guide",
  "greeting": "Hi! Want a quick tour of our product?",
  "instructions": "You are a friendly product tour guide...",
  "tts_type": "openai-nova",
  "model_style": "chaehee_livechat-front-white_suit-natural_loop",
  "background_image": "default",
  "max_session_sec": 600,
  "is_active": true,
  "created_at": "2026-05-26T10:15:30Z",
  "updated_at": "2026-05-26T10:15:30Z"
}

Note: context_id is the public token you put on your website.

Get the Embed Snippet

Instead of building the HTML yourself, ask the embed endpoint for ready-to-paste code. Use the context’s id (the UUID from the previous step) in the path — not the context_id.

curl 'https://platform.perso.ai/api/console/b2c/contexts/4e6f8c2a-1234-4abc-9def-0123456789ab/embed/' \
  -H 'PersoPlatform-APIKey: <YOUR-KEY>'

Example response:

{
  "context_id": "plctx_8f9a0bdc1e2f3a4b5c6d7e8f",
  "viewer_url": "https://platform.perso.ai/perso-interactive/embed/?context_id=plctx_8f9a0bdc1e2f3a4b5c6d7e8f",
  "mode": "standard",
  "width": 1920,
  "height": 1080,
  "iframe_snippet": "<iframe src=\"https://platform.perso.ai/perso-interactive/embed/?context_id=plctx_8f9a0bdc1e2f3a4b5c6d7e8f\" width=\"1920\" height=\"1080\" allow=\"autoplay; microphone\" frameborder=\"0\"></iframe>",
  "script_snippet": "<script src=\"https://platform.perso.ai/embed/loader.js\" data-context-id=\"plctx_8f9a0bdc1e2f3a4b5c6d7e8f\"></script>"
}

Copy iframe_snippet or script_snippet straight into your page.

Get Started

Perso Interactive

Perso Speech

Get your API Key