Create Photo Avatar - JoggAI API

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.

Key Features

Personal Branding

Your face, your voice, your brand

Multilingual

One photo avatar speaks 40+ languages

Realistic Motion

Natural facial expressions and movements

Fast Generation

2-5 minutes to create custom avatar

Workflow Overview

Photo avatar creation follows these steps:

Generate Avatar

Upload portrait photo → AI generates avatar (2-5 min)

Check Status

Poll for completion or use webhooks

Use in Videos

Create videos using your custom avatar

Add Motion (Optional)

Enhance avatar with realistic movements (2-3 min)

Optional Step: Add motion for enhanced realism (additional 2-3 minutes). See Step 4: Add Motion to Avatar section below.

Quick Start

Endpoint	Purpose	Documentation
`POST /v2/photo_avatar/photo/generate`	Generate photo avatar	API Reference
`GET /v2/photo_avatar/photo?photo_id={id}`	Check generation status	API Reference
`GET /v2/avatars/photo_avatars`	List your photo avatars	API Reference
`POST /v2/photo_avatar/add_motion`	Add motion to avatar	API Reference
`GET /v2/photo_avatar?motion_id={id}`	Check motion status	API Reference

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

Photo Requirements: Use high-quality portrait photos (min 512x512px, recommended 1024x1024px). Face should be frontal, well-lit, and unobstructed. See Photo Requirements section for details.

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:

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:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123"
  }
}

Save the photo_id to check generation status!

Step 2: Check Generation Status

Check if avatar generation is complete:

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):

{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123",
    "status": "in_progress"
  }
}

Response (Completed):

{
  "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"
    ]
  }
}

Avatar generation typically takes 2-5 minutes. Use [Webhooks](/api-reference/v2/API Documentation/WebhookIntegration) for instant notifications instead of polling.

Image Generation Charges:

Each call generates four images
Each image deducts 0.05 credit
Four images deduct a total of 0.2 credit

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.

Step 3: Create Video with Photo Avatar

Create a video using your photo avatar:

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:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}

Important: Always use avatar_type: 1 for photo avatars (custom avatars). Use avatar_type: 0 for public avatars.

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:

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:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123"
  }
}

Step 2: Check Generation Status

Check if avatar generation is complete:

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):

{
  "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:

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:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "motion_id": "motion_xyz789",
    "status": "processing"
  }
}

Save the motion_id to check motion generation status!

Step 4: Check Motion Status

Check if motion generation is complete:

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

Response (Processing):

{
  "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):

{
  "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"
  }
}

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

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

Step 5: Create Video with Enhanced Avatar

Create a video using your photo avatar with motion:

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:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}

Important: Always use avatar_type: 1 for photo avatars (custom avatars). Use avatar_type: 0 for public avatars.

Advanced Examples

Scenario 1: List Your Photo Avatars

Get all your photo avatars:

curl --request GET \
  --url 'https://api.jogg.ai/v2/avatars/photo_avatars' \
  --header 'x-api-key: YOUR_API_KEY'

Response:

{
  "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": ""
      }
    ]
  }
}

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

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

✅ 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

❌ 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

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

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

Use Case Examples

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

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

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

Tips for Best Results

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

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

Always use avatar_type: 1 when creating videos with photo avatars.

Troubleshooting

Photo Quality Too Low

Error: Photo quality insufficientSolutions:

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

Face Not Detected

Error: No face detected in photoSolutions:

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

Generation Failed

Error: Avatar generation failedSolutions:

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

Avatar Looks Unnatural

Issue: Generated avatar doesn’t look realisticSolutions:

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

Motion Not Working

Issue: Motion generation fails or looks wrongSolutions:

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

Avatar Videos with Photo Avatar

Using photo avatars in videos

Create Avatar Videos

Main avatar video guide

Upload Media

How to upload photos and media

Generate Photo Avatar API

Complete API reference

QuickStart

Workflows Guides

Video

Avatar

Voice

Asset

Template

Product

User

Webhook

​Introduction

​Key Features

Personal Branding

Multilingual

Realistic Motion

Fast Generation

​Workflow Overview

​Quick Start

​Related API Endpoints

​Key Parameters

​Code Examples

​Scenario 1: Basic Photo Avatar Creation

​Step 1: Generate Photo Avatar

​Step 2: Check Generation Status

​Step 3: Create Video with Photo Avatar

​Scenario 2: Photo Avatar with Motion Enhancement

​Step 1: Generate Photo Avatar

​Step 2: Check Generation Status

​Step 3: Add Motion to Avatar

​Step 4: Check Motion Status

​Step 5: Create Video with Enhanced Avatar

​Advanced Examples

​Scenario 1: List Your Photo Avatars

​Photo Requirements

​Image Specifications

​Photo Quality Guidelines

​Use Case Examples

​Tips for Best Results

​Troubleshooting

​Related Documentation

Avatar Videos with Photo Avatar

Create Avatar Videos

Upload Media

Generate Photo Avatar API

Introduction

Key Features

Workflow Overview

Quick Start

Related API Endpoints

Key Parameters

Code Examples

Scenario 1: Basic Photo Avatar Creation

Step 1: Generate Photo Avatar

Step 2: Check Generation Status

Step 3: Create Video with Photo Avatar

Scenario 2: Photo Avatar with Motion Enhancement

Step 1: Generate Photo Avatar

Step 2: Check Generation Status

Step 3: Add Motion to Avatar

Step 4: Check Motion Status

Step 5: Create Video with Enhanced Avatar

Advanced Examples

Scenario 1: List Your Photo Avatars

Photo Requirements

Image Specifications

Photo Quality Guidelines

Use Case Examples

Tips for Best Results

Troubleshooting

Related Documentation