# Twelve Labs Integration via LowCodeAPI

## Overview

Twelve Labs is a video understanding and search platform with AI-powered video indexing and search capabilities. The Twelve Labs API provides:

- **Video Search** - Search videos by text, image, or video query
- **Video Indexing** - Index videos for semantic search
- **Embeddings** - Generate multimodal embeddings for video content
- **Classification** - Classify video content by categories
- **Summarization** - Generate video summaries

## Base Endpoint

```
https://api.lowcodeapi.com/twelvelabs/
```

## Authentication

LowCodeAPI handles authentication automatically using API Key header authentication. You only need to:

1. **Sign up** at [Twelve Labs](https://www.twelvelabs.io) to get your API Key
2. **Connect your account** in the LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Twelve Labs API key
- Apply it to each request via the x-api-key header

**Auth Type**: API Key (Header)

## API Categories

- **Video Analysis AI** - AI-powered video understanding

## Common Endpoints

### Category: Any-to-video search

#### Search Videos

**Method**: `POST` | **LowCodeAPI Path**: `/v1.2/search-v22`

**Full URL**:
```
https://api.lowcodeapi.com/twelvelabs/v1.2/search-v22?api_token={api_token}
```

**Description**: Search videos using text, image, or video queries across indexed content.

**Request Body**:
```json
{
  "index_id": "your-index-id",
  "query_text": "a person riding a bicycle",
  "search_options": ["visual", "conversation"],
  "threshold": "medium",
  "adjust_confidence_level": 0.5
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `index_id` | string | Yes | Unique identifier of the index to search |
| `query_text` | string | No | Text query to search for |
| `query_media_url` | string | No | Publicly accessible URL of media to use as query |
| `query_media_file` | array | No | Local media file to use as query |
| `query_media_type` | string | No | Type of media to use (text, image, video) |
| `search_options` | array | Yes | Sources to search (visual, conversation, text_in_video) |
| `threshold` | string | No | Filter by confidence level (high, medium, low) |
| `adjust_confidence_level` | number | No | Strictness of confidence thresholds |
| `group_by` | string | No | Group or ungroup items in response |
| `sort_option` | string | No | Sort order for response |
| `operator` | string | No | Broaden or narrow search with multiple sources |
| `conversation_option` | string | No | Type of match for conversation search |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/twelvelabs/v1.2/search-v22?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "your-index-id",
    "query_text": "a person riding a bicycle",
    "search_options": ["visual", "conversation"],
    "threshold": "medium"
  }'
```

**Official Documentation**: [Search](https://docs.twelvelabs.io/reference/api-reference)

---

### Category: Index

#### Create Index

**Method**: `POST` | **LowCodeAPI Path**: `/v1.2/indexes`

**Full URL**:
```
https://api.lowcodeapi.com/twelvelabs/v1.2/indexes?api_token={api_token}
```

**Description**: Create a new index for video indexing.

**Request Body**:
```json
{
  "name": "My Video Index",
  "engine_id": "marengo2.6"
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Name for the index |
| `engine_id` | string | Yes | Engine to use (marengo2.6, etc.) |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/twelvelabs/v1.2/indexes?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Video Index",
    "engine_id": "marengo2.6"
  }'
```

**Official Documentation**: [Create Index](https://docs.twelvelabs.io/reference/api-reference)

---

#### List Indexes

**Method**: `GET` | **LowCodeAPI Path**: `/v1.2/indexes`

**Full URL**:
```
https://api.lowcodeapi.com/twelvelabs/v1.2/indexes?api_token={api_token}
```

**Description**: List all indexes in your account.

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/twelvelabs/v1.2/indexes?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [List Indexes](https://docs.twelvelabs.io/reference/api-reference)

---

### Category: Tasks

#### Get Task Status

**Method**: `GET` | **LowCodeAPI Path**: `/v1.2/tasks/task_id`

**Full URL**:
```
https://api.lowcodeapi.com/twelvelabs/v1.2/tasks/task_id?id={task_id}&api_token={api_token}
```

**Description**: Check the status of an asynchronous task.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Task ID to check |

**Example Request**:
```bash
# Replace TASK_ID with actual task ID
curl -X GET "https://api.lowcodeapi.com/twelvelabs/v1.2/tasks/task_id?id=TASK_ID&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Task](https://docs.twelvelabs.io/reference/api-reference)

---

## Usage Examples

### Example 1: Search Videos

Search indexed video content:

```bash
# Search by text description
# No ID needed in path - index_id in body
curl -X POST "https://api.lowcodeapi.com/twelvelabs/v1.2/search-v22?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "your-index-id",
    "query_text": "person talking about technology",
    "search_options": ["visual", "conversation"],
    "threshold": "medium"
  }'

# Search by image URL
# No ID needed in path
curl -X POST "https://api.lowcodeapi.com/twelvelabs/v1.2/search-v22?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "your-index-id",
    "query_media_url": "https://example.com/query-image.jpg",
    "query_media_type": "image",
    "search_options": ["visual"]
  }'
```

### Example 2: Manage Indexes

Create and list indexes:

```bash
# Create a new index
# No ID needed - creates new index
curl -X POST "https://api.lowcodeapi.com/twelvelabs/v1.2/indexes?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Demo Videos",
    "engine_id": "marengo2.6"
  }'

# List all indexes
# No ID needed - lists all indexes
curl -X GET "https://api.lowcodeapi.com/twelvelabs/v1.2/indexes?api_token=YOUR_API_TOKEN"
```

### Example 3: Check Task Status

Monitor indexing and processing:

```bash
# Check task status
# Replace TASK_ID with actual task ID
curl -X GET "https://api.lowcodeapi.com/twelvelabs/v1.2/tasks/task_id?id=TASK_ID&api_token=YOUR_API_TOKEN"
```

## Complete Endpoint Reference

For a complete list of all 38 endpoints and their parameters, refer to:

- **OpenAPI Definition**: https://backend.lowcodeapi.com/twelvelabs/definition
- **Official Twelve Labs Documentation**: https://docs.twelvelabs.io/reference/api-reference

## Rate Limits & Best Practices

- **Rate Limit**: Refer to your Twelve Labs plan for rate limits
- **Best Practices**:
  - Store index IDs for efficient searches
  - Use appropriate search options for your use case
  - Adjust threshold based on desired precision/recall
  - Monitor task status for long-running operations
  - Use conversation options for dialogue-heavy content
  - Combine visual and text search for best results

## Error Handling

All responses are wrapped in a `data` key:
```json
{
  "data": {
    // Actual response from Twelve Labs
  }
}
```

Task status values:
- **PENDING**: Task is queued
- **PROCESSING**: Task is in progress
- **COMPLETED**: Task completed successfully
- **FAILED**: Task failed

Common errors:
- **400**: Invalid request parameters
- **401**: Invalid API key
- **404**: Index or task not found
- **429**: Rate limit exceeded
- **500**: Processing failed