@docyrus/animaguru 0.19.0 → 0.22.0

package/README.md

@@ -84,6 +84,19 @@ Running `init` again refreshes an existing skill with the bundled version withou
 
 The default server is https://animaguru.com. Use `--url http://localhost:5190` on the leaf command or `ANIMAGURU_URL` to override it. HTTP is allowed only for loopback development. Authentication is stored separately per server in `~/.config/animaguru/credentials.json`, with file permissions 0600. Set `ANIMAGURU_CONFIG_DIR` for an isolated configuration directory. Browser login uses a ten-minute, single-use device code and receives a seven-day revocable Better Auth session. `auth login --no-browser` prints the URL for manual use. `auth logout` revokes the token. `ANIMAGURU_TOKEN` supports secret injection by agent runners; do not put tokens in arguments or commit them.
 
+## Call the API directly
+
+CLI 0.22.0 adds `animaguru curl` for API endpoints that have no command of their own. It takes curl's flags but no host and no `Authorization` header: it calls only the signed-in server (`--server` or `ANIMAGURU_URL`) and adds the session's token itself, so the token never appears in a command line.
+
+```sh
+animaguru curl /api/v1/me
+animaguru curl -X PATCH /api/v1/projects/prj_123 -d '{"name":"Launch film"}'
+animaguru curl -T film.mp4 /api/v1/some/upload        # streams the file with PUT and Content-Type: video/mp4
+animaguru curl /api/v1/some/download -o film.mp4      # saves to a new file and prints a JSON summary
+```
+
+`-d`/`--data` and `--json` take text, `@FILE` or `@-` (JSON text is sent as `application/json`); `-T` streams a file with `PUT` unless `-X` says otherwise; `-H` adds headers; `-i` prints the status line and headers. Redirects are not followed. Unlike plain curl, an HTTP 4xx or 5xx prints the body and exits non-zero; `--no-fail` exits 0. Video, images and other binary responses go to a file with `-o`, which never overwrites one.
+
 ## Personal and team projects
 
 CLI 0.7.1 can select a cloud workspace for project listing, project creation, and credit balances:
@@ -255,6 +268,18 @@ animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
 
 H3 takes fractions of a second (`--seconds 6.5`). Lip-sync, recast, relight and 3d-to-video last as long as their speech or video, and `--seconds` doesn't apply to them. Reference images, clips and audio past fal's included allowance add to the cost; so do the references 3d-to-video draws. Their `--dry-run` asks the server, which measures the saved files. `--resolution` and `--mode` default to the first the workflow offers.
 
+CLI 0.21.0 adds Black Forest Labs' FLUX 3 Max on fal.ai (`fal/flux-3-max`). It films from an image (optionally ending on `--end-reference`) or from text, for 5–20 whole seconds at 720p (default) or 1080p, and makes its own sound; it takes no `--soundtrack`. `--workflow keyframes-to-video` passes through up to ten saved images at chosen moments:
+
+```sh
+# Pass through three images: the start, a pose at 2.5 seconds, and the end.
+animaguru assets generate PROJECT_ID --type video --model fal/flux-3-max \
+  --workflow keyframes-to-video --name "Hat on" \
+  --prompt "She picks up the hat, puts it on and smiles at the camera" \
+  --keyframes "0,START_SHA;2.5,POSE_SHA;6,END_SHA" --seconds 6 --dry-run
+```
+
+`--keyframes` takes 1–10 `seconds,SHA` pairs, separated by semicolons, of this project's images or sprite art. Each is reached at its second, within `--seconds`; the clip has 24 frames a second and each keyframe needs a frame of its own. `--aspect-ratio auto` (default) follows the first keyframe, or give a ratio. FLUX 3 Max always works through the prompt before filming: `--prompt-expansion quality` asks for its thorough, slower level, any other value its light one. It takes `--seed`. Its dry runs are local estimates.
+
 Images have a full background by default; `--transparent` requests a cutout. CLI 0.17.0 adds `--references`, `--mask` and the 16:9 and 9:16 shapes. `--aspect-ratio` is 1:1 (default, 1024×1024), 3:2 (1536×1024), 2:3 (1024×1536), 16:9 (1536×864) or 9:16 (864×1536). `--references` takes up to four comma-separated blob SHAs of this project's images (including attached uploads) or sprite art, and the new image follows them: generate a character sheet once, then reference it in every scene to keep the character consistent. Refer to them in the prompt as Image 1, Image 2 and so on, and say what to take from each. Each reference adds a little to the estimate. `--mask` edits only part of Image 1, the first reference: give up to eight rectangles as `x,y,width,height` fractions of its size from the top left, separated by semicolons (`0,0,1,0.4` is the top 40%). The rest of the image is kept, and the result keeps Image 1's shape, which must be one of the five above. Gemini speech's `--prompt` is the verbatim transcript, and `--delivery` controls how it sounds without being spoken. Gemini speech supports both `gemini-3.8-flash-tts` and `gemini-3.8-flash-lite-tts`. Music uses Lyria. Google audio requires the server's `AI_PROVIDER_KEY_GOOGLE` secret; no provider keys are stored in the CLI.
 
 Preview a validated request and its estimated credits with `--dry-run`, without spending credits; most dry runs work offline without signing in:
