Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Python 3.10+ — python3 --version
  • ffmpeg — ffmpeg -version (used for video assembly)
  • pip — pip --version
You will also need a Google AI API key with access to Gemini models. Get one at aistudio.google.com.
1

Clone the repository

git clone https://github.com/rushilkukreja/hoohacks.git
cd hoohacks
2

Install dependencies

pip install -r requirements.txt
Use a virtual environment to keep dependencies isolated: python3 -m venv .venv && source .venv/bin/activate
3

Create your .env file

Copy the example file and add your API key:
cp .env.example .env
Then open .env and set your key:
.env
GEMINI_API_KEY=your_google_ai_api_key_here
GEMINI_API_KEY is the only required variable to get started. ElevenLabs keys and other overrides are optional — see Configuration for the full list.
If you don’t have an ElevenLabs API key yet, set ALLOW_SILENT_VOICEOVER=1 in your .env to skip voiceover generation:
.env
GEMINI_API_KEY=your_google_ai_api_key_here
ALLOW_SILENT_VOICEOVER=1
4

Start the server

python run.py
You should see output like:
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
The server runs with --reload enabled by default, so it restarts automatically when you edit source files.
5

Verify the server is healthy

curl http://127.0.0.1:8000/api/health
Expected response:
{
  "status": "ok",
  "service": "splyce-ad-personalization",
  "prompt_api": "product-prompt-v2-no-standard-ad",
  "gemini_configured": true,
  "elevenlabs_configured": false
}
6

Make your first API call

Call /api/identify-product with a brand name and viewer profile. Gemini returns the best-matching specific product SKU for that viewer.
curl -X POST http://127.0.0.1:8000/api/identify-product \
  -H "Content-Type: application/json" \
  -d '{
    "brand_name": "Toyota",
    "user_data": {
      "household_income": "$75k-$100k",
      "interests": ["road trips", "outdoors"],
      "region": "US-West",
      "family_size": 2
    }
  }'
Expected response:
{
  "product_name": "2025 Toyota RAV4 XLE Hybrid AWD",
  "prompt": "..."
}
The product_name field contains the specific retail SKU that Gemini selected based on the viewer profile. Use this value in subsequent calls to /api/analyze-video and /api/generate-ad-video.
The exact product returned will vary — Gemini reasons about the viewer data and picks the most relevant SKU at the time of the call.

​
Next steps

Configuration

Set up ElevenLabs voiceover, tune model selection, and adjust video processing defaults

API reference

Full endpoint documentation with request and response schemas

Build docs developers (and LLMs) love

Get started for freeTalk to us