@sogni-ai/sogni-client 5.34.0 → 5.35.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 (43) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/dist/Projects/Job.js +7 -0
  3. package/dist/Projects/Job.js.map +1 -1
  4. package/dist/Projects/Project.js +14 -0
  5. package/dist/Projects/Project.js.map +1 -1
  6. package/dist/Projects/createJobRequestMessage.js +56 -3
  7. package/dist/Projects/createJobRequestMessage.js.map +1 -1
  8. package/dist/Projects/index.d.ts +13 -1
  9. package/dist/Projects/index.js +26 -9
  10. package/dist/Projects/index.js.map +1 -1
  11. package/dist/Projects/types/index.d.ts +31 -0
  12. package/dist/Projects/types/index.js.map +1 -1
  13. package/dist/Projects/utils/index.d.ts +7 -0
  14. package/dist/Projects/utils/index.js +9 -2
  15. package/dist/Projects/utils/index.js.map +1 -1
  16. package/dist/index.d.ts +4 -4
  17. package/dist/index.js +2 -1
  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 +8 -1
  22. package/dist-esm/Projects/Job.js.map +1 -1
  23. package/dist-esm/Projects/Project.js +14 -0
  24. package/dist-esm/Projects/Project.js.map +1 -1
  25. package/dist-esm/Projects/createJobRequestMessage.js +57 -4
  26. package/dist-esm/Projects/createJobRequestMessage.js.map +1 -1
  27. package/dist-esm/Projects/index.js +27 -10
  28. package/dist-esm/Projects/index.js.map +1 -1
  29. package/dist-esm/Projects/types/index.js.map +1 -1
  30. package/dist-esm/Projects/utils/index.js +8 -1
  31. package/dist-esm/Projects/utils/index.js.map +1 -1
  32. package/dist-esm/index.js +2 -2
  33. package/dist-esm/index.js.map +1 -1
  34. package/dist-esm/version.js +1 -1
  35. package/package.json +2 -1
  36. package/src/Projects/Job.ts +8 -1
  37. package/src/Projects/Project.ts +13 -0
  38. package/src/Projects/createJobRequestMessage.ts +59 -5
  39. package/src/Projects/index.ts +27 -10
  40. package/src/Projects/types/index.ts +32 -0
  41. package/src/Projects/utils/index.ts +11 -1
  42. package/src/index.ts +4 -0
  43. package/src/version.ts +1 -1
@@ -5,6 +5,7 @@ import {
5
5
  isAudioParams,
6
6
  isImageParams,
7
7
  isVideoParams,
8
+ Pixal3dTemplateVariant,
8
9
  ProjectParams,
9
10
  VideoProjectParams
10
11
  } from './types/index.js';
@@ -59,7 +60,8 @@ import {
59
60
  MINIMAX_H3_MIN_FRAMES,
60
61
  MINIMAX_H3_MAX_FRAMES,
61
62
  MINIMAX_H3_FRAME_STEP,
62
- MINIMAX_H3_BASE_FRAMES
63
+ MINIMAX_H3_BASE_FRAMES,
64
+ isSegmentationModel
63
65
  } from './utils/index.js';
64
66
  import { ApiError } from '../ApiClient/index.js';
