### Install Dependencies

Source: https://github.com/runware/sdk-js/blob/main/tests/TEST.md

Install project dependencies using npm.

```bash
npm install
```

--------------------------------

### Install Runware SDK with Yarn

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Install the Runware SDK using Yarn. This command adds the SDK as a dependency to your project.

```sh
yarn add @runware/sdk-js
```

--------------------------------

### Install Runware SDK with npm

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Install the Runware SDK using npm. This is the first step to integrate Runware's AI image generation capabilities into your project.

```sh
npm install @runware/sdk-js
```

--------------------------------

### controlNetPreProcess / controlNetPreprocess

Source: https://context7.com/runware/sdk-js/llms.txt

Preprocesses an input image using a specified ControlNet preprocessor (e.g., Canny edge detection, OpenPose skeleton extraction) to generate a guide image for `imageInference`. Supports various preprocessor types and output configurations.

```APIDOC
## controlNetPreProcess / controlNetPreprocess

Preprocesses an input image through a ControlNet preprocessor (e.g., Canny edge detection, OpenPose skeleton extraction) to produce a guide image usable in `imageInference`.

```typescript
import { EPreProcessorGroup } from "@runware/sdk-js";

const guide = await runware.controlNetPreProcess({
  inputImage: "image-uuid-or-File",
  preProcessorType: EPreProcessorGroup.openpose,
  width: 768,
  height: 768,
  includeHandsAndFaceOpenPose: true,
  outputType: "URL",
  outputFormat: "PNG",
  includeCost: true,
});
// guide: IControlNetImage { guideImageUUID, guideImageURL, cost, taskUUID }
console.log(guide.guideImageURL);

// Canny edge detection with thresholds
const cannyGuide = await runware.controlNetPreProcess({
  inputImage: "image-uuid",
  preProcessorType: EPreProcessorGroup.canny,
  lowThresholdCanny: 100,
  highThresholdCanny: 200,
  outputType: "URL",
  outputFormat: "PNG",
});
```
```

--------------------------------

### ControlNet Preprocess

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Preprocesses an input image to generate a guide image using ControlNet. Supports various preprocessor types and image manipulation options.

```APIDOC
## ControlNet Preprocess

### Description
Preprocesses an input image to generate a guide image using ControlNet. Supports various preprocessor types and image manipulation options.

### Method
```js
runware.controlNetPreprocess(options)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **inputImage** (string | File) - Required - Specifies the input image to be preprocessed to generate a guide image.
- **preProcessorType** (EPreProcessor) - Required - Specifies the pre processor type to use.
- **width** (number) - Optional - Controls the image width.
- **height** (number) - Optional - Controls the image height.
- **outputType** (IOutputType) - Optional - Specifies the output type in which the image is returned.
- **outputFormat** (IOutputFormat) - Optional - Specifies the format of the output image.
- **highThresholdCanny** (number) - Optional - Defines the high threshold when using the Canny edge detection preprocessor.
- **lowThresholdCanny** (number) - Optional - Defines the lower threshold when using the Canny edge detection preprocessor.
- **includeHandsAndFaceOpenPose** (boolean) - Optional - Include the hands and face in the pose outline when using the OpenPose preprocessor.

### Request Example
```js
const controlNetPreProcessed = await runware.controlNetPreprocess({
	inputImage: "path/to/image.jpg",
	preProcessorType: "canny",
	width: 512,
	height: 512
})
```

### Response
#### Success Response (200)
- **taskUUID** (string) - The unique identifier for the task.
- **inputImageUUID** (string) - The unique identifier for the input image.
- **guideImageUUID** (string) - The unique identifier for the generated guide image.
- **guideImageURL** (string) - Optional - The URL of the generated guide image.
- **guideImageBase64Data** (string) - Optional - The base64 encoded data of the generated guide image.
- **guideImageDataURI** (string) - Optional - The data URI of the generated guide image.
- **cost** (number) - The cost associated with the task.

#### Response Example
```json
{
  "taskUUID": "some-uuid",
  "inputImageUUID": "input-image-uuid",
  "guideImageUUID": "guide-image-uuid",
  "guideImageURL": "https://example.com/guide.jpg",
  "cost": 0.05
}
```
```

--------------------------------

### ControlNet Preprocessing with runware.controlNetPreProcess

Source: https://context7.com/runware/sdk-js/llms.txt

Preprocesses an input image using a ControlNet preprocessor, such as OpenPose or Canny edge detection, to generate a guide image for `imageInference`. Supports various preprocessor types and output formats.

```typescript
import { EPreProcessorGroup } from "@runware/sdk-js";

const guide = await runware.controlNetPreProcess({
  inputImage: "image-uuid-or-File",
  preProcessorType: EPreProcessorGroup.openpose,
  width: 768,
  height: 768,
  includeHandsAndFaceOpenPose: true,
  outputType: "URL",
  outputFormat: "PNG",
  includeCost: true,
});
// guide: IControlNetImage { guideImageUUID, guideImageURL, cost, taskUUID }
console.log(guide.guideImageURL);
```

```typescript
// Canny edge detection with thresholds
const cannyGuide = await runware.controlNetPreProcess({
  inputImage: "image-uuid",
  preProcessorType: EPreProcessorGroup.canny,
  lowThresholdCanny: 100,
  highThresholdCanny: 200,
  outputType: "URL",
  outputFormat: "PNG",
});
```

--------------------------------

### Instantiating the SDK

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Demonstrates how to instantiate the Runware SDK, either synchronously or asynchronously, using an API key.

```APIDOC
## Instantiating the SDK

