Avatar API Overview

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

Method	Endpoint	Description
POST	`/avatars/generate`	Generate a new avatar from prompt
POST	`/avatars/percify-yourself`	Create avatar from photo
POST	`/avatars/cast`	Generate multi-character scene
GET	`/avatars/{avatarId}`	Get avatar details
GET	`/avatars`	List your avatars
PATCH	`/avatars/{avatarId}`	Update avatar metadata
POST	`/avatars/{avatarId}/publish`	Publish avatar to feed
DELETE	`/avatars/{avatarId}`	Delete avatar
POST	`/avatars/{avatarId}/like`	Like an avatar
POST	`/avatars/{avatarId}/comment`	Comment on avatar
POST	`/avatars/{avatarId}/remix`	Remix/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}`);

import os
import requests

response = requests.post(
    'https://api.percify.io/v1/avatars/generate',
    headers={
        'Authorization': f'Bearer {os.environ["PERCIFY_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'prompt': 'fantasy elf warrior, forest background, magical aura',
        'model': 'flux',
        'aspectRatio': '1:1'
    }
)

avatar = response.json()
print(f"Avatar ID: {avatar['id']}")

curl -X POST https://api.percify.io/v1/avatars/generate \
  -H "Authorization: Bearer $PERCIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "fantasy elf warrior, forest background, magical aura",
    "model": "flux",
    "aspectRatio": "1:1"
  }'

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:

Status	Description	Next Action
`queued`	Waiting in generation queue	Poll for status update
`processing`	AI model is generating	Continue polling
`completed`	Generation successful	Image URLs available
`failed`	Generation failed	Check 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

Tier	Requests/minute	Concurrent Generations
Free	10	1
Pro	60	5
Enterprise	300	20

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

Polling for Completion

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');
}

Idempotency

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": "..."}'

Error Handling

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.

Getting Started

Avatar API

Video Studio API

Audio & Voice API

User & Credits API

Overview

Base URL

Authentication

Core Endpoints

Avatar Object

Quick Start Examples

Generate Basic Avatar

Get Avatar Status

List Your Avatars

Generation Status

Error Responses

Rate Limits

Webhooks

Best Practices

Next Steps

Generate Avatar

Manage Avatars

Publish Avatar

Support

​Overview

​Base URL

​Authentication

​Core Endpoints

​Avatar Object

​Quick Start Examples

​Generate Basic Avatar

​Get Avatar Status

​List Your Avatars

​Generation Status

​Error Responses

​Rate Limits

​Webhooks

​Best Practices

​Next Steps

Generate Avatar

Manage Avatars

Publish Avatar

​Support

Overview

Base URL

Authentication

Core Endpoints

Avatar Object

Quick Start Examples

Generate Basic Avatar

Get Avatar Status

List Your Avatars

Generation Status

Error Responses

Rate Limits

Webhooks

Best Practices

Next Steps

Support