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

# Create Photo Avatar

> Generate custom AI avatars from portrait photos

## Introduction

Transform portrait photos into talking AI avatars that can speak any script in 40+ languages. Create personalized avatars for branding, marketing, or custom content production. Photo avatars allow you to use your own face or team members' faces in videos, maintaining brand consistency across all content.

<video controls className="w-full aspect-video" src="https://res.jogg.ai/upload/sam/2025-04-13/0f0d7deb55054b8c9e4cb60e27160ee5.mp4" />

### Key Features

<CardGroup cols={2}>
  <Card title="Personal Branding" icon="user-tie">
    Your face, your voice, your brand
  </Card>

  <Card title="Multilingual" icon="globe">
    One photo avatar speaks 40+ languages
  </Card>

  <Card title="Realistic Motion" icon="video">
    Natural facial expressions and movements
  </Card>

  <Card title="Fast Generation" icon="bolt">
    2-5 minutes to create custom avatar
  </Card>
</CardGroup>

### Workflow Overview

Photo avatar creation follows these steps:

<Steps>
  <Step title="Generate Avatar">
    Upload portrait photo → AI generates avatar (2-5 min)
  </Step>

  <Step title="Check Status">
    Poll for completion or use webhooks
  </Step>

  <Step title="Use in Videos">
    Create videos using your custom avatar
  </Step>

  <Step title="Add Motion (Optional)">
    Enhance avatar with realistic movements (2-3 min)
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Queue
    participant Webhook as Your Server (Optional)
    
    Note over Client,Webhook: Setup Webhook (Optional - One Time)
    Client->>API: POST /v2/endpoint
    API-->>Client: {endpoint_id, secret}
    
    Note over Client: Step 1: Generate Avatar
    Client->>API: POST /v2/photo_avatar/photo/generate
    API->>Queue: Queue generation
    API-->>Client: 200 OK {photo_id}
    
    Note over Queue: Processing (2-5 min)
    Queue->>Queue: Generate avatar
    
    alt Webhook Mode
        Note over Queue,Webhook: Step 2a: Webhook Notification
        Queue->>API: Generation complete
        API->>Webhook: POST webhook (generated_image_success)
        Webhook-->>API: 200 OK
    else Polling Mode
        Note over Client,Queue: Step 2b: Poll Status
        Client->>API: GET /v2/photo_avatar/photo?photo_id={id}
        API-->>Client: {status, image_url_list}
    end
    
    Note over Client: Step 3: Use in Videos
    Client->>API: POST /v2/create_video_from_avatar
    API-->>Client: {video_id}
    
    Note over Client,Queue: Step 4: Add Motion (Optional)
    Client->>API: POST /v2/photo_avatar/add_motion
    API->>Queue: Queue motion generation
    API-->>Client: 200 OK {motion_id}
    
    Note over Queue: Processing (2-3 min)
    Queue->>Queue: Generate motion
    
    alt Webhook Mode
        Note over Queue,Webhook: Step 5a: Motion Webhook Notification
        Queue->>API: Motion complete
        API->>Webhook: POST webhook (generated_motion_success)
        Webhook-->>API: 200 OK
    else Polling Mode
        Note over Client,Queue: Step 5b: Poll Motion Status
        Client->>API: GET /v2/photo_avatar?motion_id={id}
        API-->>Client: {status, motion_preview_url}
    end