### Instantiating Synchronously

```js
const runware = new Runware({ apiKey: "API_KEY" });
```

### Instantiating Asynchronously

```js
const runware = await Runware.initialize({ apiKey: "API_KEY" });
```

| Parameter        | Type                                         | Use                                                                                                                                                        |
| ---------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| url              | string                                       | Url to get images from (optional)                                                                                                                          |
| apiKey           | string                                       | The environment api key                                                                                                                                    |
| shouldReconnect  | boolean `(default = true)`                   | This handles reconnection when there is websocket inactivity                                                                                               |
| globalMaxRetries | number `(default = 2)`                       | The number of retries it should make before throwing an error `(NB: you can specify a retry parameters for every request that overrides the global retry)` |
| timeoutDuration  | number (in milliseconds) `(default = 60000)` | The timeout span per retry before timing out                                                                                                               |
```

--------------------------------

### Runware SDK Instantiation

Source: https://context7.com/runware/sdk-js/llms.txt

Demonstrates how to instantiate the Runware client, both synchronously and asynchronously, and manage the connection lifecycle.

```APIDOC
## Instantiation

The `Runware` class auto-selects `RunwareClient` (browser) or `RunwareServer` (Node.js). Pass constructor options directly or use the async factory to guarantee the connection is ready before the first call.

```typescript
import { Runware } from "@runware/sdk-js";

// Synchronous instantiation (connection established in background)
const runware = new Runware({
  apiKey: "YOUR_API_KEY",
  shouldReconnect: true,      // default: true
  globalMaxRetries: 2,        // default: 2
  timeoutDuration: 60000,     // ms, default: 60000
  heartbeatInterval: 45000,   // ms, clamped 10000–120000, default: 45000
  enableLogging: false,       // default: false
});

// Asynchronous instantiation — awaits authentication before returning
const runware = await Runware.initialize({
  apiKey: "YOUR_API_KEY",
});

// Ensure connection is ready before the first request
await runware.ensureConnection();

// Gracefully disconnect
await runware.disconnect();
```
```

--------------------------------

### Set Up Environment Variables

Source: https://github.com/runware/sdk-js/blob/main/tests/TEST.md

Ensure your .env file contains valid production API credentials and the SDK URL.

```env
API_KEY = "your-api-key"
VITE_RUNWARE_SDK_URL = "wss://ws-api.runware.ai/v1"
```

--------------------------------

### Instantiate Runware SDK Asynchronously

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Instantiate the Runware SDK client asynchronously using the `initialize` method. This is recommended for asynchronous operations. Replace 'API_KEY' with your actual Runware API key.

```js
const runware = await Runware.initialize({apiKey: "API_KEY"});
```

--------------------------------

### Instantiate Runware SDK Synchronously

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Instantiate the Runware SDK client synchronously. Ensure you replace 'API_KEY' with your actual Runware API key.

```js
const runware = new Runware({apiKey: "API_KEY"});
```

--------------------------------

### Instantiate Runware SDK Client

Source: https://context7.com/runware/sdk-js/llms.txt

Instantiate the Runware SDK client synchronously or asynchronously. Configure connection options like API key, reconnection, retries, timeouts, and heartbeat intervals. Ensure the connection is ready before making requests and disconnect gracefully when finished.

```typescript
import { Runware } from "@runware/sdk-js";

// Synchronous instantiation (connection established in background)
const runware = new Runware({
  apiKey: "YOUR_API_KEY",
  shouldReconnect: true,      // default: true
  globalMaxRetries: 2,        // default: 2
  timeoutDuration: 60000,     // ms, default: 60000
  heartbeatInterval: 45000,   // ms, clamped 10000–120000, default: 45000
  enableLogging: false,       // default: false
});

// Asynchronous instantiation — awaits authentication before returning
const runware = await Runware.initialize({
  apiKey: "YOUR_API_KEY",
});

// Ensure connection is ready before the first request
await runware.ensureConnection();

// Gracefully disconnect
await runware.disconnect();
```

--------------------------------

### Perform Parallel Image Inference and Prompt Enhancement

Source: https://context7.com/runware/sdk-js/llms.txt

Initializes the Runware SDK and then uses Promise.all to concurrently generate images with different prompts and dimensions, and enhance a prompt. Ensure you have your API key for initialization. Results are logged to the console.

```typescript
const runware = await Runware.initialize({ apiKey: "YOUR_API_KEY" });

const [ portrait, landscape, enhanced ] = await Promise.all([
  runware.imageInference({
    positivePrompt: "Cinematic portrait of a warrior in ancient armor",
    model: "runware:100@1",
    width: 768, height: 1024,
    numberResults: 1, outputType: "URL",
  }),
  runware.imageInference({
    positivePrompt: "Sweeping aerial view of the Grand Canyon at sunrise",
    model: "runware:100@1",
    width: 1024, height: 576,
    numberResults: 1, outputType: "URL",
  }),
  runware.enhancePrompt({
    prompt: "A dragon flying over mountains",
    promptVersions: 2,
  }),
]);

