🖼️ GitHub Avatar Frame API

Officially accepted for GSSoC!

Explore the Live Demo »

Report Bug • Request Feature

🖼️ GitHub Avatar Frame API

🌟 Stars	🍴 Forks	🐛 Issues	🔔 Open PRs	🔕 Closed PRs	🛠️ Languages	👥 Contributors

---

📚 Table of Contents

• ✨ Vision
• 🎯 Mission
• ⚙️ Setup & Local Development
• 📂 Project Structure
• 📌 API Usage
• 🧮 Query Parameters
• � CLI Usage
• �💡 Why GitHub Avatar Frame API?
• 🤝 Contributing
• 🛠️ Troubleshooting
• 📜 License

---

✨ Vision

Democratize creative avatar customization by providing a free, open-source API that transforms GitHub profiles into engaging visual experiences for developers worldwide.

🎯 Mission

• 🏗️ Build the most comprehensive and user-friendly avatar framing API
• 💪 Empower developers to personalize their GitHub presence with minimal effort
• 🎨 Foster creative expression through customizable themes, text, and emoji overlays
• 🆓 Maintain a free, accessible service that supports the open-source community

🎨 About GitHub Avatar Frame API

A free and open-source API to frame your GitHub avatar using creative themes. Perfect for README files, portfolios, or social media.

🌐 Live API: https://github-avatar-frame-api.onrender.com

⚙️ Setup & Local Development

Follow these steps to run the GitHub Avatar Frame API locally for development or testing:

🧩 Prerequisites

• 🟢 Node.js 16+ and npm installed
• 🐙 Git for version control
• 🖥️ Code editor (VS Code recommended)
• 📦 Optional: TypeScript knowledge for contributing

💻 Steps

1. Clone the Repository

git clone https://github.com/TechQuanta/github-avatar-frame-api.git
cd github-avatar-frame-api

2. Install Backend Dependencies

npm install

3. Setup Frontend

cd client
npm install
cd ..

Running the Application

Start Backend (Terminal 1)

npm run dev

The backend will start on http://localhost:3000

Start Frontend (Terminal 2)

cd client
npm run dev

The frontend will start on http://localhost:5173 (or another port if 5173 is in use)

Verify Everything Works

1. Open your browser and go to http://localhost:5173
2. You should see the GitHub Avatar Frames interface
3. Enter a GitHub username (e.g., "torvalds")
4. Select a theme and click "Generate"
5. If successful, your framed avatar will appear

---

📂 Project Structure

📦 github-avatar-frame-api
├── 🖥️ api
│   ├── 📄 FRAMETHEMES.md
│   ├── 🖼️ collage.js
│   ├── 🖼️ frames.js
│   ├── 🚀 server.ts
│   └── 🎨 themes.js
├── 🌐 client
│   ├── src
│   │   ├── components
│   │   │   └── 🧩 ThemeSlider.jsx
│   │   ├── pages
│   │   │   └── 📄 NotFound.jsx
│   │   ├── 🎨 App.css
│   │   ├── 📄 App.jsx
│   │   ├── 🎨 index.css
│   │   └── 🚀 main.jsx
│   ├── 📄 index.html
│   ├── ⚡ vite.config.js
│   └── 🌍 vercel.json
├── 🖼️ public
│   └── assets
│       └── 🖼️ gssoc.png
├── � cli
│   ├── 📄 package.json
│   ├── ⚙️ tsconfig.json
│   └── 🚀 src/index.ts
├── �📄 README.md
├── 📄 LICENSE
├── 📄 CODE_OF_CONDUCT.md
├── 📄 CONTRIBUTING.md
├── 📄 CUSTOMIZATION_FEATURE.md
├── 📝 TODO.md
├── 📦 package.json
├── ⚙️ render.yml
└── 📄 tsconfig.server.json

💻 CLI Usage

The GitHub Avatar Frame API comes with a command-line interface (CLI) for easy avatar generation directly from your terminal. Perfect for developers who prefer working in code editors and terminals.

🚀 Installation

Option 1: Install globally from npm

```bash npm install -g github-avatar-frame-cli ```

