# Twelve Labs Integration via LowCodeAPI

**Last Updated**: January 27, 2025

## Overview
Video understanding and search platform with AI-powered video indexing and search capabilities

**Categories:**
- {'id': 'video-analysis', 'name': 'Video Analysis AI'}

## Base Endpoint
https://api.lowcodeapi.com/twelvelabs

**Important**: Always include the provider name in the URL path after `api.lowcodeapi.com/`

## Authentication
**Type:** TOKEN

**Official Documentation:** https://docs.twelvelabs.io/reference/api-reference

## URL Format (Important)

LowCodeAPI supports two URL formats. **Always try the New Format first**, then fall back to Old Format if needed.

### New Format (Priority)
- Path parameters stay in the URL path
- Do NOT include path parameters as query parameters
- Example: `https://api.lowcodeapi.com/{provider}/resource/{id}?api_token=XXX`

### Old Format (Fallback)
- Path parameters become query parameters
- Example: `https://api.lowcodeapi.com/{provider}/resource/id?id={id}&api_token=XXX`

### Decision Flow for AI Agents
1. Always use **New Format** first - keep path parameters in the URL path
2. If you get a 404 or error, try **Old Format** with sanitized path
3. Log which format worked for future requests to this provider

## API Categories

## Common Endpoints

### Make any-to-video search requests

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

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/search-v22?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/search-v22?api_token=YOUR_API_TOKEN

**Request Body:**

| Field | Type | Description |
|-------|------|-------------|
| adjust_confidence_level | number |  |
| conversation_option | string |  |
| filter | string |  |
| group_by | string |  |
| index_id | string |  |
| operator | string |  |
| page_limit | number |  |
| query_media_file | array |  |
| query_media_type | string |  |
| query_media_url | string |  |
| query_text | string |  |
| search_options | array |  |
| sort_option | string |  |
| threshold | string |  |

**Example Request (New Format):**

```bash
curl -X POST 'https://api.lowcodeapi.com/twelvelabs/v1.2/search-v22?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/perform-any-to-video-search-requests

### Retrieve a specific page of search results

**Method:** GET
**LowCodeAPI Path:** /v1.2/search-v2/{page-token}

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/search-v2/{page-token}?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/search-v2/page-token?page-token={page-token}&api_token=YOUR_API_TOKEN

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| page-token | string |  |

**Example Request (New Format):**

```bash
curl -X GET 'https://api.lowcodeapi.com/twelvelabs/v1.2/search-v2/{page-token}?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/any-to-video-retrieve-specific-page

### Classify a set of videos

**Method:** POST
**LowCodeAPI Path:** /v1.2/classify

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/classify?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/classify?api_token=YOUR_API_TOKEN

**Request Body:**

| Field | Type | Description |
|-------|------|-------------|
| classes | array |  |
| conversation_option | string |  |
| include_clips | boolean |  |
| options | array |  |
| page_limit | number |  |
| show_detailed_score | boolean |  |
| threshold | object |  |
| video_ids | array |  |

**Example Request (New Format):**

```bash
curl -X POST 'https://api.lowcodeapi.com/twelvelabs/v1.2/classify?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/classify-videos

### Classify all the videos in an index

**Method:** POST
**LowCodeAPI Path:** /v1.2/classify/bulk

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/classify/bulk?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/classify/bulk?api_token=YOUR_API_TOKEN

**Request Body:**

| Field | Type | Description |
|-------|------|-------------|
| classes | array |  |
| conversation_option | string |  |
| include_clips | boolean |  |
| index_id | string |  |
| options | array |  |
| page_limit | number |  |
| show_detailed_score | boolean |  |
| threshold | object |  |

**Example Request (New Format):**

```bash
curl -X POST 'https://api.lowcodeapi.com/twelvelabs/v1.2/classify/bulk?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/classify-bulk

### Retrieve a specific page of results

**Method:** GET
**LowCodeAPI Path:** /v1.2/classify/{page_token}

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/classify/{page_token}?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/classify/page_token?page-token={page-token}&api_token=YOUR_API_TOKEN

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| page-token | string |  |

**Example Request (New Format):**

```bash
curl -X GET 'https://api.lowcodeapi.com/twelvelabs/v1.2/classify/{page_token}?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/classify-retrieve-specific-page

### List engines

**Method:** GET
**LowCodeAPI Path:** /v1.2/engines

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/engines?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/engines?api_token=YOUR_API_TOKEN

**Example Request (New Format):**

```bash
curl -X GET 'https://api.lowcodeapi.com/twelvelabs/v1.2/engines?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/list-engines

### Retrieve an engine

**Method:** GET
**LowCodeAPI Path:** /v1.2/engines/{engine-id}

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/engines/{engine-id}?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/engines/engine-id?api_token=YOUR_API_TOKEN

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| engine-id | string |  |

**Example Request (New Format):**

```bash
curl -X GET 'https://api.lowcodeapi.com/twelvelabs/v1.2/engines/{engine-id}?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/retrieve-engine

### Titles, topics, or hashtags

**Method:** POST
**LowCodeAPI Path:** /v1.2/gist

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/gist?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/gist?api_token=YOUR_API_TOKEN

**Request Body:**

| Field | Type | Description |
|-------|------|-------------|
| types | array |  |
| video_id | string |  |

**Example Request (New Format):**

```bash
curl -X POST 'https://api.lowcodeapi.com/twelvelabs/v1.2/gist?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/generate-gist

