@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/lipnardo/examples/single-video.md

@@ -1,44 +0,0 @@
-# Single Video Generation Example
-
-## User Request
-> "Create a talking head video of a professional woman explaining our Q3 results"
-
-## Claude (using Lipnardo)
-
-### 1. Read references
-Reads `references/credit-costs.md` and `references/heygen-api-reference.md`.
-
-### 2. Estimate cost
-```bash
-python3 ${CLAUDE_SKILL_DIR}/scripts/credit_check.py estimate --feature video_agent --duration 60
-# Output: {"estimated_cost": 2.00, "feature": "video_agent", "duration": 60}
-```
-
-> "This will cost approximately **$2.00** for a ~60 second video. Shall I proceed?"
-
-### 3. Generate
-```bash
-python3 ${CLAUDE_SKILL_DIR}/scripts/generate_video.py --mode agent \
-  --prompt "A professional woman in business attire explaining quarterly financial results. She stands in front of a modern office background, speaking clearly and confidently about revenue growth and strategic initiatives." \
-  --aspect-ratio 16:9
-```
-
-### 4. Poll (automatic)
-Script polls with exponential backoff: 10s, 20s, 40s, 60s...
-Typical generation time: 2-5 minutes.
-
-### 5. Download (automatic)
-Video downloads to `~/Documents/lipnardo_videos/abc123.mp4`.
-
-### 6. Log cost
-```bash
-python3 ${CLAUDE_SKILL_DIR}/scripts/credit_check.py log \
-  --feature video_agent --duration 62 --video-id abc123 --prompt "Q3 results"
-```
-
-### 7. Report
-> "Video saved to `~/Documents/lipnardo_videos/abc123.mp4`
-> - Duration: 62 seconds
-> - Size: 12.4 MB
-> - Cost: ~$2.07
-> - Video ID: abc123 (use for translation or re-download)"

package/skills/lipnardo/references/avatar-types.md

@@ -1,42 +0,0 @@
-# HeyGen Avatar Types and Photo Requirements
-
-## Avatar Types Comparison
-
-| Type | How Created | Cost/Sec | Max Duration | Training | Best For |
-|------|-----------|----------|-------------|----------|---------|
-| Avatar III | Pre-built by HeyGen | $0.0167 | 30 min | None | Quick videos, standard presenters |
-| Photo Avatar (IV) | User uploads photo | $0.0500 | 3 min | Minutes-hours | Custom face, personal branding |
-| Digital Twin (IV) | Studio recording + consent | $0.0667 | 30 min | Hours-days | Professional, high-fidelity |
-
-## Photo Avatar Requirements
-
-- **Resolution**: Minimum 512x512px, recommended 1024x1024+
-- **Face**: Front-facing, centered, full face visible
-- **Lighting**: Even, natural lighting, no harsh shadows
-- **Background**: Clean, uncluttered preferred
-- **Expression**: Neutral or slight smile, mouth closed
-- **Accessories**: No sunglasses, large hats, or face coverings
-- **Format**: JPEG or PNG
-- **File size**: Under 10MB
-
-## Photo-to-Avatar Pipeline
-
-1. Upload photo: `POST /v1/asset` (returns `asset_id`)
-2. Create group: `POST /v2/photo_avatar/group` (returns `group_id`)
-3. Poll training: `GET /v2/photo_avatar/group/{group_id}`
-4. Status: `pending` → `training` → `completed`
-5. Get `avatar_id` from completed response
-6. Use in video generation with `use_avatar_iv_model: true`
-
-## Voice Selection
-
-- 100+ pre-built voices across 40+ languages
-- List: `GET /v2/voices`
-- Filter by language, gender
-- Each has `preview_audio` URL for sampling
-
-## Listing Avatars
-
-- `GET /v2/avatars` returns all accessible avatars
-- Fields: `avatar_id`, `avatar_name`, `gender`, `preview_image_url`
-- Photo avatars appear after training completes

package/skills/lipnardo/references/credit-costs.md

