Endpoint
POST https://api.percify.io/v1/avatars/generate
Request Body
Text description of the desired avatar. Be specific about appearance, style, setting, and mood.Example: "cyberpunk warrior, neon lights, futuristic city, dramatic lighting"
AI model to use for generation.Options:
flux - Fast, 2 credits (standard quality)imagen3 - High quality, 5 creditsreality4 - Ultra realistic, 5 credits
Elements to avoid in the generation.Example: "blurry, low quality, distorted, extra limbs"
Output image aspect ratio.Options: 1:1, 16:9, 9:16, 4:3, 3:4
How closely to follow the prompt (7-15 recommended).Range: 1-20. Higher values = stricter adherence
Random seed for reproducible results. Use same seed with same prompt for identical output.Range: 0 to 2147483647
Number of variations to generate simultaneously.Range: 1-4. Each variation costs credits.
Apply a predefined style template.Options: professional, anime, fantasy, cyberpunk, renaissance, realistic
Response
Current generation status: queued, processing, completed, failed
The prompt used for generation
Full resolution image URL (available when status = completed)
Thumbnail image URL (available when status = completed)
Credits deducted for this generation
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);
Example 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
Text description of the avatar to generate
Example:"Professional headshot of a young entrepreneur, confident smile, modern office background, warm lighting"
AI model to use for generation
Available options:
flux,
imagen3,
reality4
Output image aspect ratio
Available options:
1:1,
16:9,
9:16,
4:3,
3:4
Elements to avoid in the generation
Seed for reproducible results
Avatar generated successfully
URL to the generated avatar image
Prompt used for generation
Available options:
processing,
completed,
failed
Credits consumed for this generation