### Summaries, chapters, or highlights

**Method:** POST
**LowCodeAPI Path:** /v1.2/summarize

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/summarize?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/summarize?api_token=YOUR_API_TOKEN

**Request Body:**

| Field | Type | Description |
|-------|------|-------------|
| prompt | string |  |
| temperature | number |  |
| types | string |  |
| video_id | string |  |

**Example Request (New Format):**

```bash
curl -X POST 'https://api.lowcodeapi.com/twelvelabs/v1.2/summarize?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/summarize

### Open-ended texts

**Method:** POST
**LowCodeAPI Path:** /v1.2/generate

**New Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/generate?api_token=YOUR_API_TOKEN

**Old Format URL:**
https://api.lowcodeapi.com/twelvelabs/v1.2/generate?api_token=YOUR_API_TOKEN

**Request Body:**

| Field | Type | Description |
|-------|------|-------------|
| prompt | string |  |
| temperature | number |  |
| video_id | string |  |

**Example Request (New Format):**

```bash
curl -X POST 'https://api.lowcodeapi.com/twelvelabs/v1.2/generate?api_token=YOUR_API_TOKEN'
```

**Official Documentation:** https://docs.twelvelabs.io/reference/generate-text-representation


## Usage Examples

### Example 1: Basic API Request (New Format)

Making a simple GET request to retrieve resources:

```bash
# Get a list of resources - no path parameters needed
curl -X GET "https://api.lowcodeapi.com/twelvelabs/endpoint?api_token=YOUR_API_TOKEN"
```

### Example 2: Request with Path Parameters (New Format)

Retrieving a specific resource using its ID:

```bash
# Get specific resource by ID - replace RESOURCE_ID with actual ID from previous response
curl -X GET "https://api.lowcodeapi.com/twelvelabs/endpoint/{RESOURCE_ID}?api_token=YOUR_API_TOKEN"
# Note: RESOURCE_ID typically comes from a previous list request or from the provider dashboard
```

### Example 3: POST Request with Body (New Format)

Creating a new resource:

```bash
# Create a new resource
curl -X POST "https://api.lowcodeapi.com/twelvelabs/endpoint?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field": "value", "another_field": "another_value"}'
```

## Error Handling

LowCodeAPI returns standard HTTP status codes. Common errors:

| Status Code | Description |
|-------------|-------------|
| 200 | Success - Request completed successfully |
| 400 | Bad Request - Invalid parameters or request body |
| 401 | Unauthorized - Invalid or missing API token |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Endpoint or resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - Provider API error |

All error responses include error details:

```json
{
  "data": {
    "error": {
      "message": "Error description",
      "code": "ERROR_CODE"
    }
  }
}
```

## Complete Endpoint Reference

| Endpoint | Method | Category |
|----------|--------|----------|
| Make any-to-video search requests | POST | Any-to-video search |
| Retrieve a specific page of search results | GET | Any-to-video search |
| Classify a set of videos | POST | Classify |
| Classify all the videos in an index | POST | Classify |
| Retrieve a specific page of results | GET | Classify |
| List engines | GET | Engines |
| Retrieve an engine | GET | Engines |
| Titles, topics, or hashtags | POST | Generate text from video |
| Summaries, chapters, or highlights | POST | Generate text from video |
| Open-ended texts | POST | Generate text from video |
| Create an index | POST | Indexes |
| List indexes | GET | Indexes |
| Retrieve an index | GET | Indexes |
| Update an index | PUT | Indexes |
| Delete an index | DELETE | Indexes |
| List videos | GET | Indexes/Videos |
| Retrieve video information | GET | Indexes/Videos |
| Update video information | PUT | Indexes/Videos |
| Delete video information | DELETE | Indexes/Videos |
| Retrieve a transcription | GET | Indexes/Videos |
| Retrieve text recognized in video (OCR) | GET | Indexes/Videos |
| Extract logos | GET | Indexes/Videos |
| Retrieve a thumbnail | GET | Indexes/Videos |
| Create a video indexing task | POST | Tasks |
| List video indexing tasks | GET | Tasks |
| Retrieve a video indexing task | GET | Tasks |
| Delete a video indexing task | DELETE | Tasks |
| Retrieve tasks by status | GET | Tasks |
| Upload videos from external providers | POST | Tasks |
| Make a cloud-to-cloud transfer | POST | Tasks/Transfers |
| Create text embeddings | POST | Text embeddings |
| Make a text-to-video search request | POST | Text-to-video search |
| Make a combined search request | POST | Text-to-video search |
| Retrieve a specific page of search results | GET | Text-to-video search |
| Retrieve a specific page of combined search result... | GET | Text-to-video search |
| Create a video embedding task | POST | Video embeddings |
| Retrieve the status of a video embedding task | GET | Video embeddings |
| Retrieve video embeddings | GET | Video embeddings |

## API Definition Endpoints

You can fetch the complete API specification for this provider:

**New Format (OpenAPI spec):**
```bash
curl 'https://backend.lowcodeapi.com/twelvelabs/openapi'
```

**Old Format (API definition):**
```bash
curl 'https://backend.lowcodeapi.com/twelvelabs/definition'
```

## Response Format

All responses are wrapped in a `data` key:

```json
{
  "data": {
    // Actual response from provider (object or array)
  }
}
```