Skip to main content
GET
/
avatars
List Avatars
curl --request GET \
  --url https://percify.io/api/avatars \
  --header 'Authorization: Bearer <token>'
{
  "avatars": [
    {
      "id": "<string>",
      "imageUrl": "<string>",
      "prompt": "<string>",
      "model": "<string>",
      "status": "processing",
      "creditsUsed": 123,
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "nextCursor": "<string>",
  "hasMore": true
}

​
Endpoint

GET https://api.percify.io/v1/avatars

​
Query Parameters

​
limit
number
default:"20"
Number of avatars to return per pageRange: 1-100
​
offset
number
default:"0"
Number of avatars to skip (for pagination)Example: offset=20 with limit=20 returns avatars 21-40
​
status
string
Filter by generation statusOptions: queued, processing, completed, failed
​
model
string
Filter by AI model usedOptions: flux, imagen3, reality4
​
visibility
string
Filter by visibility settingOptions: public, unlisted, private
​
published
boolean
Filter by publication statusOptions: true (published only), false (unpublished only)
​
sortBy
string
default:"createdAt"
Sort fieldOptions: createdAt, likes, comments, remixes
​
sortOrder
string
default:"desc"
Sort directionOptions: asc, desc
​
search
string
Search avatars by prompt text or tagsExample: search=cyberpunk

​
Response

​
avatars
array
Array of avatar objects
​
pagination
object
Pagination metadata

​
Example Request

const response = await fetch(
  'https://api.percify.io/v1/avatars?limit=20&offset=0&status=completed&sortBy=createdAt&sortOrder=desc',
  {
    headers: {
      'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
    }
  }
);

const data = await response.json();
console.log(`Found ${data.pagination.total} avatars`);
data.avatars.forEach(avatar => {
  console.log(`${avatar.id}: ${avatar.prompt}`);
});

​
Example Response

{
  "avatars": [
    {
      "id": "avatar_abc123",
      "status": "completed",
      "prompt": "cyberpunk warrior, neon lights, futuristic city",
      "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,
      "creditCost": 5,
      "visibility": "public",
      "published": true,
      "likes": 42,
      "comments": 8,
      "createdAt": "2025-11-25T06:00:00Z"
    },
    {
      "id": "avatar_def456",
      "status": "completed",
      "prompt": "fantasy elf mage, magical forest, glowing staff",
      "model": "flux",
      "imageUrl": "https://cdn.percify.io/avatars/avatar_def456.png",
      "thumbnailUrl": "https://cdn.percify.io/avatars/avatar_def456_thumb.png",
      "width": 1024,
      "height": 1024,
      "creditCost": 2,
      "visibility": "private",
      "published": false,
      "likes": 0,
      "comments": 0,
      "createdAt": "2025-11-25T05:45:00Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

​
Pagination Example

async function fetchAllAvatars() {
  const allAvatars = [];
  let offset = 0;
  const limit = 50;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://api.percify.io/v1/avatars?limit=${limit}&offset=${offset}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
        }
      }
    );
    
    const data = await response.json();
    allAvatars.push(...data.avatars);
    
    hasMore = data.pagination.hasMore;
    offset += limit;
  }
  
  return allAvatars;
}

​
Filtering Examples

​
Get Published Avatars Only

curl "https://api.percify.io/v1/avatars?published=true&visibility=public" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

​
Search by Keyword

curl "https://api.percify.io/v1/avatars?search=fantasy&limit=10" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

​
Get Most Liked Avatars

curl "https://api.percify.io/v1/avatars?sortBy=likes&sortOrder=desc&limit=10" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

​
Get Processing Avatars

curl "https://api.percify.io/v1/avatars?status=processing" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

Authorizations

​
Authorization
string
header
required

Your Percify API token

Query Parameters

​
limit
integer
default:20

Maximum number of avatars to return

Required range: x <= 100
​
cursor
string

Pagination cursor for next page

Response

List of avatars

​
avatars
object[]
​
nextCursor
string | null
​
hasMore
boolean