@docyrus/animaguru 0.11.0 → 0.13.0

package/README.md

@@ -222,6 +222,49 @@ animaguru assets submit PROJECT_ID --file speech.json --model gemini-3.8-flash-t
 
 `--model` overrides the file's model. Unrelated type-specific flags are rejected rather than ignored. Individual downloads and complete ZIP exports refuse to overwrite existing files. Generated files are saved in the project's `assets/<id>/` directory and are shared with the web Assets workspace.
 
+## HeyGen avatars
+
+CLI 0.13.0 adds `avatars` for HeyGen's avatar API. A group is a character; its looks are outfits, poses or styles, and a look ID is what HeyGen renders with. Any project can browse HeyGen's public catalog. An avatar you create belongs to the project that created it: only that project lists, changes or deletes it.
+
+```sh
+animaguru avatars list PROJECT_ID --limit 10
+animaguru avatars looks PROJECT_ID --avatar-type studio_avatar
+animaguru avatars list PROJECT_ID --ownership private
+
+# A synthetic character from a description.
+animaguru avatars create PROJECT_ID --type prompt --name "Ada" \
+  --prompt "Woman in her early 30s, warm smile, navy blazer, bright studio, soft key light" \
+  --aspect-ratio 16:9 --dry-run
+# A new outfit or setting for one of the project's avatars.
+animaguru avatars create PROJECT_ID --type prompt --name "Ada, keynote" \
+  --look LOOK_ID --prompt "On a conference stage under a spotlight" --yes
+# A photo avatar from a saved image, an HTTPS URL or a local file.
+animaguru avatars create PROJECT_ID --type photo --name "Sam" \
+  --file portrait.jpg --subject-consent --yes
+animaguru avatars wait PROJECT_ID LOOK_ID
+```
+
+`create` and `add-looks` return the new look IDs. Looks start `processing`; `avatars wait` polls until HeyGen finishes (`completed`) or fails. `--file` and `--reference-images` take a project image's SHA (from `assets list`, or a character's `art`), an HTTPS URL HeyGen downloads (up to 32 MB), or a local file sent inline (up to 8 MB). Photos and footage show a real person: pass `--subject-consent` only when that person agreed to become an avatar.
+
+A digital twin trains on footage of a real person (about two minutes of natural talking: a project video SHA, a URL or a local file) and clones their voice. It renders only after that person records consent on camera:
+
+```sh
+animaguru avatars create PROJECT_ID --type digital_twin --name "Sam" \
+  --file https://example.com/sam-footage.mp4 --subject-consent --yes
+animaguru avatars consent PROJECT_ID GROUP_ID      # a 24-hour link for that person
+animaguru avatars get PROJECT_ID --group GROUP_ID  # consentStatus: pending, accepted or rejected
+```
+
+Look Packs dress one of the project's looks in a themed set of five looks; a single template makes two. `avatars templates` lists their IDs, each in a female and a male variant:
+
+```sh
+animaguru avatars templates
+animaguru avatars add-looks PROJECT_ID --look LOOK_ID \
+  --template 5a8e6be843ee4321a014946bf62aa322 --aspect-ratio 9:16 --yes
+```
+
+Credits are charged once HeyGen accepts a request: 132 for a photo or prompt avatar, 213 for a digital twin, and 132 for each generated look (a Look Pack makes five). `--dry-run` validates and estimates offline; the server checks files, avatar ownership and credits before calling HeyGen. Paid requests carry a retry key, so a retried request is not charged twice. `avatars rename PROJECT_ID LOOK_ID --name NAME` and `avatars voice PROJECT_ID GROUP_ID --voice VOICE_ID` change the project's own avatars. `avatars delete PROJECT_ID --group GROUP_ID --yes` (or `--look LOOK_ID`) deletes for good; deleting an avatar's last look deletes the avatar. The server needs `AI_PROVIDER_KEY_HEYGEN`.
+
 ## Typed job files
 
 Use `animaguru jobs submit PROJECT_ID --file job.json --yes`. The server and CLI validate the same schema. Available job bodies: