@sogni-ai/sogni-client 5.58.0 → 5.58.1

package/AGENTS.md

@@ -365,7 +365,7 @@ const urls = await project.waitForCompletion();
 | Text-to-Video | `*_t2v*` | None |
 | Image-to-Video | `*_i2v*` | `referenceImage` (and/or `referenceImageEnd`) |
 | First/Last-Frame Video | `*_flf2v*` (MiniMax H3) | `referenceImage` + `referenceImageEnd` |
-| MiniMax H3 intermediate keyframes | every H3 id except `*_t2v*`: `*_i2v*`, `*_flf2v*`, `*_ia2v*`, `*_flfa2v*`, `*_a2v*`, `*_r2v*` (`isMinimaxH3KeyframeModel`, 21 ids) | optional `keyframes: [{ image, frameIndex }]`, up to 8, alongside the workflow's own uploads; `frameIndex` is a 0-based 24 fps frame from 1 to `frames - 2` (pass `frames`: `duration` snaps to the 124 + n*17 grid); images upload to `keyframeImage1..N` in order (r2v references keep their `contextImage` slots); the prompt must describe each keyframe, never label it, and cut to a new shot where framing or light changes (see `llms.txt`) |
+| MiniMax H3 intermediate keyframes | every H3 id except `*_t2v*`: `*_i2v*`, `*_flf2v*`, `*_ia2v*`, `*_flfa2v*`, `*_a2v*`, `*_r2v*` (`isMinimaxH3KeyframeModel`, 21 ids) | optional `keyframes: [{ image, frameIndex }]`, up to 8, alongside the workflow's own uploads; `frameIndex` is a 0-based 24 fps frame from 1 to `frames - 2` (pass `frames`: `duration` snaps to the 124 + n*17 grid); images upload to `keyframeImage1..N` in order (r2v references keep their `contextImage` slots); the prompt names each keyframe `<Picture N>` after the workflow's own pictures, lists it in the alignment line (r2v: keyframe entry, `keyframe completion` task, retention entry), describes what it shows, and cuts to a new shot where framing or light changes (see `llms.txt`) |
 | Reference-to-Video | `*_r2v*` (Happy Horse) | 1-9 images via `referenceImage`/`referenceImageUrls` |
 | Video-to-Video | `*_v2v*` (LTX-2.3) | `referenceVideo` + `controlNet` |
 | Sound-to-Video | `*_s2v*` (WAN only) | `referenceImage` + `referenceAudio` |

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [5.58.1](https://github.com/Sogni-AI/sogni-client/compare/v5.58.0...v5.58.1) (2026-09-27)
+
+
+### Bug Fixes
+
+* **minimax-h3:** name keyframes as <Picture N> in the prompt guidance ([db85ad7](https://github.com/Sogni-AI/sogni-client/commit/db85ad709e6764c9b0b8fe3da60e18edccff69f2))
+
 # [5.58.0](https://github.com/Sogni-AI/sogni-client/compare/v5.57.0...v5.58.0) (2026-09-27)
 
 

package/README.md

@@ -1065,7 +1065,7 @@ When creating video projects, you can specify:
 - `referenceVideoDurations` - Optional MiniMax H3 r2v duration hints in `[referenceVideo, ...referenceVideos]` order for early client-side validation; Socket probes the uploaded files and uses measured durations for pricing and admission
 - `referenceAudio` - Reference audio for sound-to-video workflows (s2v, ia2v, flfa2v, a2v)
 - `referenceImageEnd` - Last frame for i2v, flf2v and the MiniMax H3 FastH3 flfa2v audio-guide workflow
-- `keyframes` - Every MiniMax H3 workflow except t2v (21 ids, `isMinimaxH3KeyframeModel()`: i2v and flf2v on every tier, Sound to Video ia2v/flfa2v/a2v, and Ref2VA r2v): up to `MINIMAX_H3_MAX_KEYFRAMES` (8) `{ image, frameIndex }` stills pinned between the first and last frame. `frameIndex` is the 0-based frame at 24 fps (`Math.round(seconds * 24)`), an integer from 1 to `frames - 2`, each frame used once. Pass `frames` from the H3 grid (124, 141, 158, … 362) so the count is exact: `duration` snaps to the grid (`duration: 6` renders 141 frames, not 144). Frame 0 and the last frame are never keyframes: i2v, flf2v and flfa2v set them with `referenceImage` / `referenceImageEnd`, ia2v sets frame 0 with `referenceImage`, and a2v and r2v cannot pin them. H3 never sees the keyframe images as references, so the prompt must describe what each keyframe shows at its time; keyframes are never labelled, and on r2v `<Picture N>` / `<Subject N>` refer to the references only. On Sound to Video the audio drives the performance and keyframes pin how it looks at their times. When a keyframe changes the framing, camera angle, location or light, start a new shot (a hard cut) in the prompt at its time: two differently framed or lit stills inside one continuous shot cross-fade, and a shot described differently from its still can flash the still for a single frame. Images upload to their own `keyframeImage1..N` slots in array order, so r2v sends its references (`referenceImage`, `contextImages`) and keyframes together. If no worker serving the model can pin keyframes yet, the job is refused with error code `4100` MiniMax H3 keyframe pricing: the first two keyframes are included; each extra keyframe adds output time at the job's per-second rate, 0.75 s on FastH3 and 0.3 s on every other tier (an 8 s FastH3 clip with 8 keyframes: 32 + 18 = 50 Spark). Pass `keyframeCount` (or the job's `keyframes`) to `estimateVideoCost` to quote it.
+- `keyframes` - Every MiniMax H3 workflow except t2v (21 ids, `isMinimaxH3KeyframeModel()`: i2v and flf2v on every tier, Sound to Video ia2v/flfa2v/a2v, and Ref2VA r2v): up to `MINIMAX_H3_MAX_KEYFRAMES` (8) `{ image, frameIndex }` stills pinned between the first and last frame. `frameIndex` is the 0-based frame at 24 fps (`Math.round(seconds * 24)`), an integer from 1 to `frames - 2`, each frame used once. Pass `frames` from the H3 grid (124, 141, 158, … 362) so the count is exact: `duration` snaps to the grid (`duration: 6` renders 141 frames, not 144). Frame 0 and the last frame are never keyframes: i2v, flf2v and flfa2v set them with `referenceImage` / `referenceImageEnd`, ia2v sets frame 0 with `referenceImage`, and a2v and r2v cannot pin them. The prompt names each keyframe `<Picture N>` (MiniMax's keyframe format), numbered in time order after the workflow's own pictures: after the first frame on i2v and ia2v (after the last frame on a last-frame-only i2v job), after the first and last frames on flf2v and flfa2v, from `<Picture 1>` on a2v, and after the reference images on r2v; keyframes still never count as references. i2v, flf2v and Sound to Video prompts open with one alignment line listing every picture at its mark (`How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot 2) aligns with the 2.88-second mark of the target video.`), the shot where a keyframe lands says "the shot's keyframe corresponds to `<Picture N>`", and r2v adds a `<Picture N> is the keyframe of [Shot M], showing ...` entry, `keyframe completion` in the summary tasks and a `<Picture N> ([Shot M] keyframe): fully_preserved - ...` retention entry. H3's text encoder never sees the keyframe images, so the prompt must still describe what each keyframe shows at its time. On Sound to Video the audio drives the performance and keyframes pin how it looks at their times. When a keyframe changes the framing, camera angle, location or light, start a new shot (a hard cut) in the prompt at its time: two differently framed or lit stills inside one continuous shot cross-fade, and a shot described differently from its still can flash the still for a single frame. Images upload to their own `keyframeImage1..N` slots in array order, so r2v sends its references (`referenceImage`, `contextImages`) and keyframes together. If no worker serving the model can pin keyframes yet, the job is refused with error code `4100` MiniMax H3 keyframe pricing: the first two keyframes are included; each extra keyframe adds output time at the job's per-second rate, 0.75 s on FastH3 and 0.3 s on every other tier (an 8 s FastH3 clip with 8 keyframes: 32 + 18 = 50 Spark). Pass `keyframeCount` (or the job's `keyframes`) to `estimateVideoCost` to quote it.
 - `referenceImageUrls` - Loose image context URLs for Seedance, Happy Horse, and Wan 3; Wan 3 accepts up to 10
 - `referenceVideoUrls` - Loose video context URLs for Seedance and Wan 3; Wan 3 accepts up to 5
 - `referenceAudioUrls` - Loose audio context URLs for Seedance and Wan 3; Wan 3 accepts up to 5

package/dist/Projects/types/index.d.ts

@@ -159,8 +159,9 @@ export type InputMedia = File | Buffer | Blob | boolean;
  */
 export interface MinimaxH3Keyframe {
     /**
-     * The still image the video passes through at `frameIndex`. H3 never sees it
-     * as a reference, so the prompt must describe what it shows at that time.
+     * The still image the video passes through at `frameIndex`. The prompt names
+     * it `<Picture N>` and describes what it shows at that time: H3's text
+     * encoder never sees the image, which only pins the frame.
      */
     image: InputMedia;
     /**
@@ -268,15 +269,29 @@ export interface MinimaxH3Keyframe {
  *   `ia2v` sets frame 0 with `referenceImage`, and `a2v` and `r2v` cannot pin
  *   them. Each workflow keeps its own uploads, and `contextImages` stays
  *   r2v-only.
- * - H3 never sees the keyframe images as references, so the prompt must
- *   describe what each keyframe shows at its time. Keyframes are never
- *   labelled: the `i2v`/`flf2v` alignment line names only the first and last
- *   frame, and on `r2v` `<Picture N>` and `<Subject N>` refer to the
- *   references only. On Sound to Video the audio drives the performance, and
- *   keyframes pin how it looks at their times.
+ * - The prompt names each keyframe `<Picture N>` (MiniMax's keyframe format),
+ *   numbered in time order after the workflow's own pictures: after the first
+ *   frame on `i2v` and `ia2v` (after the last frame on a last-frame-only `i2v`
+ *   job), after the first and last frames on `flf2v` and `flfa2v`, from
+ *   `<Picture 1>` on `a2v`, and after the reference images on `r2v`.
+ *   Keyframes still never count as references.
+ * - `i2v`, `flf2v` and Sound to Video prompts open with one alignment line
+ *   listing every picture at its mark, in time order: `How the reference
+ *   pictures align with the target video — Picture 1 (from Shot 1) aligns with
+ *   the 0.00-second mark of the target video; Picture 2 (from Shot 2) aligns
+ *   with the 2.88-second mark of the target video.` The shot where a keyframe
+ *   lands says "the shot's keyframe corresponds to `<Picture N>`". `r2v` adds
+ *   `<Picture N> is the keyframe of [Shot M], showing ...` to
+ *   `subject_definitions`, `keyframe completion` to the summary tasks and
+ *   `<Picture N> ([Shot M] keyframe): fully_preserved - ...` to
+ *   `retention_analysis`.
+ * - H3's text encoder never sees the keyframe images, so the prompt must still
+ *   describe what each keyframe shows at its time. On Sound to Video the audio
+ *   drives the performance, and keyframes pin how it looks at their times.
  * - When a keyframe changes the framing, camera angle, location or light, the
- *   prompt must start a new shot (a hard cut, `[Shot N] At MM:SS.mmm, ...`) at
- *   its time, `frameIndex / 24` seconds. Two differently framed or lit stills
+ *   prompt must start a new shot (a hard cut, `[Shot N] At MM:SS.mmm, the
+ *   camera cuts to ..., whose keyframe corresponds to <Picture N>.`) at its
+ *   time, `frameIndex / 24` seconds. Two differently framed or lit stills
  *   inside one continuous shot cross-fade into each other, and a shot described
  *   differently from its still can flash the still for a single frame.
  * - `keyframes[i].image` uploads to its own `keyframeImage<i+1>` slot and the
@@ -538,11 +553,14 @@ export interface VideoProjectParams extends BaseProjectParams {
      * sets frame 0 with `referenceImage`, and `a2v` and `r2v` cannot pin them.
      * Every workflow keeps its own upload rules.
      *
-     * H3 never sees the keyframe images as references, so the prompt must describe
-     * what each one shows at its time. Keyframes are never labelled: on `r2v`,
-     * `<Picture N>` and `<Subject N>` refer to the references only. On Sound to
-     * Video the audio drives the performance, and keyframes pin how it looks at
-     * their times. When a keyframe changes the framing, camera angle, location or
+     * The prompt names each keyframe `<Picture N>`, numbered in time order after
+     * the workflow's own pictures (the first and last frames, or the `r2v`
+     * reference images), lists it in the alignment line (`r2v`: a keyframe entry,
+     * the `keyframe completion` task and a retention entry), and describes what
+     * it shows at its time, since H3's text encoder never sees the keyframe
+     * images. Keyframes still never count as references. On Sound to Video the
+     * audio drives the performance, and keyframes pin how it looks at their
+     * times. When a keyframe changes the framing, camera angle, location or
      * light, start a new shot (a hard cut) at its time, `frameIndex / 24` seconds:
      * two differently framed or lit stills inside one continuous shot cross-fade
      * into each other, and a shot described differently from its still can flash

package/dist/Projects/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/Projects/types/index.ts"],"names":[],"mappings":";;AAilCA,sCAEC;AAED,sCAEC;AAED,sCAEC;AAVD,SAAgB,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,SAAgB,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,SAAgB,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/Projects/types/index.ts"],"names":[],"mappings":";;AAmmCA,sCAEC;AAED,sCAEC;AAED,sCAEC;AAVD,SAAgB,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,SAAgB,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,SAAgB,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC"}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const LIB_VERSION = "5.58.0";
+export declare const LIB_VERSION = "5.58.1";

package/dist/version.js

@@ -3,5 +3,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LIB_VERSION = void 0;
 // AUTO-GENERATED by scripts/generate-version.mjs — do not edit.
 // Source of truth: package.json version.
-exports.LIB_VERSION = '5.58.0';
+exports.LIB_VERSION = '5.58.1';
 //# sourceMappingURL=version.js.map

package/dist-esm/Projects/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/Projects/types/index.ts"],"names":[],"mappings":"AAilCA,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/Projects/types/index.ts"],"names":[],"mappings":"AAmmCA,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;AACjC,CAAC"}

package/dist-esm/version.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/generate-version.mjs — do not edit.
 // Source of truth: package.json version.
-export const LIB_VERSION = '5.58.0';
+export const LIB_VERSION = '5.58.1';
 //# sourceMappingURL=version.js.map

package/llms-full.txt

@@ -1071,18 +1071,33 @@ to its own `keyframeImage<i+1>` slot in array order and the indices travel as
 together. If no worker serving the model can pin keyframes yet, the job is
 refused with error code `4100`. MiniMax H3 keyframe pricing: the first two keyframes are included; each extra keyframe adds output time at the job's per-second rate, 0.75 s on FastH3 and 0.3 s on every other tier (an 8 s FastH3 clip with 8 keyframes: 32 + 18 = 50 Spark). Pass `keyframeCount` (or the job's `keyframes`) to `estimateVideoCost` to quote it.
 
-Prompts for keyframes: H3 never sees the keyframe images as references, so the
-prompt must describe what each keyframe shows at its time. Keyframes are never
-labelled: the I2V/FLF2V alignment line still names only the first and last
-frame, and on R2V `<Picture N>` and `<Subject N>` refer to the references only.
-On Sound to Video the uploaded audio drives the performance and keyframes pin
-how it looks at their times. When a keyframe changes the framing, camera angle,
-location or light,
-start a new shot (a hard cut) at its time: `[Shot N] At MM:SS.mmm, ...`, where
-the time is `frameIndex / 24` seconds (frame 144 is `00:06.000`). Two
-differently framed or lit stills inside one continuous shot cross-fade into each
-other, and a shot described differently from its still can flash the still for
-a single frame.
+Prompts for keyframes (MiniMax's keyframe format): name each keyframe
+`<Picture N>`, numbered in time order after the workflow's own pictures: after
+the first frame `<Picture 1>` on I2V and IA2V (after the last frame
+`<Picture 1>` on a last-frame-only I2V job), after `<Picture 1>` (first) and
+`<Picture 2>` (last) on FLF2V and FLFA2V, from `<Picture 1>` on A2V, and after
+the last reference image `<Picture N>` on R2V. Keyframes are still not
+references and never count toward the reference limits. I2V, FLF2V and Sound to
+Video prompts open with one alignment line listing every picture at its mark
+(`frameIndex / 24` seconds, two decimals; a last frame at the clip's end), in
+time order, each credited to the shot on screen there: `How the reference
+pictures align with the target video — Picture 1 (from Shot 1) aligns with the
+0.00-second mark of the target video; Picture 2 (from Shot 2) aligns with the
+2.88-second mark of the target video.` The shot where a keyframe lands says
+"the shot's keyframe corresponds to `<Picture N>`". R2V adds
+`<Picture N> is the keyframe of [Shot M], showing ...` to
+`subject_definitions`, `keyframe completion` to the summary tasks, and
+`<Picture N> ([Shot M] keyframe): fully_preserved - ...` to
+`retention_analysis`. H3's text encoder never sees the keyframe images (they
+only pin frames), so the prompt must still describe what each keyframe shows at
+its time. On Sound to Video the uploaded audio drives the performance and
+keyframes pin how it looks at their times. When a keyframe changes the framing,
+camera angle, location or light, start a new shot (a hard cut) at its time:
+`[Shot N] At MM:SS.mmm, the camera cuts to ..., whose keyframe corresponds to
+<Picture N>.`, where the time is `frameIndex / 24` seconds (frame 144 is
+`00:06.000`). Two differently framed or lit stills inside one continuous shot
+cross-fade into each other, and a shot described differently from its still can
+flash the still for a single frame.
 
 FASTH3 AUDIO GUIDE (`minimax-h3-fastvideo-int8_ia2v_turbo`,
 `minimax-h3-fastvideo-int8_flfa2v_turbo`, `minimax-h3-fastvideo-int8_a2v_turbo`
@@ -1277,8 +1292,8 @@ Ref2VA uses six sections in exact order: `subject_definitions`, `summary`,
 `retention_analysis`, `detailed_description`, `overall_soundscape`, and
 `non_diegetic_music`. Use `<Subject N>` for reusable visible content abstracted
 from a reference. Reserve standalone `<Picture N>` for a reference image used
-as a concrete keyframe or composition anchor (MiniMax's wording; images passed
-in `keyframes` are never labelled); a still used only for identity, wardrobe, environment, or
+as a concrete keyframe or composition anchor (MiniMax's wording; each image
+passed in `keyframes` is one, numbered after the reference images); a still used only for identity, wardrobe, environment, or
 style belongs in a `<Subject N>` definition. `<Video N>` represents whole-video
 structure and `<Audio N>` represents copied or referenced audio. Keep labels
 stable across all sections. `summary` begins with official task types such as

package/llms.txt

@@ -548,14 +548,20 @@ Intermediate keyframes: every H3 workflow except text-to-video accepts `keyframe
 
 Writing the prompt for keyframes:
 
-- H3 never sees the keyframe images as references, so the prompt must describe what each keyframe shows at its time. Keyframes are never labelled: the I2V/FLF2V alignment line still names only the first and last frame, and on R2V `<Picture N>` and `<Subject N>` refer to the references only.
+- Name each keyframe `<Picture N>` (MiniMax's keyframe format), numbered in time order after the workflow's own pictures: after the first frame `<Picture 1>` on I2V and IA2V (after the last frame `<Picture 1>` on a last-frame-only I2V job), after `<Picture 1>` (first) and `<Picture 2>` (last) on FLF2V and FLFA2V, from `<Picture 1>` on A2V, and after the last reference image `<Picture N>` on R2V. Keyframes are still not references and never count toward the reference limits.
+- I2V, FLF2V and Sound to Video prompts open with one alignment line listing every picture at its mark (`frameIndex / 24` seconds, two decimals; a last frame at the clip's end), in time order, each credited to the shot on screen there: `How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot 2) aligns with the 2.88-second mark of the target video.` The shot where a keyframe lands says "the shot's keyframe corresponds to `<Picture N>`".
+- R2V adds `<Picture N> is the keyframe of [Shot M], showing ...` to `subject_definitions`, `keyframe completion` to the summary tasks (as in `[reference generation + keyframe completion]`), and `<Picture N> ([Shot M] keyframe): fully_preserved - ...` to `retention_analysis`.
+- H3's text encoder never sees the keyframe images (they only pin frames), so the prompt must still describe what each keyframe shows at its time: shot size, camera angle, where each subject stands, pose, setting and light.
 - On Sound to Video the uploaded audio drives the performance; keyframes pin how it looks at their times, so describe the look at each keyframe's time and let the audio carry timing and delivery.
-- When a keyframe changes the framing, camera angle, location or light, start a new shot (a hard cut) at its time: `[Shot N] At MM:SS.mmm, ...`, where the time is `frameIndex / 24` seconds (frame 144 is `00:06.000`). Two differently framed or lit stills inside one continuous shot cross-fade into each other, and a shot described differently from its still can flash the still for a single frame.
+- When a keyframe changes the framing, camera angle, location or light, start a new shot (a hard cut) at its time: `[Shot N] At MM:SS.mmm, the camera cuts to ..., whose keyframe corresponds to <Picture N>.`, where the time is `frameIndex / 24` seconds (frame 144 is `00:06.000`). Two differently framed or lit stills inside one continuous shot cross-fade into each other, and a shot described differently from its still can flash the still for a single frame.
 
 ```javascript
 // 192 frames (8 s): frame 0 is referenceImage, frame 191 is referenceImageEnd.
-// flf2vPrompt describes keyframe 1 inside [Shot 1] at 00:02.500 and starts
-// [Shot 2] At 00:06.000 with the new camera angle keyframe 2 shows.
+// The keyframes are <Picture 3> and <Picture 4>, after the first and last
+// frames. flf2vPrompt opens with the alignment line (Picture 1 at 0.00, Picture
+// 3 at 2.50, Picture 4 at 6.00, Picture 2 at 8.00), says "the shot's keyframe
+// corresponds to <Picture 3>" inside [Shot 1], and starts [Shot 2] At
+// 00:06.000 with the new camera angle <Picture 4> shows.
 const project = await sogni.projects.create({
   type: 'video',
   network: 'fast',
@@ -626,7 +632,7 @@ const project = await sogni.projects.create({
 
 MiniMax's [official H3 prompt-writing skill](https://github.com/MiniMax-AI/MiniMax-H3/tree/main/skills/h3-prompt-writing) makes Context-IR part of the prompt contract. T2V, I2V, L2V, and FLF2V use `integrated_multimodal_description`, `overall_soundscape`, then `non_diegetic_music`, in that exact order. Frame-conditioned modes prepend their official image-alignment line. I2V anchors `<Picture 1>` at 0.00 seconds; L2V uses `How the reference pictures align with the target video — <Picture 1> (from [Shot N]) aligns with the S.SS-second mark of the target video.`; FLF2V aligns both endpoints. Use `[Shot 1]` without a timestamp, then `[Shot N] At MM:SS.mmm, ...` for later cuts. Speakers keep stable `(S1)` IDs and exact spoken words go in `<d>[Language] ...</d>`. Write the structural sections in English while preserving dialogue, lyrics, and visible text in their original language. Use `non_diegetic_music: N/A` when there is no audience-only score.
 
-Ref2VA (`_r2v`) is a separate checkpoint with no frame anchors, so `referenceImageEnd` is rejected; intermediate `keyframes` still work (see above) and never take a `<Picture N>` label. It runs on a Sogni worker, so every artist reference uses the normal S3 upload path: `referenceImage` plus `contextImages`, `referenceVideo` plus `referenceVideos`, and `referenceAudio` plus `referenceAudios`. Direct URL arrays are rejected. `referenceVideoDurations` is optional early-validation metadata in matching video order. If supplied, each hint must be 2-15 seconds and all hints may total at most 15 seconds; if omitted, project submission still proceeds. Socket always probes the uploaded files, overwrites caller claims, and uses measured durations for pricing and admission. At least one visual reference (image or video) is required; audio alone is rejected. Its prompt uses six ordered sections: `subject_definitions`, `summary`, `retention_analysis`, `detailed_description`, `overall_soundscape`, `non_diegetic_music`. Use `<Subject N>` for reusable visible content, `<Picture N>` only for concrete keyframes/composition anchors, `<Video N>` for whole-video structure, and `<Audio N>` for copied or referenced audio.
+Ref2VA (`_r2v`) is a separate checkpoint with no frame anchors, so `referenceImageEnd` is rejected; intermediate `keyframes` still work (see above) and are named `<Picture N>` after the reference images, without counting as references. It runs on a Sogni worker, so every artist reference uses the normal S3 upload path: `referenceImage` plus `contextImages`, `referenceVideo` plus `referenceVideos`, and `referenceAudio` plus `referenceAudios`. Direct URL arrays are rejected. `referenceVideoDurations` is optional early-validation metadata in matching video order. If supplied, each hint must be 2-15 seconds and all hints may total at most 15 seconds; if omitted, project submission still proceeds. Socket always probes the uploaded files, overwrites caller claims, and uses measured durations for pricing and admission. At least one visual reference (image or video) is required; audio alone is rejected. Its prompt uses six ordered sections: `subject_definitions`, `summary`, `retention_analysis`, `detailed_description`, `overall_soundscape`, `non_diegetic_music`. Use `<Subject N>` for reusable visible content, `<Picture N>` only for concrete keyframes/composition anchors, `<Video N>` for whole-video structure, and `<Audio N>` for copied or referenced audio.
 
 ```javascript
 const project = await sogni.projects.create({

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "5.58.0",
+  "version": "5.58.1",
   "engines": {
     "node": ">=22"
   },

package/src/Projects/types/index.ts

@@ -177,8 +177,9 @@ export type InputMedia = File | Buffer | Blob | boolean;
  */
 export interface MinimaxH3Keyframe {
   /**
-   * The still image the video passes through at `frameIndex`. H3 never sees it
-   * as a reference, so the prompt must describe what it shows at that time.
+   * The still image the video passes through at `frameIndex`. The prompt names
+   * it `<Picture N>` and describes what it shows at that time: H3's text
+   * encoder never sees the image, which only pins the frame.
    */
   image: InputMedia;
   /**
@@ -287,15 +288,29 @@ export interface MinimaxH3Keyframe {
  *   `ia2v` sets frame 0 with `referenceImage`, and `a2v` and `r2v` cannot pin
  *   them. Each workflow keeps its own uploads, and `contextImages` stays
  *   r2v-only.
- * - H3 never sees the keyframe images as references, so the prompt must
- *   describe what each keyframe shows at its time. Keyframes are never
- *   labelled: the `i2v`/`flf2v` alignment line names only the first and last
- *   frame, and on `r2v` `<Picture N>` and `<Subject N>` refer to the
- *   references only. On Sound to Video the audio drives the performance, and
- *   keyframes pin how it looks at their times.
+ * - The prompt names each keyframe `<Picture N>` (MiniMax's keyframe format),
+ *   numbered in time order after the workflow's own pictures: after the first
+ *   frame on `i2v` and `ia2v` (after the last frame on a last-frame-only `i2v`
+ *   job), after the first and last frames on `flf2v` and `flfa2v`, from
+ *   `<Picture 1>` on `a2v`, and after the reference images on `r2v`.
+ *   Keyframes still never count as references.
+ * - `i2v`, `flf2v` and Sound to Video prompts open with one alignment line
+ *   listing every picture at its mark, in time order: `How the reference
+ *   pictures align with the target video — Picture 1 (from Shot 1) aligns with
+ *   the 0.00-second mark of the target video; Picture 2 (from Shot 2) aligns
+ *   with the 2.88-second mark of the target video.` The shot where a keyframe
+ *   lands says "the shot's keyframe corresponds to `<Picture N>`". `r2v` adds
+ *   `<Picture N> is the keyframe of [Shot M], showing ...` to
+ *   `subject_definitions`, `keyframe completion` to the summary tasks and
+ *   `<Picture N> ([Shot M] keyframe): fully_preserved - ...` to
+ *   `retention_analysis`.
+ * - H3's text encoder never sees the keyframe images, so the prompt must still
+ *   describe what each keyframe shows at its time. On Sound to Video the audio
+ *   drives the performance, and keyframes pin how it looks at their times.
  * - When a keyframe changes the framing, camera angle, location or light, the
- *   prompt must start a new shot (a hard cut, `[Shot N] At MM:SS.mmm, ...`) at
- *   its time, `frameIndex / 24` seconds. Two differently framed or lit stills
+ *   prompt must start a new shot (a hard cut, `[Shot N] At MM:SS.mmm, the
+ *   camera cuts to ..., whose keyframe corresponds to <Picture N>.`) at its
+ *   time, `frameIndex / 24` seconds. Two differently framed or lit stills
  *   inside one continuous shot cross-fade into each other, and a shot described
  *   differently from its still can flash the still for a single frame.
  * - `keyframes[i].image` uploads to its own `keyframeImage<i+1>` slot and the
@@ -560,11 +575,14 @@ export interface VideoProjectParams extends BaseProjectParams {
    * sets frame 0 with `referenceImage`, and `a2v` and `r2v` cannot pin them.
    * Every workflow keeps its own upload rules.
    *
-   * H3 never sees the keyframe images as references, so the prompt must describe
-   * what each one shows at its time. Keyframes are never labelled: on `r2v`,
-   * `<Picture N>` and `<Subject N>` refer to the references only. On Sound to
-   * Video the audio drives the performance, and keyframes pin how it looks at
-   * their times. When a keyframe changes the framing, camera angle, location or
+   * The prompt names each keyframe `<Picture N>`, numbered in time order after
+   * the workflow's own pictures (the first and last frames, or the `r2v`
+   * reference images), lists it in the alignment line (`r2v`: a keyframe entry,
+   * the `keyframe completion` task and a retention entry), and describes what
+   * it shows at its time, since H3's text encoder never sees the keyframe
+   * images. Keyframes still never count as references. On Sound to Video the
+   * audio drives the performance, and keyframes pin how it looks at their
+   * times. When a keyframe changes the framing, camera angle, location or
    * light, start a new shot (a hard cut) at its time, `frameIndex / 24` seconds:
    * two differently framed or lit stills inside one continuous shot cross-fade
    * into each other, and a shot described differently from its still can flash

package/src/version.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED by scripts/generate-version.mjs — do not edit.
 // Source of truth: package.json version.
-export const LIB_VERSION = '5.58.0';
+export const LIB_VERSION = '5.58.1';