@sogni-ai/sogni-client 5.78.0 → 5.80.0

package/src/Projects/types/index.ts

@@ -875,14 +875,100 @@ export interface Sam3PromptBox {
   label?: 'positive' | 'negative';
 }
 
-/** A bounded prompt for the SAM3 image-segmentation workflow. */
+/**
+ * A selection made from a drawn region instead of clicks, boxes or text. The
+ * region starts the tracker on the prompt frame, as a click does, so that
+ * frame's mask is the tracker's own shape for the region rather than the exact
+ * drawing, consistent with the frames around it. Draw it tight: background or
+ * a foreground object inside the region stays in the mask for several frames.
+ */
+export interface Sam3PromptMask {
+  /**
+   * 1 to 64 rings of `[x, y]` points, each 3 to 2048 points and 4096 points in
+   * total; a whole prompt holds at most 4096 across its objects and frames.
+   * Coordinates are normalized to the source frame (0 to 1, origin top
+   * left). Rings fill even-odd: a ring inside another ring is a hole.
+   */
+  polygons: Array<Array<[number, number]>>;
+}
+
+/**
+ * One object to select in a video: exactly one of `points` (with at most one
+ * box), `boxes`, `text` (with optional signed boxes) or `mask`.
+ */
+export interface Sam3VideoSelection extends Pick<
+  Sam3ImagePrompt,
+  'points' | 'boxes' | 'text' | 'threshold' | 'multimask'
+> {
+  /**
+   * Select this drawn region. Not combinable with `points`, `boxes`, `text`,
+   * `threshold` or `multimask`; `objectIndex` must be 0 or absent.
+   */
+  mask?: Sam3PromptMask;
+  /** Zero-based candidate in confidence order. Defaults to the best match. */
+  objectIndex?: number;
+}
+
+/** One prompted frame of `Sam3VideoPrompt.frames`: a selection plus the source frame it refers to. */
+export type Sam3VideoFramePrompt = Sam3VideoSelection & {
+  /** Zero-based source frame. Each entry names a different frame. */
+  frameIndex: number;
+};
+
+/**
+ * A bounded prompt for SAM 3 video selection. Output is one hard binary mask
+ * video. By default it selects one object (`points`, `boxes` or `text`) on one
+ * frame and tracks it through the clip.
+ *
+ * `mask`, `objects`, `frames` and `memory` are optional and absent by default;
+ * a prompt without them behaves exactly as before.
+ */
 export interface Sam3VideoPrompt extends Omit<Sam3ImagePrompt, 'applyMask' | 'maxInstances'> {
-  /** Zero-based source frame the selection refers to. Defaults to 0. */
+  /**
+   * Zero-based source frame the selection refers to. Defaults to 0. Not used
+   * with `frames`, where each entry carries its own.
+   */
   frameIndex?: number;
-  /** Zero-based candidate in confidence order. Defaults to the best match. */
+  /** Zero-based text candidate or supplied box. Point prompts require 0. Defaults to 0. */
   objectIndex?: number;
   output?: 'mask';
   edges?: 'hard';
+  /**
+   * Select a drawn region on the prompt frame instead of `points`, `boxes` or
+   * `text`. Not combinable with them, nor with `threshold` or `multimask`;
+   * `objectIndex` must be 0 or absent.
+   */
+  mask?: Sam3PromptMask;
+  /**
+   * Track 2 to 16 objects together and merge them into one mask: a crowd, a
+   * figure plus the prop it holds, a monitor plus the webcam on it. Every
+   * object is selected on `frameIndex` and tracked jointly; every output frame
+   * is the union of their masks. Requires `combine: 'union'`. Put each object's
+   * selection inside its entry: the top-level `points`, `boxes`, `text`,
+   * `mask`, `threshold`, `multimask` and `objectIndex` are rejected alongside
+   * `objects`, and so is `frames`.
+   */
+  objects?: Sam3VideoSelection[];
+  /** How `objects` combine into the output. Required with `objects`; `'union'` is the only value. */
+  combine?: 'union';
+  /**
+   * Prompt the same object on 2 to 8 different source frames. Each output frame
+   * takes the track from the nearest prompted frame (ties go to the earlier
+   * one), so the whole clip is still tracked about once. Use it for a loop
+   * whose last frame repeats its first (prompt frame 0 and the last frame with
+   * the same selection), or to correct drift mid-clip. Rejected together with
+   * the top-level `frameIndex`, the top-level selection fields and `objects`.
+   */
+  frames?: Sam3VideoFramePrompt[];
+  /**
+   * How tracking carries from one 32-frame chunk to the next. `'chunk'` (the
+   * default, the original behaviour) seeds each chunk from the previous chunk's
+   * last mask; an object lost at the end of a chunk is not found again.
+   * `'anchor'` tracks every chunk from the prompt frame and its selection
+   * instead, so tracking errors do not carry from chunk to chunk and a lost
+   * object can be picked up again, but the mask can shift where a chunk starts.
+   */
+  memory?: 'chunk' | 'anchor';
 }
 
 export interface Sam3ImagePrompt {
@@ -1408,6 +1494,12 @@ export interface VideoEstimateRequest {
   keyframeCount?: number;
   /** The job's `keyframes`; only their count is used, to price them. */
   keyframes?: readonly unknown[];
+  /**
+   * SAM 3 video selection: the job's own `sam3VideoPrompt`. Only the options that
+   * change its price are sent: the number of `objects` and the `memory` mode. A
+   * prompt without them quotes exactly as before.
+   */
+  sam3VideoPrompt?: Sam3VideoPrompt;
   /**
    * Combined duration of MiniMax H3 r2v reference-video input, in seconds.
    * The estimate bills it at the selected output resolution/tier rate.

package/src/index.ts

@@ -67,7 +67,10 @@ import {
   Pixal3dTemplateVariant,
   Sam3ImagePrompt,
   Sam3VideoPrompt,
+  Sam3VideoSelection,
+  Sam3VideoFramePrompt,
   Sam3PromptBox,
+  Sam3PromptMask,
   Sam3PromptPoint,
   Sam3Selection,
   ProjectParams,
@@ -360,7 +363,10 @@ export type {
   Pixal3dTemplateVariant,
   Sam3ImagePrompt,
   Sam3VideoPrompt,
+  Sam3VideoSelection,
+  Sam3VideoFramePrompt,
   Sam3PromptBox,
+  Sam3PromptMask,
   Sam3PromptPoint,
   Sam3Selection,
   JobStatus,

package/src/lib/getUUID.ts

@@ -1,8 +1,37 @@
-import { v4 as uuidV4 } from '@lukeed/uuid';
+// Two hex digits per byte, ES6-safe (no padStart in this package's lib target).
+const HEX: string[] = [];
+for (let byte = 0; byte < 256; byte++) HEX.push((byte + 256).toString(16).slice(1));
 
-// Mac app is using uppercase UUIDs, we need to keep it consistent so Mac workers can process the data
-function getUUID() {
-  return uuidV4().toUpperCase();
+/**
+ * A random (version 4) UUID drawn from the runtime's cryptographically secure
+ * generator. `crypto.randomUUID()` exists in Node.js and in browser pages served
+ * over HTTPS or localhost; a page served over plain HTTP has only
+ * `crypto.getRandomValues()`, so the same version 4 layout is built from it.
+ * A runtime with neither cannot produce an unpredictable id and throws: there
+ * is no Math.random fallback.
+ *
+ * Uppercase, because the Mac app uses uppercase UUIDs and Mac workers must be
+ * able to process the data.
+ */
+function getUUID(): string {
+  const webCrypto: Partial<Crypto> | undefined = globalThis.crypto;
+  if (typeof webCrypto?.randomUUID === 'function') {
+    return webCrypto.randomUUID().toUpperCase();
+  }
+  if (typeof webCrypto?.getRandomValues === 'function') {
+    const bytes = webCrypto.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 9562 variant
+    let out = '';
+    for (let i = 0; i < 16; i++) {
+      out += HEX[bytes[i]];
+      if (i === 3 || i === 5 || i === 7 || i === 9) out += '-';
+    }
+    return out.toUpperCase();
+  }
+  throw new Error(
+    'Sogni SDK: this runtime has no Web Crypto API (globalThis.crypto), so it cannot generate secure IDs'
+  );
 }
 
 export default getUUID;

package/src/lib/validation.ts

@@ -43,12 +43,9 @@ export function validateGptImageOptions(params: ImageProjectParams): void {
       throw new Error('Unsupported GPT Image complexity');
     if (
       advancedFormat &&
-      (params.contextImages?.length ||
-        params.gptImageMask ||
-        params.gptImageMaskUrl ||
-        params.gptImageMarkupUrl)
+      (params.gptImageMask || params.gptImageMaskUrl || params.gptImageMarkupUrl)
     )
-      throw new Error('GIF output require text-to-image generation');
+      throw new Error('GIF output cannot combine with masks or markup');
     if (
       params.outputFormat !== 'gif' &&
       (params.gptImageFrameCount !== undefined || params.gptImageFrameDurationMs !== undefined)

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.78.0';
+export const LIB_VERSION = '5.80.0';