@facelessad/cli 2.1.1 → 2.2.0

package/README.md

@@ -109,11 +109,25 @@ These are not alternative spellings but forms of their own, and they stay:
 | `--no-voice` | no narration |
 | `--no-brand-kit` | build without the Brand Kit |
 | `--no-refine-style` | use the custom style text verbatim |
+| `--visual-direction-refine "<preset\|text>"` | how the story is told, not how it looks (2.2.0) |
+| `--layout <A\|HA\|AC\|HAC\|AIA\|HAIA\|AIAC\|HAIAC>` | card layout; data card drops if too short, hook/CTA stay (2.2.0) |
 
 `--no-brand-kit` now works; before 1.0.1 it was accepted on the command line
 and silently dropped, so the video was built with the Brand Kit anyway. **An unknown flag is now an error** rather than
 something quietly ignored — that silence is what hid the whole problem.
 
+## 2.2.0 — `--visual-direction-refine`
+
+Animated Ad and Music Video: a preset id (`metaphoric`, `realistic`,
+`dramatic`, `calm`, `playful`, `dark`, `bright`, `magical` — `facelessad tools`
+lists them) or your own instruction up to 300 characters. Reshapes how the
+visual story is told, not how it looks; applied on top of `--visual-direction`
+or the generated one. Free.
+
+`--layout` (same two tools) picks the card layout. Too short for the data
+card? It is dropped, the hook/CTA you chose stay, and the output says so.
+`facelessad tools` lists the layouts and what each becomes per duration.
+
 ## 1.3.0 — turn any text file into a video
 
 **Agent skill included.** The package ships `SKILL.md` — drop it where your

package/SKILL.md

