Introduction to model fine-tuning

Images

Formula: Image Tokens = h_bar * w_bar / token_pixels + 2

• h_bar, w_bar: The height and width of the scaled image. Before processing an image, the model performs pre-processing to scale it down to a specific pixel limit. This limit depends on the values of the max_pixels and vl_high_resolution_images parameters. For more information, see Process high-resolution images.

• token_pixels: The pixel value corresponding to each visual token. This varies by model:

  • qwen3.7-series, qwen3.6-series, qwen3.5-series, Qwen3-VL, qwen-vl-max, and qwen-vl-plus: Each token corresponds to 32x32 pixels.

  • QVQ and other Qwen2.5-VL models: Each token corresponds to 28x28 pixels.

The following code demonstrates the approximate image scaling logic used by the model. Use it to estimate the tokens for an image. For actual billing, refer to the API response.

import math
from PIL import Image  # pip install Pillow

def smart_size(image_path, max_pixels, vl_high_resolution_images):
    """Calculates the scaled dimensions of an image based on model parameters to estimate image tokens."""
    image = Image.open(image_path)
    height, width = image.height, image.width

    # The scaling factor is 32 for models such as Qwen3.6, Qwen3.5, and Qwen3-VL. For other models, it is 28.
    factor = 32
    h_bar = round(height / factor) * factor
    w_bar = round(width / factor) * factor

    # Token lower limit: 4 tokens
    min_pixels = 4 * factor * factor

    # If vl_high_resolution_images=True, the token upper limit is fixed at 16384, and max_pixels is ignored.
    if vl_high_resolution_images:
        max_pixels = 16384 * factor * factor

    # Constrains the total number of pixels to the range [min_pixels, max_pixels].
    if h_bar * w_bar > max_pixels:
        beta = math.sqrt((height * width) / max_pixels)
        h_bar = math.floor(height / beta / factor) * factor
        w_bar = math.floor(width / beta / factor) * factor
    elif h_bar * w_bar < min_pixels:
        beta = math.sqrt(min_pixels / (height * width))
        h_bar = math.ceil(height * beta / factor) * factor
        w_bar = math.ceil(width * beta / factor) * factor

    return h_bar, w_bar

if __name__ == "__main__":
    # Note: The values of max_pixels and vl_high_resolution_images must match the parameters passed when calling the model.
    h_bar, w_bar = smart_size("xxx/test.jpg", max_pixels=2560 * 32 * 32, vl_high_resolution_images=False)
    print(f"Scaled image dimensions: Height {h_bar}, Width {w_bar}")

    # Each image includes one <vision_bos> and one <vision_eos> token.
    token = int(h_bar * w_bar / (32 * 32)) + 2
    print(f"Number of image tokens: {token}")

Videos

