🖼️ GitHub Avatar Frame API

Officially accepted for GSSoC!

🖼️ 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

Open your browser and go to http://localhost:5173
You should see the GitHub Avatar Frames interface
Enter a GitHub username (e.g., "torvalds")
Select a theme and click "Generate"
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
light	circle	-	URL
dark	circle	-	URL
light	rounded	20	URL
dark	rounded	50	URL

🧪 Live Examples by Theme

Theme	Canvas / Shape / Radius	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

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

Name		Name	Last commit message	Last commit date
Latest commit History 149 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
api		api
cli		cli
client		client
public		public
.all-contributorsrc		.all-contributorsrc
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
CUSTOMIZATION_FEATURES.md		CUSTOMIZATION_FEATURES.md
LICENSE		LICENSE
QUICK_PUSH_COMMANDS.md		QUICK_PUSH_COMMANDS.md
README.md		README.md
SECURITY.md		SECURITY.md
TODO.md		TODO.md
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
render.yml		render.yml
test.png		test.png
test_combined.png		test_combined.png
test_download.jpg		test_download.jpg
test_download.png		test_download.png
test_download.svg		test_download.svg
test_emojis.png		test_emojis.png
test_text.png		test_text.png
test_with_text.png		test_with_text.png
tsconfig.server.json		tsconfig.server.json

License

kishanrathor/github-avatar-frame-api

Folders and files

Latest commit

History

Repository files navigation

🖼️ GitHub Avatar Frame API

🖼️ GitHub Avatar Frame API

📚 Table of Contents

✨ Vision

🎯 Mission

🎨 About GitHub Avatar Frame API

⚙️ Setup & Local Development

🧩 Prerequisites

💻 Steps

1. Clone the Repository

2. Install Backend Dependencies

3. Setup Frontend

Running the Application

Start Backend (Terminal 1)

Start Frontend (Terminal 2)

Verify Everything Works

📂 Project Structure

💻 CLI Usage

🚀 Installation

Use the CLI

⚙️ CLI Options

📋 Other Commands

🤖 AI-Powered Frame Suggestions

💡 Why GitHub Avatar Frame API?

📌 API Usage

🧭 Flowchart

🧮 Query Parameters:

🧱 Canvas, Shape & Radius Explained

✍️ Text & Emoji Overlays

🧪 Live Examples by Theme

📥 Embed in README

🧩 Prerequisites

🤝 Contributing

⚙ Tech Stack

🖼️ Screenshot

🔗 Links

🌟 Show Your Support

🛠️ Troubleshooting

🧩 API Issues:

🖼️ Avatar not loading

🐢 Slow response times

📜 License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages