@sogni-ai/sogni-client 4.0.0-alpha.5 → 4.0.0-alpha.51

package/src/Projects/index.ts

@@ -4,12 +4,18 @@ import {
   EnhancementStrength,
   EstimateRequest,
   ImageUrlParams,
+  MediaUrlParams,
+  CostEstimation,
   ProjectParams,
   SizePreset,
-  SupportedModel
+  SupportedModel,
+  ImageProjectParams,
+  VideoProjectParams,
+  VideoEstimateRequest
 } from './types';
 import {
   JobErrorData,
+  JobETAData,
   JobProgressData,
   JobResultData,
   JobStateData,
@@ -26,13 +32,50 @@ import ErrorData from '../types/ErrorData';
 import { SupernetType } from '../ApiClient/WebSocketClient/types';
 import Cache from '../lib/Cache';
 import { enhancementDefaults } from './Job';
-import { getEnhacementStrength } from './utils';
+import {
+  getEnhacementStrength,
+  getVideoWorkflowType,
+  isVideoModel,
+  VIDEO_WORKFLOW_ASSETS
+} from './utils';
 import { TokenType } from '../types/token';
+import { getMaxContextImages, validateSampler } from '../lib/validation';
+import ModelTiersRaw, { isComfyImageTier, isImageTier, isVideoTier } from './types/ModelTiersRaw';
+import { mapComfyImageTier, mapImageTier, mapVideoTier, ModelOptions } from './types/ModelOptions';
 
 const sizePresetCache = new Cache<SizePreset[]>(10 * 60 * 1000);
 const GARBAGE_COLLECT_TIMEOUT = 30000;
 const MODELS_REFRESH_INTERVAL = 1000 * 60 * 60 * 24; // 24 hours
 
+/**
+ * Detect content type from a file object.
+ * For File objects in browser, uses the type property.
+ * Returns undefined if content type cannot be detected.
+ */
+function getFileContentType(file: File | Buffer | Blob): string | undefined {
+  if (file instanceof Blob && 'type' in file && file.type) {
+    return file.type;
+  }
+  return undefined;
+}
+
+/**
+ * Convert file to a format compatible with fetch body.
+ * Converts Node.js Buffer to Blob for cross-platform compatibility.
+ */
+function toFetchBody(file: File | Buffer | Blob): BodyInit {
+  // Node.js Buffer is not supported in browsers, so we can skip this conversion
+  if (typeof Buffer === 'undefined') {
+    return file as BodyInit;
+  }
+  if (Buffer.isBuffer(file)) {
+    // Copy Buffer data to a new ArrayBuffer to ensure type compatibility
+    const arrayBuffer = file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
+    return new Blob([arrayBuffer as ArrayBuffer]);
+  }
+  return file as BodyInit;
+}
+
 function mapErrorCodes(code: string): number {
   switch (code) {
     case 'serverRestarting':
@@ -57,11 +100,32 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     data: null,
     updatedAt: new Date(0)
   };
+  private _modelTiers: {
+    data: ModelTiersRaw;
+    updatedAt: Date;
+  } = {
+    data: {},
+    updatedAt: new Date(0)
+  };
 
   get availableModels() {
     return this._availableModels;
   }
 
+  /**
+   * Check if a model produces video output using the cached models list.
+   * Uses the `media` property from the models API when available,
+   * falls back to model ID prefix check if models aren't loaded yet.
+   */
+  isVideoModelId(modelId: string): boolean {
+    const model = this._supportedModels.data?.find((m) => m.id === modelId);
+    if (model) {
+      return model.media === 'video';
+    }
+    // Fallback to prefix check if models not loaded
+    return isVideoModel(modelId);
+  }
+
   constructor(config: ApiConfig) {
     super(config);
     // Listen to server events and emit them as project and job events
@@ -69,8 +133,13 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     this.client.socket.on('swarmModels', this.handleSwarmModels.bind(this));
     this.client.socket.on('jobState', this.handleJobState.bind(this));
     this.client.socket.on('jobProgress', this.handleJobProgress.bind(this));
+    this.client.socket.on('jobETA', this.handleJobETA.bind(this));
     this.client.socket.on('jobError', this.handleJobError.bind(this));
-    this.client.socket.on('jobResult', this.handleJobResult.bind(this));
+    this.client.socket.on('jobResult', (data: any) => {
+      this.handleJobResult(data).catch((err) => {
+        this.client.logger.error('Error in handleJobResult:', err);
+      });
+    });
     // Listen to the server disconnect event
     this.client.on('disconnected', this.handleServerDisconnected.bind(this));
     // Listen to project and job events and update project and job instances
@@ -78,6 +147,17 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     this.on('job', this.handleJobEvent.bind(this));
   }
 
+  /**
+   * Retrieves a list of projects created and tracked by this SogniClient instance.
+   *
+   * Note: When a project is finished, it will be removed from this list after 30 seconds
+   *
+   * @return {Array} A copy of the array containing the tracked projects.
+   */
+  get trackedProjects() {
+    return this.projects.slice(0);
+  }
+
   private handleChangeNetwork() {
     this._availableModels = [];
     this.emit('availableModels', this._availableModels);
@@ -97,7 +177,8 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     this._availableModels = Object.entries(data).map(([id, workerCount]) => ({
       id,
       name: modelIndex[id]?.name || id.replace(/-/g, ' '),
-      workerCount
+      workerCount,
+      media: modelIndex[id]?.media || 'image'
     }));
     this.emit('availableModels', this._availableModels);
   }
@@ -165,20 +246,60 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     }
   }
 