```

<Info>
  **Optional Step:** Add motion for enhanced realism (additional 2-3 minutes). See [Step 4: Add Motion to Avatar](#step-4-add-motion-to-avatar-optional) section below.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                                   | Purpose                 | Documentation                                                  |
| ------------------------------------------ | ----------------------- | -------------------------------------------------------------- |
| `POST /v2/photo_avatar/photo/generate`     | Generate photo avatar   | [API Reference](/api-reference/v2/Avatar/PhotoAvatarGenerate)  |
| `GET /v2/photo_avatar/photo?photo_id={id}` | Check generation status | [API Reference](/api-reference/v2/Avatar/PhotoAvatarStatusGet) |
| `GET /v2/avatars/photo_avatars`            | List your photo avatars | [API Reference](/api-reference/v2/Avatar/PhotoAvatarsGet)      |
| `POST /v2/photo_avatar/add_motion`         | Add motion to avatar    | [API Reference](/api-reference/v2/Avatar/PhotoAvatarMotionAdd) |
| `GET /v2/photo_avatar?motion_id={id}`      | Check motion status     | [API Reference](/api-reference/v2/Avatar/MotionStatusCheck)    |

### Key Parameters

| Parameter      | Type   | Required | Description                                                                                                                |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `age`          | string | ✅        | Avatar age group: "Teenager", "Young adult", "Adult", "Elderly"                                                            |
| `avatar_style` | string | ✅        | Style category: "Professional", "Social"                                                                                   |
| `gender`       | string | ✅        | Avatar gender: "Female", "Male"                                                                                            |
| `model`        | string | ✅        | Photo generation model: "classic", "modern"                                                                                |
| `aspect_ratio` | string | ✅        | Photo aspect ratio: "portrait", "landscape", "square"                                                                      |
| `image_url`    | string | ❌        | Reference image URL (your portrait photo)                                                                                  |
| `ethnicity`    | string | ❌        | Avatar ethnicity: "European", "African", "South Asian", "East Asian", "Middle Eastern", "South American", "North American" |
| `background`   | string | ❌        | Background description                                                                                                     |
| `appearance`   | string | ❌        | Appearance description                                                                                                     |

<Warning>
  **Photo Requirements:** Use high-quality portrait photos (min 512x512px, recommended 1024x1024px). Face should be frontal, well-lit, and unobstructed. See [Photo Requirements](#photo-requirements) section for details.
</Warning>

***

## Code Examples

### Scenario 1: Basic Photo Avatar Creation

Create and use a photo avatar in videos:

#### Step 1: Generate Photo Avatar

Generate a custom avatar from your portrait photo:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo/generate' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "age": "Adult",
    "avatar_style": "Professional",
    "gender": "Male",
    "model": "modern",
    "aspect_ratio": "portrait",
    "image_url": "https://example.com/portrait.jpg"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123"
  }
}
```

<Check>
  Save the `photo_id` to check generation status!
</Check>

***

#### Step 2: Check Generation Status

Check if avatar generation is complete:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo?photo_id=photo_abc123' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123",
    "status": "in_progress"
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123",
    "status": "success",
    "image_url_list": [
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ],
    "image_key_list": [
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ]
  }
}
```

<Tip>
  Avatar generation typically takes 2-5 minutes. Use [Webhooks](/api-reference/v2/API%20Documentation/WebhookIntegration) for instant notifications instead of polling. See [Webhook Mode](#webhook-mode) section below for complete setup.
</Tip>

<Info>
  **Image Generation Charges:**

  * Each call generates four images
  * Each image deducts 0.05 credit
  * Four images deduct a total of 0.2 credit
</Info>

<Check>
  We have generated our AI Avatar photos. Now we can use these `image_key` values to create new looks or use the avatar in videos.
</Check>

***

#### Step 3: Create Video with Photo Avatar

Create a video using your photo avatar:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 123,
      "avatar_type": 1
    },
    "voice": {
      "type": "script",
      "voice_id": "en-US-ChristopherNeural",
      "script": "Hello! I am your custom photo avatar."
    },
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "caption": true
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

<Warning>
  **Important:** Always use `avatar_type: 1` for photo avatars (custom avatars). Use `avatar_type: 0` for public avatars.
</Warning>

***

### Webhook Mode

Use webhooks to receive instant notifications when avatar generation completes, eliminating the need for polling.

#### Step 1: Setup Webhook Endpoint

First, create a webhook endpoint to receive notifications:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/endpoint' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://your-domain.com/webhook",
    "events": [
      "generated_image_success",
      "generated_image_failed",
      "generated_motion_success",
      "generated_motion_failed"
    ],
    "status": "enabled"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "endpoint_id": "wh_123456789",
    "url": "https://your-domain.com/webhook",
    "secret": "whsec_abc123xyz",
    "status": "enabled",
    "events": [
      "generated_image_success",
      "generated_image_failed",
      "generated_motion_success",
      "generated_motion_failed"
    ],
    "username": "johndoe",
    "created_at": 1732806631
  }
}
```

