### Complete End-to-End Workflow

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

A full working example demonstrating the SDK initialization, asset upload, indexing, search, and analysis.

```APIDOC
## Complete End-to-End Workflow

Full working example from SDK initialization through search and analysis.

```typescript
import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js";

async function main() {
  const client = new TwelveLabs({ apiKey: process.env.TWELVELABS_API_KEY! });

  // 1. Create an index
  const index = await client.indexes.create({
    indexName: "demo-index",
    models: [
      { modelName: "marengo3.0", modelOptions: ["visual", "audio"] },
      { modelName: "pegasus1.2", modelOptions: ["visual", "audio"] },
    ],
  });
  console.log(`Index created: ${index.id}`);

  // 2. Upload an asset
  const asset = await client.assets.create({
    method: "url",
    url: "https://example.com/demo-video.mp4",
  });

  // 3. Wait for asset to be ready (for large files)
  let readyAsset = await client.assets.retrieve(asset.id);
  while (readyAsset.status !== "ready" && readyAsset.status !== "failed") {
    await new Promise((r) => setTimeout(r, 5000));
    readyAsset = await client.assets.retrieve(asset.id);
  }

  // 4. Index the asset
  let indexedAsset = await client.indexes.indexedAssets.create(index.id, {
    assetId: asset.id,
  });

  // 5. Wait for indexing to complete
  while (indexedAsset.status !== "ready" && indexedAsset.status !== "failed") {
    await new Promise((r) => setTimeout(r, 5000));
    indexedAsset = await client.indexes.indexedAssets.retrieve(index.id, indexedAsset.id);
  }
  console.log("Indexing complete!");

  // 6. Search the indexed video
  const searchResults = await client.search.query({
    indexId: index.id,
    queryText: "the most exciting moment",
    searchOptions: ["visual", "audio"],
  });
  for await (const clip of searchResults) {
    console.log(`Clip: start=${clip.start}s end=${clip.end}s score=${clip.score}`);
  }

  // 7. Analyze the video
  const analysis = await client.analyze({
    videoId: indexedAsset.id,
    prompt: "Summarize this video in 2-3 sentences.",
  });
  console.log("Summary:", analysis.data);
}

main().catch(console.error);
```
```

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

### Install twelvelabs-js SDK

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/README.md

Install the latest version of the twelvelabs-js package using npm or yarn.

```sh
npm install twelvelabs-js
# or yarn add twelvelabs-js
```

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

### Initialize TwelveLabs Client

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Instantiate the SDK client with your API key. Ensure the API key is securely stored and accessed, for example, via environment variables.

```typescript
import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: process.env.TWELVELABS_API_KEY! });
```

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

### Complete End-to-End Video Indexing and Search Workflow

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

A full example demonstrating SDK initialization, index creation, asset upload, waiting for readiness, indexing, searching, and video analysis. Includes error handling and asynchronous operations.

```typescript
import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js";

async function main() {
  const client = new TwelveLabs({ apiKey: process.env.TWELVELABS_API_KEY! });

  // 1. Create an index
  const index = await client.indexes.create({
    indexName: "demo-index",
    models: [
      { modelName: "marengo3.0", modelOptions: ["visual", "audio"] },
      { modelName: "pegasus1.2", modelOptions: ["visual", "audio"] },
    ],
  });
  console.log(`Index created: ${index.id}`);

  // 2. Upload an asset
  const asset = await client.assets.create({
    method: "url",
    url: "https://example.com/demo-video.mp4",
  });

  // 3. Wait for asset to be ready (for large files)
  let readyAsset = await client.assets.retrieve(asset.id);
  while (readyAsset.status !== "ready" && readyAsset.status !== "failed") {
    await new Promise((r) => setTimeout(r, 5000));
    readyAsset = await client.assets.retrieve(asset.id);
  }

  // 4. Index the asset
  let indexedAsset = await client.indexes.indexedAssets.create(index.id, {
    assetId: asset.id,
  });

  // 5. Wait for indexing to complete
  while (indexedAsset.status !== "ready" && indexedAsset.status !== "failed") {
    await new Promise((r) => setTimeout(r, 5000));
    indexedAsset = await client.indexes.indexedAssets.retrieve(index.id, indexedAsset.id);
  }
  console.log("Indexing complete!");

  // 6. Search the indexed video
  const searchResults = await client.search.query({
    indexId: index.id,
    queryText: "the most exciting moment",
    searchOptions: ["visual", "audio"],
  });
  for await (const clip of searchResults) {
    console.log(`Clip: start=${clip.start}s end=${clip.end}s score=${clip.score}`);
  }

  // 7. Analyze the video
  const analysis = await client.analyze({
    videoId: indexedAsset.id,
    prompt: "Summarize this video in 2-3 sentences.",
  });
  console.log("Summary:", analysis.data);
}

main().catch(console.error);
```

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