@@ -14,10 +14,11 @@ facelessad login                   # API key from https://facelessad.com/develop
 facelessad balance                 # proves the key works
 ```
 
-**The API needs a paid plan.** Trial credits cover the web app but do not
-open API keys — if a command answers `api_access_required`, the user has to
-subscribe first. That is a billing state, not a broken key, so say so rather
-than retrying.
+**The API needs a paid plan or an active trial.** The $15 trial (300
+credits, 7 days) opens API keys, the CLI and MCP for its duration. If a
+command answers `api_access_required`, the subscription has ended or the
+trial has expired or run out of credits — a billing state, not a broken
+key, so say so rather than retrying.
 
 In CI, skip `login` and set `FACELESSAD_API_KEY`; the environment variable
 wins over the saved key.
@@ -139,6 +140,8 @@ you leave out is chosen for you** from the materials.
 | `--voice-over` / `--no-voice` | force narration on or off, where the tool allows a choice |
 | `--voiceover-text "<script>"` / `--voiceover-file <path>` | your own narration (see below) |
 | `--visual-direction "<...>"` | how it should look and what happens, max 600 |
+| `--visual-direction-refine "<preset\|text>"` | how the story is TOLD, not how it looks: preset id or your own instruction, max 300. Animated Ad, Music Video. Free |
+| `--layout <A\|HA\|AC\|HAC\|AIA\|HAIA\|AIAC\|HAIAC>` | card layout — hook/CTA stay, data card drops if too short. Animated Ad, Music Video |
 | `--hook-text "<...>"` | your own first-frame card text, max 120 |
 | `--cta "<...>"` | the call to action it ends on |
 | `--brand-name "<...>"` / `--brand-color "#RRGGBB"` | brand as said and shown, and its colour |
@@ -169,6 +172,35 @@ before sending. Not on music-video (its script is sung) or video-banner.
 `--visual-direction` steers the storyboard and `--hook-text` the first frame.
 Neither replaces the style: the look still comes from `--style`.
 
+## Refining the visual story (optional)
+
+`--visual-direction-refine` reshapes **how the visual story is told** — its
+narrative device, scale, tempo, mood, what the product's effect leads to — not
+how it looks. It is applied on top of `--visual-direction` if you gave one,
+and otherwise on the visual direction the script writer generates, so an
+intent is enough.
+
+Two forms: a preset id (`metaphoric`, `realistic`, `dramatic`, `calm`,
+`playful`, `dark`, `bright`, `magical` — `facelessad tools` lists them under
+`visual_direction_refine.presets`) or any other text, max 300 characters,
+used as your own instruction. Animated Ad and Music Video only; elsewhere it
+is an error, not ignored. Free. Art-style words belong in `--custom-style`.
+
+## Card layout (optional)
+
+`--layout` picks the card layout on Animated Ad and Music Video: `A` (scenes
+only), `HA` (hook card + scenes), `AC` (scenes + CTA card), `HAC`, `AIA`
+(scenes + data card + scenes), `HAIA`, `AIAC`, `HAIAC`. `facelessad tools`
+lists them under `layouts` with a name and, per duration, what each becomes.
+
+Length is never an error. The hook and CTA cards you chose always stay; the
+data card is dropped when the video is too short for it — `HAIAC` at 30 s
+becomes `HAC`, `AIA` at 15 s becomes `A`. The create response reports
+`layout.applied` and a `layout.notice` when it was reduced. Omit `--layout` to
+let the ad structure decide (its own layout, fitted to the duration the same
+way).
+
+
 ## Captions
 
 On by default, outline style, no dark box over the visuals.
@@ -291,9 +323,10 @@ names the offending field and usually the valid values.
 
 **Access and capacity**
 
-- `api_access_required` — no active paid plan. Trial credits do not open the API.
+- `api_access_required` — no active paid plan or live trial. An active $15 trial opens the API for its 7 days.
 - `insufficient_credits` — the body carries the estimate and the balance; nothing was spent.
 - `too_many_active` — the plan's queue is full (Starter 10, Growth 25, Scale 50; app and API share it). Wait for a build to finish, then retry.
+- `test_quota_exceeded` — 100 test runs per day per account (`"test": true` only). Real runs are unaffected; the quota resets at 00:00 UTC and the body carries `retryAfter`.
 - `rate_limited` — over 300 POSTs this hour (`estimate` has its own 600). `retryAfter` gives the seconds until the counter resets on the hour.
 - `unauthorized` — the key is unknown or revoked.
 
@@ -306,6 +339,8 @@ names the offending field and usually the valid values.
 - `custom_style_without_custom` — `--custom-style` without `--style custom`.
 - `custom_style_not_supported` — that tool's styles are fixed presets.
 - `custom_script_too_long` / `custom_script_too_short` — `--voiceover-text` does not fit the duration.
+- `visual_direction_refine_too_long` / `visual_direction_refine_not_supported` — free-text instruction over 300, or a tool other than animated-ad / music-video.
+- `unknown_layout` / `layout_not_supported` — a layout id not in the list, or a tool other than animated-ad / music-video. Length never errors: the data card is dropped and the response says so.
 - `voice_not_supported` / `voice_over_not_supported` / `speakers_not_supported` / `option_not_supported` — that tool does not have that setting.
 - `structure_speaker_mismatch` — a dialogue structure with `--speakers 1`, or the reverse.
 - `product_image_required` — product-showcase cannot start without one.

package/index.js

@@ -157,6 +157,10 @@ const KNOWN_FLAGS = new Set([
   'no-captions', 'no-music', 'no-sfx',
   // 1.4.0 (§799): oma kasikirjoitus ja visuaalinen ohjaus createssa.
   'voiceover-text', 'voiceover-file', 'visual-direction', 'hook-text',
+  // 2.2.0 (§903): kerronnan esitystavan jalostus (preset-id tai vapaa ohje).
+  'visual-direction-refine',
+  // 2.2.0 (§912): H/I/C-layout (A, HA, AC, HAC, AIA, HAIA, AIAC, HAIAC).
+  'layout',
 ]);
 const unknownFlags = Object.keys(flags).filter((f) => !KNOWN_FLAGS.has(f)).map((f) => '--' + f).concat(badShort);
 
@@ -395,6 +399,8 @@ function buildBody() {
     body.voiceover_text = vo;
   }
   set('visual_direction', flags['visual-direction'] !== undefined ? String(flags['visual-direction']) : undefined);
+  set('visual_direction_refine', flags['visual-direction-refine'] !== undefined ? String(flags['visual-direction-refine']) : undefined); // 2.2.0 (§903)
+  set('layout', flags['layout'] !== undefined ? String(flags['layout']).toUpperCase() : undefined); // 2.2.0 (§912)
   // 1.5.0 (§806): tekstitysten ulkoasu — samat arvot kuin appissa.
   set('caption_style', flags['caption-style'] !== undefined ? String(flags['caption-style']) : undefined);
   set('caption_color', flags['caption-color'] !== undefined ? String(flags['caption-color']) : undefined);
@@ -567,6 +573,10 @@ const commands = {
       } else if (t.adStructures?.length) {
         lines.push('  ad structures: ' + t.adStructures.map((s) => s.id).join(', '));
       }
+      // 2.2.0 (§912): layoutit + mihin ne tippuvat pituuksittain.
+      if (t.layouts?.length) {
+        lines.push('  layouts (15s / 30s / 50s): ' + t.layouts.map((l) => l.id + ' → ' + l.at.quick + '/' + l.at.medium + '/' + l.at.long).join(', '));
+      }
       // Tyylit joilla on OMA rakennepooli — valinta riippuu tyylistä, ja
       // yleisen listan rakenne hylätään niillä (structure_style_mismatch).
       // §708: characterin rakenteet ovat kaksi poolia puhujamäärän mukaan.
@@ -711,7 +721,9 @@ const commands = {
     if (flags['dry-run'] === true) { out({ ok: true, body }, JSON.stringify(body, null, 2)); return; }
     const d = await call('POST', '/api/v1/videos', body);
     if (!(flags.wait === true)) {
-      out(d, 'Queued. id=' + d.id + ' (estimate: up to ~' + d.estimate + ' credits)\nFollow it: facelessad status ' + d.id + ' --wait');
+      // 2.2.0 (§912): layout-kuittaus — mitä käytetään ja miksi se tippui.
+      const layoutLine = d.layout ? ('\nLayout: ' + d.layout.applied + (d.layout.notice ? ' — ' + d.layout.notice : '')) : '';
+      out(d, 'Queued. id=' + d.id + ' (estimate: up to ~' + d.estimate + ' credits)' + layoutLine + '\nFollow it: facelessad status ' + d.id + ' --wait');
       return;
     }
     await waitFor(d.id);
@@ -866,6 +878,16 @@ Create flags:
   --voiceover-file <path>          (same, read from a local text file)
   --visual-direction "<...>"       (how the video should LOOK and what happens
        visually, max 600 chars — steers the storyboard, not the art style)
+  --visual-direction-refine "<preset|text>"
+      (how the story is TOLD, not how it looks: a preset id — metaphoric,
+       realistic, dramatic, calm, playful, dark, bright, magical — or your own
+       instruction, max 300 chars. Applied on top of --visual-direction or the
+       generated one. animated-ad and music-video only. Free.)
+  --layout <A|HA|AC|HAC|AIA|HAIA|AIAC|HAIAC>
+      (card layout, animated-ad and music-video only. H = hook card, I = data
+       card, C = CTA card, A = scenes. Too short for the data card? It is
+       dropped and the hook/CTA you chose stay — e.g. HAIAC at 30s becomes
+       HAC; the response says so. "facelessad tools" lists the layouts.)
   --hook-text "<...>"              (your own first-frame card text, max 120)
   --voice --gender --no-voice --voice-over --music --sfx --captions
       (leave --voice out and the voice is cast from the finished script;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facelessad/cli",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Create faceless video ads from your terminal or build scripts \u2014 the FacelessAd command line.",
   "license": "MIT",
   "type": "module",