+  private async handleJobETA(data: JobETAData) {
+    this.emit('job', {
+      type: 'jobETA',
+      projectId: data.jobID,
+      jobId: data.imgID || '',
+      etaSeconds: data.etaSeconds
+    });
+  }
+
   private async handleJobResult(data: JobResultData) {
     const project = this.projects.find((p) => p.id === data.jobID);
     const passNSFWCheck = !data.triggeredNSFWFilter || !project || project.params.disableNSFWFilter;
-    let downloadUrl = null;
-    // If NSFW filter is triggered, image will be only available for download if user explicitly
-    // disabled the filter for this project
-    if (passNSFWCheck && !data.userCanceled) {
-      downloadUrl = await this.downloadUrl({
-        jobId: data.jobID,
-        imageId: data.imgID,
-        type: 'complete'
-      });
+    let downloadUrl = data.resultUrl || null; // Use resultUrl from event if provided
+
+    // If no resultUrl provided and NSFW check passes, generate download URL
+    if (!downloadUrl && passNSFWCheck && !data.userCanceled) {
+      // Use media endpoint for video models, image endpoint for image models
+      const isVideo = project && this.isVideoModelId(project.params.modelId);
+      try {
+        if (isVideo) {
+          downloadUrl = await this.mediaDownloadUrl({
+            jobId: data.jobID,
+            id: data.imgID,
+            type: 'complete'
+          });
+        } else {
+          downloadUrl = await this.downloadUrl({
+            jobId: data.jobID,
+            imageId: data.imgID,
+            type: 'complete'
+          });
+        }
+      } catch (error: any) {
+        this.client.logger.error('Failed to generate download URL for job result');
+        this.client.logger.error(error);
+      }
     }
 
+    // Update the job directly with the result URL to prevent duplicate API calls
+    if (project) {
+      const job = project.job(data.imgID);
+      if (job) {
+        job._update({
+          status: data.userCanceled ? 'canceled' : 'completed',
+          step: data.performedStepCount,
+          seed: Number(data.lastSeed),
+          resultUrl: downloadUrl,
+          isNSFW: data.triggeredNSFWFilter,
+          userCanceled: data.userCanceled
+        });
+      }
+    }
+
+    // Emit job completion event with the generated download URL
     this.emit('job', {
       type: 'completed',
       projectId: data.jobID,
@@ -248,7 +369,11 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     if (project.finished) {
       // Sync project data with the server and remove it from the list after some time
       project._syncToServer().catch((e) => {
-        this.client.logger.error(e);
+        // 404 errors are expected when project is still initializing
+        // Only log non-404 errors to avoid confusing users
+        if (e.status !== 404) {
+          this.client.logger.error(e);
+        }
       });
       setTimeout(() => {
         this.projects = this.projects.filter((p) => !p.finished);
@@ -268,7 +393,7 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
         projectId: event.projectId,
         status: 'pending',
         step: 0,
-        stepCount: project.params.steps
+        stepCount: project.params.steps ?? 0
       });
     }
     switch (event.type) {
@@ -295,7 +420,7 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
       case 'progress':
         job._update({
           status: 'processing',
-          // Jus in case event comes out of order
+          // Just in case event comes out of order
           step: Math.max(event.step, job.step),
           stepCount: event.stepCount
         });
@@ -303,6 +428,24 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
           project._update({ status: 'processing' });
         }
         break;
+      case 'jobETA': {
+        // ETA updates keep the project alive (refreshes lastUpdated) and store the ETA value.
+        // This is critical for long-running jobs like video generation that can take several
+        // minutes and may not send frequent progress updates.
+        // We always call _keepAlive() to ensure lastUpdated is refreshed, preventing premature timeouts.
+        project._keepAlive();
+
+        const newEta = new Date(Date.now() + event.etaSeconds * 1000);
+        if (job.eta?.getTime() !== newEta?.getTime()) {
+          job._update({ eta: newEta });
+          const maxEta = project.jobs.reduce((max, j) => Math.max(max, j.eta?.getTime() || 0), 0);
+          const projectETA = maxEta ? new Date(maxEta) : undefined;
+          if (project.eta?.getTime() !== projectETA?.getTime()) {
+            project._update({ eta: projectETA });
+          }
+        }
+        break;
+      }
       case 'preview':
         job._update({ previewUrl: event.url });
         break;
@@ -319,6 +462,17 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
       }
       case 'error':
         job._update({ status: 'failed', error: event.error });
+        // Check if project should also fail when a job fails
+        // For video jobs (single image) or when all jobs have failed, propagate to project
+        const allJobsStarted = project.jobs.length >= project.params.numberOfMedia;
+        const allJobsFailed = allJobsStarted && project.jobs.every((j) => j.status === 'failed');
+        const isSingleJobProject = project.params.numberOfMedia === 1;
+        if (isSingleJobProject || allJobsFailed) {
+          project._update({
+            status: 'failed',
+            error: event.error
+          });
+        }
         break;
     }
   }
@@ -341,53 +495,97 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
       return Promise.resolve(this._availableModels);
     }
     return new Promise((resolve, reject) => {
+      let settled = false;
       const timeoutId = setTimeout(() => {
-        reject(new Error('Timeout waiting for models'));
+        if (!settled) {
+          settled = true;
+          this.off('availableModels', handler);
+          reject(new Error('Timeout waiting for models'));
+        }
       }, timeout);
-      this.once('availableModels', (models) => {
-        clearTimeout(timeoutId);
-        if (models.length) {
+
+      const handler = (models: AvailableModel[]) => {
+        // Only resolve when we get a non-empty models list
+        // Empty arrays may be emitted during disconnects/reconnects
+        if (models.length && !settled) {
+          settled = true;
+          clearTimeout(timeoutId);
+          this.off('availableModels', handler);
           resolve(models);
-        } else {
-          reject(new Error('No models available'));
         }
-      });
+      };
+
+      this.on('availableModels', handler);
     });
   }
 
   /**
    * Send new project request to the network. Returns project instance which can be used to track
-   * progress and get resulting images.
+   * progress and get resulting images or videos.
    * @param data
    */
   async create(data: ProjectParams): Promise<Project> {
     const project = new Project({ ...data }, { api: this, logger: this.client.logger });
+    const modelOptions = await this.getModelOptions(data.modelId);
+    const request = createJobRequestMessage(project.id, data, modelOptions);
+
+    switch (data.type) {
+      case 'image':
+        await this._processImageAssets(project, data);
+        break;
+      case 'video':
+        await this._processVideoAssets(project, data);
+        break;
+    }
+    await this.client.socket.send('jobRequest', request);
+    this.projects.push(project);
+    return project;
+  }
+
+  private async _processImageAssets(project: Project, data: ImageProjectParams) {
+    //Guide image
     if (data.startingImage && data.startingImage !== true) {
       await this.uploadGuideImage(project.id, data.startingImage);
     }
+
+    // ControlNet image
     if (data.controlNet?.image && data.controlNet.image !== true) {
       await this.uploadCNImage(project.id, data.controlNet.image);
     }
+
+    // Context images (Flux.2 Dev supports up to 6; Qwen Image Edit Plus supports up to 3; Flux Kontext supports up to 2)
     if (data.contextImages?.length) {
-      if (data.contextImages.length > 2) {
+      const maxContextImages = getMaxContextImages(data.modelId);
+      if (data.contextImages.length > maxContextImages) {
         throw new ApiError(500, {
           status: 'error',
           errorCode: 0,
-          message: `Up to 2 context images are supported`
+          message: `Up to ${maxContextImages} context images are supported for this model`
         });
       }
       await Promise.all(
         data.contextImages.map((image, index) => {
           if (image && image !== true) {
-            return this.uploadContextImage(project.id, index as 0 | 1, image);
+            return this.uploadContextImage(project.id, index as 0 | 1 | 2 | 3 | 4 | 5, image);
           }
         })
       );
     }
-    const request = createJobRequestMessage(project.id, data);
-    await this.client.socket.send('jobRequest', request);
-    this.projects.push(project);
-    return project;
+  }
+
+  private async _processVideoAssets(project: Project, data: VideoProjectParams) {
+    if (data?.referenceImage && data.referenceImage !== true) {
+      await this.uploadReferenceImage(project.id, data.referenceImage);
+    }
+    if (data?.referenceImageEnd && data.referenceImageEnd !== true) {
+      await this.uploadReferenceImageEnd(project.id, data.referenceImageEnd);
+    }
+    if (data?.referenceAudio && data.referenceAudio !== true) {
+      await this.uploadReferenceAudio(project.id, data.referenceAudio);
+    }
+    if (data?.referenceVideo && data.referenceVideo !== true) {
+      await this.uploadReferenceVideo(project.id, data.referenceVideo);
+    }
   }
 
   /**
@@ -422,7 +620,6 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     }
     // Remove project from the list to stop tracking it
     this.projects = this.projects.filter((p) => p.id !== projectId);
-
     // Cancel all jobs in the project
     project.jobs.forEach((job) => {
       if (!job.finished) {
@@ -438,13 +635,13 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
   private async uploadGuideImage(projectId: string, file: File | Buffer | Blob) {
     const imageId = getUUID();
     const presignedUrl = await this.uploadUrl({
-      imageId: imageId,
+      imageId,
       jobId: projectId,
       type: 'startingImage'
     });
     const res = await fetch(presignedUrl, {
       method: 'PUT',
-      body: file
+      body: toFetchBody(file)
     });
     if (!res.ok) {
       throw new ApiError(res.status, {
@@ -459,13 +656,13 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
   private async uploadCNImage(projectId: string, file: File | Buffer | Blob) {
     const imageId = getUUID();
     const presignedUrl = await this.uploadUrl({
-      imageId: imageId,
+      imageId,
       jobId: projectId,
       type: 'cnImage'
     });
     const res = await fetch(presignedUrl, {
       method: 'PUT',
-      body: file
+      body: toFetchBody(file)
     });
     if (!res.ok) {
       throw new ApiError(res.status, {
@@ -477,17 +674,22 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     return imageId;
   }
 
-  private async uploadContextImage(projectId: string, index: 0 | 1, file: File | Buffer | Blob) {
+  private async uploadContextImage(
+    projectId: string,
+    index: 0 | 1 | 2 | 3 | 4 | 5,
+    file: File | Buffer | Blob
+  ) {
     const imageId = getUUID();
-    const imageIndex = (index + 1) as 1 | 2;
+    const imageIndex = (index + 1) as 1 | 2 | 3 | 4 | 5 | 6;
     const presignedUrl = await this.uploadUrl({
       imageId,
       jobId: projectId,
       type: `contextImage${imageIndex}`
     });
+    const body = toFetchBody(file);
     const res = await fetch(presignedUrl, {
       method: 'PUT',
-      body: file
+      body
     });
     if (!res.ok) {
       throw new ApiError(res.status, {
@@ -499,8 +701,124 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     return imageId;
   }
 
+  // ============================================
+  // VIDEO WORKFLOW UPLOADS (WAN 2.2)
+  // ============================================
+
+  /**
+   * Upload reference image for WAN video workflows
+   * @internal
+   */
+  private async uploadReferenceImage(projectId: string, file: File | Buffer | Blob) {
+    const imageId = getUUID();
+    const presignedUrl = await this.uploadUrl({
+      imageId,
+      jobId: projectId,
+      type: 'referenceImage'
+    });
+    const res = await fetch(presignedUrl, {
+      method: 'PUT',
+      body: toFetchBody(file)
+    });
+    if (!res.ok) {
+      throw new ApiError(res.status, {
+        status: 'error',
+        errorCode: 0,
+        message: 'Failed to upload reference image'
+      });
+    }
+    return imageId;
+  }
+
+  /**
+   * Upload reference image end for i2v interpolation
+   * @internal
+   */
+  private async uploadReferenceImageEnd(projectId: string, file: File | Buffer | Blob) {
+    const imageId = getUUID();
+    const presignedUrl = await this.uploadUrl({
+      imageId,
+      jobId: projectId,
+      type: 'referenceImageEnd'
+    });
+    const res = await fetch(presignedUrl, {
+      method: 'PUT',
+      body: toFetchBody(file)
+    });
+    if (!res.ok) {
+      throw new ApiError(res.status, {
+        status: 'error',
+        errorCode: 0,
+        message: 'Failed to upload reference image end'
+      });
+    }
+    return imageId;
+  }
+
+  /**
+   * Upload reference audio for s2v workflows
+   * Supported formats: mp3, m4a, wav
+   * @internal
+   */
+  private async uploadReferenceAudio(projectId: string, file: File | Buffer | Blob) {
+    const contentType = getFileContentType(file);
+    const presignedUrl = await this.mediaUploadUrl({
+      jobId: projectId,
+      type: 'referenceAudio'
+    });
+    const headers: Record<string, string> = {};
+    if (contentType) {
+      headers['Content-Type'] = contentType;
+    }
+    const res = await fetch(presignedUrl, {
+      method: 'PUT',
+      body: toFetchBody(file),
+      headers
+    });
+    if (!res.ok) {
+      throw new ApiError(res.status, {
+        status: 'error',
+        errorCode: 0,
+        message: 'Failed to upload reference audio'
+      });
+    }
+  }
+
   /**
-   * Estimate project cost
+   * Upload reference video for animate workflows
+   * Supported formats: mp4, mov
+   * @internal
+   */
+  private async uploadReferenceVideo(projectId: string, file: File | Buffer | Blob) {
+    const contentType = getFileContentType(file);
+    const presignedUrl = await this.mediaUploadUrl({
+      jobId: projectId,
+      type: 'referenceVideo'
+    });
+    const headers: Record<string, string> = {};
+    if (contentType) {
+      headers['Content-Type'] = contentType;
+    }
+    const res = await fetch(presignedUrl, {
+      method: 'PUT',
+      body: toFetchBody(file),
+      headers
+    });
+    if (!res.ok) {
+      throw new ApiError(res.status, {
+        status: 'error',
+        errorCode: 0,
+        message: 'Failed to upload reference video'
+      });
+    }
+  }
+
+  // ============================================
+  // COST ESTIMATION
+  // ============================================
+
+  /**
+   * Estimate image project cost
    */
   async estimateCost({
     network,
@@ -515,12 +833,13 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     height,
     sizePreset,
     guidance,
-    scheduler,
+    sampler,
     contextImages
-  }: EstimateRequest) {
+  }: EstimateRequest): Promise<CostEstimation> {
     let apiVersion = 2;
+    const modelOptions = await this.getModelOptions(model);
     const pathParams = [
-      tokenType || 'sogni',
+      tokenType || 'spark',
       network,
       model,
       imageCount,
@@ -541,10 +860,10 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     } else {
       pathParams.push(0, 0);
     }
-    if (scheduler) {
+    if (sampler) {
       apiVersion = 3;
       pathParams.push(guidance || 0);
-      pathParams.push(scheduler || '');
+      pathParams.push(validateSampler(sampler, modelOptions)!);
       pathParams.push(contextImages || 0);
     }
     const r = await this.client.socket.get<EstimationResponse>(
@@ -552,11 +871,18 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     );
     return {
       token: r.quote.project.costInToken,
-      usd: r.quote.project.costInUSD
+      usd: r.quote.project.costInUSD,
+      spark: r.quote.project.costInSpark,
+      sogni: r.quote.project.costInSogni
     };
   }
 
-  async estimateEnhancementCost(strength: EnhancementStrength, tokenType: TokenType = 'sogni') {
+  /**
+   * Estimate image enhancement cost
+   * @param strength
+   * @param tokenType
+   */
+  async estimateEnhancementCost(strength: EnhancementStrength, tokenType: TokenType = 'spark') {
     return this.estimateCost({
       network: enhancementDefaults.network,
       tokenType,
@@ -569,10 +895,53 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     });
   }
 
+  /**
+   * Estimates the cost of generating a video based on the provided parameters.
+   *
+   * @param {VideoEstimateRequest} params - The parameters required for video cost estimation. This includes:
+   *   - tokenType: The type of token to be used for generation.
+   *   - model: The model to be used for video generation.
+   *   - width: The width of the video in pixels.
+   *   - height: The height of the video in pixels.
+   *   - frames: The total number of frames in the video.
+   *   - fps: The frames per second for the video.
+   *   - steps: Number of steps.
+   * @return {Promise<Object>} Returns an object containing the estimated costs for the video in different units:
+   *   - token: Cost in tokens.
+   *   - usd: Cost in USD.
+   *   - spark: Cost in Spark.
+   *   - sogni: Cost in Sogni.
+   */
+  async estimateVideoCost(params: VideoEstimateRequest) {
+    const pathParams = [
+      params.tokenType,
+      params.model,
+      params.width,
+      params.height,
+      params.frames ? params.frames : params.duration * 16 + 1,
+      params.fps,
+      params.steps,
+      params.numberOfMedia
+    ];
+    const path = pathParams.map((p) => encodeURIComponent(p)).join('/');
+    const r = await this.client.socket.get<EstimationResponse>(
+      `/api/v1/job-video/estimate/${path}`
+    );
+    return {
+      token: r.quote.project.costInToken,
+      usd: r.quote.project.costInUSD,
+      spark: r.quote.project.costInSpark,
+      sogni: r.quote.project.costInSogni
+    };
+  }
+
+  // ============================================
+  // URL HELPERS
+  // ============================================
+
   /**
    * Get upload URL for image
    * @internal
-   * @param params
    */
   async uploadUrl(params: ImageUrlParams) {
     const r = await this.client.rest.get<ApiResponse<{ uploadUrl: string }>>(
@@ -585,16 +954,49 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
   /**
    * Get download URL for image
    * @internal
-   * @param params
    */
   async downloadUrl(params: ImageUrlParams) {
     const r = await this.client.rest.get<ApiResponse<{ downloadUrl: string }>>(
       `/v1/image/downloadUrl`,
       params
     );
+    if (!r?.data?.downloadUrl) {
+      throw new Error(`API returned no downloadUrl: ${JSON.stringify(r)}`);
+    }
     return r.data.downloadUrl;
   }
 
+  /**
+   * Get upload URL for media (video/audio)
+   * @internal
+   */
+  async mediaUploadUrl(params: MediaUrlParams) {
+    const r = await this.client.rest.get<ApiResponse<{ uploadUrl: string }>>(
+      `/v1/media/uploadUrl`,
+      params
+    );
+    return r.data.uploadUrl;
+  }
+
+  /**
+   * Get download URL for media (video/audio)
+   * @internal
+   */
+  async mediaDownloadUrl(params: MediaUrlParams) {
+    const r = await this.client.rest.get<ApiResponse<{ downloadUrl: string }>>(
+      `/v1/media/downloadUrl`,
+      params
+    );
+    if (!r?.data?.downloadUrl) {
+      throw new Error(`API returned no downloadUrl: ${JSON.stringify(r)}`);
+    }
+    return r.data.downloadUrl;
+  }
+
+  // ============================================
+  // MODEL/PRESET HELPERS
+  // ============================================
+
   async getSupportedModels(forceRefresh = false) {
     if (
       this._supportedModels.data &&
@@ -608,12 +1010,25 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     return models;
   }
 
+  private async _getModelTiers(forceRefresh = false) {
+    if (
+      this._modelTiers.data &&
+      !forceRefresh &&
+      Date.now() - this._modelTiers.updatedAt.getTime() < MODELS_REFRESH_INTERVAL
+    ) {
+      return this._modelTiers.data;
+    }
+    const tiers = await this.client.socket.get<ModelTiersRaw>(`/api/v2/models/tiers`);
+    this._modelTiers = { data: tiers, updatedAt: new Date() };
+    return tiers;
+  }
+
   /**
    * Get supported size presets for the model and network. Size presets are cached for 10 minutes.
    *
    * @example
    * ```ts
-   * const presets = await client.projects.getSizePresets('fast', 'flux1-schnell-fp8');
+   * const presets = await sogni.projects.getSizePresets('fast', 'flux1-schnell-fp8');
    * console.log(presets);
    * ```
    *
@@ -642,6 +1057,49 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     return data;
   }
 
+  /**
+   * Retrieves the video asset configuration for a given video model identifier.
+   * Validates whether the provided model ID corresponds to a video model. If it does,
+   * returns the appropriate video asset configuration based on the workflow type.
+   *
+   * @example Returned object for a model that implements image to video workflow:
+   * ```json
+   * {
+   *   "workflowType": "i2v",
+   *   "assets": {
+   *     "referenceImage": "required",
+   *     "referenceImageEnd": "optional",
+   *     "referenceAudio": "forbidden",
+   *     "referenceVideo": "forbidden"
+   *   }
+   * }
+   * ```
+   *
+   * @param {string} modelId - The identifier of the video model to retrieve the configuration for.
+   * @return {Object} The video asset configuration object where key is asset field and value is
+   * either `required`, `forbidden` or `optional`. Returns `null` if no rules defined for the model.
+   * @throws {ApiError} Throws an error if the provided model ID is not a video model.
+   */
+  async getVideoAssetConfig(modelId: string) {
+    if (!this.isVideoModelId(modelId)) {
+      throw new ApiError(400, {
+        status: 'error',
+        errorCode: 0,
+        message: `Model ${modelId} is not a video model`
+      });
+    }
+    const workflow = getVideoWorkflowType(modelId);
+    if (!workflow) {
+      return {
+        workflowType: null
+      };
+    }
+    return {
+      workflowType: workflow,
+      assets: VIDEO_WORKFLOW_ASSETS[workflow]
+    };
+  }
+
   /**
    * Get available models and their worker counts. Normally, you would get list once you connect
    * to the server, but you can also call this method to get the list of available models manually.
@@ -658,10 +1116,34 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
       return {
         id: model?.id || sid,
         name: model?.name || sid.replace(/-/g, ' '),
-        workerCount
+        workerCount,
+        media: model?.media || 'image'
       };
     });
   }
+
+  async getModelOptions(modelId: string): Promise<ModelOptions> {
+    const models = await this.getSupportedModels();
+    const tiers = await this._getModelTiers();
+    const model = models.find((m) => m.id === modelId);
+    if (!model) {
+      throw new Error(`Model ${modelId} not supported`);
+    }
+    const tier = tiers[model.tier];
+    if (!tier) {
+      throw new Error(`Unable to find model tier "${model.tier}" please contact support`);
+    }
+    if (isImageTier(tier)) {
+      return mapImageTier(tier);
+    }
+    if (isVideoTier(tier)) {
+      return mapVideoTier(tier);
+    }
+    if (isComfyImageTier(tier)) {
+      return mapComfyImageTier(tier);
+    }
+    throw new Error(`Unsupported model tier "${model.tier}"`);
+  }
 }
 
 export default ProjectsApi;