> ## Documentation Index
> Fetch the complete documentation index at: https://platform.perso.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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

<Card title="Get your API Key" icon="key" horizontal href="https://platform.perso.ai/settings/apikey/">
  Login to your Perso Platform account and create an API Key.
</Card>

<Steps>
  <Step title="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:

    ```shellscript theme={null}
    curl 'https://platform.perso.ai/api/console/b2c/form-resources/' \
      -H 'PersoPlatform-APIKey: <YOUR-KEY>'
    ```

    Example response:

    ```json theme={null}
      "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`.
  </Step>

  <Step title="Create a Context">
    A `context` is the session template for your avatar agent. Replace `PersoPlatform-APIKey` with your own API Key.

    ```text theme={null}
    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.

    ```text theme={null}
    {
      "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.
  </Step>

  <Step title="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`.

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

    Example response:

    ```json theme={null}
    {
      "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.
  </Step>
</Steps>