@sogni-ai/sogni-client 4.2.0-alpha.2 → 4.2.0-alpha.21

package/src/Projects/types/index.ts

@@ -32,7 +32,9 @@ export interface SizePreset {
   aspect: string;
 }
 
-export type ImageOutputFormat = 'png' | 'jpg';
+export type ImageOutputFormat = 'png' | 'jpg' | 'webp';
+export type GptImageQuality = 'low' | 'medium' | 'high' | 'auto' | 'standard' | 'hd';
+export type GptImageBackground = 'opaque' | 'auto';
 export type VideoOutputFormat = 'mp4';
 export type AudioOutputFormat = 'mp3' | 'flac' | 'wav';
 
@@ -85,6 +87,10 @@ export interface BaseProjectParams {
    * If not specified, the Sogni token will be used.
    */
   tokenType?: TokenType;
+  /**
+   * Optional client app/source label to attach to the project request for server-side attribution.
+   */
+  appSource?: string;
   /**
    * Array of LoRA IDs to apply.
    * Available LoRAs are model-specific. The worker will download the LoRA
@@ -123,6 +129,14 @@ export type InputMedia = File | Buffer | Blob | boolean;
  * - Frame count is calculated as: `duration * fps + 1`
  * - Frame count must follow the pattern: `1 + n*8` (i.e., 1, 9, 17, 25, 33, ...)
  * - Example: 5 seconds at 24fps = 121 frames (since 121 = 1 + 15*8)
+ *
+ * ### Seedance 2.0 Models (seedance-2-0*)
+ * - External API-backed video models for text-to-video, image-to-video,
+ *   multimodal reference generation, image+audio-to-video, and video-to-video
+ * - Generate at fixed 24fps
+ * - Direct SDK project duration range is 4 to 15 seconds
+ * - Frame count is calculated as: `duration * 24 + 1`
+ * - Vendor reference limits are 9 images, 3 videos, 3 audios, and 12 asset files total
  */
 export interface VideoProjectParams extends BaseProjectParams {
   type: 'video';
@@ -133,11 +147,13 @@ export interface VideoProjectParams extends BaseProjectParams {
    */
   frames?: number;
   /**
-   * Duration of the video in seconds. Supported range 1 to 10 (WAN) or 4 to 20 (LTX-2.3).
+   * Duration of the video in seconds. Supported range 1 to 10 (WAN), 4 to 20 (LTX-2.3),
+   * or 4 to 15 (Seedance direct SDK projects).
    *
    * The SDK automatically calculates the correct frame count based on the model:
    * - WAN 2.2: `duration * 16 + 1` (always 16fps generation)
    * - LTX-2.3: `duration * fps + 1`, snapped to frame step constraint
+   * - Seedance: `duration * 24 + 1`
    */
   duration?: number;
   /**
@@ -148,6 +164,8 @@ export interface VideoProjectParams extends BaseProjectParams {
    *
    * **LTX-2.3 Models:** Any value from 1-60 fps. This directly controls the generation
    * frame rate - there is no post-render interpolation.
+   *
+   * **Seedance Models:** Fixed 24fps external API generation.
    */
   fps?: number;
   /**
@@ -167,6 +185,12 @@ export interface VideoProjectParams extends BaseProjectParams {
    * Maps to: startImage (i2v), characterImage (animate), referenceImage (s2v, ia2v)
    */
   referenceImage?: InputMedia;
+  /**
+   * Seedance-only loose image context references. These must be publicly
+   * accessible HTTPS URLs that the vendor can fetch. Use referenceImage /
+   * referenceImageEnd when the image should lock the first or last frame.
+   */
+  referenceImageUrls?: string[];
   /**
    * Optional end image for i2v interpolation workflows.
    * When provided with referenceImage, the video will interpolate between the two images.
@@ -176,6 +200,17 @@ export interface VideoProjectParams extends BaseProjectParams {
    * Reference audio for audio-driven video workflows (s2v, ia2v, a2v).
    */
   referenceAudio?: InputMedia;
+  /**
+   * Seedance-only audio context references. These must be publicly accessible
+   * HTTPS URLs. Seedance does not support text+audio-only requests; include at
+   * least one image or video reference when using audio URL references.
+   */
+  referenceAudioUrls?: string[];
+  /**
+   * Enable native audio generation for external API-backed video models that support it.
+   * Seedance defaults to audio enabled server-side; set to false to request a silent video.
+   */
+  generateAudio?: boolean;
   /**
    * Reference audio for ID-LoRA speaker identity transfer (LTX-2.3 only).
    * Provide a ~5 second audio clip of the target speaker's voice.
@@ -208,6 +243,11 @@ export interface VideoProjectParams extends BaseProjectParams {
    * Maps to: drivingVideo (animate-move), sourceVideo (animate-replace), referenceVideo (v2v)
    */
   referenceVideo?: InputMedia;
+  /**
+   * Seedance-only video context references. These must be publicly accessible
+   * HTTPS URLs and map to Seedance reference_video assets.
+   */
+  referenceVideoUrls?: string[];
   /**
    * ControlNet parameters for LTX-2.3 v2v workflows.
    * Specifies which control signal to extract from the reference video.
@@ -301,6 +341,7 @@ export interface ImageProjectParams extends BaseProjectParams {
   startingImageStrength?: number;
   /**
    * Context images for multi-reference image generation.
+   * GPT Image 2 supports up to 16 context images.
    * Flux.2 Dev supports up to 6 context images.
    * Qwen Image Edit Plus supports up to 3 context images.
    * Flux Kontext supports up to 2 context images.
@@ -337,6 +378,15 @@ export interface ImageProjectParams extends BaseProjectParams {
    * Output format. Can be 'png' or 'jpg'. Defaults to 'png'.
    */
   outputFormat?: ImageOutputFormat;
+  /**
+   * GPT Image 2 quality preset. Only used by external OpenAI image models.
+   * Defaults to 'medium'.
+   */
+  gptImageQuality?: GptImageQuality;
+  /**
+   * GPT Image 2 background mode. Only used by external OpenAI image models.
+   */
+  gptImageBackground?: GptImageBackground;
 }
 
 export interface AudioProjectParams extends BaseProjectParams {
@@ -446,6 +496,16 @@ export type ImageUrlParams = {
     | 'contextImage4'
     | 'contextImage5'
     | 'contextImage6'
+    | 'contextImage7'
+    | 'contextImage8'
+    | 'contextImage9'
+    | 'contextImage10'
+    | 'contextImage11'
+    | 'contextImage12'
+    | 'contextImage13'
+    | 'contextImage14'
+    | 'contextImage15'
+    | 'contextImage16'
     | 'referenceImage'
     | 'referenceImageEnd';
   startContentType?: string;
@@ -520,10 +580,18 @@ export interface EstimateRequest {
    */
   sampler?: string;
   /**
-   * Number of context images to use (for Flux Kontext).
-   * Note that this parameter is ignored if `scheduler` is not provided
+   * Number of context images to use. Affects GPT Image 2 input-image pricing
+   * and context-aware worker timing estimates.
    */
   contextImages?: number;
+  /**
+   * GPT Image 2 quality preset, when estimating external OpenAI image jobs.
+   */
+  gptImageQuality?: GptImageQuality;
+  /**
+   * Output format, when estimating models with format-specific request metadata.
+   */
+  outputFormat?: ImageOutputFormat;
 }
 
 export interface VideoEstimateRequest {
@@ -538,8 +606,20 @@ export interface VideoEstimateRequest {
    */
   frames?: number;
   fps: number;
-  steps: number;
+  steps?: number;
   numberOfMedia: number;
+  /**
+   * Price Seedance estimates using the video-input rate band.
+   */
+  hasVideoInput?: boolean;
+  /**
+   * Optional estimate-only signal: presence implies Seedance video-input pricing.
+   */
+  referenceVideo?: unknown;
+  /**
+   * Optional estimate-only signal: non-empty list implies Seedance video-input pricing.
+   */
+  referenceVideoUrls?: string[];
 }
 
 export interface AudioEstimateRequest {
@@ -567,7 +647,7 @@ export interface CostEstimation {
 export type EnhancementStrength = 'light' | 'medium' | 'heavy';
 
 /**
- * Video workflow types for WAN and LTX-2.3 models
+ * Video workflow types for WAN, LTX-2.3, and Seedance models
  */
 export type VideoWorkflowType =
   | 't2v'

package/src/Projects/utils/index.ts

@@ -17,7 +17,12 @@ export function getEnhacementStrength(strength: EnhancementStrength): number {
  * Video models produce MP4 output; image models produce PNG/JPG output.
  */
 export function isVideoModel(modelId: string): boolean {
-  return modelId.startsWith('wan_') || modelId.startsWith('ltx2-') || modelId.startsWith('ltx23-');
+  return (
+    modelId.startsWith('wan_') ||
+    modelId.startsWith('ltx2-') ||
+    modelId.startsWith('ltx23-') ||
+    modelId.startsWith('seedance-2-0')
+  );
 }
 
 /**
@@ -67,6 +72,16 @@ export function isLtx2Model(modelId: string): boolean {
   return modelId.startsWith('ltx2-') || modelId.startsWith('ltx23-');
 }
 
+/**
+ * Check if a model ID is a Seedance 2.0 video model.
+ *
+ * Seedance models are external API-backed video models. They generate at
+ * 24fps and support 4-15 second direct SDK project durations.
+ */
+export function isSeedanceModel(modelId: string): boolean {
+  return modelId.startsWith('seedance-2-0');
+}
+
 /**
  * LTX-2.3 frame step constraint.
  * Valid frame counts follow the pattern: 1 + n*8 (i.e., 1, 9, 17, 25, 33, ...)
@@ -76,7 +91,7 @@ export const LTX2_FRAME_STEP = 8;
 /**
  * Calculate the frame count for a given duration and fps based on the video model.
  *
- * ## Standard Behavior (LTX-2.3 and future models)
+ * ## Standard Behavior (LTX-2.3, Seedance, and future models)
  * - Generate at the actual specified FPS (no interpolation)
  * - Formula: duration * fps + 1
  * - LTX-2.3 specific: Frame count must follow the pattern: 1 + n*8
@@ -139,21 +154,22 @@ export function getVideoWorkflowType(modelId: string): VideoWorkflowType {
   // Check for supported video model prefixes
   const isWan = modelId.startsWith('wan_');
   const isLtx2 = modelId.startsWith('ltx2-') || modelId.startsWith('ltx23-');
+  const isSeedance = modelId.startsWith('seedance-2-0');
 
-  if (!isWan && !isLtx2) return null;
+  if (!isWan && !isLtx2 && !isSeedance) return null;
 
-  // WAN and LTX-2.3 models share similar workflow type suffixes
+  // WAN, LTX-2.3, and Seedance models share similar workflow type suffixes
   if (modelId.includes('_i2v')) return 'i2v';
   if (modelId.includes('_t2v')) return 't2v';
 
-  // LTX-2.3 v2v ControlNet workflows (model IDs use underscore: ltx23-22b-fp8_v2v_distilled)
-  if (isLtx2 && modelId.includes('_v2v')) return 'v2v';
+  // LTX-2.3 v2v ControlNet and Seedance v2v workflows
+  if ((isLtx2 || isSeedance) && modelId.includes('_v2v')) return 'v2v';
 
-  // LTX-2.3 audio-to-video workflows
+  // LTX-2.3 and Seedance image+audio workflows
   // ia2v = image+audio to video (requires referenceImage + referenceAudio)
   // a2v = audio to video (requires referenceAudio only)
   // Note: Check _ia2v before _a2v since _ia2v contains _a2v as a substring
-  if (isLtx2 && modelId.includes('_ia2v')) return 'ia2v';
+  if ((isLtx2 || isSeedance) && modelId.includes('_ia2v')) return 'ia2v';
   if (isLtx2 && modelId.includes('_a2v')) return 'a2v';
 
   // WAN-specific workflow types

package/src/index.ts

@@ -4,6 +4,16 @@ import CurrentAccount from './Account/CurrentAccount';
 // ApiClient
 import ApiClient, { ApiError, ApiResponse } from './ApiClient';
 import { SupernetType } from './ApiClient/WebSocketClient/types';
+import type {
+  SocketEventName,
+  SocketEventSubscriptionsUpdatedData
+} from './ApiClient/WebSocketClient/events';
+import type {
+  SocketEventSubscriptionInput,
+  SocketEventSubscriptionName,
+  SocketEventSubscriptions,
+  SocketEventSubscriptionUpdate
+} from './ApiClient/WebSocketClient/eventSubscriptions';
 import { ApiConfig } from './ApiGroup';
 // Utils
 import { DefaultLogger, Logger, LogLevel } from './lib/DefaultLogger';
@@ -42,7 +52,13 @@ import {
   ChatCompletionChunk,
   ChatCompletionResult,
   ChatJobStateEvent,
+  ChatResponseFormat,
   ContentPart,
+  HostedChatCompletionParams,
+  HostedChatCompletionResult,
+  HostedChatCompletionChoice,
+  HostedChatCompletionMessage,
+  HostedCreativeWorkflowReference,
   TextContentPart,
   ImageUrlContentPart,
   TokenUsage as ChatTokenUsage,
@@ -57,12 +73,32 @@ import {
   ToolCallFunction,
   ToolChoice,
   ToolFunction,
+  SogniToolsMode,
   ToolExecutionProgress,
   ToolExecutionResult,
   ToolHistoryEntry,
   ToolExecutionOptions
 } from './Chat/types';
 import { SogniTools, buildSogniTools, isSogniToolCall, parseToolCallArguments } from './Chat/tools';
+// Creative Workflows API
+import CreativeWorkflowsApi, { parseCreativeWorkflowSseChunk } from './CreativeWorkflows';
+import {
+  CreativeWorkflowArtifact,
+  CreativeWorkflowEvent,
+  CreativeWorkflowKind,
+  CreativeWorkflowRecord,
+  CreativeWorkflowSseEvent,
+  CreativeWorkflowStatus,
+  CreativeWorkflowHostedToolName,
+  ListCreativeWorkflowOptions,
+  StartCreativeWorkflowOptions,
+  StartCreativeWorkflowParams,
+  StartHostedToolSequenceWorkflowDependency,
+  StartHostedToolSequenceWorkflowInput,
+  StartHostedToolSequenceWorkflowStep,
+  StartImageToVideoWorkflowInput,
+  StreamCreativeWorkflowEventsOptions
+} from './CreativeWorkflows/types';
 // Stats API
 import StatsApi from './Stats';
 // Base Types
@@ -86,9 +122,22 @@ export type {
   ChatCompletionResult,
   ChatJobStateEvent,
   ChatMessage,
+  ChatResponseFormat,
   ChatTokenUsage,
   ContentPart,
+  HostedChatCompletionChoice,
+  HostedChatCompletionMessage,
+  HostedChatCompletionParams,
+  HostedChatCompletionResult,
+  HostedCreativeWorkflowReference,
+  CreativeWorkflowArtifact,
+  CreativeWorkflowEvent,
+  CreativeWorkflowKind,
+  CreativeWorkflowRecord,
+  CreativeWorkflowSseEvent,
+  CreativeWorkflowStatus,
   ImageUrlContentPart,
+  ListCreativeWorkflowOptions,
   LLMCostEstimation,
   LLMJobCost,
   LLMModelInfo,
@@ -106,6 +155,14 @@ export type {
   LogLevel,
   ProjectParams,
   ProjectStatus,
+  CreativeWorkflowHostedToolName,
+  StartCreativeWorkflowOptions,
+  StartCreativeWorkflowParams,
+  StartHostedToolSequenceWorkflowDependency,
+  StartHostedToolSequenceWorkflowInput,
+  StartHostedToolSequenceWorkflowStep,
+  StartImageToVideoWorkflowInput,
+  StreamCreativeWorkflowEventsOptions,
   SupernetType,
   TokenType,
   ToolCall,
@@ -118,6 +175,13 @@ export type {
   ToolExecutionResult,
   ToolFunction,
   ToolHistoryEntry,
+  SogniToolsMode,
+  SocketEventName,
+  SocketEventSubscriptionInput,
+  SocketEventSubscriptionName,
+  SocketEventSubscriptions,
+  SocketEventSubscriptionsUpdatedData,
+  SocketEventSubscriptionUpdate,
   VideoControlNetName,
   VideoControlNetParams,
   VideoFormat,
@@ -131,12 +195,14 @@ export {
   ApiKeyAuthManager,
   ChatStream,
   ChatToolsApi,
+  CreativeWorkflowsApi,
   CurrentAccount,
   Job,
   Project,
   SogniTools,
   buildSogniTools,
   isSogniToolCall,
+  parseCreativeWorkflowSseChunk,
   parseToolCallArguments
 };
 
@@ -145,6 +211,19 @@ export interface SogniClientConfig {
    * The application ID string. Must be unique, multiple connections with the same ID will be rejected.
    */
   appId: string;
+  /**
+   * Optional client app/source label to attach to this connection for server-side attribution.
+   * The socket server uses this as the default source for project and chat requests from this client.
+   */
+  appSource?: string;
+  /**
+   * Initial WebSocket event subscriptions for this connection.
+   *
+   * Omit this option to receive the default socket event stream. To reduce socket traffic for
+   * proxy or headless clients that do not need live worker counts, set
+   * `{ modelAvailability: false }` to opt out of `swarmModels` and `swarmLLMModels` updates.
+   */
+  socketEventSubscriptions?: SocketEventSubscriptions;
   /**
    * Override the default REST API endpoint
    * @internal
@@ -214,6 +293,7 @@ export class SogniClient {
   projects: ProjectsApi;
   stats: StatsApi;
   chat: ChatApi;
+  creativeWorkflows: CreativeWorkflowsApi;
 
   apiClient: ApiClient;
 
@@ -222,6 +302,7 @@ export class SogniClient {
     this.projects = new ProjectsApi(config);
     this.stats = new StatsApi(config);
     this.chat = new ChatApi(config, this.projects);
+    this.creativeWorkflows = new CreativeWorkflowsApi(config);
 
     this.apiClient = config.client;
   }
@@ -277,6 +358,16 @@ export class SogniClient {
     this.apiClient.dispose();
   }
 
+  /**
+   * Update WebSocket event subscriptions for this live client.
+   *
+   * This is useful when a process needs the initial model availability snapshot for startup, but
+   * does not need ongoing worker count updates afterward.
+   */
+  async setSocketEventSubscriptions(update: SocketEventSubscriptionInput): Promise<void> {
+    await this.apiClient.setSocketEventSubscriptions(update);
+  }
+
   /**
    * Create client instance, with default configuration
    * @param config
@@ -293,6 +384,8 @@ export class SogniClient {
       baseUrl: restEndpoint,
       socketUrl: socketEndpoint,
       appId: config.appId,
+      appSource: config.appSource,
+      socketEventSubscriptions: config.socketEventSubscriptions,
       networkType: network,
       logger,
       authType,

package/src/lib/RestClient.ts

@@ -4,6 +4,10 @@ import { JSONValue } from '../types/json';
 import { Logger } from './DefaultLogger';
 import { AuthManager } from './AuthManager';
 
+interface RestRequestInit extends RequestInit {
+  timeoutMs?: number;
+}
+
 class RestClient<E extends EventMap = never> extends TypedEventEmitter<E> {
   readonly baseUrl: string;
   protected _auth: AuthManager;
@@ -28,14 +32,15 @@ class RestClient<E extends EventMap = never> extends TypedEventEmitter<E> {
     return url.toString();
   }
 
-  private async request<T = JSONValue>(url: string, options: RequestInit = {}): Promise<T> {
-    const init = await this.auth.authenticateRequest(options);
+  private async request<T = JSONValue>(url: string, options: RestRequestInit = {}): Promise<T> {
+    const { timeoutMs = 30000, ...requestOptions } = options;
+    const init = await this.auth.authenticateRequest(requestOptions);
 
     // Add a timeout to detect hanging requests
     const controller = new AbortController();
     const timeoutId = setTimeout(() => {
       controller.abort();
-    }, 30000);
+    }, timeoutMs);
 
     try {
       const response = await fetch(url, { ...init, signal: controller.signal });
@@ -69,13 +74,18 @@ class RestClient<E extends EventMap = never> extends TypedEventEmitter<E> {
     return this.request<T>(this.formatUrl(path, query));
   }
 
-  post<T = JSONValue>(path: string, body: Record<string, unknown> = {}): Promise<T> {
+  post<T = JSONValue>(
+    path: string,
+    body: Record<string, unknown> = {},
+    options: Pick<RestRequestInit, 'timeoutMs'> = {}
+  ): Promise<T> {
     return this.request<T>(this.formatUrl(path), {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json'
       },
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      ...options
     });
   }
 }