<Check>
  Save the `secret` - you'll need it to verify webhook signatures!
</Check>

#### Step 2: Generate Photo Avatar

Generate avatar as usual:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo/generate' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "age": "Adult",
    "avatar_style": "Professional",
    "gender": "Male",
    "model": "modern",
    "aspect_ratio": "portrait",
    "image_url": "https://example.com/portrait.jpg"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123"
  }
}
```

#### Step 3: Receive Webhook Notification

When generation completes (2-5 minutes), your webhook endpoint will receive a POST request:

**Success Event Payload:**

```json theme={null}
{
  "event": "generated_image_success",
  "timestamp": 1732806631,
  "data": {
    "photo_id": "photo_abc123",
    "photo_urls": [
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ]
  }
}
```

**Failed Event Payload:**

```json theme={null}
{
  "event": "generated_image_failed",
  "timestamp": 1732806631,
  "data": {
    "photo_id": "photo_abc123",
    "error": "Image generation failed due to invalid parameters"
  }
}
```

#### Step 4: Verify Webhook Signature

Always verify webhook signatures to ensure requests come from JoggAI:

**Example (Node.js):**

```javascript theme={null}
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  
  if (event.event === 'generated_image_success') {
    // Handle success
    const { photo_id, photo_urls } = event.data;
    console.log(`Avatar ${photo_id} generated successfully!`);
    // Process photo_urls...
  } else if (event.event === 'generated_image_failed') {
    // Handle failure
    const { photo_id, error } = event.data;
    console.error(`Avatar ${photo_id} failed: ${error}`);
  }
  
  res.status(200).send('OK');
});
```

#### Step 5: Motion Generation with Webhooks

When adding motion, you'll receive notifications for motion generation:

**Motion Success Event:**

```json theme={null}
{
  "event": "generated_motion_success",
  "timestamp": 1732806631,
  "data": {
    "motion_id": "motion_xyz789",
    "motion_url": "https://files2.jogg.ai/avatar/v3/motion_xyz789/full/2.0/preview_video_target.mp4",
    "photo_url": "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png"
  }
}
```

**Motion Failed Event:**

```json theme={null}
{
  "event": "generated_motion_failed",
  "timestamp": 1732806631,
  "data": {
    "motion_id": "motion_xyz789",
    "error": "Motion generation failed due to processing error"
  }
}
```

<Info>
  **Webhook Events for Photo Avatar:**

  * `generated_image_success` - Triggered when image generation completes successfully
  * `generated_image_failed` - Triggered when image generation fails
  * `generated_motion_success` - Triggered when motion generation completes successfully
  * `generated_motion_failed` - Triggered when motion generation fails

  See [Webhook Integration Guide](/api-reference/v2/API%20Documentation/WebhookIntegration) for complete webhook documentation.
</Info>

***

### Scenario 2: Photo Avatar with Motion Enhancement

Create a photo avatar with enhanced motion for more realistic videos:

#### Step 1: Generate Photo Avatar

Generate a custom avatar from your portrait photo:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo/generate' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "age": "Adult",
    "avatar_style": "Professional",
    "gender": "Male",
    "model": "modern",
    "aspect_ratio": "portrait",
    "image_url": "https://example.com/portrait.jpg"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123"
  }
}
```

***

#### Step 2: Check Generation Status

Check if avatar generation is complete:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo?photo_id=photo_abc123' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123",
    "status": "success",
    "image_url_list": [
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ],
    "image_key_list": [
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ]
  }
}
```

***

#### Step 3: Add Motion to Avatar

Enhance avatar with realistic movements:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/photo_avatar/add_motion' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "photo_id": "photo_abc123",
    "image_url": "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
    "name": "My Photo Avatar",
    "voice_id": "en-US-ChristopherNeural",
    "model": "2.0",
    "description": "Professional avatar for marketing videos"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "avatar_id": 123,
    "motion_id": "motion_xyz789",
    "status": "processing"
  }
}
```

<Check>
  Save the `motion_id` and `avatar_id` to check motion generation status!
</Check>

***

#### Step 4: Check Motion Status

Check if motion generation is complete:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/photo_avatar?motion_id=motion_xyz789' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "motion_id": "motion_xyz789",
    "avatar_id": 123,
    "image_url": "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
    "name": "My Photo Avatar",
    "status": "processing",
    "motion_preview_url": "",
    "voice_id": "en-US-ChristopherNeural"
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "motion_id": "motion_xyz789",
    "avatar_id": 123,
    "image_url": "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
    "name": "My Photo Avatar",
    "status": "completed",
    "motion_preview_url": "https://files2.jogg.ai/avatar/v3/motion_xyz789/full/2.0/preview_video_target.mp4",
    "voice_id": "en-US-ChristopherNeural"
  }
}
```

<Tip>
  Motion generation adds 2-3 minutes but significantly improves avatar realism and natural movement.
</Tip>

<Info>
  **Motion Generation Charges:**

  * Motion 1.0 deducts 2 credits
  * Motion 2.0 deducts 2 credits
  * Motion 2.0 Pro deducts 3 credits
  * Motion 3.0 deducts 2 credits
</Info>

***

#### Step 5: Create Video with Enhanced Avatar

Create a video using your photo avatar with motion:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 123,
      "avatar_type": 1
    },
    "voice": {
      "type": "script",
      "voice_id": "en-US-ChristopherNeural",
      "script": "Hello! I am your custom photo avatar with enhanced motion."
    },
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "caption": true
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

<Warning>
  **Important:** Always use `avatar_type: 1` for photo avatars (custom avatars). Use `avatar_type: 0` for public avatars.
</Warning>

***

## Advanced Examples

### Scenario 1: List Your Photo Avatars

Get all your photo avatars:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatars/photo_avatars' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "avatars": [
      {
        "id": 123,
        "name": "My Photo Avatar",
        "cover_url": "https://res.jogg.ai/avatars/cover_123.jpg",
        "status": 1,
        "fail_msg": ""
      }
    ]
  }
}
```

<Info>
  Status values: `0` = Processing, `1` = Completed, `2` = Failed. Save the `id` (integer) to use in video creation.
</Info>

***

## Photo Requirements

### Image Specifications

| Requirement      | Specification                            |
| ---------------- | ---------------------------------------- |
| **Format**       | JPG, PNG, WebP                           |
| **File Size**    | Maximum 10MB                             |
| **Resolution**   | Min: 512x512px, Recommended: 1024x1024px |
| **Aspect Ratio** | Square or portrait                       |
| **Face**         | Clear, frontal, well-lit, unobstructed   |

### Photo Quality Guidelines

<AccordionGroup>
  <Accordion title="✅ Good Photos">
    **What works best:**

    * Face directly facing camera (frontal view)
    * Even, soft lighting (no harsh shadows)
    * Clear facial features (high resolution)
    * Neutral or slight smile expression
    * Plain, solid-color background
    * Natural makeup and appearance
    * No glasses (or non-reflective if needed)
    * Hair not covering face
  </Accordion>

  <Accordion title="❌ Avoid These">
    **What doesn't work:**

    * Side profile or angled face
    * Poor lighting or harsh shadows
    * Blurry or low-resolution images
    * Face obstructed (hands, objects, masks)
    * Busy or cluttered backgrounds
    * Sunglasses or reflective glasses
    * Hats or head coverings
    * Extreme expressions (laughing, frowning)
    * Heavy filters or editing
  </Accordion>

  <Accordion title="Lighting Tips">
    **Best lighting setup:**

    * Natural outdoor light (overcast day is ideal)
    * Soft indoor lighting (no overhead harsh lights)
    * Face evenly lit (no one-sided shadows)
    * Avoid backlit photos (light behind subject)
    * Use diffused light when possible
    * Golden hour for outdoor photos
  </Accordion>

  <Accordion title="Background Recommendations">
    **Background best practices:**

    * Plain, solid color works best
    * White, gray, or neutral tones
    * Good contrast with subject
    * No distracting elements
    * Avoid patterns or textures
    * Professional backdrop preferred
  </Accordion>
</AccordionGroup>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="Personal Branding">
    Create your digital spokesperson:

    * **Social Media**: Personalized video messages at scale
    * **Email Marketing**: Custom video intros
    * **Online Courses**: Instructor presence without recording
    * **Thought Leadership**: Consistent personal brand across content
  </Accordion>

  <Accordion title="Company Spokesperson">
    Feature executives or team members:

    * **Announcements**: CEO messages in multiple languages
    * **Product Demos**: Consistent company voice
    * **Training Videos**: Scale expert knowledge
    * **Customer Support**: Personalized video responses
  </Accordion>

  <Accordion title="Multilingual Content">
    One photo, many languages:

    * Create avatar once from photo
    * Generate videos in 40+ languages
    * Maintain same face across all markets
    * No need for multiple recordings
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Photo Preparation:**

  * Use professional headshots or high-quality smartphone photos
  * Studio or natural outdoor lighting works best
  * Sharp focus, no blur
  * No filters or heavy editing
  * Natural skin tones
</Tip>

**Testing Strategy:**

* Test with one photo first
* Generate video with short script
* Verify avatar quality and movements
* Test different voices and languages
* Adjust source photo if needed

**Organization:**

* Use descriptive names for avatars
* Document avatar IDs for easy reference
* Note which photos work best
* Maintain source photo library
* Track motion settings used

**Avatar Type Reference:**

| Type              | Value | Description              | Use Case                 |
| ----------------- | ----- | ------------------------ | ------------------------ |
| **Public Avatar** | `0`   | Pre-made library avatars | Quick, generic content   |
| **Custom Avatar** | `1`   | Photo avatars            | Personal/branded content |

<Check>
  Always use `avatar_type: 1` when creating videos with photo avatars.
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Photo Quality Too Low">
    **Error:** `Photo quality insufficient`

    **Solutions:**

    * Use minimum 512x512px resolution (1024x1024px recommended)
    * Ensure image is sharp, not blurry
    * Use well-lit photo
    * Avoid heavily compressed images
    * Try professional headshot
  </Accordion>

  <Accordion title="Face Not Detected">
    **Error:** `No face detected in photo`

    **Solutions:**

    * Ensure face is clearly visible and frontal
    * Remove obstructions (hands, masks, hair)
    * Face should not be profile or angled
    * Check lighting and contrast
    * Ensure face occupies enough of frame
  </Accordion>

  <Accordion title="Generation Failed">
    **Error:** `Avatar generation failed`

    **Solutions:**

    * Try a different photo
    * Verify photo meets all requirements
    * Ensure photo URL is publicly accessible
    * Check file format is supported (JPG/PNG/WebP)
    * Verify file size is under 10MB
    * Retry the generation
  </Accordion>

  <Accordion title="Avatar Looks Unnatural">
    **Issue:** Generated avatar doesn't look realistic

    **Solutions:**

    * Use higher quality source photo
    * Ensure proper, even lighting
    * Use photo with neutral expression
    * Plain background helps AI focus on face
    * Consider professional headshot
    * Test with different photos
  </Accordion>

  <Accordion title="Motion Not Working">
    **Issue:** Motion generation fails or looks wrong

    **Solutions:**

    * Ensure base avatar generation completed first
    * Check avatar status is "completed" (status = 1)
    * Verify avatar quality is good
    * Try different `motion_type`
    * Re-generate avatar with better photo
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Avatar Videos with Photo Avatar" icon="video" href="/api-reference/v2/API Documentation/AvatarVideosWithPhotoAvatar">
    Using photo avatars in videos
  </Card>

  <Card title="Create Avatar Videos" icon="user" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Main avatar video guide
  </Card>

  <Card title="Upload Media" icon="upload" href="/api-reference/v2/API Documentation/UploadMedia">
    How to upload photos and media
  </Card>

  <Card title="Generate Photo Avatar API" icon="camera" href="/api-reference/v2/Avatar/PhotoAvatarGenerate">
    Complete API reference
  </Card>

  <Card title="Webhook Integration" icon="webhook" href="/api-reference/v2/API%20Documentation/WebhookIntegration">
    Complete webhook setup guide
  </Card>
</CardGroup>