Claude Video Token Costs by Detail Mode: A Complete Breakdown

The four detail modes in claude-video range from 0 image tokens (transcript mode) to approximately 22.8k image tokens (token-burner mode), with efficient (~9.8k) and balanced (~19.7k) falling in between.

The claude-video project provides a /watch skill that extracts visual information from video URLs using a single detail dial to trade off speed, visual fidelity, and token consumption. This guide breaks down the estimated token cost for each mode based on the actual implementation in skills/watch/scripts/watch.py.

How Detail Modes Determine Token Costs

The token cost in claude-video is driven almost entirely by image tokens, calculated using Anthropic's formula: (width × height) ÷ 750. With the default 512px width, 720p frames resolve to 512 × 288px ≈ 197 tokens per frame. The --detail flag controls how many frames get extracted and sent to Claude.

Token Cost Comparison Table

Mode	Extraction Engine	Frame Cap	Typical Time	Estimated Image Tokens
transcript	No frames (captions/Whisper only)	0	~4.5s	0 (≈ 26.6k text tokens)
efficient	Fast key-frame pass (ffmpeg -skip_frame nokey)	50	~0.5s	≈ 9.8k
balanced	Scene-change detection with fallback	100	~20.9s	≈ 19.7k
token-burner	Scene-change detection, uncapped	uncapped*	~21.0s	≈ 22.8k

*Uncapped mode extracted 116 frames in a 49-minute test video.

Detailed Mode Breakdown

Transcript Mode: Zero Image Tokens

transcript mode skips frame extraction entirely, relying solely on captions or Whisper-generated transcripts. This yields the lowest possible token cost for video analysis—zero image tokens—at the expense of all visual information. The ~26.6k text tokens come from the transcript itself.

Use this mode when:

• Visual content is irrelevant (e.g., lecture audio, podcast video)
• Token budget is severely constrained
• Speed is the absolute priority

# Transcript-only (cheapest)

/watch https://youtu.be/example --detail transcript

Efficient Mode: ~9.8k Image Tokens

efficient mode uses ffmpeg -skip_frame nokey to grab up to 50 keyframes in approximately half a second. This extracts only designated keyframes—typically scene cuts or significant motion changes—providing minimal visual coverage at minimal cost.

The token estimate assumes 50 frames × 197 tokens ≈ 9,850 image tokens.

Use this mode when:

• Speed is critical (sub-second extraction)
• You need basic visual context without fine detail
• Processing many videos in batch

# Fast key-frame mode (~50 frames)

watch https://youtu.be/example --detail efficient

Balanced Mode: ~19.7k Image Tokens (Default)

balanced mode runs scene-change detection with a hard cap of 100 frames, falling back to uniform sampling if scene detection fails. At ~20.9 seconds extraction time, this is the default mode offering reasonable coverage without excessive token burn.

The token estimate assumes 100 frames × 197 tokens ≈ 19,700 image tokens.

Use this mode when:

• You need comprehensive visual understanding
• Token budget allows moderate image token consumption
• No specific constraints on speed or cost

# Balanced scene-aware mode (default, ~100 frames)

watch https://youtu.be/example --detail balanced

Token-Burner Mode: ~22.8k+ Image Tokens

token-burner mode runs scene-change detection with no frame cap, keeping every detected scene change. In testing, this extracted 116 frames from a 49-minute video for approximately 22.8k image tokens.

Actual costs vary significantly with video length and scene complexity. Long videos with frequent cuts can push this much higher.

Use this mode when:

• Maximum visual fidelity is required
• Token budget is not a constraint
• Analyzing short, visually dense content

# Full uncapped mode (most tokens)

watch https://youtu.be/example --detail token-burner

Overriding Frame Caps Manually

Regardless of detail mode, you can enforce a hard limit with --max-frames. This caps extraction even in token-burner mode:

# Limit to 40 frames regardless of mode

watch https://youtu.be/example --detail balanced --max-frames 40

This override is processed in skills/watch/scripts/watch.py after the detail mode determines the base extraction strategy.

Implementation Reference

The token-budget logic lives in three key files:

• skills/watch/SKILL.md — Defines the skill contract and documents the detail dial's token implications
• skills/watch/scripts/watch.py — Parses --detail, orchestrates ffmpeg extraction, and reports frames for Claude to Read
• README.md — Contains measured frame budgets and token estimates for each mode

The extraction pipeline in watch.py branches based on the parsed --detail argument, selecting between:

• No extraction (transcript)
• Fast key-frame extraction (efficient)
• Scene-detection with explicit caps (balanced) or without (token-burner)

Summary

• Token costs scale linearly with extracted frames at ~197 tokens per 512×288 frame
• transcript mode eliminates image tokens entirely (~26.6k text tokens only)
• efficient mode costs ~9.8k image tokens for 50 keyframes in <1 second
• balanced mode costs ~19.7k image tokens for 100 scene-aware frames (default)
• token-burner mode has uncapped costs starting at ~22.8k image tokens
• Use --max-frames to hard-cap any mode's token consumption

Frequently Asked Questions

How does claude-video calculate image token costs?

Claude-video uses Anthropic's documented formula: (width × height) ÷ 750. With the default 512px width and 720p frames (512 × 288px), this yields approximately 197 tokens per frame. Multiply by the number of extracted frames determined by your --detail mode to estimate total image token cost.

Can I reduce token costs without using transcript mode?

Yes. Use --max-frames to override any mode's frame cap, or select efficient mode for up to 50 keyframes at ~9.8k tokens. You can also combine balanced mode with a lower --max-frames value to stay well under the default 100-frame, ~19.7k token budget.

Why does token-burner mode vary in cost?

token-burner mode has no frame cap, so costs depend entirely on video length and scene density. A 49-minute test video generated 116 frames (~22.8k tokens), but a two-hour film with frequent cuts could extract 300+ frames. Only use this mode when visual completeness outweighs token predictability.

Where is the detail mode logic implemented?

The extraction pipeline is implemented in skills/watch/scripts/watch.py, which parses the --detail argument and invokes the appropriate ffmpeg command. The token budgeting documentation and measured performance tables live in README.md, while skills/watch/SKILL.md defines the skill contract and dial semantics.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}