Option 2: Use locally (from project root)

```bash # Build the CLI npm run build:cli

Use the CLI

npm run cli --

<h3 style="color:#ff4081;">📖 Usage</h3>

<p style="font-size: 1.05em;"><b>Generate an avatar:</b></p>
```bash
github-avatar-frame generate <username> [options]

Examples:

# Basic usage
github-avatar-frame generate octocat

# With custom theme and size
github-avatar-frame generate octocat --theme flamingo --size 512

# With text overlay
github-avatar-frame generate octocat --text "GitHub User" --text-color "#ff0000"

# With emojis
github-avatar-frame generate octocat --emojis "🚀,💻,🔥" --emoji-position corners

# Save to custom file
github-avatar-frame generate octocat --output my-avatar.png

# Use local API server
github-avatar-frame generate octocat --url http://localhost:3000

⚙️ CLI Options

Option	Default	Description
--theme, -t	base	Frame theme (base, classic, darkmode, eternity, flamingo, gitblaze, macros, minimal, neon, ocean, starry)
--size, -s	256	Avatar size in pixels (64-1024)
--canvas, -c	light	Background color (light, dark)
--shape, -sh	circle	Avatar shape (circle, rounded)
--radius, -r	25	Corner radius for rounded shape
--text, -tx	none	Custom text to display
--text-color, -tc	#ffffff	Text color in HEX format
--text-size, -ts	20	Text size in pixels (8-100)
--text-position, -tp	bottom	Text position (top, bottom, center)
--emojis, -e	none	Comma-separated list of emojis
--emoji-size, -es	40	Emoji size in pixels (16-120)
--emoji-position, -ep	top	Emoji position (top, bottom, corners)
--output, -o	avatar.png	Output file path
--url, -u	https://github-avatar-frame-api.onrender.com	API base URL

📋 Other Commands

# List available themes
github-avatar-frame themes

# Show API information
github-avatar-frame info

# Show help
github-avatar-frame --help

🤖 AI-Powered Frame Suggestions

The CLI also supports AI-powered frame suggestions that analyze your GitHub profile and recommend the perfect theme:

# Get AI-powered frame suggestion
github-avatar-frame suggest <username>

# Example
github-avatar-frame suggest octocat

The AI analyzes:

• 🎨 Avatar colors and brightness
• 📊 Contribution activity and patterns
• 👥 Follower-to-repository ratios
• 🔄 Consistency of activity

And suggests themes like:

• Dark avatars → Starry/Galaxy themes
• Professional photos → Minimal themes
• High contributions → Pro/Advanced themes
• Beginners → Classic themes

💡 Why GitHub Avatar Frame API?

• 🆓 Zero Setup: No registration, API keys, or complex configurations needed
• ⚡ Instant Results: Real-time avatar processing with customizable themes
• 👨‍💻 Developer-Friendly: Simple REST API with comprehensive documentation
• 🎭 Creative Freedom: Text overlays, emojis, multiple themes, and shape options
• 🔓 Open Source: Community-driven development with transparent contributions
• 💖 Always Free: No usage limits or premium tiers—built for the community

📌 API Usage

🔗 Base Endpoint:

https://github-avatar-frame-api.onrender.com/api/framed-avatar/{username}?theme={theme}&size={size}&canvas={canvas}&shape={shape}&radius={radius}

🧭 Flowchart

🧮 Query Parameters:

Parameter	Type	Default	Description	Example
username	string	required	GitHub username	octocat
theme	string	base	Frame theme (eternity, base, flamingo)	flamingo
size	integer	256	Avatar size in px (64–1024)	300
canvas	string	light	Background color of avatar canvas: light / dark	dark
shape	string	circle	Avatar shape: circle or rounded	rounded
radius	integer	25	Corner radius for rounded shape in px	50
text	string	optional	Custom text to display on avatar	Hello World
textColor	string	#ffffff	Color of text in HEX format	#ff0000
textSize	integer	20	Size of text in pixels (8-100)	24
textPosition	string	bottom	Position of text: top / bottom / center	top
emojis	string	optional	Comma-separated list of emojis	🚀,💻,🔥
emojiSize	integer	40	Size of emojis in pixels (16-120)	30
emojiPosition	string	top	Position of emojis: top / bottom / corners	corners

