@sogni-ai/sogni-client 5.32.0 → 5.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/dist/ApiClient/WebSocketClient/events.d.ts +10 -0
  3. package/dist/Projects/createJobRequestMessage.js +65 -5
  4. package/dist/Projects/createJobRequestMessage.js.map +1 -1
  5. package/dist/Projects/index.js +43 -0
  6. package/dist/Projects/index.js.map +1 -1
  7. package/dist/Projects/types/JobProvenance.d.ts +15 -0
  8. package/dist/Projects/types/index.d.ts +62 -1
  9. package/dist/Projects/types/index.js.map +1 -1
  10. package/dist/Projects/utils/index.d.ts +17 -0
  11. package/dist/Projects/utils/index.js +24 -1
  12. package/dist/Projects/utils/index.js.map +1 -1
  13. package/dist/index.d.ts +4 -3
  14. package/dist/index.js +30 -22
  15. package/dist/index.js.map +1 -1
  16. package/dist/version.d.ts +1 -1
  17. package/dist/version.js +1 -1
  18. package/dist-esm/Projects/createJobRequestMessage.js +65 -5
  19. package/dist-esm/Projects/createJobRequestMessage.js.map +1 -1
  20. package/dist-esm/Projects/index.js +43 -0
  21. package/dist-esm/Projects/index.js.map +1 -1
  22. package/dist-esm/Projects/types/index.js.map +1 -1
  23. package/dist-esm/Projects/utils/index.js +21 -0
  24. package/dist-esm/Projects/utils/index.js.map +1 -1
  25. package/dist-esm/index.js +2 -1
  26. package/dist-esm/index.js.map +1 -1
  27. package/dist-esm/version.js +1 -1
  28. package/package.json +2 -1
  29. package/src/ApiClient/WebSocketClient/events.ts +10 -0
  30. package/src/Projects/createJobRequestMessage.ts +70 -6
  31. package/src/Projects/index.ts +42 -0
  32. package/src/Projects/types/JobProvenance.ts +16 -0
  33. package/src/Projects/types/index.ts +64 -1
  34. package/src/Projects/utils/index.ts +25 -0
  35. package/src/index.ts +20 -0
  36. package/src/version.ts +1 -1
@@ -77,6 +77,17 @@ const WORLD_TRANSITION_MODEL_ID = 'minimax-h3-fastvideo-int8_flf2v_turbo';
77
77
  const MAX_SAM3_POINTS = 32;
78
78
  const MAX_SAM3_BOXES = 16;
79
79
  const MAX_SAM3_TEXT_LENGTH = 240;
80
+ const MAX_SAM3_INSTANCES = 16;
81
+ // Pixal3D reduce-only options. Each max is the shipped default, so a request
82
+ // can only ever ask for less work than the flat price already covers; the
83
+ // socket and the worker both clamp again.
84
+ const PIXAL3D_REDUCE_ONLY_LIMITS: Record<string, { min: number; max: number }> = {
85
+ textureSize: { min: 1024, max: 4096 },
86
+ meshTargetFaces: { min: 5000, max: 700000 },
87
+ normalMapSize: { min: 512, max: 2048 },
88
+ ambientOcclusionSize: { min: 256, max: 1024 },
89
+ shapeResolution: { min: 1024, max: 1536 }
90
+ };
80
91
 
81
92
  function normalizeWorldGenerationReceipt(params: ProjectParams) {
82
93
  const receipt = params.worldGenerationReceipt;
@@ -1011,12 +1022,21 @@ function getVideoControlNet(params: VideoControlNetParams): VideoControlNetParam
1011
1022
 
1012
1023
  function normalizeSam3Prompt(
1013
1024
  prompt: Sam3ImagePrompt
1014
- ): Required<Pick<Sam3ImagePrompt, 'points' | 'boxes' | 'threshold' | 'multimask'>> &
1015
- Pick<Sam3ImagePrompt, 'text'> {
1025
+ // multimask is emitted only on the point path, so it stays optional here.
1026
+ ): Required<Pick<Sam3ImagePrompt, 'points' | 'boxes' | 'threshold' | 'applyMask'>> &
1027
+ Pick<Sam3ImagePrompt, 'text' | 'multimask' | 'maxInstances'> {
1016
1028
  if (!prompt || typeof prompt !== 'object' || Array.isArray(prompt)) {
1017
1029
  throw new Error('sam3Prompt must be an object');
1018
1030
  }
1019
- const allowedRootKeys = new Set(['points', 'boxes', 'text', 'threshold', 'multimask']);
1031
+ const allowedRootKeys = new Set([
1032
+ 'points',
1033
+ 'boxes',
1034
+ 'text',
1035
+ 'threshold',
1036
+ 'multimask',
1037
+ 'applyMask',
1038
+ 'maxInstances'
1039
+ ]);
1020
1040
  const unknownRootKeys = Object.keys(prompt).filter((key) => !allowedRootKeys.has(key));
1021
1041
  if (unknownRootKeys.length > 0) {
1022
1042
  throw new Error(`sam3Prompt contains unsupported fields: ${unknownRootKeys.join(', ')}`);
@@ -1058,15 +1078,23 @@ function normalizeSam3Prompt(
1058
1078
  if (!box || typeof box !== 'object' || Array.isArray(box)) {
1059
1079
  throw new Error(`sam3Prompt.boxes[${index}] must be an object`);
1060
1080
  }
1061
- const unknown = Object.keys(box).filter((key) => !['x0', 'y0', 'x1', 'y1'].includes(key));
1081
+ const unknown = Object.keys(box).filter(
1082
+ (key) => !['x0', 'y0', 'x1', 'y1', 'label'].includes(key)
1083
+ );
1062
1084
  if (unknown.length > 0) {
1063
1085
  throw new Error(`sam3Prompt.boxes[${index}] contains unsupported fields`);
1064
1086
  }
1087
+ if (box.label !== undefined && box.label !== 'positive' && box.label !== 'negative') {
1088
+ throw new Error(`sam3Prompt.boxes[${index}].label must be "positive" or "negative"`);
1089
+ }
1065
1090
  const normalized = {
1066
1091
  x0: coordinate(box.x0, `sam3Prompt.boxes[${index}].x0`),
1067
1092
  y0: coordinate(box.y0, `sam3Prompt.boxes[${index}].y0`),
1068
1093
  x1: coordinate(box.x1, `sam3Prompt.boxes[${index}].x1`),
1069
- y1: coordinate(box.y1, `sam3Prompt.boxes[${index}].y1`)
1094
+ y1: coordinate(box.y1, `sam3Prompt.boxes[${index}].y1`),
1095
+ // Boxes have always been positive exemplars, so an absent label leaves
1096
+ // every existing caller on exactly its current behavior.
1097
+ label: box.label === undefined ? ('positive' as const) : box.label
1070
1098
  };
1071
1099
  if (normalized.x0 >= normalized.x1 || normalized.y0 >= normalized.y1) {
1072
1100
  throw new Error(`sam3Prompt.boxes[${index}] must have x0 < x1 and y0 < y1`);
@@ -1091,6 +1119,11 @@ function normalizeSam3Prompt(
1091
1119
  if (normalizedPoints.length > 0 && normalizedBoxes.length > 1) {
1092
1120
  throw new Error('sam3Prompt supports at most one box when point prompts are present');
1093
1121
  }
1122
+ // SAM 3 takes an exclusion exemplar only alongside a text prompt; the
1123
+ // interactive point path has no way to express one.
1124
+ if (normalizedPoints.length > 0 && normalizedBoxes.some((box) => box.label === 'negative')) {
1125
+ throw new Error('sam3Prompt negative boxes require a text prompt');
1126
+ }
1094
1127
  if (
1095
1128
  prompt.threshold !== undefined &&
1096
1129
  (typeof prompt.threshold !== 'number' ||
@@ -1103,12 +1136,32 @@ function normalizeSam3Prompt(
1103
1136
  if (prompt.multimask !== undefined && typeof prompt.multimask !== 'boolean') {
1104
1137
  throw new Error('sam3Prompt.multimask must be a boolean');
1105
1138
  }
1139
+ // multimask chooses among SAM's whole/part/subpart candidates for one
1140
+ // ambiguous click, so it only means anything on the point path.
1141
+ if (prompt.multimask !== undefined && normalizedPoints.length === 0) {
1142
+ throw new Error('sam3Prompt.multimask requires point prompts');
1143
+ }
1144
+ if (prompt.applyMask !== undefined && typeof prompt.applyMask !== 'boolean') {
1145
+ throw new Error('sam3Prompt.applyMask must be a boolean');
1146
+ }
1147
+ if (
1148
+ prompt.maxInstances !== undefined &&
1149
+ (!Number.isSafeInteger(prompt.maxInstances) ||
1150
+ prompt.maxInstances < 1 ||
1151
+ prompt.maxInstances > MAX_SAM3_INSTANCES)
1152
+ ) {
1153
+ throw new Error(`sam3Prompt.maxInstances must be an integer from 1 to ${MAX_SAM3_INSTANCES}`);
1154
+ }
1106
1155
  return {
1107
1156
  points: normalizedPoints,
1108
1157
  boxes: normalizedBoxes,
1109
1158
  ...(text ? { text } : {}),
1110
1159
  threshold: prompt.threshold === undefined ? 0.5 : prompt.threshold,
1111
- multimask: prompt.multimask === undefined ? true : prompt.multimask
1160
+ ...(normalizedPoints.length > 0
1161
+ ? { multimask: prompt.multimask === undefined ? true : prompt.multimask }
1162
+ : {}),
1163
+ applyMask: prompt.applyMask === true,
1164
+ ...(prompt.maxInstances === undefined ? {} : { maxInstances: prompt.maxInstances })
1112
1165
  };
1113
1166
  }
1114
1167
 
@@ -1158,6 +1211,17 @@ function applyImageParams(
1158
1211
  if (params.modelId === PIXAL3D_WORKFLOW_ID && !params.startingImage) {
1159
1212
  throw new Error('Pixal3D reconstruction requires startingImage');
1160
1213
  }
1214
+ for (const [key, limit] of Object.entries(PIXAL3D_REDUCE_ONLY_LIMITS)) {
1215
+ const requested = (params as Record<string, any>)[key];
1216
+ if (requested === undefined) continue;
1217
+ if (params.modelId !== PIXAL3D_WORKFLOW_ID) {
1218
+ throw new Error(`${key} is only supported by ${PIXAL3D_WORKFLOW_ID}`);
1219
+ }
1220
+ if (!Number.isSafeInteger(requested) || requested < limit.min || requested > limit.max) {
1221
+ throw new Error(`${key} must be an integer from ${limit.min} to ${limit.max}`);
1222
+ }
1223
+ keyFrame[key] = requested;
1224
+ }
1161
1225
 
1162
1226
  if (params.controlNet) {
1163
1227
  keyFrame.currentControlNetsJob = getControlNet(params.controlNet);
@@ -123,6 +123,19 @@ const JOB_PROVENANCE_HASH_FIELDS = [
123
123
  'lastFrameSha256'
124
124
  ] as const;
125
125
 
126
+ function isUnitInterval(value: unknown): value is number {
127
+ return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
128
+ }
129
+
130
+ /** Accept normalized [x0, y0, x1, y1] bounds, rejecting inverted or empty ones. */
131
+ function normalizedBounds(value: unknown): [number, number, number, number] | undefined {
132
+ if (!Array.isArray(value) || value.length !== 4 || !value.every(isUnitInterval)) {
133
+ return undefined;
134
+ }
135
+ const [x0, y0, x1, y1] = value as [number, number, number, number];
136
+ return x0 < x1 && y0 < y1 ? [x0, y0, x1, y1] : undefined;
137
+ }
138
+
126
139
  function jobProvenanceFromResult(data: Partial<JobResultData>): JobProvenance | undefined {
127
140
  const result: JobProvenance = {};
128
141
  for (const field of JOB_PROVENANCE_HASH_FIELDS) {
@@ -143,6 +156,35 @@ function jobProvenanceFromResult(data: Partial<JobResultData>): JobProvenance |
143
156
  ) {
144
157
  result.samVersion = data.samVersion;
145
158
  }
159
+ const bounds = normalizedBounds(data.maskBox);
160
+ if (bounds) result.maskBox = bounds;
161
+ if (isUnitInterval(data.maskCoverage)) result.maskCoverage = data.maskCoverage;
162
+ if (Number.isSafeInteger(data.maskDetectedCount) && Number(data.maskDetectedCount) >= 0) {
163
+ result.maskDetectedCount = Number(data.maskDetectedCount);
164
+ }
165
+ if (Number.isSafeInteger(data.maskReturnedCount) && Number(data.maskReturnedCount) >= 0) {
166
+ result.maskReturnedCount = Number(data.maskReturnedCount);
167
+ }
168
+ if (Array.isArray(data.maskSelections)) {
169
+ // Drop anything malformed rather than surfacing a half-valid selection:
170
+ // a caller reading `score` should never get undefined from a typed field.
171
+ const selections = data.maskSelections
172
+ .filter(
173
+ (entry): entry is NonNullable<typeof entry> =>
174
+ !!entry &&
175
+ typeof entry === 'object' &&
176
+ typeof entry.included === 'boolean' &&
177
+ isUnitInterval(entry.coverage) &&
178
+ (entry.score === null || isUnitInterval(entry.score))
179
+ )
180
+ .map((entry) => ({
181
+ score: entry.score === null ? null : Number(entry.score),
182
+ box: normalizedBounds(entry.box) ?? null,
183
+ coverage: Number(entry.coverage),
184
+ included: entry.included
185
+ }));
186
+ if (selections.length > 0) result.maskSelections = selections;
187
+ }
146
188
  return Object.keys(result).length > 0 ? result : undefined;
147
189
  }
148
190
  // Socket owns a 105s provider-confirmation deadline. Keep transport/UI slack
@@ -1,3 +1,5 @@
1
+ import type { Sam3Selection } from './index.js';
2
+
1
3
  /**
2
4
  * Worker-attested hashes used to bind generated media to its exact inputs.
3
5
  * Every field is optional because ordinary projects and older workers do not
@@ -14,6 +16,20 @@ export interface JobProvenance {
14
16
  maskRleSha256?: string;
15
17
  maskWidth?: number;
16
18
  maskHeight?: number;
19
+ /** Selection bounds as normalized [x0, y0, x1, y1]; absent for an empty mask. */
20
+ maskBox?: [number, number, number, number];
21
+ /** Fraction of the source covered by the returned mask, 0 to 1. */
22
+ maskCoverage?: number;
23
+ /** Selections that passed the threshold; may exceed the reported window. */
24
+ maskDetectedCount?: number;
25
+ /** Selections unioned into the returned mask. */
26
+ maskReturnedCount?: number;
27
+ /**
28
+ * Per-selection confidence and bounds, highest confidence first. Use it to
29
+ * tell a confident selection from a marginal one, and to discover that a
30
+ * concept matched more instances than the single returned mask suggests.
31
+ */
32
+ maskSelections?: Sam3Selection[];
17
33
  /** Immutable operator-provisioned SAM runtime/checkpoint version. */
18
34
  samVersion?: string;
19
35
  /** World selection receipt bound to an image-edit job. */
@@ -626,6 +626,12 @@ export interface Sam3PromptBox {
626
626
  y0: number;
627
627
  x1: number;
628
628
  y1: number;
629
+ /**
630
+ * `positive` (the default) is an example of the thing to select. `negative`
631
+ * excludes one instance of a text-prompted concept — "every dog but this
632
+ * one" — and requires `text`, since the point path cannot express it.
633
+ */
634
+ label?: 'positive' | 'negative';
629
635
  }
630
636
 
631
637
  /** A bounded prompt for the SAM3 image-segmentation workflow. */
@@ -633,11 +639,68 @@ export interface Sam3ImagePrompt {
633
639
  points?: Sam3PromptPoint[];
634
640
  boxes?: Sam3PromptBox[];
635
641
  text?: string;
642
+ /**
643
+ * With `points`, a pass/fail gate: the job fails if the best candidate scores
644
+ * below it. With `text`, the detection filter applied to concept matches.
645
+ * Defaults to 0.5.
646
+ */
636
647
  threshold?: number;
648
+ /**
649
+ * Choose among SAM's whole/part/subpart candidates for one ambiguous click.
650
+ * Point prompts only — supplying it with `text` is rejected.
651
+ */
637
652
  multimask?: boolean;
653
+ /**
654
+ * Return the selection cut out of the source as an RGBA PNG, with the mask
655
+ * carried in alpha, instead of the bare black-and-white mask. Defaults to
656
+ * false so existing callers keep receiving a mask.
657
+ */
658
+ applyMask?: boolean;
659
+ /**
660
+ * Keep only the highest-scoring N selections, 1 to 16. With `text` those are
661
+ * distinct instances of the concept, so `maxInstances: 1` returns just the
662
+ * strongest match instead of every match merged together; with `points` they
663
+ * are SAM's whole/part/subpart candidates for the one clicked object.
664
+ * Defaults to keeping every selection above `threshold`.
665
+ */
666
+ maxInstances?: number;
667
+ }
668
+
669
+ /**
670
+ * Pixal3D image-to-3D generation options. Every one may only REDUCE work: each
671
+ * maximum is the shipped default, so the flat price is a guaranteed upper bound
672
+ * and a smaller value simply costs less to produce.
673
+ *
674
+ * `meshTargetFaces` is the one most worth setting. The 700,000-triangle default
675
+ * is far heavier than a real-time engine wants, so asking for less yields a
676
+ * more useful asset.
677
+ */
678
+ export interface Pixal3dGenerationOptions {
679
+ /** Base-colour bake and UV atlas resolution, 1024 to 4096. Default 4096. */
680
+ textureSize?: number;
681
+ /** Decimation target in triangles, 5000 to 700000. Default 700000. */
682
+ meshTargetFaces?: number;
683
+ /** Normal map resolution, 512 to 2048. Default 2048. */
684
+ normalMapSize?: number;
685
+ /** Ambient occlusion map resolution, 256 to 1024. Default 1024. */
686
+ ambientOcclusionSize?: number;
687
+ /** Sparse-latent upsampling resolution, 1024 to 1536. Default 1536. */
688
+ shapeResolution?: number;
689
+ }
690
+
691
+ /** One SAM3 selection: a concept instance, or a candidate for one click. */
692
+ export interface Sam3Selection {
693
+ /** Model confidence, 0 to 1. */
694
+ score: number | null;
695
+ /** Normalized [x0, y0, x1, y1]; null for an empty selection. */
696
+ box: [number, number, number, number] | null;
697
+ /** Fraction of the source this selection covers, 0 to 1. */
698
+ coverage: number;
699
+ /** Whether this selection is part of the returned mask. */
700
+ included: boolean;
638
701
  }
639
702
 
640
- export interface ImageProjectParams extends BaseProjectParams {
703
+ export interface ImageProjectParams extends BaseProjectParams, Pixal3dGenerationOptions {
641
704
  type: 'image';
642
705
  /**
643
706
  * Number of previews to generate. Note that previews affect project cost
@@ -93,11 +93,36 @@ export function isAudioModel(modelId: string): boolean {
93
93
  return modelId.startsWith('ace_step') || modelId === 'minimax_music3';
94
94
  }
95
95
 
96
+ /** Canonical id of the prompt-guided image-to-3D reconstruction workflow. */
97
+ export const PIXAL3D_IMAGE_TO_3D_MODEL_ID = 'pixal3d_int8_i23d';
98
+
99
+ /** Canonical id of the SAM 3 interactive image-segmentation workflow. */
100
+ export const SAM3_IMAGE_SEGMENT_MODEL_ID = 'sam3_image_segment_bf16';
101
+
96
102
  /** Check if a model returns a downloadable 3D model artifact. */
97
103
  export function isModelArtifactModel(modelId: string): boolean {
98
104
  return modelId.startsWith('pixal3d_');
99
105
  }
100
106
 
107
+ /**
108
+ * Check if a model performs image segmentation rather than generation.
109
+ *
110
+ * Segmentation returns a lossless mask PNG the same size as the source, not a
111
+ * new image, so callers must not treat it as a generated result: it has no
112
+ * meaningful prompt-to-pixels relationship and is not enhanceable.
113
+ */
114
+ export function isSegmentationModel(modelId: string): boolean {
115
+ return modelId === SAM3_IMAGE_SEGMENT_MODEL_ID;
116
+ }
117
+
118
+ /**
119
+ * Models that need a starting image because they transform one rather than
120
+ * generating from a prompt alone.
121
+ */
122
+ export function requiresStartingImage(modelId: string): boolean {
123
+ return isSegmentationModel(modelId) || isModelArtifactModel(modelId);
124
+ }
125
+
101
126
  /**
102
127
  * Check if a model ID is a WAN 2.2 video model.
103
128
  *
package/src/index.ts CHANGED
@@ -23,6 +23,15 @@ import { ApiConfig } from './ApiGroup.js';
23
23
  import { DefaultLogger, Logger, LogLevel } from './lib/DefaultLogger.js';
24
24
  import EIP712Helper from './lib/EIP712Helper.js';
25
25
  // Projects API
26
+ import {
27
+ PIXAL3D_IMAGE_TO_3D_MODEL_ID,
28
+ SAM3_IMAGE_SEGMENT_MODEL_ID,
29
+ isAudioModel,
30
+ isModelArtifactModel,
31
+ isSegmentationModel,
32
+ isVideoModel,
33
+ requiresStartingImage
34
+ } from './Projects/utils/index.js';
26
35
  import ProjectsApi from './Projects/index.js';
27
36
  import Job, { JobStatus } from './Projects/Job.js';
28
37
  import Project, { ProjectStatus } from './Projects/Project.js';
@@ -33,9 +42,11 @@ import {
33
42
  BillingMode,
34
43
  ImageProjectParams,
35
44
  ImageOutputFormat,
45
+ Pixal3dGenerationOptions,
36
46
  Sam3ImagePrompt,
37
47
  Sam3PromptBox,
38
48
  Sam3PromptPoint,
49
+ Sam3Selection,
39
50
  ProjectParams,
40
51
  VideoProjectParams,
41
52
  AudioFormat,
@@ -279,9 +290,11 @@ export type {
279
290
  ErrorData,
280
291
  ImageProjectParams,
281
292
  ImageOutputFormat,
293
+ Pixal3dGenerationOptions,
282
294
  Sam3ImagePrompt,
283
295
  Sam3PromptBox,
284
296
  Sam3PromptPoint,
297
+ Sam3Selection,
285
298
  JobStatus,
286
299
  Logger,
287
300
  LogLevel,
@@ -405,6 +418,13 @@ export type {
405
418
  };
406
419
 
407
420
  export {
421
+ PIXAL3D_IMAGE_TO_3D_MODEL_ID,
422
+ SAM3_IMAGE_SEGMENT_MODEL_ID,
423
+ isAudioModel,
424
+ isModelArtifactModel,
425
+ isSegmentationModel,
426
+ isVideoModel,
427
+ requiresStartingImage,
408
428
  ApiError,
409
429
  ApiKeyAuthManager,
410
430
  ChatJobError,
package/src/version.ts CHANGED
@@ -1,3 +1,3 @@
1
1
  // AUTO-GENERATED by scripts/generate-version.mjs — do not edit.
2
2
  // Source of truth: package.json version.
3
- export const LIB_VERSION = '5.32.0';
3
+ export const LIB_VERSION = '5.34.0';