| Item | Value |
|---|---|
| Base URL | https://api.twelvelabs.io/v1.3 |
| Analysis Request (async) | POST /analyze/tasks |
| Result Retrieval | GET /analyze/tasks/{task_id} (status ready (polling)) |
| Authentication | x-api-key: <API_KEY> |
| Model | pegasus1.5 |
| Analysis Mode | analysis_mode: "time_based_metadata" |
| Official Docs | docs.twelvelabs.io |
The analysis result is returned as a JSON string in result.data of the task. Parse it once more on the client to obtain the response structure below.
Define the items to extract using segment_definitions. Each definition consists of a segmentation instruction (description) and a list of extraction fields (fields), which can be freely written in natural language. The payload below is a representative request (3 layers: shot boundaries / soccer events / broadcast structure).
The full description text (including per-field instructions) is included verbatim in the file downloaded via the button above.
The response groups segments under three layer keys (shot_boundary, soccer_event, broadcast_structure). Each segment contains start_time / end_time (in seconds) and a metadata object with the fields defined in the request.
{
"soccer_event": [
{
"start_time": 2510,
"end_time": 2534,
"metadata": {
"event_type": "GOAL",
"playback_status": "LIVE_GAMEPLAY",
"match_phase": "FIRST_HALF",
"highlight_score": 9,
"score": "1-0",
"description": "A forward meets a free-kick delivery at the top of the box and finishes low past the diving goalkeeper for the opening goal.",
"player_names": []
}
}
]
}
| Layer (key) | Key Fields |
|---|---|
| shot_boundary | shot_type, description, main_actions[], emotional_elements, player_names[] |
| soccer_event | event_type, playback_status(LIVE/REPLAY), match_phase, highlight_score, score, description, player_names[] |
| broadcast_structure | segment_type, description, player_names[], emotional_state |
All three layers (shot_boundary, soccer_event, broadcast_structure) follow this same segment shape.
| Option | Configuration | Internet | Best For |
|---|---|---|---|
| A First | Pegasus standalone: extract event JSON, then text search | Cloud for extraction only | Live broadcast (offline) |
| B Next | Pegasus + LLM: JSON-based event chain analysis / natural language queries | LLM API (pre-computable) | Deep analysis (e.g. pre-goal buildup) |