Flowscale NPM | npm.io

Flowscale Node.js SDK

A comprehensive SDK designed to simplify interaction with the FlowScale ComfyUI API. This library works in both Node.js and browser environments.

⚠️ Important Security Notice for Browser Usage

When using this SDK in a browser environment, your API key will be exposed to end users. This is a significant security risk. We strongly recommend:

Using this SDK in a Node.js backend environment
Creating a proxy API that securely handles the API key server-side

If you understand the risks and still need to use the SDK directly in the browser, you must explicitly acknowledge this by setting the allowDangerouslyExposeApiKey option:

const flowscale = new FlowscaleAPI({
  apiKey: 'your-api-key',
  baseUrl: 'your-api-url',
  allowDangerouslyExposeApiKey: false // Only set to true if you understand the security risks
});

Installation

Install the Flowscale SDK by npm, yarn, pnpm or bun:

npm install flowscale

yarn add flowscale

pnpm install flowscale

bun install flowscale

Quick Start

Importing the SDK

To get started, import the Flowscale SDK into your project:

import { FlowscaleAPI } from 'flowscale';

// Node.js Environment (Recommended)
const apiKey = process.env.FLOWSCALE_API_KEY;
const apiUrl = process.env.FLOWSCALE_API_URL;

const flowscale = new FlowscaleAPI({
  apiKey,
  baseUrl: apiUrl
});

// Browser Environment (Not Recommended)
const flowscale = new FlowscaleAPI({
  apiKey: 'your-api-key', // ⚠️ WARNING: This will be exposed to users
  baseUrl: 'https://your-api-url.pod.flowscale.ai',
  allowDangerouslyExposeApiKey: true // Explicitly acknowledge the security risk
});

Environment-Specific Considerations

Node.js (Recommended)

Store API keys in environment variables
Use .env files for configuration
Full access to all SDK features

Browser

API key will be visible in network requests
Supports File/Blob uploads directly from browser
Consider implementing a backend proxy instead

Environment Variables: Add the following to your .env file:

FLOWSCALE_API_KEY=your-api-key
FLOWSCALE_API_URL=https://your-api-url.pod.flowscale.ai

SDK Methods

Below is a detailed guide to the SDK methods, including descriptions, usage, and response formats.

1. `checkHealth()`

Description: Check the health status of the Flowscale platform, including the status of containers and services.

Usage:

const health = await flowscale.checkHealth();
console.log('API Health:', health);

Response Example:

{
  "status": "success",
  "data": [
    {
      "container": "container #1",
      "status": "idle"
    },
    {
      "container": "container #2",
      "status": "running"
    }
  ]
}

2. `getQueue()`

Description: Retrieve the current status of the workflow queue, including running and pending jobs.

Usage:

const queue = await flowscale.getQueue();
console.log('Queue Details:', queue);

Response Example:

{
  "status": "success",
  "data": [
    {
      "container": "container #1",
      "queue": {
        "queue_running": [
          [
            0,
            "2a0babc4-acce-4521-9576-00fa0e6ecc91"
          ]
        ],
        "queue_pending": [
          [
            1,
            "5d60718a-7e89-4c64-b32d-0d1366b44e2a"
          ]
        ]
      }
    }
  ]
}

3. `executeWorkflow(workflowId, data, groupId?)`

Description: Trigger a workflow execution using its unique workflowId. Input data and an optional groupId can be provided for better organization and tracking.

Parameters:

workflowId (string): The unique ID of the workflow.
data (object): Input parameters for the workflow.
groupId (string, optional): A custom identifier for grouping runs.

Usage:

const workflowId = "bncu0a1kipv";
const groupId = "test_group";

const inputs = {
   "text_51536": "Prompt test",
   "image_1234": { /* File or Blob of image */ },
   "video_1239": { /* File or Blob of video */ }
};

const result = await flowscale.executeWorkflow(workflowId, inputs, groupId);
console.log('Workflow Result:', result);

Response Example:

