Generate Avatar

curl --request POST \
  --url https://percify.io/api/avatars/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting",
  "model": "flux",
  "aspectRatio": "1:1",
  "negativePrompt": "<string>",
  "seed": 123
}
'

import requests

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

payload = {
    "prompt": "Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting",
    "model": "flux",
    "aspectRatio": "1:1",
    "negativePrompt": "<string>",
    "seed": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: 'Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting',
    model: 'flux',
    aspectRatio: '1:1',
    negativePrompt: '<string>',
    seed: 123
  })
};

fetch('https://percify.io/api/avatars/generate', 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/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => 'Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting',
    'model' => 'flux',
    'aspectRatio' => '1:1',
    'negativePrompt' => '<string>',
    'seed' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"prompt\": \"Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting\",\n  \"model\": \"flux\",\n  \"aspectRatio\": \"1:1\",\n  \"negativePrompt\": \"<string>\",\n  \"seed\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://percify.io/api/avatars/generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting\",\n  \"model\": \"flux\",\n  \"aspectRatio\": \"1:1\",\n  \"negativePrompt\": \"<string>\",\n  \"seed\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting\",\n  \"model\": \"flux\",\n  \"aspectRatio\": \"1:1\",\n  \"negativePrompt\": \"<string>\",\n  \"seed\": 123\n}"

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

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

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

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

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

POST

avatars

generate

Generate Avatar

curl --request POST \
  --url https://percify.io/api/avatars/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting",
  "model": "flux",
  "aspectRatio": "1:1",
  "negativePrompt": "<string>",
  "seed": 123
}
'

import requests

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

payload = {
    "prompt": "Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting",
    "model": "flux",
    "aspectRatio": "1:1",
    "negativePrompt": "<string>",
    "seed": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: 'Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting',
    model: 'flux',
    aspectRatio: '1:1',
    negativePrompt: '<string>',
    seed: 123
  })
};

fetch('https://percify.io/api/avatars/generate', 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/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => 'Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting',
    'model' => 'flux',
    'aspectRatio' => '1:1',
    'negativePrompt' => '<string>',
    'seed' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"prompt\": \"Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting\",\n  \"model\": \"flux\",\n  \"aspectRatio\": \"1:1\",\n  \"negativePrompt\": \"<string>\",\n  \"seed\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://percify.io/api/avatars/generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting\",\n  \"model\": \"flux\",\n  \"aspectRatio\": \"1:1\",\n  \"negativePrompt\": \"<string>\",\n  \"seed\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting\",\n  \"model\": \"flux\",\n  \"aspectRatio\": \"1:1\",\n  \"negativePrompt\": \"<string>\",\n  \"seed\": 123\n}"

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

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

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

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

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

Endpoint

POST https://api.percify.io/v1/avatars/generate

Request Body

string

required

Text description of the desired avatar. Be specific about appearance, style, setting, and mood.Example: "cyberpunk warrior, neon lights, futuristic city, dramatic lighting"

string

default:"flux"

AI model to use for generation.Options:

flux - Fast, 2 credits (standard quality)
imagen3 - High quality, 5 credits
reality4 - Ultra realistic, 5 credits

string

Elements to avoid in the generation.Example: "blurry, low quality, distorted, extra limbs"

string

default:"1:1"

Output image aspect ratio.Options: 1:1, 16:9, 9:16, 4:3, 3:4

number

default:"10"

How closely to follow the prompt (7-15 recommended).Range: 1-20. Higher values = stricter adherence

number

Random seed for reproducible results. Use same seed with same prompt for identical output.Range: 0 to 2147483647

number

default:"1"

Number of variations to generate simultaneously.Range: 1-4. Each variation costs credits.

string

Apply a predefined style template.Options: professional, anime, fantasy, cyberpunk, renaissance, realistic

Response

string

Unique avatar identifier

string

Current generation status: queued, processing, completed, failed

string

The prompt used for generation

string

AI model used

string

Full resolution image URL (available when status = completed)

string

Thumbnail image URL (available when status = completed)

number

Image width in pixels

number

Image height in pixels

number

Credits deducted for this generation

string

ISO 8601 timestamp of creation

Example Request

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: 'elegant elven sorceress, flowing robes, mystical forest, magical glow',
    model: 'imagen3',
    negativePrompt: 'blurry, low quality, distorted',
    aspectRatio: '1:1',
    guidanceScale: 12,
    seed: 42
  })
});

const avatar = await response.json();
console.log(avatar);

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': 'elegant elven sorceress, flowing robes, mystical forest, magical glow',
        'model': 'imagen3',
        'negativePrompt': 'blurry, low quality, distorted',
        'aspectRatio': '1:1',
        'guidanceScale': 12,
        'seed': 42
    }
)

avatar = response.json()
print(avatar)

