Starferry is a FastAPI-based API service that generates custom bingo game items using multiple AI providers. The service accepts prompts from users and returns 25 bingo items generated by the selected AI model (OpenAI, Google's Gemini, or Grok).

Starferry Documentation

Overview

Starferry is a FastAPI-based API service that generates custom bingo game items using multiple AI providers. The service accepts prompts from users and returns 25 bingo items generated by the selected AI model (OpenAI, Google's Gemini, or Gemini).

Pypi Project

https://pypi.org/project/starferry/

Features

• Multi-Provider AI Integration: Generate content using OpenAI (GPT-4o-mini), Google's Gemini (gemini-2.0-flash), or Gemini (gemini-2-latest)
• Standardized Output Format: Consistently delivers 25 bingo items separated by the '|' character
• Rate Limiting: Built-in IP-based rate limiting (10 requests per 30 minutes)
• API-First Design: Clean REST API with FastAPI
• Cross-Origin Resource Sharing: Configured with CORS support for frontend integration

Setup

Prerequisites

• Python 3.10+
• API keys for the AI providers you plan to use:
  • OpenAI API key
  • Google Claude API key
  • Gemini (XAI) API key

Installation

1. Clone the repository:

   git clone https://github.com/JerrySu5379/Starferry.git
   cd Starferry
   

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure environment variables:

   • Copy the env.example file to .env
   • Fill in your API keys and other required configuration

   cp env.example .env
   

5. Start the server:

   python -m src.main
   

Alternative way to install and run the server

pip install starferry

starferry

The API will be available at http://localhost:8008.

API Documentation

Generate Bingo Items

Generates 25 bingo items based on the provided prompt using the specified AI service.

Endpoint: POST /api/bingo

Form Parameters:

• prompt (required): The prompt describing what