### Synchronously Analyze Video with Custom Prompt

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Use this method to analyze videos up to 1 hour and get immediate results. It supports custom prompts for generating text based on video content. Ensure videos meet duration, format, and resolution requirements.

```typescript
await client.analyze({
    videoId: "6298d673f1090f1100476d4c",
    prompt: "I want to generate a description for my video with the following format - Title of the video, followed by a summary in 2-3 sentences, highlighting the main topic, key events, and concluding remarks.",
    temperature: 0.2,
    responseFormat: {
        type: "json_schema",
        jsonSchema: {
            type: "object",
            properties: {
                title: {
                    type: "string",
                },
                summary: {
                    type: "string",
                },
                keywords: {
                    type: "array",
                    items: {
                        type: "string",
                    },
                },
            },
        },
    },
    maxTokens: 2000,
});
```

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

### Error Handling

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/README.md

The SDK maps specific exceptions to HTTP status codes for robust error handling. Examples demonstrate how to catch and manage these errors.

```APIDOC
## Error Handling

### Description
The SDK includes a set of exceptions mapped to specific HTTP status codes to facilitate error handling.

### Exception Mapping
| Exception                | HTTP Status Code |
| ------------------------ | ---------------- |
| BadRequestError          | 400              |
| AuthenticationError      | 401              |
| PermissionDeniedError    | 403              |
| NotFoundError            | 404              |
| ConflictError            | 409              |
| UnprocessableEntityError | 422              |
| RateLimitError           | 429              |
| InternalServerError      | 5xx              |

### Example Usage
```js
import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: process.env.TWELVELABS_API_KEY });
try {
  const indexes = await client.indexes.list();
  console.log(indexes);
} catch (e) {
  if (e instanceof TwelvelabsApi.BadRequestError) {
    console.log("Bad request.");
  } else if (e instanceof TwelvelabsApi.NotFoundError) {
    console.log("Not found.");
  } else {
    console.log(`An error occurred: ${e}`);
  }
}
```
```

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

### Analyze Video with Non-Streaming Responses

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/README.md

Use this method to get the complete generated text in a single response, suitable for reports or summaries. The prompt can be up to 2,000 tokens, and the response data can be up to 4,096 tokens.

```javascript
const result = await client.analyze({
  videoId: indexedAsset.id,
  prompt: "<YOUR_PROMPT>"
});
console.log(result.data);
```

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

### Get Additional Presigned URLs with `client.multipartUpload.getAdditionalPresignedUrls`

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Generates new presigned URLs for specific chunks when the originals have expired or additional chunks need uploading. Specify the upload ID, start chunk index, and count of URLs needed.

```typescript
const urlsResponse = await client.multipartUpload.getAdditionalPresignedUrls("507f1f77bcf86cd799439011", {
  start: 21,  // Start at chunk index 21
  count: 10,  // Generate 10 new URLs (chunks 21–30)
});
console.log(`Generated ${urlsResponse.parts?.length} new presigned URLs`)
```

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

### Get Task Transfer Logs

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Retrieves the logs associated with a task transfer for a specified integration. Requires an integration ID.

```typescript
await client.tasks.transfers.getLogs("integration-id");
```

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

### Import and Initialize TwelveLabs SDK

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/README.md

Import the SDK and instantiate the client with your API key.

```javascript
import { TwelveLabs } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });
```

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

### Create an Index with Models and Addons

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Create a new index for organizing video content. Specify the desired AI models (e.g., Marengo for search, Pegasus for text generation) and their modalities, as well as any additional features like thumbnails.

```typescript
import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: process.env.TWELVELABS_API_KEY! });

// Create an index with both Marengo (search) and Pegasus (text generation)
const index = await client.indexes.create({
  indexName: "my-video-library",
  models: [
    { modelName: "marengo3.0", modelOptions: ["visual", "audio"] },
    { modelName: "pegasus1.2", modelOptions: ["visual", "audio"] },
  ],
  addons: ["thumbnail"],
});

if (!index.id) throw new Error("Failed to create index");
console.log(`Created index: id=${index.id}`);
// Created index: id=6298d673f1090f1100476d4c
```

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

### Get Task Transfer Status

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Retrieves the current status of a task transfer for a specified integration. Requires an integration ID.

```typescript
await client.tasks.transfers.getStatus("integration-id");
```

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

### Get Embed Task Status

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Retrieves the status of a video embedding task. This is useful for determining when embeddings are ready for retrieval.

