> ## Documentation Index
> Fetch the complete documentation index at: https://docs.percify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Avatar

> Create a new AI avatar from a text prompt

## Endpoint

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

## Request Body

<ParamField body="prompt" type="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"`
</ParamField>

<ParamField body="model" type="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
</ParamField>

<ParamField body="negativePrompt" type="string">
  Elements to avoid in the generation.

  **Example:** `"blurry, low quality, distorted, extra limbs"`
</ParamField>

<ParamField body="aspectRatio" type="string" default="1:1">
  Output image aspect ratio.

  **Options:** `1:1`, `16:9`, `9:16`, `4:3`, `3:4`
</ParamField>

<ParamField body="guidanceScale" type="number" default="10">
  How closely to follow the prompt (7-15 recommended).

  **Range:** 1-20. Higher values = stricter adherence
</ParamField>

<ParamField body="seed" type="number">
  Random seed for reproducible results. Use same seed with same prompt for identical output.

  **Range:** 0 to 2147483647
</ParamField>

<ParamField body="batchSize" type="number" default="1">
  Number of variations to generate simultaneously.

  **Range:** 1-4. Each variation costs credits.
</ParamField>

<ParamField body="stylePreset" type="string">
  Apply a predefined style template.

  **Options:** `professional`, `anime`, `fantasy`, `cyberpunk`, `renaissance`, `realistic`
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique avatar identifier
</ResponseField>

<ResponseField name="status" type="string">
  Current generation status: `queued`, `processing`, `completed`, `failed`
</ResponseField>

<ResponseField name="prompt" type="string">
  The prompt used for generation
</ResponseField>

<ResponseField name="model" type="string">
  AI model used
</ResponseField>

<ResponseField name="imageUrl" type="string">
  Full resolution image URL (available when status = completed)
</ResponseField>

<ResponseField name="thumbnailUrl" type="string">
  Thumbnail image URL (available when status = completed)
</ResponseField>

<ResponseField name="width" type="number">
  Image width in pixels
</ResponseField>

<ResponseField name="height" type="number">
  Image height in pixels
</ResponseField>

<ResponseField name="creditCost" type="number">
  Credits deducted for this generation
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of creation
</ResponseField>

## Example Request

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

## Example Response

### Processing (Immediate Response)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

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

### Invalid Prompt

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

### Rate Limited

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```javascript theme={null}
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
```

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

## Best Practices

<Tip>
  **Prompt Engineering:** Be specific and descriptive. Good prompts include:

  * Subject/character description
  * Art style or aesthetic
  * Setting and environment
  * Lighting conditions
  * Mood or emotion
</Tip>

<Info>
  **Cost Optimization:**

  1. Start with `flux` model (2 credits) for iteration
  2. Switch to premium models once prompt is refined
  3. Use seeds to reproduce good results without regenerating
  4. Batch similar prompts together for efficiency
</Info>

## Related Endpoints

* [Get Avatar](/api-reference/avatars/get) - Check generation status
* [List Avatars](/api-reference/avatars/list) - View all your avatars
* [Publish Avatar](/api-reference/avatars/publish) - Share to community


## OpenAPI

````yaml POST /avatars/generate
openapi: 3.1.0
info:
  title: Percify API
  description: >-
    Percify AI Avatar & Video Generation API - Create stunning AI-generated
    avatars, videos, and voice content
  version: 1.0.0
  contact:
    name: Percify Support
    email: support@percify.io
    url: https://percify.io
servers:
  - url: https://percify.io/api
    description: Production API
security:
  - bearerAuth: []
paths:
  /avatars/generate:
    post:
      tags:
        - Avatars
      summary: Generate Avatar
      description: Generate a new AI avatar using the specified model and prompt
      operationId: generateAvatar
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAvatarRequest'
      responses:
        '200':
          description: Avatar generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Avatar'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GenerateAvatarRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: Text description of the avatar to generate
          example: >-
            Professional headshot of a young entrepreneur, confident smile,
            modern office background, warm lighting
        model:
          type: string
          enum:
            - flux
            - imagen3
            - reality4
          default: flux
          description: AI model to use for generation
        aspectRatio:
          type: string
          enum:
            - '1:1'
            - '16:9'
            - '9:16'
            - '4:3'
            - '3:4'
          default: '1:1'
          description: Output image aspect ratio
        negativePrompt:
          type: string
          description: Elements to avoid in the generation
        seed:
          type: integer
          description: Seed for reproducible results
    Avatar:
      type: object
      properties:
        id:
          type: string
          description: Unique avatar identifier
        imageUrl:
          type: string
          format: uri
          description: URL to the generated avatar image
        prompt:
          type: string
          description: Prompt used for generation
        model:
          type: string
          description: AI model used
        status:
          type: string
          enum:
            - processing
            - completed
            - failed
          description: Generation status
        creditsUsed:
          type: integer
          description: Credits consumed for this generation
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Your Percify API token

````