List Avatars

curl --request GET \
  --url https://percify.io/api/avatars \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://percify.io/api/avatars', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://percify.io/api/avatars",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://percify.io/api/avatars"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://percify.io/api/avatars")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "avatars": [
    {
      "id": "<string>",
      "imageUrl": "<string>",
      "prompt": "<string>",
      "model": "<string>",
      "status": "processing",
      "creditsUsed": 123,
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "nextCursor": "<string>",
  "hasMore": true
}

{
  "error": "<string>",
  "message": "<string>",
  "code": "<string>"
}

GET

avatars

List Avatars

curl --request GET \
  --url https://percify.io/api/avatars \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://percify.io/api/avatars', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://percify.io/api/avatars",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://percify.io/api/avatars"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://percify.io/api/avatars")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "avatars": [
    {
      "id": "<string>",
      "imageUrl": "<string>",
      "prompt": "<string>",
      "model": "<string>",
      "status": "processing",
      "creditsUsed": 123,
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "nextCursor": "<string>",
  "hasMore": true
}

{
  "error": "<string>",
  "message": "<string>",
  "code": "<string>"
}

Endpoint

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

Query Parameters

number

default:"20"

Number of avatars to return per pageRange: 1-100

number

default:"0"

Number of avatars to skip (for pagination)Example: offset=20 with limit=20 returns avatars 21-40

string

Filter by generation statusOptions: queued, processing, completed, failed

string

Filter by AI model usedOptions: flux, imagen3, reality4

string

Filter by visibility settingOptions: public, unlisted, private

boolean

Filter by publication statusOptions: true (published only), false (unpublished only)

string

default:"createdAt"

Sort fieldOptions: createdAt, likes, comments, remixes

string

default:"desc"

Sort directionOptions: asc, desc

string

Search avatars by prompt text or tagsExample: search=cyberpunk

Response

array

Array of avatar objects

object

Pagination metadata

Show pagination fields

number

Total number of avatars matching filters

number

Items per page

number

Current offset

boolean

Whether more pages exist

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

import os
import requests

response = requests.get(
    'https://api.percify.io/v1/avatars',
    params={
        'limit': 20,
        'offset': 0,
        'status': 'completed',
        'sortBy': 'createdAt',
        'sortOrder': 'desc'
    },
    headers={
        'Authorization': f'Bearer {os.environ["PERCIFY_API_KEY"]}'
    }
)

data = response.json()
print(f"Found {data['pagination']['total']} avatars")
for avatar in data['avatars']:
    print(f"{avatar['id']}: {avatar['prompt']}")

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

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"

Get Avatar - Get single avatar details
Generate Avatar - Create new avatar
Delete Avatar - Remove avatar

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[]

Show child attributes

nextCursor

string | null

hasMore

boolean

Getting Started

Avatar API

Video Studio API

Audio & Voice API

User & Credits API

List Avatars

Endpoint

Query Parameters

Response

Example Request

Example Response

Filtering Examples

Get Published Avatars Only

Search by Keyword

Get Most Liked Avatars

Get Processing Avatars

Authorizations

Query Parameters

Response

​Endpoint

​Query Parameters

​Response

​Example Request

​Example Response

​Pagination Example

​Filtering Examples

​Get Published Avatars Only

​Search by Keyword

​Get Most Liked Avatars

​Get Processing Avatars

​Related Endpoints

Authorizations

Query Parameters

Response

Endpoint

Query Parameters

Response

Example Request

Example Response

Pagination Example

Filtering Examples

Get Published Avatars Only

Search by Keyword

Get Most Liked Avatars

Get Processing Avatars

Related Endpoints