🧱 Canvas, Shape & Radius Explained

• 🎨 canvas: Sets the avatar background color. Options: light or dark.
• 🔷 shape: Sets the avatar outline. Options: circle or rounded.
• 📐 radius: Controls corner rounding in px when shape=rounded. 0 = square, higher = more rounded.

Combine all three to customize your avatar:

✍️ Text & Emoji Overlays

Add personalized text and emojis to make your avatar more expressive:

• 📝 text: Add custom text like your name, role, or tagline.
• 🎨 textColor: Set text color using HEX format (e.g., #ff0000 for red).
• 🔠 textSize: Control text size from 8-100 pixels.
• 📍 textPosition: Place text at top, bottom, or center of the avatar.
• 😀 emojis: Add multiple emojis separated by commas (e.g., 🚀,💻,🔥).
• 📏 emojiSize: Control emoji size from 16-120 pixels.
• 📍 emojiPosition: Place emojis at top, bottom, or in corners.

📌 Example with text and emojis:

https://github-avatar-frame-api.onrender.com/api/framed-avatar/octocat?theme=base&text=GitHub%20User&textColor=%23ffffff&textSize=20&textPosition=bottom&emojis=%F0%9F%9A%80%2C%F0%9F%92%BB%2C%F0%9F%94%A5&emojiSize=30&emojiPosition=top

Canvas	Shape	Radius	Example URL	Preview
light	circle	-	URL
dark	circle	-	URL
light	rounded	20	URL
dark	rounded	50	URL

🧪 Live Examples by Theme

Theme	Canvas / Shape / Radius	Preview	Description
eternity	light / circle / 0		Classic eternity theme, light background, circular avatar
eternity	dark / circle / 0		Dark canvas version of eternity theme
base	light / rounded / 20		Base theme, light background, rounded corners 20px
base	light / rounded / 50		Base theme, light background, rounded corners 50px
flamingo	dark / circle / 0		Flamingo theme, dark canvas
flamingo	light / rounded / 30		Flamingo theme, light canvas, rounded corners 30px

📥 Embed in README

![My Avatar](https://github-avatar-frame-api.onrender.com/api/framed-avatar/your-username?theme=flamingo&size=256&canvas=dark&shape=rounded&radius=20)

🧩 Prerequisites

For API Usage:
• Any modern web browser or HTTP client
• Valid GitHub username
• Basic understanding of URL parameters

For Development/Contributing:

• Node.js 16+ and npm
• TypeScript knowledge
• Git for version control
• Code editor (VS Code recommended)

🤝 Contributing

• 🎨 Add new themes in public/frames/
• 🐛 Bug fixes
• ✨ New features
• 📚 Improve documentation

⚙ Tech Stack

• 🟢 Node.js & Express.js (TypeScript)
• 🖼️ Sharp (image processing)
• ☁️ Render (hosting)
• 📘 TypeScript

🖼️ Screenshot

🔗 Links

• Live API: https://github-avatar-frame-api.onrender.com
• Issues: GitHub Issues
• Contributing Guidelines: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md

🌟 Show Your Support

• ⭐ Star the repository
• 🐛 Report bugs or suggest features
• 🤝 Contribute new themes
• 📢 Share with the community

🛠️ Troubleshooting

🧩 API Issues:

🖼️ Avatar not loading

• Check if GitHub username is valid
• Verify theme name spelling (eternity, base, flamingo)
• Ensure size is between 64-1024 pixels

🐢 Slow response times

• API may be cold-starting (hosted on Render free tier)
• Wait 10-15 seconds for first request
• Subsequent requests will be faster

🔧 Development Issues: 🧰 Installation problems

npm cache clean --force rm -rf node_modules package-lock.json npm install

🔌 Port conflicts 🔎 Check if port 3000 is in use netstat -ano | findstr :3000 Kill process or change port in server config

📜 License

MIT License