Build an AI Study Buddy Avatar

Connect Google Gemini to a real-time talking avatar you can chat with.

Introduction

30 Second Summary

Studying alone can feel isolating. Imagine having a supportive friend available anytime you need to talk through a tough concept or quiz yourself before an exam.

In this project, you will build an AI study buddy with a real-time talking avatar that listens to you speak and responds with synchronized voice and facial expressions, all running from a Python script on your computer.

What You'll Build

A Python application that connects Google Gemini (a free large language model) to Simli (a free avatar API) to create a lifelike video conversation you can interact with through your browser.

By the end of this project, you'll have:

  • A Python test script that verifies your Gemini API connection works.
  • A main Python script that launches a live avatar study session in your browser.
  • A customized study buddy persona with a tailored system prompt and greeting that makes the avatar feel like a supportive friend.
  • Secret Mission: Build a multi-mode study companion with selectable modes like Quiz, Explain, and Debate.

Are there any prerequisites?

You need Python installed on your computer and a Google account. No credit card is required for any service used in this project.

Set Up Your Accounts and Environment

Before you can build your AI study buddy, you need accounts on two free services and a project folder ready to go.

In this step, you will create a Simli account (for the talking avatar), grab a Gemini API key (for the AI brain), and set up your Python project folder with the right packages installed.

In this step, get ready to:
  • Create a Simli account and get your API key and Face ID.
  • Create a Gemini API key from Google AI Studio.
  • Install Python packages and create your project folder with a .env file.
Create your Simli account and get your API key

Simli is the service that turns text-to-speech audio into a lifelike talking avatar in real time. You need an account to get an API key and choose which avatar face your study buddy will use.

  • Open your browser and go to app.simli.com.
  • Click Sign Up and create a free account (no credit card required).
  • Once signed in, navigate to app.simli.com/apiKey to view your API key.
  • Copy your API key and save it somewhere temporarily (a notepad or sticky note on your screen).

What is a Face ID?

A Face ID is a unique string that tells Simli which avatar face to render during your session. Simli provides pre-made default faces you can use, or you can create your own by uploading a photo.

  • Browse the available avatars in your Simli dashboard after signing in. Look for the Face ID associated with the avatar you like.
  • Copy the Face ID and save it alongside your API key.

Use the default Face ID

If you cannot find a Face ID in the dashboard, use Simli's default: tmp9i8bbq7c. This works for any account and gives you a ready-made avatar to start with.

Get your Gemini API key

Google Gemini is the free large language model that will power your study buddy's responses. It offers an OpenAI-compatible endpoint, which means it plugs directly into Simli's custom LLM feature.

  • Open aistudio.google.com/apikey in your browser.
  • Sign in with your Google account if prompted.
  • Click Create API Key.
  • Select or create a Google Cloud project when prompted.
  • Copy the generated API key and save it alongside your Simli credentials.

Is Gemini really free?

Yes. The gemini-2.5-flash model on the Standard tier has free input and output pricing. No credit card is required to use it through Google AI Studio.

Having trouble creating a key?

Make sure you are signed in with a personal Google account. Workspace accounts managed by an organization may have API creation disabled by an admin.

help me troubleshoot my Google AI Studio API key creation

Install Python dependencies and create your project

Your project needs two Python packages: requests for making HTTP calls to the APIs, and python-dotenv for loading your secret keys from a file.

  • Press the Windows key to open your search bar.
  • Type PowerShell and press Enter to open it.
  • Install the two packages by running this command:
pip install requests python-dotenv

Seeing 'pip is not recognized'?

This means Python is not in your system PATH. Try running python -m pip install requests python-dotenv instead.

help me fix pip not being recognized in my terminal

  • Move to your Desktop by running this command:
cd ~/Desktop
  • Create your project folder and move into it by running these commands:
mkdir ai-study-buddy
cd ai-study-buddy
  • Confirm the folder exists by running:
ls

You should see an empty folder (no output yet, since we have not created any files inside it).

Now you need to create a .env file that stores your API keys and Face ID. This keeps your secrets out of your code files.

  • Open your preferred text editor (Notepad, VS Code, or any editor you have).
  • Create a new file and save it as .env inside your ai-study-buddy folder on your Desktop.
  • Paste the following template into the file, replacing each placeholder with the real values you copied earlier:
SIMLI_API_KEY=your-simli-api-key-here
GEMINI_API_KEY=your-gemini-api-key-here
SIMLI_FACE_ID=your-chosen-face-id-here

What does this file do?

The .env file is a standard way to store environment variables. The python-dotenv package reads this file and loads the values into your Python script at runtime.

This pattern keeps your secrets separate from your code so you never accidentally share them.

  • Replace your-simli-api-key-here with the Simli API key you copied.
  • Replace your-gemini-api-key-here with the Gemini API key you copied.
  • Replace your-chosen-face-id-here with the Face ID you noted (or use tmp9i8bbq7c as the default).
  • Save the file.

✔️ Awesome, I've got everything!

Great. Double check you have saved your .env file inside the ai-study-buddy folder on your Desktop.

ⓧ I'd like to double check the full code

Your .env file should look exactly like this (with your real keys substituted in):

SIMLI_API_KEY=your-simli-api-key-here
GEMINI_API_KEY=your-gemini-api-key-here
SIMLI_FACE_ID=your-chosen-face-id-here

File saved as .env.txt instead of .env?

Windows Notepad sometimes adds a .txt extension automatically. When saving, change the Save as type dropdown to All Files (*.*) and type the filename as .env (with the leading dot).

help me create a .env file on Windows without a .txt extension

Your environment is ready to go. Next up, you will write a quick test script to make sure your Gemini API key actually works before connecting it to the avatar.

Test Your AI Brain

Your environment is set up with all the keys and packages you need. Now it's time to make sure your AI brain actually works before wiring it into the avatar.

Google Gemini offers an OpenAI-compatible endpoint, which means any tool expecting OpenAI's API format can talk to Gemini without any changes. You'll write a quick test script to confirm your API key works and Gemini responds in the right tone.

In this step, get ready to:
  • Write a Python test script that sends a chat request to Gemini's OpenAI-compatible endpoint.
  • Run the script and verify Gemini responds as a friendly study buddy.
Write a Gemini test script

Before connecting Gemini to your avatar, you need to confirm the API key and endpoint actually work. You'll create a short script that sends a message to Gemini and prints the response.

  • Create a new file called test_gemini.py in your project folder (the one containing your .env file).
  • Add the following code to set up the connection to Gemini's endpoint:
import os
import requests
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Get your Gemini API key
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

# Gemini's OpenAI-compatible chat completions endpoint
url = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions"

# Set up request headers with your API key
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {GEMINI_API_KEY}",
}

What does this code do?

  • load_dotenv() reads your .env file and loads the keys as environment variables so they stay out of your code.
  • The url points to Gemini's chat completions endpoint, which mimics OpenAI's format.
  • The Authorization header sends your Gemini API key as a Bearer token, just like you would with OpenAI.
  • Next, add the message payload and response handling below your existing code in test_gemini.py:
# Define the conversation with a system prompt and a test question
data = {
    "model": "gemini-2.5-flash",
    "messages": [
        {
            "role": "system",
            "content": "You are a friendly study buddy. You talk like a supportive friend, not a formal tutor. Keep responses brief and conversational.",
        },
        {
            "role": "user",
            "content": "Hey! Can you help me understand what an API is?",
        },
    ],
}

# Send the request to Gemini and print the response
response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    message = result["choices"][0]["message"]["content"]
    print("Study Buddy says:")
    print(message)
else:
    print(f"Error {response.status_code}: {response.text}")

What does this code do?

The data dictionary defines your conversation in OpenAI's chat format. The system message sets the personality, and the user message is what you're asking.

The model field uses gemini-2.5-flash, which is free to use on Google's API. The response comes back in the same format as OpenAI, so you access the reply at result["choices"][0]["message"]["content"].

  • Save test_gemini.py.

Why the OpenAI-compatible format?

Simli's avatar API expects an LLM that speaks the OpenAI chat format. By using Gemini's OpenAI-compatible endpoint, you get a free LLM that plugs directly into Simli without any translation layer.

✔️ Awesome, I've got everything!

Great. Double check you've saved your file, then move on to running it.

ⓧ I'd like to double check the full code

import os
import requests
from dotenv import load_dotenv

load_dotenv()

GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

url = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {GEMINI_API_KEY}",
}