@@ -404,6 +429,32 @@ animaguru reference get va_… --wait
 
 The video is a local MP4, MOV or WebM file up to 100 MB and ten minutes, or an HTTPS link to the video file itself. Pages on YouTube, Instagram or TikTok cannot be fetched; download the video you have the rights to use and pass the file. An analysis takes several minutes: about eight for a 6-second clip, because Glimpse inspects the frames with code over many steps. Inside a video project it is saved to `production/references/NAME.json`, elsewhere to `NAME.analysis.json` (or `--out FILE`). It is charged what it costs, about 22 to 36 credits for a 6-second clip in testing and more for a longer video, after holding 200 credits (300 with `--effort medium`, 500 with `xhigh`). MCP clients use `analyze_video` with a link and poll `get_video_analysis`.
 
+## Branching stories
+
+CLI 0.20.0 makes branching stories: films whose viewers choose what happens next and reach one of several endings. A `story.json` beside the film's `film.config.json` lays its segments end to end on the timeline and says where each leads: to the viewer's choices, on to another segment, or to an ending.
+
+```sh
+animaguru create animation lantern --story        # a story.json over the starter film: one choice, two endings
+npm run dev                                       # play it; ?segment=ID starts at a segment
+npm run review -- --animation lantern --headless  # every segment, plus the story's playthroughs
+animaguru submit --animation lantern --yes        # uploads it as an interactive HTML5 film
+```
+
+The player shows the choices over the picture, with an optional timer that takes a default, and an ending panel with Play again and Back to the last choice. A branching story plays as HTML5 only: `npm run export:mp4` refuses it, and the cloud Animator offers no MP4 of it. The `animaguru-branching-story` skill has the format.
+
+## Quizzes
+
+CLI 0.20.0 also makes quiz films, for educational explainers, lessons and training: a `quiz.json` beside `film.config.json` pauses the film at checkpoints to ask one question or a quick round (for example after every scene), and asks a final quiz after its end, then shows the viewer's score. Questions have one right answer (multiple choice or true/false) or several (select all that apply), an optional explanation, and a pass mark for the final quiz; a wrong answer at a checkpoint offers Watch that part again.
+
+```sh
+animaguru create animation moon-lesson --quiz        # a quiz.json over the starter film: a checkpoint and a final quiz
+npm run dev                                          # play it and answer
+npm run review -- --animation moon-lesson --headless # the film under the cards, plus the quiz's questions and notes
+animaguru submit --animation moon-lesson --yes       # uploads it; the video page plays the quiz
+```
+
+The questions are HTML cards over the picture, so they play in HTML5: locally, in the exported ZIP and on AnimaGuru's video pages. A quiz film plays as HTML5 only, because its questions wait for a viewer's answers: `npm run export:mp4` refuses it, and the cloud Animator offers no MP4 of it. A quiz also works inside a branching story (`--story --quiz`). The `animaguru-quiz` skill has the format and how to write good questions.
+
 ## Motion library
 
 CLI 0.14.0 adds `animaguru motion`. Search ready-made motion design examples (PixiJS scenes built on the video film kit) by describing the motion, then install one into a film. Search uses natural language and keywords together; it needs `animaguru auth login` and spends no credits.
@@ -486,6 +537,16 @@ To request public gallery publication, upload privately, open the video in My vi
 
 `videos list --scope mine|shared|public` lists films. Owners can edit metadata, change visibility and replace recipients on the website, or use `videos share VIDEO_ID --visibility private --share "alex@example.com" --yes`. `videos delete VIDEO_ID --yes` removes the film and files. Making a film private or removing a recipient revokes access to existing playback links.
 
+CLI 0.20.0 lists and moves videos between libraries. `videos list` shows the selected workspace's library, the one `submit` uploads to; `--workspace personal` or `--workspace TEAM_ID` lists another. `videos move VIDEO_ID… --workspace TEAM_ID --yes` moves your own videos into a team you belong to, or back with `--workspace personal`:
+
+```sh
+animaguru videos list --workspace personal
+animaguru videos move vid_… vid_… --workspace team_… --yes
+animaguru videos list --workspace team_…
+```
+
+A moved video keeps its ID, watch and embed links, subtitles, recipients and review, and everyone in the team can watch it. The new library must have room for it. A video made from a project's animation stays with that project: transfer the project to the team on the website first, then move the video. Videos move one at a time; if one cannot move, the command stops, prints the IDs it moved and the ones it didn't, and exits with an error. Moving a video into the library it is already in changes nothing, so the same command can be run again.
+
 Uploads are divided into SHA-256 verified 8 MiB parts. Interrupted submissions print their video ID: inspect with `videos get VIDEO_ID`, retry a fully uploaded film with `videos complete VIDEO_ID`, or delete the unfinished draft before resubmitting. Completion is idempotent. HTML5 ZIPs allow 64 MiB compressed / 96 MiB expanded with 500 entries and 32 MiB per asset; MP4s allow 512 MiB; PNG/JPEG/WebP covers allow 2 MiB. Uploads are available to verified accounts with a 2 GiB video library allowance. Hosting does not run paid generation jobs.
 
 ## Upload directly to YouTube