Create Twin Embed SDK

Embed the hosted Create AI Twin iframe so your users can build a private twin, face, voice, and optional brain, inside your product.

Video walkthrough

Watch how to embed the Create AI Twin iframe, generate auth tokens, and handle the save response in your app.

Generate an auth token

Your backend calls getAiTwinAuthToken with your Client-Id and Client-Secret. Return the authToken to your app and pass it as the token query param on the embed URL. Never expose your Client Secret in the browser in production.

Create credentials on the API Keys page, then generate a token below to try the live preview.

bash

curl -X POST "https://us-central1-streamoji-265f4.cloudfunctions.net/getAiTwinAuthToken" \
  -H "Content-Type: application/json" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_64_CHAR_API_KEY" \
  -d '{"userId":"end-user-123","userName":"Jane Doe"}'

For testing only. In production, call getAiTwinAuthToken from your backend and pass the token to your iframe URL.

Client-IdClient-SecretuserIduserName

Embed the iframe

Host the Create AI Twin UI at /createAiTwin. End users pick a face, choose a voice, optionally add a hosted brain or their own SSE brain URL, and save a private twin, no Firebase sign-in required. See Using your own brain for the SSE format.

Optional query params:

themeColor , hex accent color for buttons and highlights (without #).
hideBrains=true , hides the Brains tab and knowledge-base UI entirely.

Theme color#EB7A1A

html

<iframe
  src="https://aitwin.me/createAiTwin?token=YOUR_TOKEN&themeColor=EB7A1A"
  width="100%"
  height="640"
  style="border:0;"
  allow="microphone; camera"
></iframe>

Live preview

Generate a token in Step 1 to load the embed preview.

Add https://aitwin.me to your CSP frame-src when embedding on your own domain.

Handle the save response

When the user saves a twin, the iframe posts a message to your window. Listen for aitwin:create-twin:success and read the payload fields below. Validate event.origin matches https://aitwin.me before trusting the message.

Field	Description
twinId	Internal twin identifier.
aiTwinUrlId	URL slug for the twin (use with <AiTwin id=… />).
faceId	Selected or uploaded face ID.
voiceId	Stored as ttsEngineId:voiceId (for example visemetts:atlas or eng_c9b1e6d4:<uuid>).
ttsEngineId	TTS engine for that voice: visemetts (standard xAI) or eng_c9b1e6d4 (premium Cartesia / custom). Also encoded in voiceId before the colon.
language	TTS language code selected in Create Twin (for example en, es-MX, auto). visemetts (Standard) and eng_c9b1e6d4 (Premium) support different codes.
name	Display name entered by the user (optional).
isPrivate	Always true for embed-created twins.
brainId	Hosted Ai Twin brain / knowledge base ID when configured (optional). Older payloads may still include knowledgeContextId as an alias.
brainUrl	Own SSE brain URL when the twin uses a client brain instead of a hosted Ai Twin brain. See Using your own brain.

javascript

window.addEventListener("message", (event) => {
  if (event.origin !== "https://aitwin.me") return;

  if (event.data?.type === "aitwin:create-twin:success") {
    const payload = event.data.payload;
    // { twinId, aiTwinUrlId, faceId, voiceId, ttsEngineId?, language?, name?, isPrivate, brainId?, brainUrl? }
  }

  if (event.data?.type === "aitwin:create-twin:error") {
    console.error(event.data.payload.message);
  }
});

Live result from preview above

Create a twin in the preview iframe to see the success payload here.

Generate production tokens on your backend via getAiTwinAuthToken. Manage credentials on the API Keys page.