Skip to main content

​
🚀 Introduction

With Custom Avatar, you can upload your own consent and lipsync videos to create a personalized speaking avatar within the Creatify platform. This feature is designed for users who want to go beyond default personas and introduce custom characters for more control and brand alignment.

​
🧾 Step 1: Submit a Custom Avatar Request

​
➡️ Option A – Upload Files Directly

Use the POST /api/personas_v2/ endpoint to upload your custom avatar assets as files.
This must be a multipart/form-data request.

​
✅ Required Fields

  • lipsync_input – MP4 file used for lipsync training (e.g., a person speaking plain text)
  • creator_name – Name for the avatar (e.g., “James”)
  • gender – Gender identifier (e.g., “m”, “f”)
  • video_scene – Context or background category (e.g., “office”)

​
📤 Example Curl Request

🎬 Ensure both video files are valid formats: video/mp4 or video/quicktime

​
➡️ Option B – Provide File URLs

Use the POST /api/personas/ endpoint to submit URLs to your consent and lipsync videos instead of uploading files.

​
✅ Required Fields

  • lipsync_input – Publicly accessible URL to the lipsync MP4 file
  • creator_name – Name for the avatar (e.g., “James”)
  • gender – Gender identifier (e.g., “m”, “f”)
  • video_scene – Context or background category (e.g., “office”)

​
📤 Example Curl Request

🌐 The URLs must be publicly accessible so Creatify can retrieve the video files.

​
Endpoint Summary

​
🔍 Step 2: Check Custom Avatar Status

After submission, use GET /api/personas/{id}/ to check the approval status of your avatar.

​
Example Request

​
What to Look For

process_status tells you where the avatar is:
⏱️ Reviews are typically completed within 24 hours

​
Get Notified Instead of Polling

Pass webhook_url when you create the avatar. When the avatar is ready, rejected or failed, we send a POST to that URL:
status is done, rejected or failed. For rejected and failed, failed_reason explains why.

​
💳 Cost and Rejections

  • Each custom avatar takes one avatar slot from your plan. Creating one does not use credits.
  • If the workspace has no free slot left, the create request returns an error right away.
  • Videos shorter than 15 seconds, longer than 300 seconds, or below 1280x720 are refused right away, when you submit, and no slot is taken.
  • If an avatar ends up rejected or failed, its slot is freed automatically. You can submit a new video straight away; nothing needs to be refunded.
💡 If you charge your own users for avatar creation, treat only ready to use (or a done webhook) as delivered. On rejected, show your user the failed_reason and let them upload a new video.

​
📌 Notes

  • You can retrieve your avatars using GET /api/personas_v2/
  • Your approved Custom Avatar avatar can then be used in any compatible API such as AI Avatar, AI Avatar V2, or Create Video from URL

​
🤝 Need Help?

If you have any issues or need assistance, please contact api@creatify.ai