curl -X POST https://api.percify.io/v1/avatars/generate \
  -H "Authorization: Bearer $PERCIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "elegant elven sorceress, flowing robes, mystical forest, magical glow",
    "model": "imagen3",
    "negativePrompt": "blurry, low quality, distorted",
    "aspectRatio": "1:1",
    "guidanceScale": 12,
    "seed": 42
  }'

Example Response

Processing (Immediate Response)

{
  "id": "avatar_abc123",
  "status": "processing",
  "prompt": "elegant elven sorceress, flowing robes, mystical forest, magical glow",
  "negativePrompt": "blurry, low quality, distorted",
  "model": "imagen3",
  "aspectRatio": "1:1",
  "guidanceScale": 12,
  "seed": 42,
  "creditCost": 5,
  "createdAt": "2025-11-25T06:10:00Z"
}

Completed (After Polling)

{
  "id": "avatar_abc123",
  "status": "completed",
  "prompt": "elegant elven sorceress, flowing robes, mystical forest, magical glow",
  "negativePrompt": "blurry, low quality, distorted",
  "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,
  "metadata": {
    "generationTime": 7.8,
    "modelVersion": "imagen3-v2.1"
  },
  "createdAt": "2025-11-25T06:10:00Z",
  "completedAt": "2025-11-25T06:10:08Z"
}

Error Responses

Insufficient Credits

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. Required: 5, Available: 2",
    "details": {
      "required": 5,
      "available": 2,
      "shortfall": 3
    }
  }
}

Invalid Prompt

{
  "error": {
    "code": "invalid_prompt",
    "message": "Prompt violates content policy",
    "details": {
      "reason": "prohibited_content",
      "categories": ["violence"]
    }
  }
}

Rate Limited

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Try again in 45 seconds",
    "details": {
      "retryAfter": 45,
      "limit": 60,
      "window": "1m"
    }
  }
}

Polling for Completion

After initiating generation, poll the avatar status endpoint:

async function waitForAvatar(avatarId) {
  const maxWait = 60000; // 60 seconds
  const pollInterval = 2000; // 2 seconds
  const startTime = Date.now();
  
  while (Date.now() - startTime < maxWait) {
    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');
}

// Usage
const avatar = await waitForAvatar('avatar_abc123');
console.log(`Avatar ready: ${avatar.imageUrl}`);

Batch Generation

Generate multiple variations in parallel:

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: 'space explorer, futuristic helmet, stars background',
    model: 'flux',
    batchSize: 4 // Generate 4 variations
  })
});

const result = await response.json();
// result.avatars = array of 4 avatar objects

Each variation in a batch costs credits. batchSize: 4 with model: 'flux' = 8 credits total (4 × 2)

Best Practices

Prompt Engineering: Be specific and descriptive. Good prompts include:

Subject/character description
Art style or aesthetic
Setting and environment
Lighting conditions
Mood or emotion

Cost Optimization:

Start with flux model (2 credits) for iteration
Switch to premium models once prompt is refined
Use seeds to reproduce good results without regenerating
Batch similar prompts together for efficiency

Get Avatar - Check generation status
List Avatars - View all your avatars
Publish Avatar - Share to community

Authorizations

Authorization

string

header

required

Your Percify API token

Body

application/json

prompt

string

required

Text description of the avatar to generate

Example:

"Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting"

model

enum<string>

default:flux

AI model to use for generation

Available options:

flux,

imagen3,

reality4

aspectRatio

enum<string>

default:1:1

Output image aspect ratio

Available options:

1:1,

16:9,

9:16,

4:3,

3:4

negativePrompt

string

Elements to avoid in the generation

seed

integer

Seed for reproducible results

Response

Avatar generated successfully

string

Unique avatar identifier

imageUrl

string<uri>

URL to the generated avatar image

prompt

string

Prompt used for generation

model

string

AI model used

status

enum<string>

Generation status

Available options:

processing,

completed,

failed

creditsUsed

integer

Credits consumed for this generation

createdAt

string<date-time>

Getting Started

Avatar API

Video Studio API

Audio & Voice API

User & Credits API

Generate Avatar

Endpoint

Request Body

Response

Example Request

Example Response

Processing (Immediate Response)

Completed (After Polling)

Error Responses

Insufficient Credits

Invalid Prompt

Rate Limited

Polling for Completion

Batch Generation

Best Practices

Authorizations

Body

Response

​Endpoint

​Request Body

​Response

​Example Request

​Example Response

​Processing (Immediate Response)

​Completed (After Polling)

​Error Responses

​Insufficient Credits

​Invalid Prompt

​Rate Limited

​Polling for Completion

​Batch Generation

​Best Practices

​Related Endpoints

Authorizations

Body

Response

Endpoint

Request Body

Response

Example Request

Example Response

Processing (Immediate Response)

Completed (After Polling)

Error Responses

Insufficient Credits

Invalid Prompt

Rate Limited

Polling for Completion

Batch Generation

Best Practices

Related Endpoints