@@ -1,39 +0,0 @@
-# HeyGen Credit Costs and Estimation
-
-## Pricing Table
-
-| Feature | Cost/Second | Cost/Minute | Notes |
-|---------|------------|------------|-------|
-| Avatar III Video | $0.0167 | ~$1.00 | Standard pre-built avatars |
-| Video Agent | $0.0333 | ~$2.00 | AI-driven prompt-to-video |
-| Photo Avatar (IV) | $0.0500 | ~$3.00 | Custom from user photo, 3-min max |
-| Digital Twin (IV) | $0.0667 | ~$4.00 | Studio-recorded avatar |
-| Translation — Fast | $0.0333 | ~$2.00 | Speed-optimized |
-| Translation — Quality | $0.0667 | ~$4.00 | Precision lip-sync |
-| Starfish TTS | $0.000667 | ~$0.04 | Text-to-speech audio only |
-
-## Cost Estimation Formulas
-
-- **Single video**: cost = duration_seconds × rate_per_second
-- **Batch estimation**: total_cost = num_videos × avg_duration_seconds × rate
-- **Balance check**: GET /v2/user/remaining_quota returns remaining API balance in USD (legacy /v1/ path returns 404)
-- **Minimum API balance**: $5 pay-as-you-go (no monthly commitment)
-- **MCP credits are separate from API credits** — don't mix them
-
-## Cost Optimization Tips
-
-- Use Avatar III ($1/min) over Photo Avatar ($3/min) when custom face isn't needed
-- Use Translation Fast ($2/min) for drafts, Quality ($4/min) for finals
-- Test with --test true flag to generate watermarked videos for free
-- Monitor balance with `python3 credit_check.py balance` before large batches
-- Use TTS ($0.04/min) to preview audio before committing to full video generation
-
-## Examples
-
-| Scenario | Duration | Rate | Cost |
-|----------|----------|------|------|
-| 1-min Avatar III video | 60s | $0.0167/s | ~$1.00 |
-| 5-min Photo Avatar video | 300s | $0.0500/s | ~$15.00 |
-| 10× 2-min Avatar III batch | 1200s total | $0.0167/s | ~$20.00 |
-| 3-min Quality Translation | 180s | $0.0667/s | ~$12.00 |
-| 10-min TTS audio | 600s | $0.000667/s | ~$0.40 |

package/skills/lipnardo/references/error-codes.md

@@ -1,66 +0,0 @@
-# HeyGen API Error Codes and Recovery Strategies
-
-## Error Taxonomy
-
-| Category | HTTP Codes | Retry? | Max Retries | Strategy |
-|----------|-----------|--------|-------------|----------|
-| Authentication | 401, 403 | No | — | Verify API key is valid and has sufficient balance |
-| Validation | 400 | No | — | Fix request body — check required fields, valid IDs |
-| Rate Limiting | 429 | Yes | 3 | Exponential backoff: 2s, 4s, 8s |
-| Server Error | 500, 502, 503 | Yes | 2 | Fixed 5-second delay between retries |
-| Concurrent Limit | 429 (specific) | Yes | — | Wait for active video to complete, then retry |
-| Generation Failed | 200 + status=failed | Maybe | 1 | Retry once with same parameters; if fails again, try different avatar |
-| URL Expired | 410 or download 404 | No | — | Re-fetch video URL via GET /v2/videos/{id} |
-| Polling Timeout | — | No | — | Video exceeded 30-minute max; check video length |
-
-## Common Error Messages and Solutions
-
-| Error Message | Cause | Solution |
-|--------------|-------|----------|
-| "Invalid API key" | Wrong or expired key | Regenerate at app.heygen.com/settings/api |
-| "Insufficient credits" | API balance depleted | Top up at app.heygen.com |
-| "Avatar not found" | Invalid avatar_id | List avatars with GET /v2/avatars |
-| "Voice not found" | Invalid voice_id | List voices with GET /v2/voices |
-| "Max concurrent limit reached" | 3 videos already processing | Wait for completion or upgrade plan |
-| "Video generation failed" | Content policy or rendering error | Try different script/avatar combination |
-| "Photo does not meet requirements" | Bad photo for avatar training | Use front-facing, well-lit, min 512x512 photo |
-| "Template not found" | Invalid template_id | List templates with GET /v2/templates |
-| "Invalid language code" | Unsupported translation language | Check supported languages list |
-
-## Retry Implementation Pattern
-
-```python
-attempt = 0
-while attempt < max_retries:
-    try:
-        result = api_call()
-        break
-    except RateLimitError:
-        delay = (2 ** attempt) * 2  # 2s, 4s, 8s
-        sleep(delay)
-        attempt += 1
-    except ServerError:
-        sleep(5)
-        attempt += 1
-    except ClientError:
-        raise  # Don't retry 4xx
-```
-
-## Error Handling Best Practices
-
-- Always check HTTP status code before parsing the response body
-- Log the full response body on errors for debugging
-- For 429 errors, check the Retry-After header if present
-- For generation failures, check the error field in the video status response
-- For concurrent limit errors, poll active videos and wait for one to finish
-- Never retry 401/403 errors — they indicate a configuration problem
-- On repeated 500 errors, check HeyGen status page before further retries
-- Store video_id immediately after creation so you can query status later even if polling fails
-
-## Status Polling Errors
-
-- Poll interval: 5 seconds minimum to avoid rate limiting
-- Max poll duration: 30 minutes (videos rarely take longer)
-- If status is "failed", the error field contains the failure reason
-- If status is "processing" after 30 minutes, the video likely failed silently
-- Always implement a timeout on the polling loop to avoid infinite waits