console.log(portrait?.[0].imageURL);
console.log(landscape?.[0].imageURL);
console.log(enhanced.map(e => e.text));
```

--------------------------------

### Run All Tests

Source: https://github.com/runware/sdk-js/blob/main/tests/TEST.md

Execute all tests in the project using vitest with a verbose reporter.

```bash
npx vitest run tests/ --reporter verbose
```

--------------------------------

### Run a Single Test File

Source: https://github.com/runware/sdk-js/blob/main/tests/TEST.md

Execute a specific test file. This is helpful for focused debugging.

```bash
npx vitest run tests/Runware/connection/heartbeat.test.ts --reporter verbose
npx vitest run tests/Runware/connection/session-uuid.test.ts --reporter verbose
npx vitest run tests/Runware/connection/send-guard.test.ts --reporter verbose
npx vitest run tests/Runware/connection/zombie-detection.test.ts --reporter verbose
npx vitest run tests/Runware/retry/async-retry.test.ts --reporter verbose
npx vitest run tests/Runware/inference/image-generation.test.ts --reporter verbose
npx vitest run tests/Runware/inference/video-generation.test.ts --reporter verbose
npx vitest run tests/Runware/inference/enhance-prompt.test.ts --reporter verbose
npx vitest run tests/Runware/inference/upscale.test.ts --reporter verbose
npx vitest run tests/Runware/inference/upload-image.test.ts --reporter verbose
npx vitest run tests/Runware/server/connection.test.ts --reporter verbose
```

--------------------------------

### Ensure connection is established

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Ensures that the connection to the Runware server is established before making any requests.

```APIDOC
## Ensure connection is established before making request

```js
const runware = new RunwareServer({ apiKey: "API_KEY" });

await runware.ensureConnection();
```
```

--------------------------------

### Request Image To Text with Runware SDK

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Initialize the Runware SDK with your API key and use the caption method to process an image. The input can be a string (image UUID) or a File object. The response includes task details and the extracted text.

```javascript
const  runware  =  new Runware({ apiKey: "API_KEY" });
const imageToText = await runware.caption({
	inputImage: string | File
})
console.log(imageToText)

return interface IImageToText {
  taskType: string;
  taskUUID: string;
  text: string;
  cost?: number;
}
```

--------------------------------

### Enhance Prompt with Runware SDK

Source: https://github.com/runware/sdk-js/blob/main/readme.md

This snippet demonstrates how to enhance a given prompt using the Runware SDK. You can specify maximum prompt length and the number of prompt versions to generate. Cost inclusion is optional.

```javascript
const  runware  =  new Runware({ apiKey: "API_KEY" });
const enhancedPrompt = await runware.promptEnhance({
	prompt: string;
	promptMaxLength?: number;
	promptVersions?: number;
	includeCost?: boolean;
})
console.log(enhancedPrompt)
return interface IEnhancedPrompt {
	taskUUID: string;
	text: string;
}
```

--------------------------------

### Generate Image Caption with runware.caption

Source: https://context7.com/runware/sdk-js/llms.txt

Generates a text description for an image or video. Supports custom captioning models and async delivery for videos. Use `inputImage` for images or `inputs.video` for videos.

```typescript
// Caption an image
const caption = await runware.caption({
  inputImage: "image-uuid-or-url",
  includeCost: true,
});
// caption: IImageToText { taskUUID, text, cost }
console.log(caption.text);
```

```typescript
// Caption using a specific model with video input
const videoCaption = await runware.caption({
  model: "memories:1@1",
  inputs: { video: "https://example.com/video.mp4" },
  deliveryMethod: "async",
});
console.log(videoCaption.text);
```

--------------------------------

### Upscale Image with Runware SDK

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Use this snippet to upscale an image using the Runware SDK. Provide the input image and the desired upscale factor. Optional parameters include output type, format, and cost inclusion.

```javascript
const  runware  =  new Runware({ apiKey: "API_KEY" });
const image = await runware.upscale({
	inputImage: File | string;
	upscaleFactor: number;
	outputType?: IOutputType;
	outputFormat?: IOutputFormat;
	includeCost?: boolean
})
console.log(image)
return interface IImage {
	taskType: ETaskType;
	imageUUID: string;
	inputImageUUID?: string;
	taskUUID: string;
	imageURL?: string;
	imageBase64Data?: string;
	imageDataURI?: string;
	NSFWContent?: boolean;
	cost: number;
}
```

--------------------------------

### Run a Single Test by Name

Source: https://github.com/runware/sdk-js/blob/main/tests/TEST.md

Execute a specific test case within a file using the '-t' flag to match the test name.

```bash
npx vitest run tests/Runware/inference/video-generation.test.ts -t "submits video job" --reporter verbose
npx vitest run tests/Runware/connection/heartbeat.test.ts -t "3-strike" --reporter verbose
npx vitest run tests/Runware/retry/async-retry.test.ts -t "customer scenario" --reporter verbose
```

--------------------------------

### Generate Images with Runware SDK

Source: https://context7.com/runware/sdk-js/llms.txt

Generate images using text-to-image or image-to-image techniques. Supports advanced features like LoRA adapters, ControlNet guidance, inpainting, and outpainting. Use `onPartialImages` for streaming results. Configure parameters such as prompts, model, dimensions, steps, and output format.

```typescript
import { Runware, EControlMode } from "@runware/sdk-js";