• Video files:

  When processing a video file, the model first extracts frames and then calculates the total number of tokens for all video frames. Because this calculation is complex, you can use the following code to estimate the total token consumption for a video by providing its path:

  # Before use, install: pip install opencv-python
  import math
  import os
  import logging
  import cv2
  
  logger = logging.getLogger(__name__)
  
  FRAME_FACTOR = 2
  
  # For models such as Qwen3.6, Qwen3.5, Qwen3-VL, qwen-vl-max-0813, qwen-vl-plus-0815, and qwen-vl-plus-0710, the image scaling factor is 32.
  IMAGE_FACTOR = 32
  
  # For other models, the image scaling factor is 28.
  # IMAGE_FACTOR = 28
  
  # Maximum aspect ratio for video frames
  MAX_RATIO = 200
  # Pixel lower limit for video frames
  VIDEO_MIN_PIXELS = 4 * 32 * 32
  # Pixel upper limit for video frames. For the Qwen3-VL-Plus model, VIDEO_MAX_PIXELS is 640 * 32 * 32. For other models, it is 768 * 32 * 32.
  VIDEO_MAX_PIXELS = 640 * 32 * 32
  
  # If the user does not pass the FPS parameter, the default value is used for fps.
  FPS = 2.0
  # Minimum number of extracted frames
  FPS_MIN_FRAMES = 4
  # Maximum number of extracted frames (set based on the selected model)
  FPS_MAX_FRAMES = 2000
  
  # Maximum pixel value for video input. For the Qwen3-VL-Plus model, set VIDEO_TOTAL_PIXELS to 131072 * 32 * 32. For other models, set it to 65536 * 32 * 32.
  VIDEO_TOTAL_PIXELS = int(float(os.environ.get('VIDEO_MAX_PIXELS', 131072 * 32 * 32)))
  
  def round_by_factor(number: int, factor: int) -> int:
      """Returns the integer closest to 'number' that is divisible by 'factor'."""
      return round(number / factor) * factor
  
  def ceil_by_factor(number: int, factor: int) -> int:
      """Returns the smallest integer that is greater than or equal to 'number' and divisible by 'factor'."""
      return math.ceil(number / factor) * factor
  
  def floor_by_factor(number: int, factor: int) -> int:
      """Returns the largest integer that is less than or equal to 'number' and divisible by 'factor'."""
      return math.floor(number / factor) * factor
  
  def extract_vision_info(conversations):
      vision_infos = []
      if isinstance(conversations[0], dict):
          conversations = [conversations]
      for conversation in conversations:
          for message in conversation:
              if isinstance(message["content"], list):
                  for ele in message["content"]:
                      if (
                          "image" in ele
                          or "image_url" in ele
                          or "video" in ele
                          or ele.get("type","") in ("image", "image_url", "video")
                      ):
                          vision_infos.append(ele)
      return vision_infos
  
  def smart_nframes(ele,total_frames,video_fps):
      """Calculates the number of extracted video frames.
  
      Args:
          ele (dict): A dictionary containing the video configuration.
              - fps: Controls the number of input frames extracted for the model.
          total_frames (int): The original total number of frames in the video.
          video_fps (int | float): The original frame rate of the video.
  
      Raises:
          An error is reported if nframes is not within the interval [FRAME_FACTOR, total_frames].
  
      Returns:
          The number of video frames for model input.
      """
      assert not ("fps" in ele and "nframes" in ele), "Only accept either `fps` or `nframes`"
      fps = ele.get("fps", FPS)
      min_frames = ceil_by_factor(ele.get("min_frames", FPS_MIN_FRAMES), FRAME_FACTOR)
      max_frames = floor_by_factor(ele.get("max_frames", min(FPS_MAX_FRAMES, total_frames)), FRAME_FACTOR)
      duration = total_frames / video_fps if video_fps != 0 else 0
      if duration-int(duration)>(1/fps):
          total_frames = math.ceil(duration * video_fps)
      else:
          total_frames = math.ceil(int(duration)*video_fps)
      nframes = total_frames / video_fps * fps
      if nframes > total_frames:
          logger.warning(f"smart_nframes: nframes[{nframes}] > total_frames[{total_frames}]")
      nframes = int(min(min(max(nframes, min_frames), max_frames), total_frames))
      if not (FRAME_FACTOR <= nframes and nframes <= total_frames):
          raise ValueError(f"nframes should in interval [{FRAME_FACTOR}, {total_frames}], but got {nframes}.")
  
      return nframes
  
  def get_video(video_path):
      # Get video information
      cap = cv2.VideoCapture(video_path)
  
      frame_width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
      # Get video height
      frame_height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
      total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
  
      video_fps = cap.get(cv2.CAP_PROP_FPS)
      return frame_height, frame_width, total_frames, video_fps
  
  def smart_resize(ele, path, factor=IMAGE_FACTOR):
      # Get the original width and height of the video
      height, width, total_frames, video_fps = get_video(path)
      # Token lower limit for video frames
      min_pixels = VIDEO_MIN_PIXELS
      total_pixels = VIDEO_TOTAL_PIXELS
      # Number of extracted video frames
      nframes = smart_nframes(ele, total_frames, video_fps)
      max_pixels = max(min(VIDEO_MAX_PIXELS, total_pixels / nframes * FRAME_FACTOR),int(min_pixels * 1.05))
  
      # The aspect ratio of the video should not exceed 200:1 or 1:200.
      if max(height, width) / min(height, width) > MAX_RATIO:
          raise ValueError(
              f"absolute aspect ratio must be smaller than {MAX_RATIO}, got {max(height, width) / min(height, width)}"
          )
  
      h_bar = max(factor, round_by_factor(height, factor))
      w_bar = max(factor, round_by_factor(width, factor))
      if h_bar * w_bar > max_pixels:
          beta = math.sqrt((height * width) / max_pixels)
          h_bar = floor_by_factor(height / beta, factor)
          w_bar = floor_by_factor(width / beta, factor)
      elif h_bar * w_bar < min_pixels:
          beta = math.sqrt(min_pixels / (height * width))
          h_bar = ceil_by_factor(height * beta, factor)
          w_bar = ceil_by_factor(width * beta, factor)
      return h_bar, w_bar
  
  def token_calculate(video_path, fps):
      # Pass the video path and the fps frame extraction parameter.
      messages = [{"content": [{"video": video_path, "fps": fps}]}]
      vision_infos = extract_vision_info(messages)[0]
  
      resized_height, resized_width = smart_resize(vision_infos, video_path)
  
      height, width, total_frames, video_fps = get_video(video_path)
      num_frames = smart_nframes(vision_infos, total_frames, video_fps)
      print(f"Original video dimensions: {height}*{width}, Model input dimensions: {resized_height}*{resized_width}, Total video frames: {total_frames}, Total frames extracted when fps is {fps}: {num_frames}", end=", ")
      video_token = int(math.ceil(num_frames / 2) * resized_height / 32 * resized_width / 32)
      video_token += 2   # The system automatically adds <|vision_bos|> and <|vision_eos|> visual markers (1 token each).
      return video_token
  
  video_token = token_calculate("xxx/test.mp4", 1)
  print("Video tokens:", video_token)

