Developer API

🔐 API Keys

All API requests require authentication via a Bearer token in the Authorization header. API keys are tied to your account and can be managed from your dashboard.

Authorization: Bearer sk_live_abc123def456...

Important: Keep your API keys secret. Never expose them in client-side code or public repositories.

🟨 JavaScript / Node.js

Install the SDK and generate avatars with just a few lines of code.

// Installation
npm install squareface
// or
yarn add squareface

// Basic Usage
import { SquareFace } from 'squareface';

// Initialize with your API key
const client = new SquareFace('sk_live_your_api_key');

// Generate a single avatar
const avatar = await client.render({
  skin: '#F2C9A0',
  hairStyle: 3,
  hairColor: '#232946',
  eyeStyle: 2,
  size: 512,
  bg: 'transparent'
});

console.log(avatar.url); // CDN URL for the avatar
console.log(avatar.image); // Base64 image data

// Generate random avatar
const randomAvatar = await client.random({ size: 256 });

// Batch generation for Discord bots
const avatars = await client.batch([
  { hairStyle: 1, skin: '#F2C9A0' },
  { hairStyle: 5, skin: '#8D5524' },
  { hairStyle: 12, skin: '#FFDBAC' }
], { size: 128 });

// Use with preset styles
const animeAvatar = await client.render({
  preset: 'anime',
  hairColor: '#FF69B4'
});

// Discord.js Integration Example
import { Client } from 'discord.js';
import { SquareFace } from 'squareface';

const bot = new Client({ intents: [...] });
const sf = new SquareFace(process.env.SQUAREFACE_KEY);

bot.on('messageCreate', async (msg) => {
  if (msg.content === '!avatar') {
    const avatar = await sf.random({ size: 256 });
    msg.reply({ files: [avatar.url] });
  }
});

🐍 Python

Python SDK with async support for high-performance applications.

# Installation
pip install squareface
# or with async support
pip install squareface[async]

# Basic Usage
from squareface import SquareFace

# Initialize client
client = SquareFace("sk_live_your_api_key")

# Generate a single avatar
avatar = client.render(
    skin="#F2C9A0",
    hair_style=3,
    hair_color="#232946",
    eye_style=2,
    size=512,
    bg="transparent"
)

print(avatar.url)  # CDN URL
avatar.save("my_avatar.png")  # Save to file

# Generate random avatar
random_avatar = client.random(size=256)

# Batch generation
avatars = client.batch([
    {"hair_style": 1, "skin": "#F2C9A0"},
    {"hair_style": 5, "skin": "#8D5524"},
    {"hair_style": 12, "skin": "#FFDBAC"}
], size=128)

# Save all avatars
for i, av in enumerate(avatars):
    av.save(f"avatar_{i}.png")

# Async Usage (for web apps like FastAPI)
from squareface import AsyncSquareFace
from fastapi import FastAPI
from fastapi.responses import Response

app = FastAPI()
sf = AsyncSquareFace("sk_live_your_api_key")

@app.get("/avatar")
async def generate_avatar():
    avatar = await sf.random(size=256)
    return {"url": avatar.url}

@app.get("/avatar/image")
async def get_avatar_image():
    avatar = await sf.random(size=256)
    return Response(
        content=avatar.bytes,
        media_type="image/png"
    )

🔧 cURL / REST API

Direct HTTP requests for any language or platform.

# Generate a single avatar
curl -X POST https://api.squarefacegenerator.net/v1/render \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "skin": "#F2C9A0",
    "hairStyle": 3,
    "hairColor": "#232946",
    "size": 512,
    "bg": "transparent"
  }'

# Generate random avatar
curl https://api.squarefacegenerator.net/v1/random?size=256 \
  -H "Authorization: Bearer sk_live_your_api_key"

# Get available options
curl https://api.squarefacegenerator.net/v1/options \
  -H "Authorization: Bearer sk_live_your_api_key"