const runware = await Runware.initialize({ apiKey: "YOUR_API_KEY" });

// Basic text-to-image
const images = await runware.imageInference({
  positivePrompt: "A cinematic shot of a futuristic city at dusk, neon lights",
  negativePrompt: "blurry, low quality, cartoon",
  model: "runware:100@1",
  width: 1024,
  height: 1024,
  numberResults: 2,
  steps: 30,
  CFGScale: 7,
  scheduler: "DPMSolverMultistepScheduler",
  seed: 42,
  outputType: "URL",
  outputFormat: "WEBP",
  outputQuality: 90,
  checkNSFW: true,
  includeCost: true,
  lora: [{ model: "civitai:12345@1", weight: 0.8 }],
  onPartialImages: (partial, error) => {
    if (error) console.error(error);
    else console.log("Partial:", partial.map(i => i.imageURL));
  },
});

// images: ITextToImage[]
// { taskType, imageUUID, taskUUID, imageURL, seed, cost, positivePrompt, NSFWContent }
console.log(images?.map(img => img.imageURL));

// Image-to-image with inpainting
const inpainted = await runware.imageInference({
  positivePrompt: "Replace background with a tropical beach",
  model: "runware:100@1",
  width: 1024,
  height: 1024,
  seedImage: "https://example.com/photo.jpg",   // URL, UUID, or File
  maskImage: "https://example.com/mask.png",
  strength: 0.75,
  numberResults: 1,
  outputType: "URL",
});

// Outpainting
const extended = await runware.imageInference({
  positivePrompt: "Continue the landscape",
  model: "runware:100@1",
  seedImage: "existing-image-uuid",
  width: 1280,
  height: 1024,
  outpaint: { top: 0, bottom: 256, left: 128, right: 128, blur: 16 },
  numberResults: 1,
  outputType: "URL",
});

// ControlNet-guided generation
const guided = await runware.imageInference({
  positivePrompt: "Portrait of a woman, studio lighting",
  model: "runware:100@1",
  width: 768,
  height: 768,
  controlNet: [{
    model: "controlnet-openpose@1",
    guideImage: "pose-image-uuid",
    weight: 0.9,
    startStepPercentage: 0,
    endStepPercentage: 1,
    controlMode: EControlMode.BALANCED,
  }],
  numberResults: 1,
  outputType: "URL",
});
```

--------------------------------

### Generate Video from Prompt

Source: https://context7.com/runware/sdk-js/llms.txt

Generates a video from a text prompt. Supports specifying dimensions, duration, FPS, and output format. Uses async delivery internally.

```typescript
const videos = await runware.videoInference({
  model: "wan:1@1",
  positivePrompt: "A serene mountain river flowing through a pine forest",
  width: 1280,
  height: 720,
  duration: 5,
  fps: 24,
  numberResults: 1,
  outputType: "URL",
  outputFormat: "MP4",
  includeCost: true,
});
// videos: IVideoToImage[] { taskUUID, videoUUID, videoURL, cost }
console.log(videos[0].videoURL);
```

--------------------------------

### Upload Checkpoint Model

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Use this to upload a checkpoint model. Provide the base payload along with checkpoint-specific parameters like defaultStrength.

```javascript
const runware = new Runware({ apiKey: "API_KEY" });

const basePayload = {
	air: string;
	name: string;
	downloadURL: string;

uniqueIdentifier: string;
	version: string;
	format: EModelFormat;
	architecture: EModelArchitecture;
	heroImageURL?: string;
	tags?: string[];
	shortDescription?: string;
	comment?: string;
	private: boolean;
	customTaskUUID?: string;
	retry?: number;
	onUploadStream?: (
		response?: IAddModelResponse,
		error?: IErrorResponse
	) => void;
}

const checkpointUpload = await runware.modelUpload({
	...basePayload,
  	category: "checkpoint";
 	positiveTriggerWords?: string;
	defaultCFGScale?: number;
	defaultStrength: number;
	defaultSteps?: number;
	defaultScheduler?: number;
	type?: EModelType;
})
console.log(checkpointUpload)
```

--------------------------------

### Upload Custom Model to Runware

Source: https://context7.com/runware/sdk-js/llms.txt

Uploads a custom model (checkpoint, LoRA, ControlNet) with metadata. Streams upload status via `onUploadStream`. Ensure all required parameters like format, architecture, and type are correctly specified.

```typescript
import { EModelFormat, EModelArchitecture, EModelType } from "@runware/sdk-js";