```APIDOC
## Get Embed Task Status

### Description
Retrieves the status of a video embedding task. This is useful for determining when embeddings are ready for retrieval.

### Method
GET

### Endpoint
/embed/tasks/{taskId}/status

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The unique identifier of your video embedding task.

#### Query Parameters
- **requestOptions** (object) - Optional - Options for the request.

### Response
#### Success Response (200)
- **status** (string) - The current status of the task (e.g., 'processing', 'ready', 'failed').

#### Response Example
```json
{
  "status": "ready"
}
```
```

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

### Create an Index with Models and Modalities

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/README.md

Create a new index for organizing video data. Configure the index with specific video understanding models like 'marengo3.0' for search or 'pegasus1.2' for text generation, and specify the modalities (e.g., 'visual', 'audio') to analyze.

```javascript
const index = await client.indexes.create({
  indexName: "<YOUR_INDEX_NAME>",
  models: [
    { modelName: "marengo3.0", modelOptions: ["visual", "audio"] },
    { modelName: "pegasus1.2", modelOptions: ["visual", "audio"] }
  ]
});
if (!index.id) {
  throw new Error("Failed to create an index.");
}
console.log(`Created index: id=${index.id}`);
```

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

### retrieve

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Retrieves detailed information about a specific entity within an entity collection. Use this method to get the current state and properties of an entity.

```APIDOC
## retrieve entityCollections.entities

### Description
Retrieves details about the specified entity.

### Method
`client.entityCollections.entities.retrieve(entityCollectionId, entityId, requestOptions)`

### Parameters
#### Path Parameters
- **entityCollectionId** (string) - Required - The unique identifier of the entity collection.
- **entityId** (string) - Required - The unique identifier of the entity to retrieve.

#### Request Options
- **requestOptions** (Entities.RequestOptions) - Optional

### Request Example
```typescript
await client.entityCollections.entities.retrieve("6298d673f1090f1100476d4c", "6298d673f1090f1100476d4c");
```

### Response
#### Success Response (200)
- **entity** (TwelvelabsApi.Entity) - Details of the retrieved entity.
```

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

### client.tasks.create

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Creates a new video indexing task.

```APIDOC
## client.tasks.create

### Description
This method creates a new video indexing task.

### Parameters
#### Request Body
- **videoId** (string) - Required - The ID of the video to index.
- **modelId** (string) - Optional - The ID of the model to use for indexing. If not provided, a default model will be used.
- **modelName** (string) - Optional - The name of the model to use for indexing. If not provided, a default model will be used.
- **customParameters** (object) - Optional - Custom parameters for the analysis.
```

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

### client.tasks.create

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Legacy endpoint that bundles upload and indexing in a single operation.

```APIDOC
## `client.tasks.create` — Create Video Indexing Task (Legacy)

### Description
Legacy endpoint that bundles upload and indexing in a single operation. New implementations should use `client.assets.create` + `client.indexes.indexedAssets.create` separately.

### Method
POST (assumed based on create operation)

### Endpoint
/tasks

### Parameters
#### Request Body
- **indexId** (string) - Required - The ID of the index to associate the video with.
- **videoUrl** (string) - Required if `videoFile` is not provided - The URL of the video file.
- **videoFile** (File) - Required if `videoUrl` is not provided - The video file to upload.

### Response
#### Success Response (200)
- (No specific response body detailed, likely a task ID or status)

#### Response Example
```json
// Example of initiating a task with a URL
await client.tasks.create({
  indexId: "6298d673f1090f1100476d4c",
  videoUrl: "https://example.com/video.mp4"
});
```
```

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

### client.indexes.create

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Creates a named index with specified AI models and modality options. Indexes group related videos and determine available capabilities.

```APIDOC
## client.indexes.create — Create an Index

Creates a named index with one or more AI models and their modality options. Indexes group related videos and determine which capabilities (search, analysis) are available.

### Method
POST

### Endpoint
/v1/indexes

### Parameters
#### Request Body
- **indexName** (string) - Required - The name of the index.
- **models** (array) - Required - An array of model objects, each specifying a modelName and its modality options.
  - **modelName** (string) - Required - The name of the AI model (e.g., "marengo3.0", "pegasus1.2").
  - **modelOptions** (array) - Required - An array of strings specifying the modality options (e.g., ["visual", "audio"]).
- **addons** (array) - Optional - An array of strings specifying additional addons (e.g., ["thumbnail"]).

### Request Example
```typescript
await client.indexes.create({
  indexName: "my-video-library",
  models: [
    { modelName: "marengo3.0", modelOptions: ["visual", "audio"] },
    { modelName: "pegasus1.2", modelOptions: ["visual", "audio"] },
  ],
  addons: ["thumbnail"],
});
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created index.
- **indexName** (string) - The name of the index.
- **models** (array) - The AI models configured for the index.
- **addons** (array) - The addons configured for the index.

