Skip to main content

​
Overview

The Avatar API provides endpoints for generating AI avatars, managing avatar metadata, publishing to the community feed, and retrieving avatar assets. All endpoints require authentication via API key.

​
Base URL

https://api.percify.io/v1

​
Authentication

All requests must include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Core Endpoints

MethodEndpointDescription
POST/avatars/generateGenerate a new avatar from prompt
POST/avatars/percify-yourselfCreate avatar from photo
POST/avatars/castGenerate multi-character scene
GET/avatars/{avatarId}Get avatar details
GET/avatarsList your avatars
PATCH/avatars/{avatarId}Update avatar metadata
POST/avatars/{avatarId}/publishPublish avatar to feed
DELETE/avatars/{avatarId}Delete avatar
POST/avatars/{avatarId}/likeLike an avatar
POST/avatars/{avatarId}/commentComment on avatar
POST/avatars/{avatarId}/remixRemix/derive from avatar

​
Avatar Object

{
  "id": "avatar_abc123",
  "userId": "user_xyz789",
  "status": "completed",
  "prompt": "cyberpunk warrior, neon lights, futuristic city",
  "negativePrompt": "blurry, low quality",
  "model": "imagen3",
  "imageUrl": "https://cdn.percify.io/avatars/avatar_abc123.png",
  "thumbnailUrl": "https://cdn.percify.io/avatars/avatar_abc123_thumb.png",
  "width": 1024,
  "height": 1024,
  "aspectRatio": "1:1",
  "guidanceScale": 12,
  "seed": 42,
  "creditCost": 5,
  "visibility": "public",
  "published": true,
  "publishedAt": "2025-11-25T06:00:00Z",
  "likes": 42,
  "comments": 8,
  "remixes": 3,
  "tags": ["cyberpunk", "character", "warrior"],
  "metadata": {
    "generationTime": 7.3,
    "modelVersion": "imagen3-v2.1"
  },
  "createdAt": "2025-11-25T05:59:52Z",
  "updatedAt": "2025-11-25T06:00:00Z"
}

​
Quick Start Examples

​
Generate Basic Avatar

const response = await fetch('https://api.percify.io/v1/avatars/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'fantasy elf warrior, forest background, magical aura',
    model: 'flux',
    aspectRatio: '1:1'
  })
});

const avatar = await response.json();
console.log(`Avatar ID: ${avatar.id}`);

​
Get Avatar Status

curl -X GET https://api.percify.io/v1/avatars/avatar_abc123 \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

​
List Your Avatars

curl -X GET https://api.percify.io/v1/avatars?limit=20&offset=0 \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

​
Generation Status

Avatars go through several status stages:
StatusDescriptionNext Action
queuedWaiting in generation queuePoll for status update
processingAI model is generatingContinue polling
completedGeneration successfulImage URLs available
failedGeneration failedCheck error details

​
Error Responses

Standard error format: 
{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to generate avatar. Required: 5, Available: 2",
    "details": {
      "required": 5,
      "available": 2
    }
  }
}
Common error codes:
  • invalid_request - Missing or invalid parameters
  • authentication_required - Missing or invalid API key
  • insufficient_credits - Not enough credits for operation
  • rate_limit_exceeded - Too many requests
  • content_policy_violation - Prompt violates content policy
  • avatar_not_found - Avatar ID doesn’t exist
  • unauthorized_access - Can’t access another user’s private avatar

​
Rate Limits

TierRequests/minuteConcurrent Generations
Free101
Pro605
Enterprise30020
Rate limit headers included in responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700000000

​
Webhooks

Subscribe to avatar events: 
{
  "event": "avatar.completed",
  "data": {
    "avatarId": "avatar_abc123",
    "status": "completed",
    "imageUrl": "https://cdn.percify.io/avatars/avatar_abc123.png"
  },
  "timestamp": "2025-11-25T06:00:00Z"
}
Available events:
  • avatar.completed - Generation finished successfully
  • avatar.failed - Generation failed
  • avatar.published - Avatar published to feed
  • avatar.liked - Someone liked your avatar
  • avatar.commented - New comment on avatar

​
Best Practices

async function waitForAvatar(avatarId) {
  const maxAttempts = 30;
  const pollInterval = 2000; // 2 seconds
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.percify.io/v1/avatars/${avatarId}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
        }
      }
    );
    
    const avatar = await response.json();
    
    if (avatar.status === 'completed') {
      return avatar;
    } else if (avatar.status === 'failed') {
      throw new Error(`Generation failed: ${avatar.error}`);
    }
    
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
  
  throw new Error('Avatar generation timed out');
}
Use idempotency keys for safe retries:
curl -X POST https://api.percify.io/v1/avatars/generate \
  -H "Authorization: Bearer $PERCIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{"prompt": "..."}'

try {
  const response = await fetch('https://api.percify.io/v1/avatars/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ prompt, model })
  });
  
  if (!response.ok) {
    const error = await response.json();
    
    if (error.error.code === 'insufficient_credits') {
      // Handle low credits
      console.log('Please purchase more credits');
    } else if (error.error.code === 'rate_limit_exceeded') {
      // Wait and retry
      const resetTime = response.headers.get('X-RateLimit-Reset');
      console.log(`Rate limited until ${new Date(resetTime * 1000)}`);
    } else {
      throw new Error(error.error.message);
    }
  }
  
  const avatar = await response.json();
  return avatar;
} catch (error) {
  console.error('Avatar generation failed:', error);
  throw error;
}

​
Next Steps

Generate Avatar

Create new avatars

Manage Avatars

List and organize

Publish Avatar

Share with community

​
Support

Questions about the Avatar API? Check our FAQ or contact support@percify.io.