const uploadResult = await runware.modelUpload({
  category: "checkpoint",
  air: "myorg:mycustom@1",
  name: "My Custom Checkpoint",
  downloadURL: "https://huggingface.co/myorg/model/resolve/main/model.safetensors",
  uniqueIdentifier: "myorg-mycustom-v1",
  version: "1.0.0",
  format: EModelFormat.safetensors,
  architecture: EModelArchitecture.sdxl,
  type: EModelType.base,
  defaultStrength: 1.0,
  defaultSteps: 30,
  defaultCFGScale: 7,
  private: false,
  tags: ["portrait", "photorealistic"],
  shortDescription: "High-quality SDXL portrait checkpoint",
  onUploadStream: (response, error) => {
    if (error) console.error("Upload error:", error.message);
    else console.log("Upload status:", response?.status, response?.message);
  },
});
// uploadResult: IAddModelResponse { status, message, air, taskUUID }
console.log(uploadResult?.status);
```

--------------------------------

### Generate Video with Speech Overlay

Source: https://context7.com/runware/sdk-js/llms.txt

Creates a video from an image input and adds a speech overlay. Specify voice and text for the speech synthesis.

```typescript
// Image-to-video with speech overlay
const speechVideo = await runware.videoInference({
  model: "wan:1@1",
  inputs: { image: "https://example.com/portrait.jpg" },
  speech: { voice: "en-US-AriaNeural", text: "Hello, welcome to my demo!" },
  duration: 6,
  outputType: "URL",
  outputFormat: "MP4",
  numberResults: 1,
});
```

--------------------------------

### Upscale Image or Video with runware.upscale

Source: https://context7.com/runware/sdk-js/llms.txt

Upscales an image by a specified factor or a video using the inputs object. Supports async delivery for videos and various output formats. Use `inputImage` for images or `inputs.video` for videos.

```typescript
// Upscale an image 4×
const result = await runware.upscale({
  inputImage: "image-uuid-or-url-or-File",
  upscaleFactor: 4,
  outputType: "URL",
  outputFormat: "PNG",
  includeCost: true,
});
// result: IImage { imageURL, mediaURL, mediaUUID, cost, taskUUID }
console.log(result.imageURL ?? result.mediaURL);
```

```typescript
// Upscale a video via inputs object (async delivery)
const videoResult = await runware.upscale({
  model: "upscaler-video@1",
  inputs: { video: "https://example.com/clip.mp4" },
  outputType: "URL",
  outputFormat: "MP4",
  deliveryMethod: "async",
  includeCost: true,
});
console.log(videoResult.mediaURL);
```

--------------------------------

### threeDInference

Source: https://context7.com/runware/sdk-js/llms.txt

Generates 3D assets in either GLB or PLY format from an image or text prompt. This operation supports both synchronous and asynchronous delivery, with file links provided in the `outputs.files` array of the response.

```APIDOC
## threeDInference

Generates 3D assets (GLB or PLY) from an image or text prompt. Supports sync and async delivery; outputs file links via the `outputs.files` array on the response.

```typescript
const models3d = await runware.threeDInference({
  model: "triplane:1@1",
  inputs: { image: "https://example.com/object.jpg" },
  outputType: "URL",
  outputFormat: "GLB",
  numberResults: 1,
  includeCost: true,
  deliveryMethod: "sync",
});
const result = Array.isArray(models3d) ? models3d[0] : models3d;
// result.outputs.files[].url
result.outputs?.files.forEach(f => console.log(f.url));
```
```

--------------------------------

### enhancePrompt / promptEnhance

Source: https://context7.com/runware/sdk-js/llms.txt

Rewrites and expands a given prompt into multiple richer, more detailed versions. This is useful as a preprocessing step before image generation. It allows customization of the number of variants and maximum length.

```APIDOC
## enhancePrompt / promptEnhance

Rewrites and expands a short prompt into a richer, more detailed version. Can return multiple prompt variants. Useful as a preprocessing step before image generation.

```typescript
const enhanced = await runware.enhancePrompt({
  prompt: "A cat sitting on a chair",
  promptMaxLength: 300,   // max characters, 1–380, default: 380
  promptVersions: 3,      // return 3 variants
  includeCost: true,
});
// enhanced: IEnhancedPrompt[] — array of { taskUUID, text, cost }
enhanced.forEach((v, i) => console.log(`Variant ${i + 1}: ${v.text}`));
```
```

--------------------------------

### modelSearch

Source: https://context7.com/runware/sdk-js/llms.txt

Searches the Runware model library by keyword, tags, category, and architecture. Returns a paginated list of models.

```APIDOC
## modelSearch

Searches the Runware model library by keyword, tags, category, and architecture. Returns a paginated list of models.

### Parameters

- **search** (string) - Optional - The search query string.
- **category** (string) - Optional - The category of models to search for (e.g., 'checkpoint', 'lora').
- **architecture** (EModelArchitecture) - Optional - The architecture of models to search for (e.g., 'sdxl', 'sd1.5').
- **tags** (string[]) - Optional - An array of tags to filter models by.
- **visibility** (string) - Optional - The visibility of the models to search for ('public' or 'private').
- **limit** (number) - Optional - The maximum number of results to return.
- **offset** (number) - Optional - The number of results to skip (for pagination).

### Returns

