Introduction
Avatar Studio adds a human-presenter layer to your creatives using the HeyGen API:- AI Spokesperson — a stock avatar and voice reads your ad script.
- Talking Product Photo — a single photo becomes a talking presenter, optionally in the user’s own uploaded voice.
- Ad Localizer — translate any video into 175+ languages while preserving the speaker’s face and voice and re-syncing the lips.
Included Tools
- Dashboard — recent creations and quick links into the tools
- AI Spokesperson — pick a stock avatar and voice, write a script, choose orientation/background, and render a presenter video
- Talking Product Photo — turn an uploaded photo into a talking presenter, driven by a stock voice or the user’s own audio
- Ad Localizer — translate a video into one or more languages, keeping the speaker’s face and voice with re-synced lips (billed per language)
- My Videos — gallery of completed creations: favorite, download and manage
What powers it
| Capability | HeyGen feature |
|---|---|
| Spokesperson & Talking Photo video | /v2/video/generate (Avatar IV) |
| Bring-your-own-voice | uploaded audio asset drives the lips directly |
| Localization | /v2/video_translate (Video Translate) |
| Avatar & voice pickers | /v3/avatars/looks and /v3/voices catalogs (synced locally) |
Avatar Studio relies on the HeyGen API, a paid third-party service with its own credit/subscription model. You’ll need a HeyGen account and an API plan that includes the avatar and video-translate features. HeyGen costs are separate from your MagicAds platform credits.
Purchase & Installation
Avatar Studio is distributed through the in-app plugin marketplace — purchasing and installation both happen inside your MagicAds admin.Open the Plugins marketplace
Sign in as an admin and go to Admin → General Settings → Plugins. Find the Avatar Studio card in the marketplace catalog.
Purchase (if required)
The card CTA depends on your license and purchase state:
- Free / already owned → installs directly.
- Paid → routes you to the plugin checkout to complete the purchase.
- Extended License holders → plugins flagged “free for Extended License” install without an extra purchase.
Install / activate
Click Install on the Avatar Studio card. The platform downloads the archive, unpacks it and runs its setup automatically — preparing the storage it needs for your generated videos, saved bring-your-own voices, and the synced avatar and stock-voice catalog.It also adds Avatar Studio’s settings (feature off, free tier off, speed translate mode, 50 MB upload cap) and a per-plan Avatar Studio access toggle.
Configure the HeyGen API key
The HeyGen key is entered on the Avatar Studio settings page itself (Admin → General Settings → Plugins → Avatar Studio) — this is the only place it lives. It powers every generation; users never supply their own key.
Create a HeyGen key
Create an API key in your HeyGen dashboard (Settings → API).
Paste it into Avatar Studio
On the Avatar Studio settings page, paste it into the HeyGen API key field.
Sync the avatar & voice catalog
The Spokesperson and Talking Photo pickers read avatars and voices from a local database copy, so they load instantly without a live API call. You populate that copy with an explicit sync.- With a valid key entered, click Test / Sync (or the sync action) on the settings page.
- The plugin contacts HeyGen and stores:
- stock voices (fast endpoint, synced first),
- avatar looks (the heavier endpoint).
- Voices sync first, so if the key is invalid you’ll get a clear error immediately.
- HeyGen’s avatar catalog can be slow; if avatars don’t come back on the first try, the voices are still synced and you can click Sync again to retry just the avatars.
- The catalog is cached for an hour, and the cron processor warms it automatically if it’s empty after install.
- Saving a new key clears the cached catalogs so the new key takes effect at once.
Enable the cron scheduler (required)
Avatar Studio renders are processed outside the web request by a cron-driven command that advances every in-flight video one step at a time (submit → poll → download → finalize). This is what keeps it reliable on shared hosting. The command is:Configure Avatar Studio
On the Avatar Studio settings page you’ll find four sections.General
| Setting | Purpose |
|---|---|
| Enable Avatar Studio | Master switch. When on, the studio appears in user menus and becomes usable. Off by default. |
| Free Tier Access | When on, users without a paid plan can use Avatar Studio. When off, only users on a plan that includes the feature get access. |
Translation fidelity
| Setting | Purpose |
|---|---|
| Translate mode | speed (faster) or precision (higher fidelity). Applies to the Ad Localizer. |
Billing — credit matrix
Avatar Studio has a single engine (HeyGen), so the grid is one column wide. Values are integers 1–9999, charged only after a successful render.| Feature | Default credits |
|---|---|
| AI Spokesperson | 20 |
| Talking Product Photo | 25 |
| Ad Localizer (per language) | 15 |
- Users are only charged on a successful generation — failed or timed-out jobs cost nothing.
- Credits are deducted atomically, so concurrent generations can’t overdraw a balance.
- The Ad Localizer cost is multiplied by the number of target languages. Translating into 3 languages at 15 credits each costs 45 credits.
Limits
| Setting | Purpose |
|---|---|
| Max upload size (MB) | Per-file cap for photos, audio and video. Integer 1–500, default 50. |
Grant access by plan
Access is gated in two layers:- Platform layer — the master Enable Avatar Studio switch must be on.
- User layer — who actually gets the tools:
- Subscribed users (on a plan): access is governed by the plan’s Avatar Studio feature toggle.
- Non-subscribed users (no plan): access only when both Enable Avatar Studio and Free Tier Access are on.
When the tools are offered platform-wide but the current user’s plan doesn’t include them, they appear as a locked, upgrade-to-unlock entry that nudges the user toward an eligible plan.
- Enable the master switch in the Avatar Studio config.
- Go to Admin → plan management, edit each plan, and turn the Avatar Studio feature on for the plans that should include it.
- Optionally enable Free Tier Access if you want plan-less users to try it.
Go-live checklist
Test & sync the catalog
Click Test / Sync to validate the key and pull avatars + voices. Confirm the synced counts.
Enable the cron scheduler
Make sure
php artisan schedule:run runs every minute via a server cron entry.Once every step above is green, Avatar Studio is live. Proceed to the section below on how to use it.
How to Use
Open Creative Tools → Avatar Studio in the user sidebar.AI Spokesperson
- Pick a stock avatar from the synced catalog.
- Pick a voice (each has a preview).
- Write a script (up to 1500 characters) — or start from one of the script suggestion chips.
- Choose orientation (portrait/landscape/square) and a background (studio white, brand indigo, slate dark, warm amber, soft indigo).
- Generate. The video is queued and finalized by the cron processor, then appears in My Videos.
Talking Product Photo
- Upload a photo (a person or product shot; up to 10 MB). HeyGen turns it into a talking-photo character.
- Choose the voice source:
- Text — pick a stock voice that reads your script.
- Own voice — upload an audio file (up to 25 MB) that drives the lips directly.
- Pick orientation and background, then generate.
Ad Localizer
- Provide the source video (up to 200 MB).
- Pick up to 5 target languages from the quick list (HeyGen supports 175+; the live list is fetched and cached).
- Generate. The speaker’s face and voice are preserved and lips re-synced per language. You’re billed the localizer cost × the number of languages.
My Videos
Browse your completed creations, mark favorites, and download the MP4s.Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Avatar Studio doesn’t appear for a user | Master switch off, plan lacks the feature, or free tier off for a plan-less user | Enable the master switch; enable the feature on their plan; or turn on Free Tier Access. |
| Videos stay stuck on “pending” | The Laravel scheduler isn’t running | Add the * * * * * php artisan schedule:run cron entry on your server. |
| Avatar/voice pickers are empty | Catalog never synced | Click Test / Sync on the settings page after adding the key. |
| Avatars didn’t sync (voices did) | HeyGen’s avatar catalog is slow | Click Sync again to retry just the avatars; voices already work. |
| ”HeyGen rejected this API key” | Invalid key | Re-check the key in your HeyGen dashboard and re-enter it. |
| ”Could not reach HeyGen (timed out)“ | Server can’t make outbound HTTPS | Ensure the server allows outbound HTTPS to api.heygen.com. |
| ”Not enough credits” | Balance below the feature cost (× languages for localizer) | Top up credits or lower the cost in the billing matrix. |
| Localizer costs more than expected | Cost is per language | It’s the localizer cost × number of selected languages — this is expected. |
| Uploads rejected | File exceeds the cap | Raise Max upload size (MB) (max 500), within the 10 MB photo / 25 MB audio / 200 MB video hard limits. |
Generated videos are stored on the platform’s public results disk. Credits are never deducted for failed or timed-out renders.