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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
Option 1: Install globally from npm
npm install -g github-avatar-frame-cli
Option 2: Use locally (from project root)
# Build the CLI
npm run build:clinpm run cli -- <command>
Generate an avatar:
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 # Export a transparent SVG github-avatar-frame generate octocat --format svg --canvas transparent --output octocat-frame # Use local API server github-avatar-frame generate octocat --url http://localhost:3001
| Option | Default | Description |
|---|---|---|
| --theme, -t | base | Frame theme (base, classic, darkmode, eternity, flamingo, gitblaze, gravityspace, hotfire, macros, minimal, neon, ocean, starry) |
| --size, -s | 256 | Avatar size in pixels (64-1024) |
| --canvas, -c | light | Background color (light, dark, transparent) |
| --shape, -sh | circle | Avatar shape (circle, rounded, rect) |
| --radius, -r | 25 | Corner radius for rounded/rect shape |
| --format, -f | png | Output format (png, jpg, svg) |
| --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 |
# List available themes github-avatar-frame themes # Show API documentation links github-avatar-frame docs # Show API information github-avatar-frame info # Show help github-avatar-frame --help
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
https://github-avatar-frame-api.onrender.com/api/framed-avatar/{username}?theme={theme}&size={size}&canvas={canvas}&shape={shape}&radius={radius}
| Resource | URL / Command | Notes |
|---|---|---|
| Swagger API docs | /api-docs |
Interactive endpoint docs served by the API app. |
| Health check | /api/health |
Quick uptime check for deployments and local dev. |
| Theme list | /api/themes |
Returns every frame theme with metadata. |
| Local API | npm run build && npm start |
Starts the compiled Express server on port 3001 by default. |
| Local client | cd client && npm run dev |
Starts the Vite UI for interactive editing. |
Run these checks before opening a pull request:
# Server helper/API unit tests npm test # TypeScript server build npm run build # CLI TypeScript build npm run build:cli # Client lint and production build cd client && npm run lint && npm run build
| 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 |
📌 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 |
🔧 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