{
  "status": "success",
  "data": {
    "number": 0,
    "node_errors": {},
    "output_names": [
      "filename_prefix_58358_5WWF7GQUYF"
    ],
    "run_id": "808f34d0-ef97-4b78-a00f-1268077ea6db"
  }
}

3.1 `executeWorkflowAsync(workflowId, data, groupId?, pollIntervalMs?, timeoutMs?)`

Description: Execute a workflow and automatically wait for the result by polling the output. This is a convenience method that combines executeWorkflow and getOutput with automatic polling.

Parameters:

workflowId (string): The unique ID of the workflow.
data (object): Input parameters for the workflow.
groupId (string, optional): A custom identifier for grouping runs.
pollIntervalMs (number, optional): Polling interval in milliseconds (default: 1000).
timeoutMs (number, optional): Maximum time to wait for results in milliseconds (default: 300000 - 5 minutes).

Usage:

const workflowId = "bncu0a1kipv";
const inputs = {
   "text_51536": "Prompt test",
   "image_1234": { /* File or Blob of image */ }
};

try {
  const result = await flowscale.executeWorkflowAsync(workflowId, inputs);
  console.log('Workflow Result:', result);
} catch (error) {
  if (error.message.includes('timed out')) {
    console.error('Workflow took too long to complete');
  } else {
    console.error('Workflow error:', error);
  }
}

Response Example:

{
  "status": "success",
  "data": {
    "download_url": "https://runs.s3.amazonaws.com/generations/...",
    "generation_status": "success"
  }
}

4. `getOutput(filename)`

Description: Fetch the output of a completed workflow using its filename. Outputs typically include downloadable files or results.

Parameters:

filename (string): The name of the output file.

Usage:

const output = await flowscale.getOutput('filename_prefix_58358_5WWF7GQUYF.png');
console.log('Workflow Output:', output);

Response Example:

{
  "status": "success",
  "data": {
    "download_url": "https://runs.s3.amazonaws.com/generations/...",
    "generation_status": "success"
  }
}

5. `cancelRun(runId)`

Description: Cancel a running workflow execution using its unique runId.

Parameters:

runId (string): The unique identifier of the running workflow.

Usage:

const result = await flowscale.cancelRun('808f34d0-ef97-4b78-a00f-1268077ea6db');
console.log('Cancellation Result:', result);

Response Example:

{
  "status": "success",
  "data": "Run cancelled successfully"
}

6. `getRun(runId)`

Description: Retrieve detailed information about a specific workflow run.

Parameters:

runId (string): The unique identifier of the run.

Usage:

const runDetails = await flowscale.getRun('808f34d0-ef97-4b78-a00f-1268077ea6db');
console.log('Run Details:', runDetails);

Response Example:

{
  "status": "success",
  "data": {
    "_id": "808f34d0-ef97-4b78-a00f-1268077ea6db",
    "status": "completed",
    "inputs": [
      {
        "path": "text_51536",
        "value": "a man riding a bike"
      }
    ],
    "outputs": [
      {
        "filename": "filename_prefix_58358_5WWF7GQUYF.png",
        "url": "https://runs.s3.amazonaws.com/generations/..."
      }
    ]
  }
}

7. `getRuns(groupId)`

Description: Retrieve all workflow runs associated with a specific groupId. If no groupId is provided, all runs for the team are returned.

Parameters:

groupId (string, optional): The identifier for grouping runs.

Usage:

const runs = await flowscale.getRuns('test_group');
console.log('Runs for Group:', runs);

// Get all runs for the team
const allRuns = await flowscale.getRuns();
console.log('All Runs:', allRuns);

Response Example:

{
  "status": "success",
  "data": {
    "group_id": "test_group",
    "count": 2,
    "runs": [
      {
        "_id": "cc29a72d-75b9-4c7b-b991-ccaf2a04d6ea",
        "status": "completed",
        "outputs": [
          {
            "filename": "filename_prefix_58358_G3DRLIVVYP.png",
            "url": "https://runs.s3.amazonaws.com/generations/..."
          }
        ]
      }
    ]
  }
}