- **TModelSearchResponse** - An object containing the total number of results and an array of model objects.
```

--------------------------------

### Model Upload

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Upload different types of models to Runware, including ControlNet, Checkpoint, and LoRA models. Each type has specific parameters for configuration.

```APIDOC
## Model Upload

This endpoint allows users to upload various types of models to the Runware platform.

### Method
POST (implied by SDK usage)

### Endpoint
Not explicitly defined, SDK method `runware.modelUpload`

### Parameters
#### Request Body (Base Payload)
- **air** (string) - Required - Identifier for the model.
- **name** (string) - Required - Name of the model.
- **downloadURL** (string) - Required - URL to download the model.
- **uniqueIdentifier** (string) - Required - A unique identifier for the model.
- **version** (string) - Required - Version of the model.
- **format** (EModelFormat) - Required - The format of the model.
- **architecture** (EModelArchitecture) - Required - The architecture of the model.
- **heroImageURL** (string) - Optional - URL for a hero image of the model.
- **tags** (string[]) - Optional - Tags associated with the model.
- **shortDescription** (string) - Optional - A brief description of the model.
- **comment** (string) - Optional - Additional comments about the model.
- **private** (boolean) - Required - Whether the model is private.
- **customTaskUUID** (string) - Optional - Custom UUID for the task.
- **retry** (number) - Optional - Number of retries for the operation.
- **onUploadStream** (function) - Optional - Callback function for upload stream events.

#### ControlNet Specific Parameters
- **category** (string) - Required - Must be "controlnet".
- **conditioning** (EModelConditioning) - Required - The conditioning type for ControlNet.

#### Checkpoint Specific Parameters
- **category** (string) - Required - Must be "checkpoint".
- **positiveTriggerWords** (string) - Optional - Trigger words for the checkpoint model.
- **defaultCFGScale** (number) - Optional - Default CFG scale for the checkpoint.
- **defaultStrength** (number) - Required - Default strength for the checkpoint.
- **defaultSteps** (number) - Optional - Default steps for the checkpoint.
- **defaultScheduler** (number) - Optional - Default scheduler for the checkpoint.
- **type** (EModelType) - Optional - The type of the checkpoint model.

#### LoRA Specific Parameters
- **category** (string) - Required - Must be "lora".
- **defaultWeight** (number) - Required - Default weight for the LoRA model.
- **positiveTriggerWords** (string) - Optional - Trigger words for the LoRA model.

### Response
#### Success Response
- **status** (string) - Status of the upload operation.
- **message** (string) - Message indicating the result of the operation.
- **taskUUID** (string) - The UUID of the task.
- **air** (string) - Identifier for the model.
- **taskType** (string) - The type of the task.

#### Error Response
- **code** (string) - Error code.
- **message** (string) - Error message.
- **parameter** (string) - The parameter that caused the error.
- **type** (string) - The type of error.
- **documentation** (string) - Link to documentation for the error.
- **taskUUID** (string) - The UUID of the task.
```

--------------------------------

### Audio Inference with Custom Settings

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Perform audio inference with specified duration, output format, and audio settings like bitrate and sample rate. Includes cost and delivery method options.

```javascript
const  runware  =  new Runware({ apiKey: "API_KEY" });
const audio = await runware.audioInference({
	duration: 10,
	outputFormat: "MP3",
	numberResults: 2,
	includeCost: true,
	audioSettings: {
		bitrate: 128,
		sampleRate: 44100
	},
	outputType: "URL",
	model: "elevenlabs:1@1",
	positivePrompt: "hip hop",
	deliveryMethod: "async"
})
console.log(audio)

return interface IAudio {
  taskUUID: string;
  taskType: string;
  audioUUID?: string;
  audioURL?: string;
  audioBase64Data?: string;
  audioDataURI?: string;
  cost?: number;
}
```

--------------------------------

### Ensure Runware Server Connection

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Ensure the connection to the Runware server is established before making requests. This is crucial for server-based operations. Replace 'API_KEY' with your actual Runware API key.

```js
const runware = new RunwareServer({ apiKey: "API_KEY" });

await runware.ensureConnection();
```

--------------------------------

### Search Runware Model Library

Source: https://context7.com/runware/sdk-js/llms.txt

Searches the model library using keywords, tags, category, and architecture. Returns a paginated list of models. Use `limit` and `offset` for pagination.

```typescript
import { EModelArchitecture } from "@runware/sdk-js";

const results = await runware.modelSearch({
  search: "portrait photography",
  category: "checkpoint",
  architecture: EModelArchitecture.sdxl,
  tags: ["photorealistic", "portrait"],
  visibility: "public",
  limit: 20,
  offset: 0,
});
// results: TModelSearchResponse { totalResults, results: TModel[] }
console.log(`Found ${results.totalResults} models`);
results.results.forEach(m => console.log(`${m.name} (${m.air})`));
```

--------------------------------

### ControlNet Preprocess Image

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Use this to preprocess an input image for ControlNet. Specify the preprocessor type and optional parameters like dimensions and thresholds.

```javascript
const  runware  =  new Runware({ apiKey: "API_KEY" });
const controlNetPreProcessed = await runware.controlNetPreprocess({
	inputImage: string | File;
	preProcessorType: EPreProcessor;
	height?: number;
	width?: number;
	outputType?: IOutputType;
	outputFormat?: IOutputFormat;
	highThresholdCanny?: number;
	lowThresholdCanny?: number;
	includeHandsAndFaceOpenPose?: boolean;
})
console.log(controlNetPreProcessed)
return interface IControlNetImage {
	taskUUID: string;
	inputImageUUID: string;
	guideImageUUID: string;
	guideImageURL?: string;
	guideImageBase64Data?: string;
	guideImageDataURI?: string;
	cost: number;
}
```

--------------------------------

### Image Inference with Parallel Requests

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Demonstrates how to make two or more image inference requests concurrently using `Promise.all` for efficient parallel processing.

```APIDOC
## Image Inference

