---
name: video-understand
description: Analyze and understand video content using Qwen3-VL vision model. Use when the user provides a video URL or a local video file path and wants to understand, describe, summarize, or answer questions about the video content. Triggers on requests like "What happens in this video?", "Describe this video", "Summarize the video at this URL", or any task requiring visual comprehension of video material.
---

# Video Understand

Analyze video content by sending a video URL to the Qwen3-VL-235B-A22B-Instruct model via OpenAI-compatible API. Supports scene description, content summarization, action recognition, Q&A, and any visual comprehension task. Accepts both video URLs and local file paths (local files are automatically uploaded to OSS).

## Quick Start

Run the bundled script with a video URL or local file and a prompt:

```bash
# Using a video URL
python3 {baseDir}/scripts/video_understand.py \
  --video-url "https://example.com/video.mp4" \
  --prompt "Describe what happens in this video"

# Using a local video file
python3 {baseDir}/scripts/video_understand.py \
  --video-file "/path/to/local/video.mp4" \
  --prompt "Describe what happens in this video"
```

The script reads API credentials from the environment or the openclaw config automatically.

## Usage

### Basic Video Description

```bash
uv run {baseDir}/scripts/video_understand.py \
  --video-url "https://example.com/video.mp4" \
  --prompt "详细描述这个视频的内容"
```

### Analyze a Local Video File

```bash
uv run {baseDir}/scripts/video_understand.py \
  --video-file "/home/node/.openclaw/workspace/my_video.mp4" \
  --prompt "详细描述这个视频的内容"
```

### Video Q&A

```bash
uv run {baseDir}/scripts/video_understand.py \
  --video-url "https://example.com/demo.mp4" \
  --prompt "How many people appear in the video and what are they doing?"
```

## Parameters

| Parameter      | Required         | Default | Description                                             |
| -------------- | ---------------- | ------- | ------------------------------------------------------- |
| `--video-url`  | Yes (either one) | —       | Public URL of the video to analyze                      |
| `--video-file` | Yes (either one) | —       | Local video file path (auto-uploaded to OSS to get URL) |
| `--prompt`     | Yes              | —       | Question or instruction                                 |
| `--base-url`   | No               | auto    | Override API base URL                                   |
| `--api-key`    | No               | auto    | Override API key                                        |

`--video-url` and `--video-file` are mutually exclusive — provide exactly one of them.

## Model Details

- **Model**: `Qwen3-VL-235B-A22B-Instruct` via provider `sophnet`
- **API**: OpenAI-compatible completions endpoint
- **Input**: Video URL + text prompt in multimodal message format
- **Context window**: 128,000 tokens
- **Max output**: 8,192 tokens

## Notes

- When using `--video-url`, the video must be accessible via a public URL.
- When using `--video-file`, the file will be uploaded to OSS and a signed URL will be generated automatically.
- Supported video formats depend on the model backend; common formats (mp4, webm, mov) are generally supported.
- The script auto-detects credentials from `~/.openclaw/openclaw.json`. Override with `--base-url` and `--api-key` if needed.
