Skip to content
2WAI Avatar Toolkit

LLM prompt — add <twai-avatar> to a page

Use this prompt when you have an existing HTML page (marketing site, static page, any framework) and want to drop a live 2wai avatar onto it with minimum ceremony.

The prompt

Section titled “The prompt”

Copy this entire block, paste into your assistant, replace the {PLACEHOLDERS} with your values:

I'm adding a 2wai live talking-avatar to an existing webpage.


CONTEXT


2wai is a lip-synced talking-avatar platform. The simplest way to embed is their `<twai-avatar>` Web Component — one <script>, one tag, Transport 0 (LiveKit under the hood).


The integration pattern is MINT-PROXY: my server holds a secret key (sk_...) and
exchanges it for a short-lived LiveKit participant token the client uses to join the
avatar's room. The client NEVER sees the sk_.


MY INPUTS


- sk_ key (server-only, do NOT embed in client code): {TWAI_SECRET_KEY}
- avatar_id to embed: {AVATAR_ID}
- optional voice_id: {VOICE_ID}
- my server stack: {NODE / PYTHON / CLOUDFLARE_WORKER / OTHER}
- my frontend: {STATIC_HTML / HUGO / JEKYLL / NEXT_JS / OTHER}


WHAT I NEED YOU TO DO


1. **On my server**, add a `POST /api/mint` route that:
   - Reads `TWAI_SECRET_KEY` from env.
   - Calls `POST https://api.2wai.ai/v1/sessions` with:
     ```
     Authorization: Bearer <sk_>
     Content-Type: application/json
     body: {"avatar_id": "<AVATAR_ID>", "voice_id": "<VOICE_ID>", "mode": "video", "transport": "livekit"}
     ```
   - Returns only `{session_id, livekit_url, participant_token, room_name}` to the browser (strips any other fields).
   - On error, returns the gateway's error body + status code unchanged.


2. **On the page I want the avatar on**, add this before `</body>`:
   ```html
   <twai-avatar
     mint-url="/api/mint"
     avatar-id="<AVATAR_ID>">
   </twai-avatar>
   <script type="module">
     import { defineTwaiAvatar } from 'https://unpkg.com/@twai/web-component';
     defineTwaiAvatar();
   </script>
   ```


3. **Verify** by:
   - Starting my server.
   - Opening the page.
   - Confirming an avatar video appears within ~5 seconds.
   - Opening DevTools Console — no errors.


GOTCHAS TO HONOR


- The sk_ must NEVER appear in client code. If you see yourself about to put it in the HTML or in a frontend .env, STOP and route through the server instead.
- `<twai-avatar>`'s imperative API: `el.send(text)`, `el.interrupt()`, `el.disconnect()`. Events: `ready`, `reply`, `speaking`, `error`.
- Default LiveKit SDK settings `adaptiveStream` + `dynacast` are MANDATORY off — the Web Component handles this internally, but if you ever drop down to `@twai/core` directly you must pass them.
- The gateway's old MSE-over-WebSocket transport is RETIRED. Don't model anything on `mse_url` or `websocket_url` fields from older docs — always use `livekit_url` + `participant_token` + `room_name`.


DELIVERABLE


- My existing server with the new `/api/mint` route added.
- My existing page with the `<twai-avatar>` block before `</body>`.
- A one-line README note telling future me how to run both.


If you need any input I haven't provided (my avatar_id, my mint-proxy base URL, whether I'm in a monorepo), ASK me — don't guess with placeholders.


Reference docs: https://developers.2wai.ai/sdks/web-component/

What the LLM should produce

Section titled “What the LLM should produce”

After pasting + filling placeholders, you should get back:

  • A diff/patch for one new server route.
  • An edit to one HTML page (or template file).
  • A quick README note.

Review the diff; the only secret in it should be read from env, never literal.