### Description
Generates images based on provided prompts and parameters. This example shows how to perform multiple requests in parallel.

### Method
`runware.imageInference(options)`

### Parameters
#### Request Body Parameters
- **positivePrompt** (string) - Required - Defines the positive prompt description of the image.
- **negativePrompt** (string) - Optional - Defines the negative prompt description of the image.
- **width** (number) - Required - Controls the image width.
- **height** (number) - Required - Controls the image height.
- **numberResults** (number) - Optional (default = 1) - The number of images to be generated.
- **model** (string) - Required - The AIR system ID of the image to be requested.
- **ipAdapters** (array) - Optional - Configuration for IP Adapters.
  - **model** (string) - Required - The model ID for the IP Adapter.
  - **weight** (number) - Required - The weight to apply for the IP Adapter.
  - **guideImage** (string) - Required - The guide image for the IP Adapter.
- **embeddings** (array) - Optional - Configuration for embeddings.
  - **model** (string) - Required - The model ID for the embedding.
  - **weight** (number) - Required - The weight to apply for the embedding.
- **outpaint** (object) - Optional - Configuration for outpainting.
  - **top** (number) - Required - Padding for the top.
  - **right** (number) - Required - Padding for the right.
  - **bottom** (number) - Required - Padding for the bottom.
  - **left** (number) - Required - Padding for the left.
  - **blur** (number) - Optional - Blur radius for outpainting.
- **onPartialImages** (function) - Optional - Callback function for partial image results.
  - **images** (array) - The partial images generated.
  - **error** (object) - Any error encountered during generation.

### Request Example
```javascript
const runware = new Runware({ apiKey: "API_KEY" });

const [firstImagesRequest, secondImagesRequest] = await Promise.all([
	runware.imageInference({
		positivePrompt: "a futuristic cityscape",
		width: 1024,
		height: 1024,
		numberResults: 1,
		model: "stable-diffusion-xl-1024-v1.0"
	}),
	runware.imageInference({
		positivePrompt: "a cat wearing a hat",
		width: 512,
		height: 512,
		numberResults: 2,
		model: "sd-v1-5",
		ipAdapters: [{
			model: "ip-adapter-faceid",
			weight: 0.7,
			guideImage: "data:image/png;base64,iVBORw0KGgo..."
		}],
		embeddings: [{
			model: "clip-vit-large-patch14",
			weight: 0.5
		}],
		outpaint: {
			top: 128,
			right: 64,
			bottom: 128,
			left: 64,
			blur: 8
		}
	})
]);

console.log({ firstImagesRequest, secondImagesRequest });
```

### Response
#### Success Response (200)
Returns an array of generated images, each conforming to the `ITextToImage` interface.

- **taskType** (ETaskType) - The type of task performed.
- **imageUUID** (string) - Unique identifier for the generated image.
- **inputImageUUID** (string) - Optional - Unique identifier for the input image, if applicable.
- **taskUUID** (string) - Unique identifier for the task.
- **imageURL** (string) - Optional - URL to access the generated image.
- **imageBase64Data** (string) - Optional - Base64 encoded image data.
- **imageDataURI** (string) - Optional - Data URI for the generated image.
- **NSFWContent** (boolean) - Optional - Indicates if the image contains NSFW content.
- **cost** (number) - The cost associated with generating the image.
- **positivePrompt** (string) - Optional - The positive prompt used for generation.
- **negativePrompt** (string) - Optional - The negative prompt used for generation.

#### Response Example
```json
[
  {
    "taskType": "IMAGE_GENERATION",
    "imageUUID": "img-abc123xyz",
    "taskUUID": "task-def456uvw",
    "imageURL": "https://cdn.runware.com/images/img-abc123xyz.png",
    "cost": 0.05,
    "positivePrompt": "a futuristic cityscape"
  }
]
```
```

--------------------------------

### Request Image Inference with Runware SDK

Source: https://github.com/runware/sdk-js/blob/main/readme.md

Perform image inference using the `imageInference` method. This method supports various parameters for text-to-image and image-to-image generation. Ensure you have imported `Runware` from '@runware/sdk-js' and replaced 'API_KEY' with your actual key.

```js
import { Runware } from "@runware/sdk-js";