data = {
    "model": "gemini-2.5-flash",
    "messages": [
        {
            "role": "system",
            "content": "You are a friendly study buddy. You talk like a supportive friend, not a formal tutor. Keep responses brief and conversational.",
        },
        {
            "role": "user",
            "content": "Hey! Can you help me understand what an API is?",
        },
    ],
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    message = result["choices"][0]["message"]["content"]
    print("Study Buddy says:")
    print(message)
else:
    print(f"Error {response.status_code}: {response.text}")
Run and verify your test script
  • Run your test script by entering this command in your terminal:
python test_gemini.py

You should see a friendly, conversational response printed under "Study Buddy says:" in your terminal. The exact wording changes each time, but it should sound like a supportive friend explaining what an API is.

Seeing an error instead of a response?

  • If you see Error 400, double check that your GEMINI_API_KEY in the .env file is correct and has no extra spaces or quotes around it.
  • If you see Error 429, you've hit a rate limit. Wait one minute and try again, or change the model in your script from gemini-2.5-flash to gemini-2.5-flash-lite.
  • If you see ModuleNotFoundError, make sure you installed both packages by running pip install requests python-dotenv again.
  • Make sure your terminal is in the same folder as your .env and test_gemini.py files.

Still stuck? Help me debug my test_gemini.py script. I'm getting an error when trying to call the Gemini API.

Your AI brain is confirmed working. Next up, you'll connect Gemini to a real-time talking avatar so you can have a face-to-face conversation with your study buddy.

Build and Launch Your Study Buddy

In the previous step, you confirmed that Gemini can respond through the OpenAI-compatible endpoint. Now you will connect Gemini to a real-time avatar so you can talk to your study buddy face-to-face.

Simli handles the heavy lifting of turning text responses into synchronized speech and facial expressions. Your job is to write a Python script that sends your configuration to Simli's API, then opens the resulting video room in your browser.

In this step, get ready to:
  • Write a script that connects Gemini to Simli's real-time avatar API.
  • Launch an interactive avatar session and have a voice conversation.
  • Customize your study buddy's personality through system prompt engineering.
Write the study buddy script

This script will load your API keys, send a session configuration to Simli, and open the avatar room in your browser automatically.

  • Create a new file called study_buddy.py in your project folder (the same folder where test_gemini.py lives).

You will build this file in four chunks. Start with the imports and environment variable loading.

  • Add the following imports and environment setup to study_buddy.py:
import os
import webbrowser
import requests
from dotenv import load_dotenv

load_dotenv()

SIMLI_API_KEY = os.getenv("SIMLI_API_KEY")
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
SIMLI_FACE_ID = os.getenv("SIMLI_FACE_ID")

What does this code do?

  • webbrowser is a built-in Python module that opens URLs in your default browser.
  • load_dotenv() reads the .env file and loads your three keys into environment variables.
  • os.getenv() pulls each key into a Python variable so the rest of the script can use them.

Next, define the personality of your study buddy. The system prompt tells the AI how to behave, and the first message is what the avatar says when the session begins.

  • Add the persona definitions below the environment variables in study_buddy.py:
SYSTEM_PROMPT = """You are a friendly, encouraging study buddy. You talk like a 
supportive classmate who genuinely wants to help. You use casual language, 
celebrate small wins, and make studying feel less lonely. You ask follow-up 
questions to check understanding. You never lecture or talk down to the user. 
Keep your responses brief and conversational since they will be spoken aloud. 
Do not use special characters, markdown, or formatting in your responses."""

FIRST_MESSAGE = "Hey! Good to see you. What are we studying today? I'm ready to help however you need."

Why keep responses brief and avoid special characters?

The avatar speaks your AI's responses aloud using text-to-speech. Long paragraphs sound unnatural in conversation. Special characters like asterisks or bullet points would be read as literal text by the TTS engine.

Now build the session configuration dictionary. This tells Simli which avatar face to use, what LLM to connect to, and how the session should behave.

  • Add the session configuration below your persona definitions in study_buddy.py:
session_config = {
    "apiKey": SIMLI_API_KEY,
    "faceId": SIMLI_FACE_ID,
    "systemPrompt": SYSTEM_PROMPT,
    "firstMessage": FIRST_MESSAGE,
    "language": "en",
    "maxSessionLength": 600,
    "maxIdleTime": 120,
    "customLLMConfig": {
        "model": "gemini-2.5-flash",
        "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
        "llmAPIKey": GEMINI_API_KEY,
    },
}

What does this configuration do?

  • customLLMConfig tells Simli to route all AI responses through Gemini's OpenAI-compatible endpoint instead of the default model.
  • maxSessionLength caps the session at 600 seconds (10 minutes) to stay within free-tier minutes.
  • maxIdleTime ends the session after 120 seconds of silence, so unused sessions don't burn through your free minutes.
  • faceId selects which avatar face appears in the video room.

Finally, add the code that sends your configuration to Simli's API and opens the resulting room URL in your browser.

  • Add the API call and response handling at the bottom of study_buddy.py:
print("Starting your AI Study Buddy session...")

response = requests.post(
    "https://api.simli.ai/auto/start/configurable",
    json=session_config,
)

if response.status_code == 200:
    result = response.json()
    room_url = result["roomUrl"]
    session_id = result["sessionId"]
    print(f"\nSession started! ID: {session_id}")
    print(f"Opening your study buddy in the browser...")
    webbrowser.open(room_url)
    print(f"\nRoom URL: {room_url}")
    print("Talk to your study buddy! Close the browser tab when you're done.")
else:
    print(f"Error starting session: {response.status_code}")
    print(response.text)

What does this code do?

  • requests.post() sends your session configuration to Simli's POST /auto/start/configurable endpoint.
  • On success, the API returns a roomUrl (the browser page where your avatar lives) and a sessionId (for tracking the session).
  • webbrowser.open(room_url) launches that page automatically so you do not have to copy and paste.
  • Save study_buddy.py.

Seeing a syntax error when you save?

  • Make sure the triple-quoted string for SYSTEM_PROMPT opens and closes with exactly three double quotes (""").
  • Check that every opening brace { in session_config has a matching closing brace }.

Help me fix a syntax error in my study_buddy.py file

✔️ Awesome, I've got everything!

Great. Double check you have saved study_buddy.py and move on to launch it.

ⓧ I'd like to double check the full code

Here is the complete study_buddy.py file. Compare yours against it:

import os
import webbrowser
import requests
from dotenv import load_dotenv

load_dotenv()

SIMLI_API_KEY = os.getenv("SIMLI_API_KEY")
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
SIMLI_FACE_ID = os.getenv("SIMLI_FACE_ID")

SYSTEM_PROMPT = """You are a friendly, encouraging study buddy. You talk like a 
supportive classmate who genuinely wants to help. You use casual language, 
celebrate small wins, and make studying feel less lonely. You ask follow-up 
questions to check understanding. You never lecture or talk down to the user. 
Keep your responses brief and conversational since they will be spoken aloud. 
Do not use special characters, markdown, or formatting in your responses."""

FIRST_MESSAGE = "Hey! Good to see you. What are we studying today? I'm ready to help however you need."

session_config = {
    "apiKey": SIMLI_API_KEY,
    "faceId": SIMLI_FACE_ID,
    "systemPrompt": SYSTEM_PROMPT,
    "firstMessage": FIRST_MESSAGE,
    "language": "en",
    "maxSessionLength": 600,
    "maxIdleTime": 120,
    "customLLMConfig": {
        "model": "gemini-2.5-flash",
        "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
        "llmAPIKey": GEMINI_API_KEY,
    },
}

print("Starting your AI Study Buddy session...")

response = requests.post(
    "https://api.simli.ai/auto/start/configurable",
    json=session_config,
)

if response.status_code == 200:
    result = response.json()
    room_url = result["roomUrl"]
    session_id = result["sessionId"]
    print(f"\nSession started! ID: {session_id}")
    print(f"Opening your study buddy in the browser...")
    webbrowser.open(room_url)
    print(f"\nRoom URL: {room_url}")
    print("Talk to your study buddy! Close the browser tab when you're done.")
else:
    print(f"Error starting session: {response.status_code}")
    print(response.text)
Launch your study buddy

Your script is ready. Time to start a live session and talk to your avatar.

  • Run your study buddy script from the terminal by running this command:
python study_buddy.py

What should I see?

Your terminal prints a session ID and a room URL, then your default browser opens automatically. In the browser, you will see an avatar face. Your browser will ask for microphone permission.

  • Click Allow when your browser asks for microphone access.
  • Wait a moment for the avatar to load and speak its first message.
  • Talk to your study buddy. Try asking it to help you study something, like "Can you quiz me on Python data types?"

The avatar responds with lip-synced speech and facial expressions in real time.

Session fails or browser does not open?

  • Check that your .env file has all three keys filled in with real values (not the placeholder text).
  • If you see a 429 error, you have hit a rate limit. Wait one minute and try again, or change the model in session_config to gemini-2.5-flash-lite.
  • If the browser does not open, copy the Room URL printed in the terminal and paste it into your browser manually.

Help me troubleshoot my Simli avatar session not starting

Iterate on the persona

The system prompt is the main lever for changing how your study buddy behaves. Small changes to the wording produce noticeably different conversation styles.

  • Open study_buddy.py and find the SYSTEM_PROMPT variable.
  • Try replacing the personality description with a different tone. For example: an encouraging senior student, a playful classmate, or a calm late-night study partner.
  • Update the FIRST_MESSAGE to match your new tone. This sets the mood for the entire conversation.
  • Save study_buddy.py and run python study_buddy.py again to start a fresh session with your new persona.

Each run starts a new session

Every time you run the script, Simli creates a brand new room. Close the old browser tab before launching a new session so you do not accidentally use up free minutes on two sessions at once.

What is system prompt engineering?

System prompt engineering is the practice of writing instructions that shape an AI's personality and behavior. The more specific you are about tone, response length, and conversational habits, the more consistent the experience will be.

You now have a fully working AI study buddy with a real-time talking avatar. You have seen how system prompt changes affect the conversation style. In the Secret Mission, you will take this further by adding selectable study modes.

Secret mission

Multi-Mode Study Companion

Your study buddy is great, but what if it could adapt to different study situations? Build an enhanced version that lets you choose between Quiz Me, Explain Like a Friend, and Debate Partner modes before each session starts.

Clean Up Your Resources

Clean Up Your Resources

This project runs entirely on your local machine using free API tiers. There are no ongoing costs from leaving your files in place or keeping your API keys active.

Decide whether to keep your resources for future study sessions, pause them, or delete them entirely.

Resources you used:

  • Project folder on your Desktop containing .env, test_gemini.py, study_buddy.py, and study_buddy_modes.py.
  • Python packages: requests and python-dotenv.
  • Gemini API key (created in Google AI Studio).

Keep everything running

No action needed. Choose this if you plan to keep using your study buddy or want to experiment with new system prompts later.

  • Your project files stay on your Desktop ready to run anytime.
  • Your Gemini API key remains active on the free tier with no charges.
  • Your Simli account keeps its free 50 minutes per month.
  • The requests and python-dotenv packages remain installed in your Python environment.

Pause - I'll come back to this later

This project has no running processes to stop. Sessions end automatically when you close the browser tab. Your setup is identical to the Keep option.

  • Close any browser tabs with active Simli sessions.
  • Your files, API keys, and packages all remain in place for when you return.

Delete - I don't want to use this again

Remove all project files, uninstall packages, and delete your API key to start fresh.

  • Delete your project folder from the Desktop. Open File Explorer, navigate to your Desktop, right-click your study buddy project folder, and select Delete.
  • Uninstall the Python packages by running this command in your terminal:
pip uninstall -y requests python-dotenv
  • Delete your Gemini API key. Open the Google Cloud API Credentials page, find the API key you created for this project, click the Actions icon, and select Delete API key. Confirm in the modal that appears.
  • Your Simli account can remain. It uses free credits and does not store any persistent data from your sessions.

That's a Wrap!

That's a Wrap!

Nice work! You just built a real-time AI study companion that talks to you through a lifelike avatar in your browser.

You've learned how to:

  • Connect two free APIs (Simli + Gemini) using Python to create a voice-interactive AI experience with synchronized facial expressions.
  • Build a real-time avatar pipeline that orchestrates speech recognition, LLM processing, text-to-speech, and avatar rendering together.
  • Design a study buddy persona through system prompt engineering, shaping how the avatar speaks and behaves in conversation.
  • Secret Mission: You built a multi-mode study companion that adapts its behavior to different study needs, with selectable Quiz, Explain, and Debate modes.

Ready to quiz yourself?