@sogni-ai/sogni-client 5.29.2 → 5.31.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 (42) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/ApiClient/WebSocketClient/events.d.ts +13 -0
  3. package/dist/Projects/Job.d.ts +4 -0
  4. package/dist/Projects/Job.js +7 -2
  5. package/dist/Projects/Job.js.map +1 -1
  6. package/dist/Projects/createJobRequestMessage.js +175 -4
  7. package/dist/Projects/createJobRequestMessage.js.map +1 -1
  8. package/dist/Projects/index.js +50 -27
  9. package/dist/Projects/index.js.map +1 -1
  10. package/dist/Projects/types/JobProvenance.d.ts +24 -0
  11. package/dist/Projects/types/JobProvenance.js +3 -0
  12. package/dist/Projects/types/JobProvenance.js.map +1 -0
  13. package/dist/Projects/types/RawProject.d.ts +2 -0
  14. package/dist/Projects/types/events.d.ts +3 -0
  15. package/dist/Projects/types/index.d.ts +43 -0
  16. package/dist/Projects/types/index.js.map +1 -1
  17. package/dist/index.d.ts +3 -2
  18. package/dist/index.js.map +1 -1
  19. package/dist/version.d.ts +1 -1
  20. package/dist/version.js +1 -1
  21. package/dist-esm/Projects/Job.js +7 -2
  22. package/dist-esm/Projects/Job.js.map +1 -1
  23. package/dist-esm/Projects/createJobRequestMessage.js +175 -4
  24. package/dist-esm/Projects/createJobRequestMessage.js.map +1 -1
  25. package/dist-esm/Projects/index.js +50 -27
  26. package/dist-esm/Projects/index.js.map +1 -1
  27. package/dist-esm/Projects/types/JobProvenance.js +2 -0
  28. package/dist-esm/Projects/types/JobProvenance.js.map +1 -0
  29. package/dist-esm/Projects/types/index.js.map +1 -1
  30. package/dist-esm/index.js.map +1 -1
  31. package/dist-esm/version.js +1 -1
  32. package/package.json +2 -1
  33. package/src/ApiClient/WebSocketClient/events.ts +13 -0
  34. package/src/Projects/Job.ts +11 -2
  35. package/src/Projects/createJobRequestMessage.ts +195 -5
  36. package/src/Projects/index.ts +66 -12
  37. package/src/Projects/types/JobProvenance.ts +24 -0
  38. package/src/Projects/types/RawProject.ts +2 -0
  39. package/src/Projects/types/events.ts +3 -0
  40. package/src/Projects/types/index.ts +49 -0
  41. package/src/index.ts +12 -2
  42. package/src/version.ts +1 -1
@@ -1,6 +1,7 @@
1
1
  import {
2
2
  AudioProjectParams,
3
3
  ImageProjectParams,
4
+ Sam3ImagePrompt,
4
5
  isAudioParams,
5
6
  isImageParams,
6
7
  isVideoParams,
@@ -69,6 +70,68 @@ import {
69
70
  } from './types/ModelOptions.js';
70
71
  import { workloadAttributionToWireFields } from '../lib/attribution.js';
71
72
 
73
+ const SAM3_IMAGE_SEGMENT_WORKFLOW_ID = 'sam3_image_segment_bf16';
74
+ const WORLD_TARGET_STILL_MODEL_ID = 'krea2_identity_edit_sogni_v0_3_alpha';
75
+ const WORLD_TRANSITION_MODEL_ID = 'minimax-h3-fastvideo-int8_flf2v_turbo';
76
+ const MAX_SAM3_POINTS = 32;
77
+ const MAX_SAM3_BOXES = 16;
78
+ const MAX_SAM3_TEXT_LENGTH = 240;
79
+
80
+ function normalizeWorldGenerationReceipt(params: ProjectParams) {
81
+ const receipt = params.worldGenerationReceipt;
82
+ if (!receipt) return undefined;
83
+ if (params.appSource !== 'sogni-world') {
84
+ throw new ApiError(400, {
85
+ status: 'error',
86
+ errorCode: 0,
87
+ message: 'worldGenerationReceipt requires appSource "sogni-world".'
88
+ });
89
+ }
90
+ const hash = (value: unknown, field: string) => {
91
+ if (typeof value !== 'string' || !/^[a-f0-9]{64}$/i.test(value)) {
92
+ throw new ApiError(400, {
93
+ status: 'error',
94
+ errorCode: 0,
95
+ message: `worldGenerationReceipt.${field} must be a SHA-256 hex digest.`
96
+ });
97
+ }
98
+ return value.toLowerCase();
99
+ };
100
+ if (receipt.stage === 'target_still') {
101
+ if (params.modelId !== WORLD_TARGET_STILL_MODEL_ID) {
102
+ throw new ApiError(400, {
103
+ status: 'error',
104
+ errorCode: 0,
105
+ message: `The target_still receipt requires ${WORLD_TARGET_STILL_MODEL_ID}.`
106
+ });
107
+ }
108
+ return {
109
+ stage: receipt.stage,
110
+ sourceImageSha256: hash(receipt.sourceImageSha256, 'sourceImageSha256'),
111
+ selectionHash: hash(receipt.selectionHash, 'selectionHash')
112
+ };
113
+ }
114
+ if (receipt.stage === 'transition') {
115
+ if (params.modelId !== WORLD_TRANSITION_MODEL_ID) {
116
+ throw new ApiError(400, {
117
+ status: 'error',
118
+ errorCode: 0,
119
+ message: `The transition receipt requires ${WORLD_TRANSITION_MODEL_ID}.`
120
+ });
121
+ }
122
+ return {
123
+ stage: receipt.stage,
124
+ firstFrameSha256: hash(receipt.firstFrameSha256, 'firstFrameSha256'),
125
+ lastFrameSha256: hash(receipt.lastFrameSha256, 'lastFrameSha256')
126
+ };
127
+ }
128
+ throw new ApiError(400, {
129
+ status: 'error',
130
+ errorCode: 0,
131
+ message: 'worldGenerationReceipt.stage must be target_still or transition.'
132
+ });
133
+ }
134
+
72
135
  /**
73
136
  * Validate that the provided assets match the workflow requirements.
74
137
  * Throws an error if required assets are missing or forbidden assets are provided.
@@ -945,6 +1008,109 @@ function getVideoControlNet(params: VideoControlNetParams): VideoControlNetParam
945
1008
  return [cn];
946
1009
  }
947
1010
 
1011
+ function normalizeSam3Prompt(
1012
+ prompt: Sam3ImagePrompt
1013
+ ): Required<Pick<Sam3ImagePrompt, 'points' | 'boxes' | 'threshold' | 'multimask'>> &
1014
+ Pick<Sam3ImagePrompt, 'text'> {
1015
+ if (!prompt || typeof prompt !== 'object' || Array.isArray(prompt)) {
1016
+ throw new Error('sam3Prompt must be an object');
1017
+ }
1018
+ const allowedRootKeys = new Set(['points', 'boxes', 'text', 'threshold', 'multimask']);
1019
+ const unknownRootKeys = Object.keys(prompt).filter((key) => !allowedRootKeys.has(key));
1020
+ if (unknownRootKeys.length > 0) {
1021
+ throw new Error(`sam3Prompt contains unsupported fields: ${unknownRootKeys.join(', ')}`);
1022
+ }
1023
+ const coordinate = (value: unknown, field: string) => {
1024
+ if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
1025
+ throw new Error(`${field} must be a finite normalized coordinate from 0 to 1`);
1026
+ }
1027
+ return value;
1028
+ };
1029
+
1030
+ const points = prompt.points || [];
1031
+ if (!Array.isArray(points) || points.length > MAX_SAM3_POINTS) {
1032
+ throw new Error(`sam3Prompt.points must contain at most ${MAX_SAM3_POINTS} entries`);
1033
+ }
1034
+ const normalizedPoints = points.map((point, index) => {
1035
+ if (!point || typeof point !== 'object' || Array.isArray(point)) {
1036
+ throw new Error(`sam3Prompt.points[${index}] must be an object`);
1037
+ }
1038
+ const unknown = Object.keys(point).filter((key) => !['x', 'y', 'label'].includes(key));
1039
+ if (unknown.length > 0) {
1040
+ throw new Error(`sam3Prompt.points[${index}] contains unsupported fields`);
1041
+ }
1042
+ if (point.label !== 'positive' && point.label !== 'negative') {
1043
+ throw new Error(`sam3Prompt.points[${index}].label must be "positive" or "negative"`);
1044
+ }
1045
+ return {
1046
+ x: coordinate(point.x, `sam3Prompt.points[${index}].x`),
1047
+ y: coordinate(point.y, `sam3Prompt.points[${index}].y`),
1048
+ label: point.label
1049
+ };
1050
+ });
1051
+
1052
+ const boxes = prompt.boxes || [];
1053
+ if (!Array.isArray(boxes) || boxes.length > MAX_SAM3_BOXES) {
1054
+ throw new Error(`sam3Prompt.boxes must contain at most ${MAX_SAM3_BOXES} entries`);
1055
+ }
1056
+ const normalizedBoxes = boxes.map((box, index) => {
1057
+ if (!box || typeof box !== 'object' || Array.isArray(box)) {
1058
+ throw new Error(`sam3Prompt.boxes[${index}] must be an object`);
1059
+ }
1060
+ const unknown = Object.keys(box).filter((key) => !['x0', 'y0', 'x1', 'y1'].includes(key));
1061
+ if (unknown.length > 0) {
1062
+ throw new Error(`sam3Prompt.boxes[${index}] contains unsupported fields`);
1063
+ }
1064
+ const normalized = {
1065
+ x0: coordinate(box.x0, `sam3Prompt.boxes[${index}].x0`),
1066
+ y0: coordinate(box.y0, `sam3Prompt.boxes[${index}].y0`),
1067
+ x1: coordinate(box.x1, `sam3Prompt.boxes[${index}].x1`),
1068
+ y1: coordinate(box.y1, `sam3Prompt.boxes[${index}].y1`)
1069
+ };
1070
+ if (normalized.x0 >= normalized.x1 || normalized.y0 >= normalized.y1) {
1071
+ throw new Error(`sam3Prompt.boxes[${index}] must have x0 < x1 and y0 < y1`);
1072
+ }
1073
+ return normalized;
1074
+ });
1075
+
1076
+ let text: string | undefined;
1077
+ if (prompt.text !== undefined) {
1078
+ if (typeof prompt.text !== 'string') throw new Error('sam3Prompt.text must be a string');
1079
+ text = prompt.text.trim();
1080
+ if (!text || text.length > MAX_SAM3_TEXT_LENGTH) {
1081
+ throw new Error(`sam3Prompt.text must contain 1 to ${MAX_SAM3_TEXT_LENGTH} characters`);
1082
+ }
1083
+ }
1084
+ if (normalizedPoints.length === 0 && normalizedBoxes.length === 0 && !text) {
1085
+ throw new Error('sam3Prompt requires at least one point, box, or text prompt');
1086
+ }
1087
+ if (text && normalizedPoints.length > 0) {
1088
+ throw new Error('sam3Prompt cannot combine text and point prompts');
1089
+ }
1090
+ if (normalizedPoints.length > 0 && normalizedBoxes.length > 1) {
1091
+ throw new Error('sam3Prompt supports at most one box when point prompts are present');
1092
+ }
1093
+ if (
1094
+ prompt.threshold !== undefined &&
1095
+ (typeof prompt.threshold !== 'number' ||
1096
+ !Number.isFinite(prompt.threshold) ||
1097
+ prompt.threshold < 0 ||
1098
+ prompt.threshold > 1)
1099
+ ) {
1100
+ throw new Error('sam3Prompt.threshold must be a finite number from 0 to 1');
1101
+ }
1102
+ if (prompt.multimask !== undefined && typeof prompt.multimask !== 'boolean') {
1103
+ throw new Error('sam3Prompt.multimask must be a boolean');
1104
+ }
1105
+ return {
1106
+ points: normalizedPoints,
1107
+ boxes: normalizedBoxes,
1108
+ ...(text ? { text } : {}),
1109
+ threshold: prompt.threshold === undefined ? 0.5 : prompt.threshold,
1110
+ multimask: prompt.multimask === undefined ? true : prompt.multimask
1111
+ };
1112
+ }
1113
+
948
1114
  function applyImageParams(
949
1115
  inputKeyframe: Record<string, any>,
950
1116
  params: ImageProjectParams,
@@ -977,6 +1143,18 @@ function applyImageParams(
977
1143
  keyFrame.strength = 1 - (Number(params.startingImageStrength) || 0.5);
978
1144
  }
979
1145
 
1146
+ if (params.modelId === SAM3_IMAGE_SEGMENT_WORKFLOW_ID) {
1147
+ if (!params.startingImage) {
1148
+ throw new Error('SAM3 image segmentation requires startingImage');
1149
+ }
1150
+ if (!params.sam3Prompt) {
1151
+ throw new Error('SAM3 image segmentation requires sam3Prompt');
1152
+ }
1153
+ keyFrame.sam3Prompt = normalizeSam3Prompt(params.sam3Prompt);
1154
+ } else if (params.sam3Prompt !== undefined) {
1155
+ throw new Error(`sam3Prompt is only supported by ${SAM3_IMAGE_SEGMENT_WORKFLOW_ID}`);
1156
+ }
1157
+
980
1158
  if (params.controlNet) {
981
1159
  keyFrame.currentControlNetsJob = getControlNet(params.controlNet);
982
1160
  }
@@ -1249,6 +1427,7 @@ function applyAudioParams(
1249
1427
 
1250
1428
  function createJobRequestMessage(id: string, params: ProjectParams, options: ModelOptions) {
1251
1429
  const template = getTemplate();
1430
+ const worldGenerationReceipt = normalizeWorldGenerationReceipt(params);
1252
1431
  const negativePrompt =
1253
1432
  isImageParams(params) ||
1254
1433
  (isVideoParams(params) &&
@@ -1271,7 +1450,10 @@ function createJobRequestMessage(id: string, params: ProjectParams, options: Mod
1271
1450
  // LoRA IDs for LoRA loading (resolved to filenames by worker via config API)
1272
1451
  ...(params.loras && params.loras.length > 0 && { loras: params.loras }),
1273
1452
  ...(params.loraStrengths &&
1274
- params.loraStrengths.length > 0 && { loraStrengths: params.loraStrengths })
1453
+ params.loraStrengths.length > 0 && { loraStrengths: params.loraStrengths }),
1454
+ ...(worldGenerationReceipt && {
1455
+ worldGenerationReceipt
1456
+ })
1275
1457
  };
1276
1458
  if (
1277
1459
  isAudioParams(params) ||
@@ -1326,15 +1508,23 @@ function createJobRequestMessage(id: string, params: ProjectParams, options: Mod
1326
1508
  const jobRequest: Record<string, any> = {
1327
1509
  ...template,
1328
1510
  keyFrames: [keyFrame],
1329
- previews: isImageParams(params) ? params.numberOfPreviews || 0 : 0,
1330
- numberOfImages: params.numberOfMedia || 1,
1511
+ previews:
1512
+ params.modelId === SAM3_IMAGE_SEGMENT_WORKFLOW_ID
1513
+ ? 0
1514
+ : isImageParams(params)
1515
+ ? params.numberOfPreviews || 0
1516
+ : 0,
1517
+ numberOfImages:
1518
+ params.modelId === SAM3_IMAGE_SEGMENT_WORKFLOW_ID ? 1 : params.numberOfMedia || 1,
1331
1519
  jobID: id,
1332
1520
  disableSafety: !!params.disableNSFWFilter,
1333
1521
  tokenType: params.tokenType,
1334
1522
  billingMode: params.billingMode,
1335
1523
  outputFormat:
1336
- params.outputFormat ||
1337
- (isAudioParams(params) ? 'mp3' : isVideoParams(params) ? 'mp4' : 'png'),
1524
+ params.modelId === SAM3_IMAGE_SEGMENT_WORKFLOW_ID
1525
+ ? 'png'
1526
+ : params.outputFormat ||
1527
+ (isAudioParams(params) ? 'mp3' : isVideoParams(params) ? 'mp4' : 'png'),
1338
1528
  ...workloadAttributionToWireFields(params.attribution)
1339
1529
  };
1340
1530
 
@@ -71,6 +71,7 @@ import {
71
71
  usesReferenceMask
72
72
  } from './utils/index.js';
73
73
  import { TokenType } from '../types/token.js';
74
+ import type { JobProvenance } from './types/JobProvenance.js';
74
75
  import { getMaxContextImages, validateSampler } from '../lib/validation.js';
75
76
  import ModelTiersRaw, {
76
77
  isAudioTier,
@@ -110,6 +111,39 @@ const DEFAULT_LORA_CONSTRAINTS: LoraConstraints = {
110
111
  maxStrength: 100
111
112
  };
112
113
  const GARBAGE_COLLECT_TIMEOUT = 30000;
114
+
115
+ const JOB_PROVENANCE_HASH_FIELDS = [
116
+ 'sha256',
117
+ 'sourceImageSha256',
118
+ 'samPromptSha256',
119
+ 'maskRleSha256',
120
+ 'selectionHash',
121
+ 'firstFrameSha256',
122
+ 'lastFrameSha256'
123
+ ] as const;
124
+
125
+ function jobProvenanceFromResult(data: Partial<JobResultData>): JobProvenance | undefined {
126
+ const result: JobProvenance = {};
127
+ for (const field of JOB_PROVENANCE_HASH_FIELDS) {
128
+ const value = data[field];
129
+ if (typeof value === 'string' && /^[a-f0-9]{64}$/i.test(value)) {
130
+ result[field] = value.toLowerCase();
131
+ }
132
+ }
133
+ if (Number.isSafeInteger(data.maskWidth) && Number(data.maskWidth) > 0) {
134
+ result.maskWidth = Number(data.maskWidth);
135
+ }
136
+ if (Number.isSafeInteger(data.maskHeight) && Number(data.maskHeight) > 0) {
137
+ result.maskHeight = Number(data.maskHeight);
138
+ }
139
+ if (
140
+ typeof data.samVersion === 'string' &&
141
+ /^[A-Za-z0-9][A-Za-z0-9._:+-]{0,79}$/.test(data.samVersion)
142
+ ) {
143
+ result.samVersion = data.samVersion;
144
+ }
145
+ return Object.keys(result).length > 0 ? result : undefined;
146
+ }
113
147
  // Socket owns a 105s provider-confirmation deadline. Keep transport/UI slack
114
148
  // above it so the client cannot report failure while Socket is still able to
115
149
  // confirm and refund the same cancellation.
@@ -550,6 +584,7 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
550
584
  // Update the job directly with the result URL to prevent duplicate API calls
551
585
  let performedStepCount = data.performedStepCount;
552
586
  let seed = data.lastSeed !== undefined ? Number(data.lastSeed) : undefined;
587
+ const provenance = jobProvenanceFromResult(data);
553
588
  if (project) {
554
589
  const job = project.job(data.imgID);
555
590
  if (job) {
@@ -574,7 +609,8 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
574
609
  isNSFW: Boolean(data.triggeredNSFWFilter),
575
610
  nsfwDetected: data.nsfwDetected === true,
576
611
  nsfwSources: Array.isArray(data.nsfwSources) ? [...data.nsfwSources] : [],
577
- userCanceled: Boolean(data.userCanceled)
612
+ userCanceled: Boolean(data.userCanceled),
613
+ ...(provenance ? { provenance } : {})
578
614
  });
579
615
  }
580
616
  }
@@ -590,7 +626,8 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
590
626
  isNSFW: Boolean(data.triggeredNSFWFilter),
591
627
  nsfwDetected: data.nsfwDetected === true,
592
628
  nsfwSources: Array.isArray(data.nsfwSources) ? [...data.nsfwSources] : [],
593
- userCanceled: Boolean(data.userCanceled)
629
+ userCanceled: Boolean(data.userCanceled),
630
+ ...(provenance ? { provenance } : {})
594
631
  });
595
632
  }
596
633
 
@@ -780,6 +817,7 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
780
817
  nsfwDetected: boolean;
781
818
  nsfwSources: string[];
782
819
  userCanceled: boolean;
820
+ provenance?: JobProvenance;
783
821
  step?: number;
784
822
  seed?: number;
785
823
  } = {
@@ -788,7 +826,8 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
788
826
  isNSFW: event.isNSFW,
789
827
  nsfwDetected: Boolean(event.nsfwDetected),
790
828
  nsfwSources: Array.isArray(event.nsfwSources) ? [...event.nsfwSources] : [],
791
- userCanceled: event.userCanceled
829
+ userCanceled: event.userCanceled,
830
+ ...(event.provenance ? { provenance: event.provenance } : {})
792
831
  };
793
832
  if (typeof event.steps === 'number') {
794
833
  delta.step = event.steps;
@@ -1134,6 +1173,9 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
1134
1173
  userCanceled: job.reason === 'artistCanceled',
1135
1174
  ...(typeof job.resultUrl === 'string' && job.resultUrl
1136
1175
  ? { resultUrl: job.resultUrl }
1176
+ : {}),
1177
+ ...(job.result && typeof job.result === 'object'
1178
+ ? jobProvenanceFromResult(job.result as Partial<JobResultData>)
1137
1179
  : {})
1138
1180
  });
1139
1181
  continue;
@@ -1244,22 +1286,34 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
1244
1286
  * @param data
1245
1287
  */
1246
1288
  async create(data: ProjectParams): Promise<Project> {
1247
- const project = new Project({ ...data }, { api: this, logger: this.client.logger });
1248
- const modelOptions = await this.getModelOptions(data.modelId);
1289
+ // SAM3 is a one-source/one-mask utility workflow. Normalize before Project
1290
+ // construction so lifecycle completion and result MIME use the same values
1291
+ // as the serialized request.
1292
+ const normalizedData =
1293
+ data.type === 'image' && data.modelId === 'sam3_image_segment_bf16'
1294
+ ? ({
1295
+ ...data,
1296
+ numberOfMedia: 1,
1297
+ numberOfPreviews: 0,
1298
+ outputFormat: 'png'
1299
+ } as ProjectParams)
1300
+ : data;
1301
+ const project = new Project({ ...normalizedData }, { api: this, logger: this.client.logger });
1302
+ const modelOptions = await this.getModelOptions(normalizedData.modelId);
1249
1303
  const requestParams = {
1250
- ...data,
1251
- appSource: data.appSource || this.client.appSource,
1252
- attribution: this.resolveWorkloadAttribution(data.attribution, project.id)
1304
+ ...normalizedData,
1305
+ appSource: normalizedData.appSource || this.client.appSource,
1306
+ attribution: this.resolveWorkloadAttribution(normalizedData.attribution, project.id)
1253
1307
  } as ProjectParams;
1254
1308
  const request = createJobRequestMessage(project.id, requestParams, modelOptions);
1255
1309
 
1256
- switch (data.type) {
1310
+ switch (normalizedData.type) {
1257
1311
  case 'image':
1258
- await this._processImageAssets(project, data);
1312
+ await this._processImageAssets(project, normalizedData);
1259
1313
  break;
1260
1314
  case 'video':
1261
- await this._processVideoAssets(project, data);
1262
- this._annotateVideoAssetContentTypes(request, data);
1315
+ await this._processVideoAssets(project, normalizedData);
1316
+ this._annotateVideoAssetContentTypes(request, normalizedData);
1263
1317
  break;
1264
1318
  case 'audio':
1265
1319
  // No assets to upload for audio
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Worker-attested hashes used to bind generated media to its exact inputs.
3
+ * Every field is optional because ordinary projects and older workers do not
4
+ * emit a receipt. Hashes are lowercase SHA-256 hex digests when present.
5
+ */
6
+ export interface JobProvenance {
7
+ /** Hash of the exact bytes uploaded as the completed artifact. */
8
+ sha256?: string;
9
+ /** Hash of the original still used by an image edit or segmentation job. */
10
+ sourceImageSha256?: string;
11
+ /** Hash of the canonical normalized SAM point/box/text prompt. */
12
+ samPromptSha256?: string;
13
+ /** Hash of the canonical SAM mask run-length encoding. */
14
+ maskRleSha256?: string;
15
+ maskWidth?: number;
16
+ maskHeight?: number;
17
+ /** Immutable operator-provisioned SAM runtime/checkpoint version. */
18
+ samVersion?: string;
19
+ /** World selection receipt bound to an image-edit job. */
20
+ selectionHash?: string;
21
+ /** Exact first and last still hashes bound to a frame-interpolation job. */
22
+ firstFrameSha256?: string;
23
+ lastFrameSha256?: string;
24
+ }
@@ -1,4 +1,5 @@
1
1
  import { SupernetType } from '../../ApiClient/WebSocketClient/types.js';
2
+ import type { JobProvenance } from './JobProvenance.js';
2
3
 
3
4
  export interface RawProject {
4
5
  id: string;
@@ -69,6 +70,7 @@ export interface RawJob {
69
70
  txId?: string;
70
71
  resultUrl?: string | null;
71
72
  resultKey?: string | null;
73
+ result?: JobProvenance & Record<string, unknown>;
72
74
  }
73
75
 
74
76
  export interface CostActual {
@@ -5,6 +5,7 @@ import type {
5
5
  ProjectRecoverySnapshot,
6
6
  RecoveredProject
7
7
  } from '../../ApiClient/WebSocketClient/events.js';
8
+ import type { JobProvenance } from './JobProvenance.js';
8
9
 
9
10
  export type { JobPreparation } from '../../ApiClient/WebSocketClient/events.js';
10
11
 
@@ -111,6 +112,8 @@ export interface JobCompleted extends JobEventBase {
111
112
  /** Which signals fired: 'prompt' and/or 'image'. */
112
113
  nsfwSources: string[];
113
114
  userCanceled: boolean;
115
+ /** Worker-attested input/output hashes, when the workflow emits them. */
116
+ provenance?: JobProvenance;
114
117
  }
115
118
 
116
119
  export interface JobError extends JobEventBase {
@@ -3,6 +3,18 @@ import { ControlNetParams, VideoControlNetParams } from './ControlNetParams.js';
3
3
  import { TokenType } from '../../types/token.js';
4
4
  import type { WorkloadAttributionInput } from '../../types/attribution.js';
5
5
 
6
+ export type WorldGenerationReceiptRequest =
7
+ | {
8
+ stage: 'target_still';
9
+ sourceImageSha256: string;
10
+ selectionHash: string;
11
+ }
12
+ | {
13
+ stage: 'transition';
14
+ firstFrameSha256: string;
15
+ lastFrameSha256: string;
16
+ };
17
+
6
18
  export interface SupportedModel {
7
19
  id: string;
8
20
  name: string;
@@ -99,6 +111,12 @@ export interface BaseProjectParams {
99
111
  * Optional client app/source label to attach to the project request for server-side attribution.
100
112
  */
101
113
  appSource?: string;
114
+ /**
115
+ * Hash receipt requested by the Sogni World pipeline. The worker verifies
116
+ * these hashes against the original uploaded frame bytes before echoing an
117
+ * attestation. This is accepted only for `appSource: "sogni-world"`.
118
+ */
119
+ worldGenerationReceipt?: WorldGenerationReceiptRequest;
102
120
  /**
103
121
  * Optional workload attribution for this project. Fields override the
104
122
  * immutable defaults configured on SogniClient.
@@ -594,6 +612,31 @@ export interface VideoProjectParams extends BaseProjectParams {
594
612
  outpaintPosition?: 'center' | 'top' | 'bottom' | 'left' | 'right';
595
613
  }
596
614
 
615
+ export interface Sam3PromptPoint {
616
+ /** Horizontal coordinate normalized to the original source image width. */
617
+ x: number;
618
+ /** Vertical coordinate normalized to the original source image height. */
619
+ y: number;
620
+ label: 'positive' | 'negative';
621
+ }
622
+
623
+ export interface Sam3PromptBox {
624
+ /** Normalized top-left and bottom-right coordinates. */
625
+ x0: number;
626
+ y0: number;
627
+ x1: number;
628
+ y1: number;
629
+ }
630
+
631
+ /** A bounded prompt for the SAM3 image-segmentation workflow. */
632
+ export interface Sam3ImagePrompt {
633
+ points?: Sam3PromptPoint[];
634
+ boxes?: Sam3PromptBox[];
635
+ text?: string;
636
+ threshold?: number;
637
+ multimask?: boolean;
638
+ }
639
+
597
640
  export interface ImageProjectParams extends BaseProjectParams {
598
641
  type: 'image';
599
642
  /**
@@ -609,6 +652,12 @@ export interface ImageProjectParams extends BaseProjectParams {
609
652
  * `true` - indicates that the image is already uploaded to the server
610
653
  */
611
654
  startingImage?: InputMedia;
655
+ /**
656
+ * Interactive selection prompt for the SAM3 image segmentation
657
+ * workflow. Coordinates are normalized from 0 to 1 and refer to the original
658
+ * `startingImage`; one source image produces one lossless binary PNG mask.
659
+ */
660
+ sam3Prompt?: Sam3ImagePrompt;
612
661
  /**
613
662
  * How strong effect of starting image should be. From 0 to 1, default 0.5
614
663
  */
package/src/index.ts CHANGED
@@ -33,6 +33,9 @@ import {
33
33
  BillingMode,
34
34
  ImageProjectParams,
35
35
  ImageOutputFormat,
36
+ Sam3ImagePrompt,
37
+ Sam3PromptBox,
38
+ Sam3PromptPoint,
36
39
  ProjectParams,
37
40
  VideoProjectParams,
38
41
  AudioFormat,
@@ -42,8 +45,10 @@ import {
42
45
  SizePreset,
43
46
  EstimateRequest,
44
47
  CostEstimation,
45
- InputMedia
48
+ InputMedia,
49
+ WorldGenerationReceiptRequest
46
50
  } from './Projects/types/index.js';
51
+ import type { JobProvenance } from './Projects/types/JobProvenance.js';
47
52
  import type {
48
53
  AvailableLorasParams,
49
54
  LoraCatalog,
@@ -274,6 +279,9 @@ export type {
274
279
  ErrorData,
275
280
  ImageProjectParams,
276
281
  ImageOutputFormat,
282
+ Sam3ImagePrompt,
283
+ Sam3PromptBox,
284
+ Sam3PromptPoint,
277
285
  JobStatus,
278
286
  Logger,
279
287
  LogLevel,
@@ -381,7 +389,9 @@ export type {
381
389
  WorkloadAttribution,
382
390
  WorkloadAttributionDefaults,
383
391
  WorkloadAttributionInput,
384
- WorkloadKind
392
+ WorkloadKind,
393
+ JobProvenance,
394
+ WorldGenerationReceiptRequest
385
395
  };
386
396
 
387
397
  export type {
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.29.2';
3
+ export const LIB_VERSION = '5.31.0';