#### Response Example
```json
{
  "id": "6298d673f1090f1100476d4c",
  "indexName": "my-video-library",
  "models": [
    { "modelName": "marengo3.0", "modelOptions": ["visual", "audio"] },
    { "modelName": "pegasus1.2", "modelOptions": ["visual", "audio"] },
  ],
  "addons": ["thumbnail"]
}
```
```

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

### Get Multipart Upload Status with `client.multipartUpload.getStatus`

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Monitors the progress of a multipart upload session, including per-chunk status and completion state. Allows pagination for large numbers of chunks.

```typescript
const statusPage = await client.multipartUpload.getStatus("507f1f77bcf86cd799439011", {
  page: 1,
  pageLimit: 50,
});

for await (const chunk of statusPage) {
  console.log(`Chunk ${chunk.chunkIndex}: status=${chunk.status} size=${chunk.chunkSize}`);
}
```

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

### client.indexes.create

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

This method creates an index. It requires an index name and a list of models with their options. Addons can also be specified.

```APIDOC
## client.indexes.create

### Description
This method creates an index.

### Method
POST

### Endpoint
/indexes

### Parameters
#### Request Body
- **indexName** (string) - Required - The name of the index to create.
- **models** (array) - Required - A list of models to associate with the index.
  - **modelName** (string) - Required - The name of the model.
  - **modelOptions** (array) - Required - Options for the model (e.g., "visual", "audio").
- **addons** (array) - Optional - Addons to enable for the index (e.g., "thumbnail").

### Request Example
```json
{
  "indexName": "myIndex",
  "models": [
    {
      "modelName": "marengo3.0",
      "modelOptions": ["visual", "audio"]
    },
    {
      "modelName": "pegasus1.2",
      "modelOptions": ["visual", "audio"]
    }
  ],
  "addons": ["thumbnail"]
}
```

### Response
#### Success Response (200)
- **data** (object) - The created index details.
- **message** (string) - Success message.
```

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

### Handle API Errors with TwelveLabs SDK

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/README.md

This example demonstrates how to catch and handle specific HTTP errors thrown by the TwelveLabs API, such as BadRequestError or NotFoundError, using a try-catch block.

```javascript
import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: process.env.TWELVELABS_API_KEY });
try {
  const indexes = await client.indexes.list();
  console.log(indexes);
} catch (e) {
  if (e instanceof TwelvelabsApi.BadRequestError) {
    console.log("Bad request.");
  } else if (e instanceof TwelvelabsApi.NotFoundError) {
    console.log("Not found.");
  } else {
    console.log(`An error occurred: ${e}`);
  }
}
```

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

### Create Multipart Upload Session with `client.multipartUpload.create`

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Creates a new multipart upload session and returns presigned URLs for uploading individual chunks. Requires filename, type, and total size of the file.

```typescript
const session = await client.multipartUpload.create({
  filename: "my-video.mp4",
  type: "video",
  totalSize: 104857600, // 100 MB in bytes
});

console.log(`Upload session created: uploadId=${session.uploadId}`);
// Use session.parts[n].url to upload each chunk via PUT requests
```

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

### Get Embed Task Status

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Retrieves the status of a video embedding task. The task can be in 'processing', 'ready', or 'failed' states. This endpoint is deprecated; consider using Embed API v2.

```typescript
await client.embed.tasks.status("663da73b31cdd0c1f638a8e6");
```

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

### Async Video Analysis Task Creation using client.analyzeAsync.tasks.create

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Creates a background analysis task for videos up to 2 hours or for video segmentation. Returns a task ID to poll for results. Use this for long videos or when immediate results are not required.

```typescript
const task = await client.analyzeAsync.tasks.create({
  video: {
    type: "url",
    url: "https://example.com/long-video.mp4",
  },
  prompt: "Generate a detailed summary of this video in 3-4 sentences",
  temperature: 0.2,
  maxTokens: 1000,
});

console.log(`Created async analysis task: id=${task.id}`);

// Poll until ready
let taskStatus = await client.analyzeAsync.tasks.retrieve(task.id);
while (taskStatus.status !== "ready" && taskStatus.status !== "failed") {
  console.log(`Task status: ${taskStatus.status}`);
  await new Promise((r) => setTimeout(r, 5000));
  taskStatus = await client.analyzeAsync.tasks.retrieve(task.id);
}