package/skills/lipnardo/references/heygen-api-reference.md

@@ -1,416 +0,0 @@
-# HeyGen API Reference
-
-Base URL: `https://api.heygen.com`
-Auth Header: `X-Api-Key: <your-key>`
-Get key: https://app.heygen.com/settings/api
-
----
-
-## Video Agent API (v3) — AI-Driven Generation
-
-### POST /v3/video-agents
-
-AI handles scriptwriting, avatar selection, and visual assembly.
-
-**Request:**
-```json
-{
-  "prompt": "A professional woman explaining quarterly results",
-  "avatar_id": "optional_avatar_id",
-  "voice_id": "optional_voice_id",
-  "aspect_ratio": "16:9"
-}
-```
-
-**Response:**
-```json
-{
-  "data": {
-    "video_id": "abc123def456"
-  }
-}
-```
-
-**Cost:** $0.0333/sec (~$2/min)
-
----
-
-## Studio Video API (v2) — Multi-Scene Control
-
-### POST /v2/video/generate
-
-Up to 50 scenes per request with per-scene avatar, voice, and background.
-
-**Request:**
-```json
-{
-  "video_inputs": [
-    {
-      "character": {
-        "type": "avatar",
-        "avatar_id": "Kristin_public_3_20240108",
-        "avatar_style": "normal"
-      },
-      "voice": {
-        "type": "text",
-        "input_text": "Hello, welcome to our presentation.",
-        "voice_id": "en-US-JennyNeural"
-      },
-      "background": {
-        "type": "color",
-        "value": "#ffffff"
-      }
-    }
-  ],
-  "dimension": {"width": 1920, "height": 1080},
-  "aspect_ratio": "16:9",
-  "test": false
-}
-```
-
-Set `"use_avatar_iv_model": true` for Photo Avatar (Avatar IV).
-
-**Response:**
-```json
-{
-  "data": {
-    "video_id": "abc123def456"
-  }
-}
-```
-
-**Cost:** $0.0167/sec for Avatar III (~$1/min)
-
----
-
-## Video Status API
-
-### GET /v2/videos/{video_id}
-
-**Response:**
-```json
-{
-  "data": {
-    "status": "completed",
-    "video_url": "https://files.heygen.ai/video/abc123.mp4",
-    "duration": 30.5,
-    "thumbnail_url": "https://files.heygen.ai/thumb/abc123.jpg"
-  }
-}
-```
-
-**Status values:** `pending` → `processing` → `completed` | `failed`
-
-**Important:** Download URLs expire after **7 days**.
-
----
-
-## Template API
-
-### GET /v3/template/{template_id}
-
-Retrieve template with scene-level variable placeholders.
-
-**Response:**
-```json
-{
-  "data": {
-    "name": "Sales Outreach",
-    "scenes": [
-      {
-        "variables": [
-          {"name": "prospect_name", "type": "text", "properties": {"content": ""}},
-          {"name": "company", "type": "text", "properties": {"content": ""}}
-        ]
-      }
-    ]
-  }
-}
-```
-
-### POST /v2/template/generate
-
-Generate video from template with injected variables.
-
-**Request:**
-```json
-{
-  "template_id": "tmpl_abc123",
-  "variables": [
-    {"name": "prospect_name", "type": "text", "properties": {"content": "John Smith"}},
-    {"name": "company", "type": "text", "properties": {"content": "Acme Corp"}}
-  ]
-}
-```
-
-**Response:**
-```json
-{
-  "data": {
-    "video_id": "vid_xyz789"
-  }
-}
-```
-
-### GET /v2/templates
-
-List all available templates.
-
----
-
-## Translation API
-
-### POST /v3/video-translations (preferred)
-
-175+ languages. Explicit mode selection for speed vs precision.
-
-**Request:**
-```json
-{
-  "video_url": "https://files.heygen.ai/video/abc123.mp4",
-  "output_language": "es",
-  "mode": "speed"
-}
-```
-
-**Mode values:** `"speed"` ($0.0333/sec) or `"precision"` ($0.0667/sec)
-
-**Response:**
-```json
-{
-  "data": {
-    "video_id": "translated_vid_001"
-  }
-}
-```
-
-### POST /v2/video_translate (legacy, no mode parameter)
-
-Still works but does not support speed/precision selection.
-
-**Request:**
-```json
-{
-  "video_url": "...",
-  "output_language": "es",
-  "translate_audio_only": false
-}
-```
-
----
-
-## TTS API (Starfish)
-
-### POST /v1/audio/text_to_speech
-
-**Request:**
-```json
-{
-  "text": "Hello, this is a test.",
-  "voice_id": "en-US-JennyNeural",
-  "speed": 1.0,
-  "pitch": 0
-}
-```
-
-**Response:**
-```json
-{
-  "data": {
-    "url": "https://files.heygen.ai/audio/tts_001.mp3",
-    "duration": 3.2
-  }
-}
-```
-
-**Cost:** $0.000667/sec (~$0.04/min)
-
----
-
-## Asset API
-
-### POST /v1/asset
-
-Upload file via multipart/form-data. Fields: `file` (required), `type` (optional: image, video, audio).
-
-**Response:**
-```json
-{
-  "data": {
-    "asset_id": "asset_abc123",
-    "url": "https://files.heygen.ai/asset/abc123.png"
-  }
-}
-```
-
-### GET /v1/asset/list
-
-Query params: `?type=image&limit=50&offset=0`
-
-**Response:**
-```json
-{
-  "data": {
-    "assets": [
-      {"asset_id": "asset_001", "url": "...", "type": "image", "created_at": "..."}
-    ],
-    "total": 25
-  }
-}
-```
-
----
-
-## Avatar API
-
-### GET /v2/avatars
-
-List all available avatars.
-
-**Response:**
-```json
-{
-  "data": {
-    "avatars": [
-      {
-        "avatar_id": "Kristin_public_3_20240108",
-        "avatar_name": "Kristin",
-        "gender": "female",
-        "preview_image_url": "https://...",
-        "preview_video_url": "https://..."
-      }
-    ]
-  }
-}
-```
-
-### POST /v2/photo_avatar/group
-
-Create avatar group from uploaded photo.
-
-**Request:**
-```json
-{
-  "name": "My Avatar",
-  "image_key": "asset_abc123"
-}
-```
-
-**Response:**
-```json
-{
-  "data": {
-    "group_id": "grp_xyz789"
-  }
-}
-```
-
-### GET /v2/photo_avatar/group/{group_id}
-
-Check training status.
-
-**Response:**
-```json
-{
-  "data": {
-    "status": "completed",
-    "avatars": [
-      {"avatar_id": "photo_avatar_001", "avatar_name": "My Avatar"}
-    ]
-  }
-}
-```
-
-**Training status:** `pending` → `training` → `completed` | `failed`
-
----
-
-## Voice API
-
-### GET /v2/voices
-
-**Response:**
-```json
-{
-  "data": {
-    "voices": [
-      {
-        "voice_id": "en-US-JennyNeural",
-        "name": "Jenny",
-        "language": "English",
-        "gender": "female",
-        "preview_audio": "https://..."
-      }
-    ]
-  }
-}
-```
-
----
-
-## Webhook API
-
-### POST /v1/webhook/endpoint.add
-
-**Request:**
-```json
-{
-  "url": "https://your-server.com/webhook",
-  "events": ["avatar_video.success", "avatar_video.fail"]
-}
-```
-
-**Response:**
-```json
-{
-  "data": {
-    "webhook_id": "wh_abc123"
-  }
-}
-```
-
-### GET /v1/webhook/endpoint.list
-
-### POST /v1/webhook/endpoint.delete
-
-**Request:** `{"webhook_id": "wh_abc123"}`
-
-**Note:** Webhook endpoints must respond to OPTIONS preflight within 1 second.
-
----
-
-## User / Credits API
-
-### GET /v2/user/remaining_quota
-
-**Response:**
-```json
-{
-  "error": null,
-  "data": {
-    "remaining_quota": 45.50,
-    "details": {
-      "avatar_iv_free_credit": 0,
-      "b_roll_free_credit": 0,
-      "generative_element_free_concept_engine_credit": 3,
-      "generative_element_free_design_element_credit": 3
-    }
-  }
-}
-```
-
-Returns remaining paid API balance in USD plus a `details` object with per-feature free-tier credits. The legacy `/v1/user/remaining_quota` returns 404 -- use v2.
-
----
-
-## Constraints
-
-| Constraint | Limit |
-|-----------|-------|
-| Concurrent videos | 3 (standard API plan) |
-| Max video length | 30 minutes (Enterprise for longer) |
-| Default resolution | 1080p (4K Enterprise only) |
-| Photo Avatar max | 3 minutes |
-| URL expiry | 7 days |
-| Scenes per request | 50 (Studio API) |
-| Min API balance | $5 pay-as-you-go |