Square Face Generator API

Quick Start

🚀 Generate Your First Avatar

Make a simple POST request to render an avatar with your desired settings. The API returns a PNG image or base64 data.

// Request
POST https://api.squarefacegenerator.net/v1/render
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "skin": "#F2C9A0",
  "hairStyle": 3,
  "hairColor": "#232946",
  "eyeStyle": 2,
  "bg": "transparent",
  "size": 512
}

// Response
{
  "success": true,
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "url": "https://cdn.squarefacegenerator.net/renders/abc123.png",
  "expiresAt": "2025-01-01T12:10:00Z"
}

Authentication

🔐 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.

Endpoints

POST /v1/render

Generate a single avatar with custom parameters. Returns a PNG image as base64 or a temporary URL.

Parameters

Name	Type	Description
skin	string optional	Hex color for skin tone (e.g., "#F2C9A0")
hairStyle	integer optional	Hair style ID (1-20). Use /v1/options for available styles.
hairColor	string optional	Hex color for hair (e.g., "#232946")
eyeStyle	integer optional	Eye style ID (1-15)
expression	string optional	Expression: "happy", "sad", "surprised", "neutral"
accessories	array optional	Array of accessory IDs to apply
bg	string optional	"transparent" or hex color (default: "#FFFFFF")
size	integer optional	Output size: 64, 128, 256, 512, or 1024 (default: 256)
format	string optional	"base64" or "url" (default: "base64")

Example Response

{
  "success": true,
  "image": "data:image/png;base64,...",
  "url": "https://cdn.squarefacegenerator.net/renders/xyz.png",
  "expiresAt": "2025-01-01T12:10:00Z",
  "renderTime": 142
}

POST /v1/batch

Generate multiple avatars in a single request. More efficient for bulk generation. Maximum 50 avatars per request.

// Request body
{
  "avatars": [
    { "hairStyle": 1, "skin": "#F2C9A0" },
    { "hairStyle": 5, "skin": "#8D5524" },
    { "hairStyle": 12, "skin": "#FFDBAC" }
  ],
  "size": 256,
  "format": "url"
}

GET /v1/random

Generate a completely random avatar. Great for placeholder avatars or inspiration.

GET /v1/random?size=512&format=url

GET /v1/presets

Get available style presets (anime, kawaii, pixel, chibi, retro). Apply a preset by ID for quick styling.

// Response
{
  "presets": [
    { "id": "anime", "name": "Anime Style", ... },
    { "id": "kawaii", "name": "Kawaii Cute", ... },
    { "id": "pixel", "name": "Pixel Art", ... }
  ]
}

GET /v1/options

Get all available customization options with their IDs. Use these IDs when making render requests.

API Pricing

Starter

$29/mo

2,500 renders/month

✓ All render endpoints
✓ Up to 512px exports
✓ Email support
✓ Standard rate limits

Growth

$59/mo

10,000 renders/month

✓ Everything in Starter
✓ 1024px HD exports
✓ Priority support
✓ Higher rate limits

Enterprise

Custom

Unlimited renders

✓ Everything in Growth
✓ Custom SLA
✓ Dedicated support
✓ Custom integrations

SDKs & Libraries

🟨

JavaScript

npm install squareface

Coming Soon

🐍

Python

pip install squareface

Coming Soon

💎

Ruby

gem install squareface

Planned

🐹

Go

go get squareface

Planned

Rate Limits

📊 Request Limits

To ensure fair usage and service stability, the API enforces rate limits based on your plan:

Plan	Requests/Minute	Requests/Day	Concurrent
Starter	30	2,500	5
Growth	60	10,000	10
Enterprise	Custom	Unlimited	Custom

Rate limit headers are included in all responses: X-RateLimit-Remaining, X-RateLimit-Reset

Ready to Get Started?

Request early access to the API. We'll notify you when it's ready and provide priority onboarding.

Request API Access →