How Token Costs Scale with Frame Count and Resolution in Claude Video

Token costs in the /watch skill scale linearly with frame count and quadratically with resolution, calculated as (width × height) ÷ 750 per frame, with extraction caps ranging from 50 to unlimited frames depending on the detail mode.

The bradautomates/claude-video repository provides a Claude Code skill that analyzes video content by extracting JPEG frames and converting them into image tokens. Understanding how token cost scales with frame count and resolution is critical for budgeting API usage when processing video content through the /watch command.

The Image Token Formula

The token cost per frame follows Anthropic's standard image token calculation: (width × height) ÷ 750. This formula, documented in the repository's README, determines exactly how many tokens each extracted frame consumes when sent to the Claude API.

Default Resolution Token Costs

At the default width of 512 px, extracted frames typically render at 512 × 288 px (assuming a 720p source aspect ratio). Applying the formula results in approximately 197 image tokens per frame: (512 × 288) ÷ 750 ≈ 197. This default configuration provides a balance between visual detail and token economy.

High Resolution Impact

Increasing the --resolution flag to 1024 px roughly quadruples the token count per frame to approximately 788 tokens. Since the formula scales linearly with total pixel count, doubling both width and height increases the divisor result by 4×. As noted in the README, this scaling makes high-resolution processing significantly more expensive for long videos.

Frame Count Scaling and Limits

Token costs grow linearly with the number of frames processed: total image tokens = frames × tokens-per-frame. However, the skill imposes hard caps based on your chosen analysis mode.

Detail Mode Frame Caps

The /watch skill caps frame extraction according to the frame_cap dictionary defined in skills/watch/scripts/config.py:

• efficient → max 50 frames
• balanced → max 100 frames (default)
• token-burner → uncapped (processes all frames)
• transcript → 0 frames (audio analysis only)

These caps prevent accidental runaway costs while allowing flexibility for different use cases.

Calculating Total Costs

For example, processing 80 frames at the default 512 px width consumes approximately 15,800 image tokens (80 × 197). The accompanying transcript text adds only a few thousand tokens even for 10-minute videos, making image tokens the dominant cost factor in video analysis.

Combined Scaling in Practice

When both frame count and resolution increase, costs scale as (frame count) × (width × height ÷ 750). This means a 100-frame analysis at 1024 px resolution (~78,800 tokens) costs roughly 16× more than the same duration at 512 px with efficient mode 50-frame cap (~9,850 tokens).

The watch.py script orchestrates this extraction and prints summary warnings about frame size and anticipated token usage before sending requests to the API.

Command Examples for Different Cost Profiles

# Balanced mode: up to 100 frames at 512px (~19,700 tokens max)

python3 "$SKILL_DIR/scripts/watch.py" "https://youtu.be/example" --detail balanced

# Efficient mode: 50 frames at 512px (~9,850 tokens)

python3 "$SKILL_DIR/scripts/watch.py" "https://youtu.be/example" --detail efficient

# Token-burner: uncapped frames (cost scales with video length)

python3 "$SKILL_DIR/scripts/watch.py" "https://youtu.be/example" --detail token-burner

# High resolution: quadruples per-frame cost (~78,800 tokens for 100 frames)

python3 "$SKILL_DIR/scripts/watch.py" "https://youtu.be/example" --detail balanced --resolution 1024

# Manual frame limit: overrides mode caps to fine-tune costs

python3 "$SKILL_DIR/scripts/watch.py" "https://youtu.be/example" --detail token-burner --max-frames 150

Summary

• Token costs follow (width × height) ÷ 750 per frame according to Anthropic's image token formula as implemented in bradautomates/claude-video
• Default 512 px width generates ~197 tokens per frame; 1024 px generates ~788 tokens (4× increase)
• Frame counts are capped by detail mode in skills/watch/scripts/config.py: 50 (efficient), 100 (balanced), or uncapped (token-burner)
• Total cost scales as frame count × resolution tokens, making high-resolution, uncapped processing exponentially more expensive
• Transcript-only mode bypasses image tokens entirely for minimal API costs

Frequently Asked Questions

How does the token cost per frame calculate in Claude Video?

Each frame costs (width × height) ÷ 750 tokens based on Anthropic's image token formula. At the default 512×288 pixel extraction size used by the /watch skill, this equals approximately 197 tokens per frame according to the README documentation.

What happens to token costs when I double the video resolution?

Doubling the resolution from 512 px to 1024 px roughly quadruples the token cost per frame because both width and height double. Since the token formula scales with total pixel count (area), a 1024 px frame generates approximately 788 tokens compared to 197 at the default width.

Which detail mode should I use to minimize token costs?

Use efficient mode to cap extraction at 50 frames, or transcript mode to process only audio with no image frames. The default balanced mode allows up to 100 frames while token-burner removes caps entirely for maximum visual analysis at higher cost.

Can I exceed the frame caps set by detail modes?

Yes. You can override the frame_cap settings defined in skills/watch/scripts/config.py by using the --max-frames flag. However, this increases token costs linearly with each additional frame extracted, so monitor usage carefully when analyzing long videos.

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