if (taskStatus.status === "failed") throw new Error("Analysis task failed");
console.log("Analysis result:", taskStatus.data);
```

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

### List Entities in Entity Collection

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Retrieves a paginated list of entities within a specified entity collection. Allows filtering by name, status, and sorting. Use this to get entities belonging to a particular collection.

```typescript
const response = await client.entityCollections.entities.list("6298d673f1090f1100476d4c", {
    page: 1,
    pageLimit: 10,
    name: "My entity",
    status: "processing",
    sortBy: "created_at",
    sortOption: "desc",
});
for await (const item of response) {
    console.log(item);
}
```

```typescript
const page = await client.entityCollections.entities.list("6298d673f1090f1100476d4c", {
    page: 1,
    pageLimit: 10,
    name: "My entity",
    status: "processing",
    sortBy: "created_at",
    sortOption: "desc",
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}
```

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

### client.tasks.transfers.create

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Initiates a task transfer process.

```APIDOC
## client.tasks.transfers.create

### Description
Initiates a task transfer process.

### Method
POST (implied by create operation)

### Endpoint
/tasks/transfers

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **integrationId** (string) - Required - The identifier of the integration.

### Request Example
```typescript
await client.tasks.transfers.create("integration-id");
```

### Response
#### Success Response (200)
- **void** - Indicates successful initiation of the transfer.
```

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

### Create Asset

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

This method creates an asset by uploading a file to the platform. Assets are media files that you can use in downstream workflows, including indexing, analyzing video content, and creating entities. Supported content includes Video, audio, and images. Upload can be done via local file or a publicly accessible URL. File size up to 4 GB.

```APIDOC
## Create Asset

### Description
This method creates an asset by uploading a file to the platform. Assets are media files that you can use in downstream workflows, including indexing, analyzing video content, and creating entities.

**Supported content**: Video, audio, and images.

**Upload methods**:

- **Local file**: Set the `method` parameter to `direct` and use the `file` parameter to specify the file.
- **Publicly accessible URL**: Set the `method` parameter to `url` and use the `url` parameter to specify the URL of your file.

**File size**: Up to 4 GB.

### Method
POST

### Endpoint
/assets

### Parameters
#### Request Body
- **method** (string) - Required - Specifies the upload method (`direct` or `url`).
- **file** (File) - Required if method is `direct` - The local file to upload.
- **url** (string) - Required if method is `url` - The publicly accessible URL of the file.

### Request Example
```typescript
await client.assets.create({
    method: "direct",
    // file: File
});
```

### Response
#### Success Response (200)
- **asset** (object) - Details of the created asset.
```

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

### Get Additional Presigned URLs

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Generates new presigned URLs for specific chunks that require uploading. Use this endpoint when initial URLs have expired, do not include all chunks, or to retry failed chunk uploads.

```APIDOC
## Get Additional Presigned URLs

### Description
Generates new presigned URLs for specific chunks that require uploading. Use this endpoint in the following situations:
- Your initial URLs have expired (URLs expire after one hour).
- The initial set of presigned URLs does not include URLs for all chunks.
- You need to retry failed chunk uploads with new URLs.
To specify which chunks need URLs, use the `start` and `count` parameters. For example, to generate URLs for chunks 21 to 30, use `start=21` and `count=10`.
The response will provide new URLs, each with a fresh expiration time of one hour.

### Method
`client.multipartUpload.getAdditionalPresignedUrls`

### Parameters
- **uploadId** (string) - Required - The unique identifier of the upload session.
- **request** (TwelvelabsApi.RequestAdditionalPresignedUrLsRequest) - Required
- **requestOptions** (MultipartUpload.RequestOptions) - Optional

### Request Example
```typescript
await client.multipartUpload.getAdditionalPresignedUrls("507f1f77bcf86cd799439011", {
    start: 1,
    count: 10,
});
```
```

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

### client.tasks.list

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Retrieves a list of video indexing tasks, sorted by creation date.

```APIDOC
## client.tasks.list

### Description
This method returns a list of the video indexing tasks in your account. The platform returns your video indexing tasks sorted by creation date, with the newest at the top of the list.

### Parameters
#### Query Parameters
- **page** (number) - Optional - The page number for pagination.
- **pageLimit** (number) - Optional - The number of items to return per page.
- **sortBy** (string) - Optional - The field to sort the tasks by (e.g., `created_at`).
- **sortOption** (string) - Optional - The sorting order (`asc` or `desc`).
- **indexId** (string) - Optional - Filter tasks by index ID.
- **filename** (string) - Optional - Filter tasks by filename.
- **duration** (number) - Optional - Filter tasks by video duration.
- **width** (number) - Optional - Filter tasks by video width.
- **height** (number) - Optional - Filter tasks by video height.
- **createdAt** (string) - Optional - Filter tasks by creation date (ISO 8601 format).
- **updatedAt** (string) - Optional - Filter tasks by update date (ISO 8601 format).
```

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

### Generate Additional Presigned URLs for Multipart Upload

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Use this method to generate new presigned URLs for specific chunks that require uploading. This is useful when initial URLs expire, do not cover all chunks, or when retrying failed uploads. Specify chunks using `start` and `count` parameters.

```typescript
await client.multipartUpload.getAdditionalPresignedUrls("507f1f77bcf86cd799439011", {
    start: 1,
    count: 10,
});
```

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

### Create Asset via Direct Upload

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Use this method to create an asset by uploading a local file. Supported content types include video, audio, and images up to 4 GB. Ensure the `method` parameter is set to `direct`.

```typescript
await client.assets.create({
    method: "direct",
});
```

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

### Get multipart upload status and chunk information

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

Retrieve the status of an upload session, including chunk progress and completion state. This is crucial for verifying completion, retrying failed chunks, and monitoring progress. Call this after reporting chunk completion to confirm the upload is 'completed' before using the asset.

```typescript
const response = await client.multipartUpload.getStatus("507f1f77bcf86cd799439011", {
    page: 1,
    pageLimit: 10,
});
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
const page = await client.multipartUpload.getStatus("507f1f77bcf86cd799439011", {
    page: 1,
    pageLimit: 10,
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}
```

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

### Create Video Indexing Task (Legacy)

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Legacy endpoint for uploading and indexing video in a single operation. New implementations should use separate asset creation and indexing calls.

```typescript
// Legacy: upload + index in one step (files up to 2 GB)
await client.tasks.create({
  indexId: "6298d673f1090f1100476d4c",
  videoUrl: "https://example.com/video.mp4",
  // Or: videoFile: fs.createReadStream("/path/to/video.mp4")
});
```

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

### client.embed.v2.create

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Synchronously creates vector embeddings for text, images, audio, or video content (up to 10 minutes). Returns immediately with the embedding vectors.

```APIDOC
## `client.embed.v2.create` — Create Embeddings (V2, Sync)

Synchronously creates vector embeddings for text, images, audio, or video content (up to 10 minutes). Returns immediately with the embedding vectors.

```typescript
// Text embedding
const textEmbedding = await client.embed.v2.create({
  inputType: "text",
  modelName: "marengo3.0",
  text: { inputText: "man walking a dog in the park" },
});
console.log(`Text embedding dimension: ${textEmbedding.embedding?.float?.length}`);

// Image embedding
const imageEmbedding = await client.embed.v2.create({
  inputType: "image",
  modelName: "marengo3.0",
  image: { mediaSource: { url: "https://example.com/image.jpg" } },
});
console.log(`Image embedding created: ${imageEmbedding.embedding?.float?.slice(0, 3)}`);
```
```

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

### Index Video Asset

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/README.md

Create an indexed asset by calling the `client.indexes.indexedAssets.create` method. This prepares the video for searching within a specific index.

```javascript
let indexedAsset = await client.indexes.indexedAssets.create(index.id, {
  assetId: asset.id
});
console.log(`Created indexed asset: id=${indexedAsset.id}`);
```

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

### Create Task

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/reference.md

This method creates a video indexing task that uploads and indexes a video in a single operation. It is a legacy endpoint and will be removed in a future major API release. New implementations should use a separated workflow involving uploading the video first and then indexing it.

```APIDOC
## POST /tasks

### Description
Creates a video indexing task that uploads and indexes a video in a single operation. This is a legacy endpoint.

### Method
POST

### Endpoint
/tasks

### Parameters
#### Request Body
- **video_file** (file) - Optional - The video file to upload.
- **video_url** (string) - Optional - The URL of the publicly accessible video.
- **indexId** (string) - Required - The ID of the index to associate the video with.

### Request Example
```json
{
  "indexId": "index_id",
  "video_file": "<video_file>",
  "video_url": "<video_url>"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created task.
- **status** (string) - The status of the task.

#### Response Example
```json
{
  "id": "6298d673f1090f1100476d4c",
  "status": "processing"
}
```
```

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

### Create Embeddings (V2, Sync) with `client.embed.v2.create`

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Synchronously creates vector embeddings for text, images, audio, or video content (up to 10 minutes). Returns immediately with the embedding vectors. Requires input type, model name, and content.

```typescript
// Text embedding
const textEmbedding = await client.embed.v2.create({
  inputType: "text",
  modelName: "marengo3.0",
  text: { inputText: "man walking a dog in the park" },
});
console.log(`Text embedding dimension: ${textEmbedding.embedding?.float?.length}`);

// Image embedding
const imageEmbedding = await client.embed.v2.create({
  inputType: "image",
  modelName: "marengo3.0",
  image: { mediaSource: { url: "https://example.com/image.jpg" } },
});
console.log(`Image embedding created: ${imageEmbedding.embedding?.float?.slice(0, 3)}`);
```

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

### client.assets.list

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Returns a paginated list of all assets in your account with optional filename filtering.

```APIDOC
## `client.assets.list` — List Assets

Returns a paginated list of all assets in your account with optional filename filtering.

```typescript
const response = await client.assets.list({
  page: 1,
  pageLimit: 10,
  filename: "meeting",
});

for await (const asset of response) {
  console.log(`Asset: id=${asset.id} status=${asset.status}`);
}
```
```

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

### client.embed.v2.tasks.create

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Creates an asynchronous embedding task for long-form audio or video content (up to 4 hours).

```APIDOC
## `client.embed.v2.tasks.create` — Create Async Embedding Task (V2)

### Description
Creates an asynchronous embedding task for long-form audio or video content (up to 4 hours).

### Method
POST (assumed based on create operation)

### Endpoint
/v2/embed/tasks

### Parameters
#### Request Body
- **inputType** (string) - Required - Type of input media ('audio' or 'video').
- **modelName** (string) - Required - The name of the model to use for embedding.
- **audio** (object) - Required if inputType is 'audio'.
  - **mediaSource** (object) - Required - Source of the media.
    - **url** (string) - Required - URL of the media file.
  - **startSec** (number) - Optional - Start time in seconds.
  - **endSec** (number) - Optional - End time in seconds.
  - **segmentation** (object) - Optional - Segmentation strategy.
    - **strategy** (string) - Required - Segmentation strategy ('fixed' or 'dynamic').
    - **fixed** (object) - Required if strategy is 'fixed'.
      - **durationSec** (number) - Required - Duration of fixed segments in seconds.
  - **embeddingOption** (array of strings) - Optional - Options for embedding ('audio', 'transcription').
  - **embeddingScope** (array of strings) - Optional - Scope for embedding ('clip', 'asset').

### Request Example
```json
{
  "inputType": "audio",
  "modelName": "marengo3.0",
  "audio": {
    "mediaSource": { "url": "https://example.com/long-audio.wav" },
    "startSec": 0,
    "endSec": 3600,
    "segmentation": {
      "strategy": "fixed",
      "fixed": { "durationSec": 6 }
    },
    "embeddingOption": ["audio", "transcription"],
    "embeddingScope": ["clip", "asset"]
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created task.

#### Response Example
```json
{
  "id": "task_abc123"
}
```
```

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

### client.multipartUpload.create

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Creates a new multipart upload session and returns presigned URLs for uploading individual chunks.

```APIDOC
## `client.multipartUpload.create` — Create Multipart Upload Session

Creates a new multipart upload session and returns presigned URLs for uploading individual chunks.

```typescript
const session = await client.multipartUpload.create({
  filename: "my-video.mp4",
  type: "video",
  totalSize: 104857600, // 100 MB in bytes
});

console.log(`Upload session created: uploadId=${session.uploadId}`);
// Use session.parts[n].url to upload each chunk via PUT requests
```
```

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

### Create Index

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/README.md

Creates a new index to store and organize video data. You can configure which video understanding models and modalities to enable for the index.

```APIDOC
## client.indexes.create

### Description
Creates a new index to store and organize video data, allowing configuration of video understanding models and modalities.

### Method
`client.indexes.create(params)`

### Parameters
#### Request Body
- **indexName** (string) - Required - The name of the index.
- **models** (array) - Required - An array of models to enable. Each entry has:
  - **modelName** (string) - Required - The model to enable (e.g., "marengo3.0", "pegasus1.2").
  - **modelOptions** (array) - Required - The modalities to analyze (e.g., ["visual", "audio"]).

### Request Example
```json
{
  "indexName": "<YOUR_INDEX_NAME>",
  "models": [
    { "modelName": "marengo3.0", "modelOptions": ["visual", "audio"] },
    { "modelName": "pegasus1.2", "modelOptions": ["visual", "audio"] }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the newly created index.
```

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

### List Video Indexing Tasks

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Returns a paginated list of video indexing tasks with filtering by index, filename, dimensions, and date.

```APIDOC
## `client.tasks.list` — List Video Indexing Tasks

Returns a paginated list of video indexing tasks with filtering by index, filename, dimensions, and date.

```typescript
const response = await client.tasks.list({
  page: 1,
  pageLimit: 10,
  sortBy: "created_at",
  sortOption: "desc",
  indexId: "6298d673f1090f1100476d4c",
  filename: "01.mp4",
});

for await (const task of response) {
  console.log(`Task: id=${task.id} status=${task.status}`);
}
```
```

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

### client.analyzeAsync.tasks.create

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Async Video Analysis Task. Creates a background analysis task for videos up to 2 hours or for video segmentation (Pegasus 1.5). Returns a task ID to poll for results.

```APIDOC
## `client.analyzeAsync.tasks.create` — Async Video Analysis Task

Creates a background analysis task for videos up to 2 hours or for video segmentation (Pegasus 1.5). Returns a task ID to poll for results.

```typescript
const task = await client.analyzeAsync.tasks.create({
  video: {
    type: "url",
    url: "https://example.com/long-video.mp4",
  },
  prompt: "Generate a detailed summary of this video in 3-4 sentences",
  temperature: 0.2,
  maxTokens: 1000,
});

console.log(`Created async analysis task: id=${task.id}`);

// Poll until ready
let taskStatus = await client.analyzeAsync.tasks.retrieve(task.id);
while (taskStatus.status !== "ready" && taskStatus.status !== "failed") {
  console.log(`Task status: ${taskStatus.status}`);
  await new Promise((r) => setTimeout(r, 5000));
  taskStatus = await client.analyzeAsync.tasks.retrieve(task.id);
}

if (taskStatus.status === "failed") throw new Error("Analysis task failed");
console.log("Analysis result:", taskStatus.data);
```
```

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

### Low-Level Search Endpoint using client.search.create

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Provides direct access to the search endpoint for text, image, media, or entity queries. Returns `SearchResults` with a page token for manual pagination. Use this for more control over search parameters.

```typescript
const results = await client.search.create({
  indexId: "6298d673f1090f1100476d4c",
  queryText: "product demonstration",
  searchOptions: ["visual", "audio", "transcription"],
});

console.log(`Found ${results.data?.length} results`);
// Retrieve next page using the page token
if (results.pageInfo?.nextPageToken) {
  const nextPage = await client.search.retrieve(results.pageInfo.nextPageToken, {
    includeUserMetadata: true,
  });
}
```

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

### client.tasks.retrieve

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Retrieves the current status and details of a legacy video indexing task.

```APIDOC
## `client.tasks.retrieve` — Retrieve a Video Indexing Task

### Description
Retrieves the current status and details of a legacy video indexing task.

### Method
GET (assumed based on retrieve operation)

### Endpoint
/tasks/{taskId}

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The ID of the legacy video indexing task.

### Response
#### Success Response (200)
- **status** (string) - The status of the task ('ready', 'processing', 'failed').

#### Response Example
```json
{
  "status": "ready"
}
```
```

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

### Analyze Video with Streaming Responses

Source: https://github.com/twelvelabs-io/twelvelabs-js/blob/main/README.md

Use this method to receive text fragments in real-time for tasks like live transcription. Ensure the Pegasus model is enabled for the index. The prompt can be up to 2,000 tokens.

```javascript
const textStream = await client.analyzeStream({
  videoId: indexedAsset.id,
  prompt: "<YOUR_PROMPT>"
});
for await (const text of textStream) {
  if ("text" in text) {
    console.log(text.text);
  }
}
```

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

### client.assets.retrieve

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Fetches details and processing status of an asset. Poll until `status === "ready"` before indexing large files (>200 MB).

```APIDOC
## `client.assets.retrieve` — Retrieve Asset Status

Fetches details and processing status of an asset. Poll until `status === "ready"` before indexing large files (>200 MB).

```typescript
let asset = await client.assets.retrieve("6298d673f1090f1100476d4c");

// Poll until ready (required for files > 200 MB)
while (asset.status !== "ready" && asset.status !== "failed") {
  console.log(`Asset status: ${asset.status}, waiting...`);
  await new Promise((r) => setTimeout(r, 5000));
  asset = await client.assets.retrieve("6298d673f1090f1100476d4c");
}

if (asset.status === "failed") throw new Error(`Asset processing failed: id=${asset.id}`);
console.log("Asset is ready");
```
```

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

### client.search.create

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Low-Level Search Endpoint. Direct access to the search endpoint for text, image, media, or entity queries. Returns `SearchResults` with a page token for manual pagination.

```APIDOC
## `client.search.create` — Low-Level Search Endpoint

Direct access to the search endpoint for text, image, media, or entity queries. Returns `SearchResults` with a page token for manual pagination.

```typescript
const results = await client.search.create({
  indexId: "6298d673f1090f1100476d4c",
  queryText: "product demonstration",
  searchOptions: ["visual", "audio", "transcription"],
});

console.log(`Found ${results.data?.length} results`);
// Retrieve next page using the page token
if (results.pageInfo?.nextPageToken) {
  const nextPage = await client.search.retrieve(results.pageInfo.nextPageToken, {
    includeUserMetadata: true,
  });
}
```
```

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

### List Async Analysis Tasks using client.analyzeAsync.tasks.list

Source: https://context7.com/twelvelabs-io/twelvelabs-js/llms.txt

Returns a paginated list of analysis tasks with optional filters for status, video URL, asset ID, and analysis mode. Useful for managing and tracking background analysis jobs.

```typescript
const tasks = await client.analyzeAsync.tasks.list({
  page: 1,
  pageLimit: 10,
  status: "ready",
  analysisMode: "time_based_metadata",
});
console.log(JSON.stringify(tasks));
```