{"id":"d3561a59-87e6-4957-ad6a-a09f97d41f0d","shortId":"xRBabq","kind":"skill","title":"lipnardo","tagline":"Generate AI avatar talking-head videos using HeyGen API. Single videos, multi-scene studio compositions, batch personalization from CSV/JSON, template variable injection, photo-to-avatar pipeline, video translation with lip-sync, Starfish TTS, credit estimation, and asset managem","description":"# Lipnardo -- HeyGen Avatar Video Production Director\n\n## Core Principle\n\nAct as a **Video Production Director** that orchestrates HeyGen's avatar video API.\nAnalyze the user's intent, select the right generation mode, estimate costs before\ngenerating, and manage the full video lifecycle from creation through download.\n\n## Mandatory Pre-reads\n\nBefore ANY video generation, you MUST read these references:\n1. `references/heygen-api-reference.md` -- endpoint details and request/response schemas\n2. `references/credit-costs.md` -- pricing table and cost estimation formulas\n\n## Quick Reference\n\n| Command | What it does |\n|---------|-------------|\n| `/lipnardo` | Interactive -- detect intent, select mode, generate |\n| `/lipnardo generate <prompt>` | Generate video with AI Video Agent (v3) |\n| `/lipnardo studio <config.json>` | Multi-scene video with Studio API (v2) |\n| `/lipnardo batch <file.csv>` | Batch generate from CSV/JSON data |\n| `/lipnardo template list` | List available HeyGen templates |\n| `/lipnardo template inspect <id>` | Show template scenes and variables |\n| `/lipnardo template generate <id>` | Generate from template with variable injection |\n| `/lipnardo translate <video_id> <lang>` | Translate video with lip-sync |\n| `/lipnardo tts <text>` | Generate TTS audio via Starfish engine |\n| `/lipnardo avatar create <photo>` | Create avatar from photo (full pipeline) |\n| `/lipnardo avatar list` | List available avatars |\n| `/lipnardo avatar voices` | List available voices |\n| `/lipnardo assets upload <file>` | Upload asset to HeyGen |\n| `/lipnardo assets list` | List uploaded assets |\n| `/lipnardo credits` | Check API balance |\n| `/lipnardo credits estimate` | Estimate cost before generation |\n| `/lipnardo download <video_id>` | Download video before URL expires |\n| `/lipnardo setup` | Validate API key and configuration |\n| `/lipnardo webhook register <url>` | Register webhook endpoint |\n\n## Setup and Authentication\n\nFirst-time users must validate their setup:\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/validate_setup.py\n```\n\nAPI key resolution order (highest priority first):\n1. `--api-key` flag on any script (explicit override)\n2. `HEYGEN_API_KEY` environment variable (recommended)\n3. `~/.heygen/config.json` file with `{\"api_key\": \"your-key\"}`\n\nGet your key from: https://app.heygen.com/settings/api\n\n## Generation Pipeline\n\nFollow this pipeline for every video generation:\n\n### Step 1: Analyze Intent\n\nDetermine what the user needs:\n- **Simple prompt** → Video Agent mode (AI selects avatar, writes script)\n- **Specific avatar/scenes** → Studio mode (precise multi-scene control)\n- **Mass personalization** → Template or Batch mode\n- **Existing video** → Translation or download\n\nIf the request is vague, ask about: use case, avatar preference, duration, aspect ratio.\n\n### Step 2: Estimate Cost\n\nALWAYS estimate before generating:\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/credit_check.py estimate --feature video_agent --duration 60\n```\n\nShow the user the estimated cost and confirm before proceeding.\n\n### Step 3: Generate\n\n**Video Agent mode** (AI-driven, simple prompt):\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/generate_video.py --mode agent \\\n  --prompt \"A professional woman explaining quarterly results\" \\\n  --aspect-ratio 16:9\n```\n\n**Studio mode** (multi-scene, precise control):\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/generate_video.py --mode studio \\\n  --config /path/to/scenes.json\n```\n\nStudio scene config format:\n```json\n{\n  \"video_inputs\": [\n    {\n      \"character\": {\"type\": \"avatar\", \"avatar_id\": \"...\", \"avatar_style\": \"normal\"},\n      \"voice\": {\"type\": \"text\", \"input_text\": \"Script here\", \"voice_id\": \"...\"},\n      \"background\": {\"type\": \"color\", \"value\": \"#ffffff\"}\n    }\n  ]\n}\n```\n\n### Step 4: Poll and Download\n\nScripts handle polling automatically with exponential backoff (10s → 60s, 30-minute ceiling).\nVideos download to `~/Documents/lipnardo_videos/` by default.\n\n### Step 5: Log Cost\n\nAfter successful generation, log the cost:\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/credit_check.py log \\\n  --feature video_agent --duration DURATION --video-id VIDEO_ID --prompt \"summary\"\n```\n\n### Step 6: Report to User\n\nShow: file path, duration, file size, estimated cost, and video_id (for later translation/download).\n\n## Batch Pipeline\n\nFor generating multiple personalized videos from CSV or JSON:\n\n1. **Estimate total cost first:**\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/credit_check.py estimate-batch \\\n  --input data.csv --feature avatar3 --avg-duration 60\n```\n\n2. **Confirm with user** before proceeding.\n\n3. **Run batch:**\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/batch_generate.py --input data.csv --mode agent\n```\n\n4. **Monitor progress** -- the script outputs JSON progress to stderr.\n\n5. **Resume interrupted batches:**\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/batch_generate.py --resume manifest.json\n```\n\nCSV format for agent mode: columns `prompt` (required), `avatar_id`, `voice_id`, `name` (optional).\nCSV format for template mode: columns match template variable names.\n\n## Template Pipeline\n\nFor template-based mass personalization:\n\n1. **List templates:** `template_video.py list`\n2. **Inspect variables:** `template_video.py inspect --template-id ID`\n3. **Generate with variables:**\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/template_video.py generate \\\n  --template-id ID --variables '{\"name\":\"John\",\"company\":\"Acme\"}'\n```\n4. **Batch from CSV:**\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/template_video.py generate \\\n  --template-id ID --input prospects.csv\n```\n\n## Photo Avatar Pipeline\n\nFull pipeline from photo to talking-head video:\n\n1. **Create avatar from photo:**\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/photo_avatar.py create \\\n  --photo /path/to/headshot.jpg --name \"My Avatar\"\n```\n2. Training takes minutes to hours -- script waits automatically.\n3. **Generate video with trained avatar:**\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/photo_avatar.py generate \\\n  --avatar-id AVATAR_ID --script \"Hello, welcome to our company!\"\n```\n\nPhoto requirements: front-facing, 512x512 min, even lighting, mouth closed.\nPhoto Avatar IV costs $0.05/sec with a 3-minute max. Read `references/avatar-types.md`.\n\n## Translation Pipeline\n\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/translate_video.py \\\n  --video-id VIDEO_ID --target-lang es --mode fast\n```\n\n- **Fast/speed mode**: speed-optimized via v3 API, $0.0333/sec\n- **Quality/precision mode**: precision lip-sync via v3 API, $0.0667/sec\n- 175+ languages supported\n\n## TTS Pipeline\n\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/tts.py synthesize \\\n  --text \"Hello world\" --voice-id en-US-JennyNeural\npython3 ${CLAUDE_SKILL_DIR}/scripts/tts.py list-voices --language en\n```\n\n## Asset Management\n\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/asset_manager.py upload --file image.png\npython3 ${CLAUDE_SKILL_DIR}/scripts/asset_manager.py list --type image\n```\n\n## Error Handling\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| 401 Unauthorized | Invalid API key | Run `/lipnardo setup`, re-check key |\n| 429 Rate Limited | Too many requests | Script auto-retries with backoff |\n| Concurrent limit | 3 videos already processing | Wait for completion |\n| Generation failed | Content policy or avatar issue | Try different avatar/script |\n| URL expired | Download URL > 7 days old | Re-download via `/lipnardo download` |\n| Insufficient credits | API balance depleted | Top up at app.heygen.com |\n\nRead `references/error-codes.md` for full error taxonomy and retry strategies.\n\n## Cost Tracking\n\nALWAYS estimate cost before generating. ALWAYS log cost after successful generation.\n\n```bash\npython3 ${CLAUDE_SKILL_DIR}/scripts/credit_check.py balance\npython3 ${CLAUDE_SKILL_DIR}/scripts/credit_check.py estimate --feature avatar3 --duration 60\npython3 ${CLAUDE_SKILL_DIR}/scripts/credit_check.py summary\n```\n\nRead `references/credit-costs.md` for full pricing table.\n\n## Response Format\n\nAfter every successful generation, report to the user:\n- **Path**: where the video file was saved\n- **Duration**: video length in seconds\n- **Size**: file size\n- **Cost**: estimated cost based on feature type and duration\n- **Video ID**: for later translation, download, or reference\n\n## API Constraints\n\n- **3 concurrent videos** max (batch script respects this automatically)\n- **30 minutes** max per video (Enterprise for longer)\n- **1080p** default resolution (4K Enterprise only)\n- **Photo Avatar IV**: 3 minutes max duration\n- **Download URLs**: expire after 7 days -- download promptly\n- **50 scenes** max per Studio API request","tags":["lipnardo","agricidaniel","agent-skills","ai-video","anthropic","avatar-video","claude-code","claude-skill","heygen","python","talking-head","video-generation"],"capabilities":["skill","source-agricidaniel","skill-lipnardo","topic-agent-skills","topic-ai-video","topic-anthropic","topic-avatar-video","topic-claude-code","topic-claude-skill","topic-heygen","topic-python","topic-talking-head","topic-video-generation"],"categories":["lipnardo"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/AgriciDaniel/lipnardo/lipnardo","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add AgriciDaniel/lipnardo","source_repo":"https://github.com/AgriciDaniel/lipnardo","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 9 github stars · SKILL.md body (8,589 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:08:45.505Z","embedding":null,"createdAt":"2026-05-18T13:14:25.287Z","updatedAt":"2026-05-18T19:08:45.505Z","lastSeenAt":"2026-05-18T19:08:45.505Z","tsv":"'/.heygen/config.json':304 '/documents/lipnardo_videos':508 '/lipnardo':123,130,139,149,156,163,171,180,188,196,205,211,217,224,230,235,242,249,256,904,952 '/path/to/headshot.jpg':741 '/path/to/scenes.json':458 '/scripts/asset_manager.py':881,889 '/scripts/batch_generate.py':606,630 '/scripts/credit_check.py':394,526,580,990,996,1006 '/scripts/generate_video.py':427,454 '/scripts/photo_avatar.py':738,765 '/scripts/template_video.py':688,708 '/scripts/translate_video.py':809 '/scripts/tts.py':852,868 '/scripts/validate_setup.py':278 '/sec':794,830,841 '/settings/api':318 '0.0333':829 '0.05':793 '0.0667':840 '1':102,286,329,570,665,728 '1080p':1075 '10s':500 '16':440 '175':842 '2':109,296,382,592,670,745 '3':303,412,598,679,754,797,924,1058,1084 '30':502,1067 '4':489,611,699 '401':898 '429':910 '4k':1078 '5':512,621 '50':1096 '512x512':783 '6':541 '60':400,591,1001 '60s':501 '7':945,1092 '9':441 'acm':698 'act':52 'action':897 'agent':137,340,398,415,429,530,610,636 'ai':3,135,342,418 'ai-driven':417 'alreadi':926 'alway':385,974,979 'analyz':65,330 'api':11,64,147,233,252,279,288,298,307,828,839,901,956,1056,1101 'api-key':287 'app.heygen.com':317,962 'app.heygen.com/settings/api':316 'ask':372 'aspect':379,438 'aspect-ratio':437 'asset':42,218,221,225,229,874 'audio':192 'authent':264 'auto':918 'auto-retri':917 'automat':496,753,1066 'avail':160,209,215 'avatar':4,29,46,62,197,200,206,210,212,344,376,468,469,471,641,717,730,744,759,768,770,790,936,1082 'avatar-id':767 'avatar/scenes':348 'avatar/script':940 'avatar3':587,999 'avg':589 'avg-dur':588 'background':483 'backoff':499,921 'balanc':234,957,991 'base':662,1042 'bash':273,389,422,449,521,575,601,625,683,703,733,760,804,847,876,985 'batch':19,150,151,360,559,583,600,624,700,1062 'case':375 'caus':896 'ceil':504 'charact':466 'check':232,908 'claud':275,391,424,451,523,577,603,627,685,705,735,762,806,849,865,878,886,987,993,1003 'close':788 'color':485 'column':638,652 'command':119 'compani':697,777 'complet':930 'composit':18 'concurr':922,1059 'config':457,461 'configur':255 'confirm':408,593 'constraint':1057 'content':933 'control':355,448 'core':50 'cost':76,114,239,384,406,514,520,552,573,792,972,976,981,1039,1041 'creat':198,199,729,739 'creation':86 'credit':39,231,236,955 'csv':567,633,647,702 'csv/json':22,154 'data':155 'data.csv':585,608 'day':946,1093 'default':510,1076 'deplet':958 'detail':105 'detect':125 'determin':332 'differ':939 'dir':277,393,426,453,525,579,605,629,687,707,737,764,808,851,867,880,888,989,995,1005 'director':49,57 'download':88,243,244,366,492,506,943,950,953,1053,1088,1094 'driven':419 'durat':378,399,531,532,548,590,1000,1031,1047,1087 'en':861,873 'en-us-jennyneur':860 'endpoint':104,261 'engin':195 'enterpris':1072,1079 'environ':300 'error':893,895,967 'es':818 'estim':40,75,115,237,238,383,386,395,405,551,571,582,975,997,1040 'estimate-batch':581 'even':785 'everi':325,1017 'exist':362 'expir':248,942,1090 'explain':434 'explicit':294 'exponenti':498 'face':782 'fail':932 'fast':820 'fast/speed':821 'featur':396,528,586,998,1044 'ffffff':487 'file':305,546,549,883,1028,1037 'first':266,285,574 'first-tim':265 'flag':290 'follow':321 'format':462,634,648,1015 'formula':116 'front':781 'front-fac':780 'full':82,203,719,966,1011 'generat':2,73,78,96,129,131,132,152,173,174,190,241,319,327,388,413,517,562,680,689,709,755,766,931,978,984,1019 'get':312 'handl':494,894 'head':7,726 'hello':773,855 'heygen':10,45,60,161,223,297 'highest':283 'hour':750 'id':470,482,535,537,555,642,644,677,678,692,693,712,713,769,771,812,814,859,1049 'imag':892 'image.png':884 'inject':25,179 'input':465,477,584,607,714 'inspect':165,671,674 'insuffici':954 'intent':69,126,331 'interact':124 'interrupt':623 'invalid':900 'issu':937 'iv':791,1083 'jennyneur':863 'john':696 'json':463,569,617 'key':253,280,289,299,308,311,314,902,909 'lang':817 'languag':843,872 'later':557,1051 'length':1033 'lifecycl':84 'light':786 'limit':912,923 'lip':35,186,835 'lip-sync':34,185,834 'lipnardo':1,44 'list':158,159,207,208,214,226,227,666,669,870,890 'list-voic':869 'log':513,518,527,980 'longer':1074 'manag':80,875 'managem':43 'mandatori':89 'mani':914 'manifest.json':632 'mass':356,663 'match':653 'max':799,1061,1069,1086,1098 'min':784 'minut':503,748,798,1068,1085 'mode':74,128,341,350,361,416,428,443,455,609,637,651,819,822,832 'monitor':612 'mouth':787 'multi':15,142,353,445 'multi-scen':14,141,352,444 'multipl':563 'must':98,269 'name':645,656,695,742 'need':336 'normal':473 'old':947 'optim':825 'option':646 'orchestr':59 'order':282 'output':616 'overrid':295 'path':547,1024 'per':1070,1099 'person':20,357,564,664 'photo':27,202,716,722,732,740,778,789,1081 'photo-to-avatar':26 'pipelin':30,204,320,323,560,658,718,720,803,846 'polici':934 'poll':490,495 'pre':91 'pre-read':90 'precis':351,447,833 'prefer':377 'price':111,1012 'principl':51 'prioriti':284 'proceed':410,597 'process':927 'product':48,56 'profession':432 'progress':613,618 'prompt':338,421,430,538,639,1095 'prospects.csv':715 'python3':274,390,423,450,522,576,602,626,684,704,734,761,805,848,864,877,885,986,992,1002 'quality/precision':831 'quarter':435 'quick':117 'rate':911 'ratio':380,439 're':907,949 're-check':906 're-download':948 'read':92,99,800,963,1008 'recommend':302 'refer':101,118,1055 'references/avatar-types.md':801 'references/credit-costs.md':110,1009 'references/error-codes.md':964 'references/heygen-api-reference.md':103 'regist':258,259 'report':542,1020 'request':369,915,1102 'request/response':107 'requir':640,779 'resolut':281,1077 'respect':1064 'respons':1014 'result':436 'resum':622,631 'retri':919,970 'right':72 'run':599,903 'save':1030 'scene':16,143,168,354,446,460,1097 'schema':108 'script':293,346,479,493,615,751,772,916,1063 'second':1035 'select':70,127,343 'setup':250,262,272,905 'show':166,401,545 'simpl':337,420 'singl':12 'size':550,1036,1038 'skill':276,392,425,452,524,578,604,628,686,706,736,763,807,850,866,879,887,988,994,1004 'skill-lipnardo' 'source-agricidaniel' 'specif':347 'speed':824 'speed-optim':823 'starfish':37,194 'stderr':620 'step':328,381,411,488,511,540 'strategi':971 'studio':17,140,146,349,442,456,459,1100 'style':472 'success':516,983,1018 'summari':539,1007 'support':844 'sync':36,187,836 'synthes':853 'tabl':112,1013 'take':747 'talk':6,725 'talking-head':5,724 'target':816 'target-lang':815 'taxonomi':968 'templat':23,157,162,164,167,172,176,358,650,654,657,661,667,676,691,711 'template-bas':660 'template-id':675,690,710 'template_video.py':668,673 'text':476,478,854 'time':267 'top':959 'topic-agent-skills' 'topic-ai-video' 'topic-anthropic' 'topic-avatar-video' 'topic-claude-code' 'topic-claude-skill' 'topic-heygen' 'topic-python' 'topic-talking-head' 'topic-video-generation' 'total':572 'track':973 'train':746,758 'translat':32,181,182,364,802,1052 'translation/download':558 'tri':938 'tts':38,189,191,845 'type':467,475,484,891,1045 'unauthor':899 'upload':219,220,228,882 'url':247,941,944,1089 'us':862 'use':9,374 'user':67,268,335,403,544,595,1023 'v2':148 'v3':138,827,838 'vagu':371 'valid':251,270 'valu':486 'variabl':24,170,178,301,655,672,682,694 'via':193,826,837,951 'video':8,13,31,47,55,63,83,95,133,136,144,183,245,326,339,363,397,414,464,505,529,534,536,554,565,727,756,811,813,925,1027,1032,1048,1060,1071 'video-id':533,810 'voic':213,216,474,481,643,858,871 'voice-id':857 'wait':752,928 'webhook':257,260 'welcom':774 'woman':433 'world':856 'write':345 'your-key':309","prices":[{"id":"55a49406-98a3-4625-af06-e65ca15ed934","listingId":"d3561a59-87e6-4957-ad6a-a09f97d41f0d","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"AgriciDaniel","category":"lipnardo","install_from":"skills.sh"},"createdAt":"2026-05-18T13:14:25.287Z"}],"sources":[{"listingId":"d3561a59-87e6-4957-ad6a-a09f97d41f0d","source":"github","sourceId":"AgriciDaniel/lipnardo/lipnardo","sourceUrl":"https://github.com/AgriciDaniel/lipnardo/tree/main/skills/lipnardo","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:25.287Z","lastSeenAt":"2026-05-18T19:08:45.505Z"}],"details":{"listingId":"d3561a59-87e6-4957-ad6a-a09f97d41f0d","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"AgriciDaniel","slug":"lipnardo","github":{"repo":"AgriciDaniel/lipnardo","stars":9,"topics":["agent-skills","ai-video","anthropic","avatar-video","claude-code","claude-skill","heygen","python","talking-head","video-generation"],"license":"other","html_url":"https://github.com/AgriciDaniel/lipnardo","pushed_at":"2026-04-18T10:53:05Z","description":"HeyGen avatar video generation skill for Claude Code. Batch, templates, translation, photo avatars, TTS. Stdlib-only Python.","skill_md_sha":"75f3ff1ce0ae76c8d3180e95b6ae1a8b3a755a40","skill_md_path":"skills/lipnardo/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/AgriciDaniel/lipnardo/tree/main/skills/lipnardo"},"layout":"multi","source":"github","category":"lipnardo","frontmatter":{"name":"lipnardo","description":"Generate AI avatar talking-head videos using HeyGen API. Single videos, multi-scene studio compositions, batch personalization from CSV/JSON, template variable injection, photo-to-avatar pipeline, video translation with lip-sync, Starfish TTS, credit estimation, and asset management. Use when user says \"avatar video\", \"talking head\", \"HeyGen\", \"lip sync\", \"video translate\", \"batch video\", \"photo avatar\", \"TTS\", \"text to speech\", \"personalized video\", \"video agent\", or \"lipnardo\"."},"skills_sh_url":"https://skills.sh/AgriciDaniel/lipnardo/lipnardo"},"updatedAt":"2026-05-18T19:08:45.505Z"}}