65
67
  import {
@@ -71,7 +73,18 @@ import {
71
73
  import { workloadAttributionToWireFields } from '../lib/attribution.js';
72
74
 
73
75
  const SAM3_IMAGE_SEGMENT_WORKFLOW_ID = 'sam3_image_segment_bf16';
76
+ const BIREFNET_BACKGROUND_REMOVAL_WORKFLOW_ID = 'birefnet_image_background_removal_fp16';
74
77
  const PIXAL3D_WORKFLOW_ID = 'pixal3d_int8_i23d';
78
+ // The two graphs ComfyUI's workflows/image/manifest.json registers under the
79
+ // Pixal3D workflow id, by their manifest `variant` names. A closed list, not a
80
+ // passthrough: `templateVariant` is the worker's generic template selector, so
81
+ // an open one would let a caller aim a paid job at any graph a worker carries.
82
+ const PIXAL3D_DEFAULT_TEMPLATE_VARIANT = 'i23d-birefnet';
83
+ const PIXAL3D_PROMPTED_TEMPLATE_VARIANT = 'i23d';
84
+ const PIXAL3D_TEMPLATE_VARIANTS: Pixal3dTemplateVariant[] = [
85
+ PIXAL3D_DEFAULT_TEMPLATE_VARIANT,
86
+ PIXAL3D_PROMPTED_TEMPLATE_VARIANT
87
+ ];
75
88
  const WORLD_TARGET_STILL_MODEL_ID = 'krea2_identity_edit_sogni_v0_3_alpha';
76
89
  const WORLD_TRANSITION_MODEL_ID = 'minimax-h3-fastvideo-int8_flf2v_turbo';
77
90
  const MAX_SAM3_POINTS = 32;
@@ -1208,9 +1221,47 @@ function applyImageParams(
1208
1221
  } else if (params.sam3Prompt !== undefined) {
1209
1222
  throw new Error(`sam3Prompt is only supported by ${SAM3_IMAGE_SEGMENT_WORKFLOW_ID}`);
1210
1223
  }
1224
+ // BiRefNet background removal. One source image, no prompt, and one option:
1225
+ // the bare foreground matte, or that matte carried as the source image's
1226
+ // alpha channel. SAM 3's applyMask is a different field on a different model,
1227
+ // nested inside sam3Prompt, and the two are never read from the same place.
1228
+ if (params.modelId === BIREFNET_BACKGROUND_REMOVAL_WORKFLOW_ID) {
1229
+ if (!params.startingImage) {
1230
+ throw new Error('BiRefNet background removal requires startingImage');
1231
+ }
1232
+ if (params.applyMask !== undefined && typeof params.applyMask !== 'boolean') {
1233
+ throw new Error('applyMask must be a boolean');
1234
+ }
1235
+ keyFrame.applyMask = params.applyMask === true;
1236
+ } else if (params.applyMask !== undefined) {
1237
+ throw new Error(`applyMask is only supported by ${BIREFNET_BACKGROUND_REMOVAL_WORKFLOW_ID}`);
1238
+ }
1211
1239
  if (params.modelId === PIXAL3D_WORKFLOW_ID && !params.startingImage) {
1212
1240
  throw new Error('Pixal3D reconstruction requires startingImage');
1213
1241
  }
1242
+ // Which of the two Pixal3D graphs to run. Unset is not the same as naming the
1243
+ // default: a worker resolves only the variants its own manifest declares, so
1244
+ // an unset field lets each worker run its own shipped default, while naming
1245
+ // one pins the graph for callers that need the other path.
1246
+ if (params.templateVariant !== undefined) {
1247
+ if (params.modelId !== PIXAL3D_WORKFLOW_ID) {
1248
+ throw new Error(`templateVariant is only supported by ${PIXAL3D_WORKFLOW_ID}`);
1249
+ }
1250
+ if (!PIXAL3D_TEMPLATE_VARIANTS.includes(params.templateVariant)) {
1251
+ throw new Error(`templateVariant must be one of: ${PIXAL3D_TEMPLATE_VARIANTS.join(', ')}`);
1252
+ }
1253
+ // The prompted graph selects the object to reconstruct. With no prompt it
1254
+ // reconstructs whatever the empty string picks out, at the same price.
1255
+ if (
1256
+ params.templateVariant === PIXAL3D_PROMPTED_TEMPLATE_VARIANT &&
1257
+ !params.positivePrompt?.trim()
1258
+ ) {
1259
+ throw new Error(
1260
+ `templateVariant "${PIXAL3D_PROMPTED_TEMPLATE_VARIANT}" requires positivePrompt`
1261
+ );
1262
+ }
1263
+ keyFrame.templateVariant = params.templateVariant;
1264
+ }
1214
1265
  for (const [key, limit] of Object.entries(PIXAL3D_REDUCE_ONLY_LIMITS)) {
1215
1266
  const requested = (params as Record<string, any>)[key];
1216
1267
  if (requested === undefined) continue;
@@ -1576,14 +1627,17 @@ function createJobRequestMessage(id: string, params: ProjectParams, options: Mod
1576
1627
  const jobRequest: Record<string, any> = {
1577
1628
  ...template,
1578
1629
  keyFrames: [keyFrame],
1630
+ // No utility workflow has intermediate images to preview: segmentation
1631
+ // returns one mask and Pixal3D a 3D reconstruction.
1579
1632
  previews:
1580
- params.modelId === SAM3_IMAGE_SEGMENT_WORKFLOW_ID
1633
+ isSegmentationModel(params.modelId) || params.modelId === PIXAL3D_WORKFLOW_ID
1581
1634
  ? 0
1582
1635
  : isImageParams(params)
1583
1636
  ? params.numberOfPreviews || 0
1584
1637
  : 0,
1585
- numberOfImages:
1586
- params.modelId === SAM3_IMAGE_SEGMENT_WORKFLOW_ID ? 1 : params.numberOfMedia || 1,
1638
+ // Segmentation is deterministic: it takes no seed, so N copies of one
1639
+ // source are N identical masks at N times the price.
1640
+ numberOfImages: isSegmentationModel(params.modelId) ? 1 : params.numberOfMedia || 1,
1587
1641
  jobID: id,
1588
1642
  disableSafety: !!params.disableNSFWFilter,
1589
1643
  tokenType: params.tokenType,
@@ -1591,7 +1645,7 @@ function createJobRequestMessage(id: string, params: ProjectParams, options: Mod
1591
1645
  outputFormat:
1592
1646
  params.modelId === PIXAL3D_WORKFLOW_ID
1593
1647
  ? 'glb'
1594
- : params.modelId === SAM3_IMAGE_SEGMENT_WORKFLOW_ID
1648
+ : isSegmentationModel(params.modelId)
1595
1649
  ? 'png'
1596
1650
  : params.outputFormat ||
1597
1651
  (isAudioParams(params) ? 'mp3' : isVideoParams(params) ? 'mp4' : 'png'),
@@ -68,6 +68,7 @@ import {
68
68
  isAudioModel,
69
69
  isModelArtifactModel,
70
70
  isMinimaxH3ReferenceModel,
71
+ isSegmentationModel,
71
72
  isVideoModel,
72
73
  usesReferenceMask
73
74
  } from './utils/index.js';
@@ -402,13 +403,23 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
402
403
  return isAudioModel(modelId);
403
404
  }
404
405
 
405
- /** Check whether a model returns a 3D artifact through the media endpoint. */
406
+ /**
407
+ * Check whether a model returns a 3D artifact through the media endpoint.
408
+ *
409
+ * The `pixal3d_` prefix is a positive override here, not merely a fallback
410
+ * for an unloaded catalog. That prefix is structural rather than curated:
411
+ * every Pixal3D workflow reconstructs a binary glTF, and the image download
412
+ * endpoint cannot serve one. A catalog that mislabels such a model as
413
+ * `image` therefore breaks every artifact download with no client-side
414
+ * recovery, so the SDK's own knowledge wins wherever it has any.
415
+ *
416
+ * The catalog stays authoritative for every model the SDK has no prefix
417
+ * knowledge of, so a future `media: 'model'` family needs no SDK release.
418
+ */
406
419
  isModelArtifactModelId(modelId: string): boolean {
420
+ if (isModelArtifactModel(modelId)) return true;
407
421
  const model = this._supportedModels.data?.find((m) => m.id === modelId);
408
- if (model) {
409
- return model.media === 'model';
410
- }
411
- return isModelArtifactModel(modelId);
422
+ return model ? model.media === 'model' : false;
412
423
  }
413
424
 
414
425
  constructor(config: ApiConfig) {
@@ -1340,11 +1351,11 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
1340
1351
  * @param data
1341
1352
  */
1342
1353
  async create(data: ProjectParams): Promise<Project> {
1343
- // SAM3 is a one-source/one-mask utility workflow. Normalize before Project
1344
- // construction so lifecycle completion and result MIME use the same values
1345
- // as the serialized request.
1346
- const normalizedData =
1347
- data.type === 'image' && data.modelId === 'sam3_image_segment_bf16'
1354
+ // Segmentation is a one-source/one-mask utility workflow, SAM 3 and
1355
+ // BiRefNet alike. Normalize before Project construction so lifecycle
1356
+ // completion and result MIME use the same values as the serialized request.
1357
+ let normalizedData =
1358
+ data.type === 'image' && isSegmentationModel(data.modelId)
1348
1359
  ? ({
1349
1360
  ...data,
1350
1361
  numberOfMedia: 1,
@@ -1352,6 +1363,12 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
1352
1363
  outputFormat: 'png'
1353
1364
  } as ProjectParams)
1354
1365
  : data;
1366
+ // Pixal3D reconstructs a 3D artifact, so there are no intermediate images
1367
+ // to preview. Normalize here as well as on the wire so the Project's own
1368
+ // params agree with the request that was actually sent.
1369
+ if (normalizedData.type === 'image' && isModelArtifactModel(normalizedData.modelId)) {
1370
+ normalizedData = { ...normalizedData, numberOfPreviews: 0 } as ProjectParams;
1371
+ }
1355
1372
  const project = new Project({ ...normalizedData }, { api: this, logger: this.client.logger });
1356
1373
  const modelOptions = await this.getModelOptions(normalizedData.modelId);
1357
1374
  const requestParams = {
@@ -675,7 +675,26 @@ export interface Sam3ImagePrompt {
675
675
  * is far heavier than a real-time engine wants, so asking for less yields a
676
676
  * more useful asset.
677
677
  */
678
+ /**
679
+ * Which Pixal3D reconstruction graph to run.
680
+ *
681
+ * ComfyUI registers two under the one workflow id. `i23d-birefnet` is the
682
+ * default: it isolates the subject with BiRefNet and takes no prompt.
683
+ * `i23d` is the prompted graph, where `positivePrompt` names the object to
684
+ * reconstruct rather than describing how it should look.
685
+ *
686
+ * Both cost the same and accept the same options. Leave it unset to let the
687
+ * worker run its own default, which is what every caller wants unless it
688
+ * specifically needs the prompted path.
689
+ */
690
+ export type Pixal3dTemplateVariant = 'i23d-birefnet' | 'i23d';
691
+
678
692
  export interface Pixal3dGenerationOptions {
693
+ /**
694
+ * Which reconstruction graph to run. Unset means the worker's own default.
695
+ * `i23d` requires `positivePrompt`.
696
+ */
697
+ templateVariant?: Pixal3dTemplateVariant;
679
698
  /** Base-colour bake and UV atlas resolution, 1024 to 4096. Default 4096. */
680
699
  textureSize?: number;
681
700
  /** Decimation target in triangles, 5000 to 700000. Default 700000. */
@@ -721,6 +740,19 @@ export interface ImageProjectParams extends BaseProjectParams, Pixal3dGeneration
721
740
  * `startingImage`; one source image produces one lossless binary PNG mask.
722
741
  */
723
742
  sam3Prompt?: Sam3ImagePrompt;
743
+ /**
744
+ * Return an RGBA cutout instead of the bare mask.
745
+ *
746
+ * Only for `birefnet_image_background_removal_fp16`, which requires a
747
+ * `startingImage` and takes no prompt. Left unset (the default) the job
748
+ * returns the foreground matte at the source dimensions; set, it returns the
749
+ * source image carrying that matte as its alpha channel, so the mask is still
750
+ * recoverable from the artifact.
751
+ *
752
+ * SAM 3 has its own `applyMask`, inside `sam3Prompt`. They are different
753
+ * fields on different models and are not interchangeable.
754
+ */
755
+ applyMask?: boolean;
724
756
  /**
725
757
  * How strong effect of starting image should be. From 0 to 1, default 0.5
726
758
  */
@@ -99,6 +99,9 @@ export const PIXAL3D_IMAGE_TO_3D_MODEL_ID = 'pixal3d_int8_i23d';
99
99
  /** Canonical id of the SAM 3 interactive image-segmentation workflow. */
100
100
  export const SAM3_IMAGE_SEGMENT_MODEL_ID = 'sam3_image_segment_bf16';
101
101
 
102
+ /** Canonical id of the standalone BiRefNet background-removal workflow. */
103
+ export const BIREFNET_BACKGROUND_REMOVAL_MODEL_ID = 'birefnet_image_background_removal_fp16';
104
+
102
105
  /** Check if a model returns a downloadable 3D model artifact. */
103
106
  export function isModelArtifactModel(modelId: string): boolean {
104
107
  return modelId.startsWith('pixal3d_');
@@ -110,9 +113,16 @@ export function isModelArtifactModel(modelId: string): boolean {
110
113
  * Segmentation returns a lossless mask PNG the same size as the source, not a
111
114
  * new image, so callers must not treat it as a generated result: it has no
112
115
  * meaningful prompt-to-pixels relationship and is not enhanceable.
116
+ *
117
+ * BiRefNet counts. It reaches the same artifact with no prompt at all, and its
118
+ * cutout branch is that mask carried as an alpha channel, so every consumer
119
+ * that hides a mask from a gallery, refuses to enhance one, or requires a
120
+ * source image has to treat it exactly as it treats SAM 3.
113
121
  */
114
122
  export function isSegmentationModel(modelId: string): boolean {
115
- return modelId === SAM3_IMAGE_SEGMENT_MODEL_ID;
123
+ return (
124
+ modelId === SAM3_IMAGE_SEGMENT_MODEL_ID || modelId === BIREFNET_BACKGROUND_REMOVAL_MODEL_ID
125
+ );
116
126
  }
117
127
 
118
128
  /**
package/src/index.ts CHANGED
@@ -24,6 +24,7 @@ import { DefaultLogger, Logger, LogLevel } from './lib/DefaultLogger.js';
24
24
  import EIP712Helper from './lib/EIP712Helper.js';
25
25
  // Projects API
26
26
  import {
27
+ BIREFNET_BACKGROUND_REMOVAL_MODEL_ID,
27
28
  PIXAL3D_IMAGE_TO_3D_MODEL_ID,
28
29
  SAM3_IMAGE_SEGMENT_MODEL_ID,
29
30
  isAudioModel,
@@ -43,6 +44,7 @@ import {
43
44
  ImageProjectParams,
44
45
  ImageOutputFormat,
45
46
  Pixal3dGenerationOptions,
47
+ Pixal3dTemplateVariant,
46
48
  Sam3ImagePrompt,
47
49
  Sam3PromptBox,
48
50
  Sam3PromptPoint,
@@ -291,6 +293,7 @@ export type {
291
293
  ImageProjectParams,
292
294
  ImageOutputFormat,
293
295
  Pixal3dGenerationOptions,
296
+ Pixal3dTemplateVariant,
294
297
  Sam3ImagePrompt,
295
298
  Sam3PromptBox,
296
299
  Sam3PromptPoint,
@@ -418,6 +421,7 @@ export type {
418
421
  };
419
422
 
420
423
  export {
424
+ BIREFNET_BACKGROUND_REMOVAL_MODEL_ID,
421
425
  PIXAL3D_IMAGE_TO_3D_MODEL_ID,
422
426
  SAM3_IMAGE_SEGMENT_MODEL_ID,
423
427
  isAudioModel,
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.34.0';
3
+ export const LIB_VERSION = '5.35.0';