• Image list:

  When a video is passed as a list of images, it means that frame extraction has already been performed. Use the following code to calculate the token consumption by providing the path and number of images:

  # Before use, install: pip install Pillow
  import math
  import os
  import logging
  from typing import Tuple
  from PIL import Image
  
  logger = logging.getLogger(__name__)
  
  # ==================== Constant Definitions ====================
  FRAME_FACTOR = 2
  # For models such as Qwen3-VL, qwen-vl-max-0813, qwen-vl-plus-0815, and qwen-vl-plus-0710, the scaling factor is 32.
  IMAGE_FACTOR = 32
  
  # For other models, the scaling factor is 28.
  # IMAGE_FACTOR = 28
  
  # Constants for token calculation
  TOKEN_DIVISOR = 32  # Divisor for token calculation
  VISION_SPECIAL_TOKENS = 2  # <|vision_bos|> and <|vision_eos|> markers
  
  # Maximum aspect ratio for video frames
  MAX_RATIO = 200
  # Pixel lower limit for video frames
  VIDEO_MIN_PIXELS = 4 * 32 * 32
  # Pixel upper limit for video frames. For the Qwen3-VL-Plus model, VIDEO_MAX_PIXELS is 640 * 32 * 32. For other models, it is 768 * 32 * 32.
  VIDEO_MAX_PIXELS = 640 * 32 * 32
  
  # Maximum pixel value for video input. For the Qwen3-VL-Plus model, set VIDEO_TOTAL_PIXELS to 131072 * 32 * 32. For other models, set it to 65536 * 32 * 32.
  VIDEO_TOTAL_PIXELS = int(float(os.environ.get('VIDEO_MAX_PIXELS', 131072 * 32 * 32)))
  
  def round_by_factor(number: int, factor: int) -> int:
      """Returns the integer closest to 'number' that is divisible by 'factor'."""
      return round(number / factor) * factor
  
  def ceil_by_factor(number: int, factor: int) -> int:
      """Returns the smallest integer that is greater than or equal to 'number' and divisible by 'factor'."""
      return math.ceil(number / factor) * factor
  
  def floor_by_factor(number: int, factor: int) -> int:
      """Returns the largest integer that is less than or equal to 'number' and divisible by 'factor'."""
      return math.floor(number / factor) * factor
  
  def get_image_size(image_path: str) -> Tuple[int, int]:
      if not os.path.exists(image_path):
          raise FileNotFoundError(f"Image file not found: {image_path}")
  
      try:
          image = Image.open(image_path)
          height = image.height
          width = image.width
          image.close()  # Close the file promptly
          return height, width
      except Exception as e:
          raise ValueError(f"Cannot read image file {image_path}: {str(e)}")
  
  def smart_resize(height: int, width: int, nframes: int, factor: int = IMAGE_FACTOR) -> Tuple[int, int]:
      """
      Calculates the scaled dimensions of an image
  
      Args:
          height: Original image height
          width: Original image width
          nframes: Number of video frames
          factor: Scaling factor, defaults to IMAGE_FACTOR
  
      Returns:
          (resized_height, resized_width) The scaled height and width
  
      Raises:
          ValueError: Aspect ratio exceeds the limit
      """
      # Token lower limit for video frames
      min_pixels = VIDEO_MIN_PIXELS
      total_pixels = VIDEO_TOTAL_PIXELS
      # Number of extracted video frames
      max_pixels = max(min(VIDEO_MAX_PIXELS, total_pixels / nframes * FRAME_FACTOR), int(min_pixels * 1.05))
  
      # The aspect ratio of the video should not exceed 200:1 or 1:200.
      aspect_ratio = max(height, width) / min(height, width)
      if aspect_ratio > MAX_RATIO:
          raise ValueError(
              f"Image aspect ratio must be less than {MAX_RATIO}:1, but is currently {aspect_ratio:.2f}:1"
          )
  
      h_bar = max(factor, round_by_factor(height, factor))
      w_bar = max(factor, round_by_factor(width, factor))
      if h_bar * w_bar > max_pixels:
          beta = math.sqrt((height * width) / max_pixels)
          h_bar = floor_by_factor(height / beta, factor)
          w_bar = floor_by_factor(width / beta, factor)
      elif h_bar * w_bar < min_pixels:
          beta = math.sqrt(min_pixels / (height * width))
          h_bar = ceil_by_factor(height * beta, factor)
          w_bar = ceil_by_factor(width * beta, factor)
      return h_bar, w_bar
  
  def calculate_video_tokens(image_path: str, nframes: int = 1, factor: int = IMAGE_FACTOR, verbose: bool = True) -> int:
      """
  
      Args:
          image_path: Path to the video frame file
          nframes: Number of video frames,
          factor: Scaling factor, defaults to IMAGE_FACTOR
          verbose: Whether to print detailed information
  
      Returns:
          The number of tokens consumed
  
      Raises:
          FileNotFoundError: The file does not exist
          ValueError: The file format is invalid or the aspect ratio exceeds the limit
      """
      # Get the original image dimensions (read only once)
      height, width = get_image_size(image_path)
  
      # Calculate the scaled dimensions
      resized_height, resized_width = smart_resize(height, width, nframes, factor)
  
      # Calculate the number of tokens
      # Formula: ceil(nframes/2) * (height/TOKEN_DIVISOR) * (width/TOKEN_DIVISOR) + VISION_SPECIAL_TOKENS
      video_token = int(
          math.ceil(nframes / 2) *
          (resized_height / TOKEN_DIVISOR) *
          (resized_width / TOKEN_DIVISOR)
      )
      # Add visual marker tokens (<|vision_bos|> and <|vision_eos|>)
      video_token += VISION_SPECIAL_TOKENS
  
      if verbose:
          print(f"Original video frame dimensions: {height}x{width}, Model input dimensions: {resized_height}x{resized_width}, ", end="")
  
      return video_token
  
  if __name__ == "__main__":
      try:
          video_token = calculate_video_tokens("xxx/test.jpg", nframes=30)
          print(f"Video tokens: {video_token}\n")
      except Exception as e:
          print(f"Error: {str(e)}\n")