const  runware  =  new  Runware({ apiKey: "API_KEY" });
const images = await runware.imageInference({
	positivePrompt: string;
	negativePrompt?: string;
	width: number;
	height: number;
	model: string;
	numberResults?: number;
	outputType?: "URL" | "base64Data" | "dataURI";
	outputFormat?: "JPG" | "PNG" | "WEBP";
	uploadEndpoint?: string;
	checkNSFW?: boolean
	seedImage?: File | string;
	maskImage?: File | string;
	strength?: number;
	steps?: number;
	scheduler?: string;
	seed?: number;
	CFGScale?: number;
	clipSkip?: number;
	refiner?: IRefiner;
	usePromptWeighting?: number;
	controlNet?: IControlNet[];
	lora?: ILora[];
  	retry?: number;
	ipAdapters?: IipAdapters[];
	providerSettings?: IProviderSettings;
	embeddings?: IEmbedding[];
	outpaint: IOutpaint;
	onPartialImages?: (images: IImage[], error: IError) =>  void;
})

return interface ITextToImage {
	taskType: ETaskType;
	imageUUID: string;
	inputImageUUID?: string;
	taskUUID: string;
	imageURL?: string;
	imageBase64Data?: string;
	imageDataURI?: string;
	NSFWContent?: boolean;
	cost: number;
	positivePrompt?: string;
  	negativePrompt?: string;
}
[]
```

--------------------------------

### mediaStorage

Source: https://context7.com/runware/sdk-js/llms.txt

Stores arbitrary media (image/video/audio) and retrieves a persistent `mediaUUID` for reference across tasks.

```APIDOC
## mediaStorage

Stores arbitrary media (image/video/audio) and retrieves a persistent `mediaUUID` for reference across tasks.

### Parameters

- **media** (string) - Required - The URL or data of the media to store.
- **operation** (string) - Required - The operation to perform, typically 'upload'.

### Returns

- **TMediaStorageResponse** - An object containing the media UUID, task UUID, and task type.
```

--------------------------------

### Generate Audio from Prompt

Source: https://context7.com/runware/sdk-js/llms.txt

Generates audio content like music or speech from a text prompt. Supports sync and async delivery and various audio settings.

```typescript
const audio = await runware.audioInference({
  model: "elevenlabs:1@1",
  positivePrompt: "Upbeat lo-fi hip hop beat with soft piano and rain sounds",
  duration: 30,
  numberResults: 1,
  outputType: "URL",
  outputFormat: "MP3",
  audioSettings: { bitrate: 192, sampleRate: 44100 },
  includeCost: true,
  deliveryMethod: "sync",
});
// audio: IAudio | IAudio[] { audioUUID, audioURL, audioBase64Data, cost }
const result = Array.isArray(audio) ? audio[0] : audio;
console.log(result.audioURL);
```

--------------------------------

### upscale / upscaleGan

Source: https://context7.com/runware/sdk-js/llms.txt

Upscales an image or video by a specified factor. Supports async delivery for video and various output formats and types. For new integrations, prefer using the `inputs` object.

```APIDOC
## upscale / upscaleGan

Upscales an image (or video via the `inputs` key) by a given factor. For new integrations, prefer `inputs.image` or `inputs.video` over `inputImage`; the response will then contain `mediaUUID`/`mediaURL`. Supports async delivery for long-running video upscaling.

```typescript
// Upscale an image 4×
const result = await runware.upscale({
  inputImage: "image-uuid-or-url-or-File",
  upscaleFactor: 4,
  outputType: "URL",
  outputFormat: "PNG",
  includeCost: true,
});
// result: IImage { imageURL, mediaURL, mediaUUID, cost, taskUUID }
console.log(result.imageURL ?? result.mediaURL);

// Upscale a video via inputs object (async delivery)
const videoResult = await runware.upscale({
  model: "upscaler-video@1",
  inputs: { video: "https://example.com/clip.mp4" },
  outputType: "URL",
  outputFormat: "MP4",
  deliveryMethod: "async",
  includeCost: true,
});
console.log(videoResult.mediaURL);
```
```

--------------------------------

### Remove Background with runware.removeBackground

Source: https://context7.com/runware/sdk-js/llms.txt

Removes the background from an image or video, supporting alpha matting for precise edges. For video, async delivery is available. The `settings` object allows fine-tuning of the background removal process.

```typescript
// Remove background from an image
const bgRemoved = await runware.removeBackground({
  model: "background-removal@1",
  inputImage: "image-uuid-or-File",
  outputType: "URL",
  outputFormat: "PNG",
  includeCost: true,
  settings: {
    alphaMatting: true,
    alphaMattingForegroundThreshold: 240,
    alphaMattingBackgroundThreshold: 10,
    alphaMattingErodeSize: 10,
    returnOnlyMask: false,
    postProcessMask: true,
    rgba: [255, 255, 255, 0],
  },
});
// bgRemoved: IRemoveImage { imageURL, mediaURL, mediaUUID, cost, taskUUID }
console.log(bgRemoved.imageURL ?? bgRemoved.mediaURL);
```

```typescript
// Remove background from video (async)
const videoResult = await runware.removeBackground({
  model: "background-removal-video@1",
  inputs: { video: "https://example.com/clip.mp4" },
  deliveryMethod: "async",
  outputType: "URL",
  outputFormat: "MP4",
});
console.log(videoResult.mediaURL);
```