@hubfluencer/mcp 0.7.1 → 0.8.2

package/README.md

@@ -68,7 +68,7 @@ claude mcp add hubfluencer --env HUBFLUENCER_API_TOKEN=YOUR_TOKEN -- npx -y @hub
 
 ## Tools
 
-89 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
+92 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
 below are the ground truth. **"$0" means it spends no video credits**; planning/AI-helper tools
 instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_assists`: 1 credit
 → +10). Reads need the `video:read` scope; writes need `video:generate`. Nothing here needs
@@ -79,11 +79,12 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | Tool | What it does | Cost |
 |---|---|---|
 | **`make_video`** | **One shot: prompt → finished MP4** (create → **price** → start → poll → download). `kind:"auto"` picks a multi-scene editor ad for ad/promo/story briefs, a short for simple ones (reported as `kind_inferred`). Pass `dry_run:true` to preview the cost without spending, or `max_credits` to cap it. | short **15**, editor ~**28** (`dry_run`/`max_credits` gate it) |
-| `create_short` | Create a short draft (12s vertical: two 6s AI segments + title overlay + music; 14s with an end-card poster). Set `headline`/`subheadline`/`music_vibe`/`visual_language` so it isn't bare. Optional opt-in conversion graphics: `offer_text`/`cta_text`/`badge_text`/`star_rating` (off unless you set them). | **0** |
-| `update_short` | Patch an existing short draft — brief (`product_prompt`), copy, styling, or the opt-in conversion graphics; only the fields you pass change. Clear one with `""` (`[]` for `text_beats`, `0` for `star_rating`). Re-run `generate_short` to apply. | **0** |
-| `generate_short` | Render an existing short. Safe to re-call (in-flight = reported, no double charge; a failed short can re-generate). | **15** |
+| `create_short` | Create a short draft (12s vertical: two 6s AI segments + title overlay + music; 14s when it ends on a poster or brand-lockup end card). Set `headline` (≈4 words, ≤40 chars), `subheadline`, `music_vibe`, and an explicit `visual_language` (`kinetic_creator` is a strong default) — and **always `cta_text`** (a short without a CTA doesn't convert; blank `cta_text` → the server renders a neutral localized ask, e.g. "Learn more" — a truly CTA-less short is not currently supported). End-card fields: `closing_claim` (≤80), `brand_name` (≤40), `end_card` (`"auto"`\|`"none"`). Other opt-in conversion graphics: `offer_text`/`badge_text`/`star_rating` — only what you can substantiate. | **0** |
+| `update_short` | Patch an existing short draft — brief (`product_prompt`), copy, styling, end-card fields (`closing_claim`/`brand_name`/`poster_includes_lockup`/`end_card`), or the opt-in conversion graphics; only the fields you pass change. Clear one with `""` (`[]` for `text_beats`, `0` for `star_rating`). Apply text/style/CTA/end-card edits to a generated short free with `rerender_short`; footage/music edits need `generate_short`. | **0** |
+| `generate_short` | Render an existing short — re-rolls the footage + music (fresh AI generation). If headline/subheadline/beats are all blank the server auto-writes the copy first (`skip_auto_text:true` for a deliberately bare clip). Safe to re-call (in-flight = reported, no double charge; a failed short can re-generate). | **15** |
+| `rerender_short` | **FREE re-render** — applies the short's current text/style/CTA/end-card state over the already-paid footage + music. Use after `update_short` for copy/style/CTA tweaks; footage or music changes need `generate_short` instead. Needs one completed generation first (422 `short_not_ready` otherwise); changed footage/music inputs return 422 `short_paid_regeneration_required`. A failed free re-render leaves the delivered video intact — retry `rerender_short`, it stays free. | **0** |
 | `generate_short_text` | AI-draft editable headline / subheadline / caption beats for a short. | 1 assist |
-| `create_editor_ad` | Create an editor project **and** run autopilot end-to-end. Style it with `creative_format` + `visual_language` + `theme`. | credits (est. first) |
+| `create_editor_ad` | Create an editor project **and** run autopilot end-to-end. Style it with `creative_format` + `visual_language` + `theme`. Cast modes need prerequisite assets, so configure them through `create_editor_draft` instead. | credits (est. first) |
 | `start_autopilot` | Run autopilot on an **existing** editor draft (resume a `make_video` `dry_run`, or after a top-up). | credits |
 | `create_slider` | Create an image-carousel draft: one prompt → N still slides + a ready-to-post caption + hashtags. `mode` `creative` (story) or `ad_driven` (facts). | **0** |
 | `generate_slider` | Render a carousel (copy → AI backgrounds → composite). Poll `get_slider` until `completed`. | **1 / slide** (3–10) |
@@ -96,12 +97,14 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 
 | Tool | What it does | Cost |
 |---|---|---|
-| `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme`. | **0** |
+| `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme` / `cast_mode` (`product_only` needs `set_product` before generation; `presenter_led` needs a configured presenter). | **0** |
 | `get_editor` | Full project state (scenario, segments, narration, music, latest render, quota) — the review step. | **0** |
 | `set_scenario` / `generate_scenario` | Write your own scenario (free) **or** AI-draft it. `generate_scenario` can also persist `creative_format` / `visual_language` / `theme`. | free / 1 assist |
+| `apply_scenario` | Compile the **ready** scenario into per-scene prompts on the timeline (`segments_count` 0 or 3..10; omitted uses the generated scenario count, then 5; AI scenes replaced, uploads preserved). Polls until applied (~2 min budget). | **0** |
 | `set_scene_count` | Grow/shrink to N scenes (1–20); deletes only trailing un-generated scenes. Each AI scene is a fixed 8s. | **0** |
 | `set_segment_prompt` | Write one scene's prompt (1–2000 chars), identified by segment id. | **0** |
-| `generate_segment` | Render one scene (re-call to retry a failed one). | **5** |
+| `generate_segment` | Render one **pending/failed** scene (re-call to retry a failed one). | **5** |
+| `regenerate_segment` | Re-roll a **completed** scene as a new version (optional new `prompt`). Mid-timeline: the next scene's transition can degrade because it was seeded from the old version's last frame. | **4** |
 | `generate_all_segments` | Render every not-yet-completed scene in order (continuity preserved); capped ~280s → re-run to continue. | **5 / segment** |
 | `set_narration_script` / `generate_narration` | Write your own voiceover script (free) **or** AI-draft it. | free / 1 assist |
 | `generate_voice` | Synthesize the voiceover. `voice_id` required (see `list_voices`). | **3** |
@@ -125,7 +128,7 @@ Reads are confined to `HUBFLUENCER_INPUT_DIR`. All $0.
 | `set_closing_image` | Set the ~2s end-card image (upload a file, or reuse the product image with `from_product:true`). |
 | `set_logo` | Upload a brand logo overlay (editor only; optional treatment/position/duration). |
 | `set_short_product` | Attach a product image to a **short**. |
-| `set_short_poster` | Set a short's end-card poster (extends the render 12s → 14s). |
+| `set_short_poster` | Set a short's end-card poster (extends the render 12s → 14s). Pass `poster_includes_lockup:true` if the poster already carries brand name/CTA/badges — suppresses the overlaid claim/CTA so they don't collide. |
 
 ### Status & delivery
 
@@ -219,7 +222,9 @@ edit are **0 credits** — you only pay to generate/render.
 |---|---|
 | Any draft create / edit / reorder | 0 |
 | Short render | **15** |
+| Short re-render (`rerender_short` — text/style/CTA/end-card over existing footage) | **0** |
 | Editor AI scene (`generate_segment`) | **5** (4 each in a batch of ≥3) |
+| Editor scene re-roll (`regenerate_segment`, new version of a completed scene) | **4** |
 | Editor voice | **3** |
 | Editor music | **5** |
 | Editor render | **0** (auto-charges only still-ungenerated scenes) |
@@ -239,9 +244,18 @@ It prices the job and only charges if it's affordable (and within `max_credits`
 If it returns `terminal:false`, the render is still going — call `wait_for_completion` with the returned slug.
 
 **Granular (control/recovery):**
-`create_short` → optional `generate_short_text` → `generate_short` → `wait_for_completion {kind:"short"}` → `download_result`, or
+`create_short` → optional `generate_hook_variations` (test hook angles free) / `generate_short_text` → `generate_short` → `wait_for_completion {kind:"short"}` → `download_result`, or
 `create_editor_ad` → `wait_for_completion {kind:"editor"}` → `download_result`.
 
+**Iterate a short for free (never re-roll):** the first `generate_short` (15 credits) buys the footage +
+music; after that, every text/style/CTA/end-card tweak re-renders over them for **0 credits** —
+`update_short` (new hook/CTA/style) → `rerender_short` → compare → repeat → keep the winner. Only
+footage/music-affecting edits (`product_prompt`, product image, `creative_format`, `visual_language`,
+`theme`, `music_vibe`, `music_instruments`, `language`) need another `generate_short`. Edits that
+add/remove the end card (poster, `end_card`) can shift the video between 12s and 14s; the pinned music
+bed is faded to fit rather than regenerated — for perfectly synced music after such a change, use
+`generate_short`.
+
 **Image carousel:**
 `create_slider({ prompt: "5 tips for…", mode: "ad_driven", slide_count: 5 })` → `generate_slider` →
 poll `get_slider` until `completed:true`, then download each `slides[].image_url` and post them with the
@@ -271,6 +285,11 @@ start a NEW project (omit `slug`, pass `video_path`).
 > Result URLs are presigned and expire (~24h). Download promptly. Publishing to
 > TikTok/Instagram requires a human-linked social account and is out of scope —
 > return the MP4 + a suggested caption instead.
+>
+> **Label synthetic media.** These videos are AI-generated: TikTok requires an
+> AI-generated content label (and attaches C2PA credentials since 2025), and Meta
+> requires disclosure for AI-generated content in paid ads. Remind the user to
+> enable the platform's AI label when posting.
 
 ## Troubleshooting