Координаты и ограничивающие рамки

Claude может находить и помечать области изображения (например, возвращать ограничивающие рамки для таблиц, полей форм, элементов диаграмм или компонентов интерфейса). В этом руководстве описано, как Claude изменяет размер изображений перед их обработкой и как работать с пиксельными координатами, которые он возвращает, чтобы рамки и точки совпадали с вашим исходным изображением.

Это понадобится вам для конвейеров OCR, извлечения данных из форм, разбора диаграмм, определения положения элементов интерфейса и любой задачи, в которой вы выполняете действия над конкретной областью изображения. Об отправке изображений, поддерживаемых форматах и ограничениях разрешения для каждой модели см. раздел Зрение.

Координаты следуют стандартному соглашению для изображений: начало координат (0, 0) находится в верхнем левом углу изображения, x увеличивается вправо, а y — вниз. Координаты, которые возвращает Claude, — это позиции пикселей в изображении, которое видит Claude: вашем изображении после того, как Claude изменит его размер под нативное разрешение модели (см. Как Claude изменяет размер изображений и добавляет отступы). Чтобы получить координаты, которые можно использовать напрямую, либо заранее измените размер изображения, чтобы координаты один к одному соответствовали имеющемуся у вас изображению (см. Измените размер изображения перед загрузкой), либо пересчитайте координаты, которые возвращает Claude (см. Пересчёт координат, когда предварительное изменение размера невозможно).

Как Claude изменяет размер изображений и добавляет отступы

Claude находит наибольший размер с сохранением пропорций, удовлетворяющий обоим ограничениям модели для изображений:

1. Ограничение по стороне: ни одна сторона не превышает максимальную длину стороны (1568 px на стандартном уровне, 2576 px на уровне высокого разрешения).
2. Ограничение по визуальным токенам: стоимость изображения в токенах ⌈width / 28⌉ × ⌈height / 28⌉ не превышает бюджет визуальных токенов модели (1568 токенов на стандартном уровне, 4784 на уровне высокого разрешения).

О том, какие модели относятся к какому уровню, см. Разрешение и стоимость в токенах.

Почти для всех фотографий и снимков экрана итоговый размер определяется ограничением по визуальным токенам. Ограничение по стороне вступает в силу только для вытянутых изображений, таких как панорамы или высокие снимки экрана телефона. Вычисляйте размер с помощью эталонной реализации, а не масштабируйте вручную до длины стороны: снимок экрана 1920×1080 уменьшается до 1456×819, а не до 1568×882, и если исходить из ограничения по стороне, каждая координата окажется заметно смещённой от цели.

Ограничение по токенам также может вызвать изменение размера, когда ни одна сторона не превышает ограничение по стороне. Упущение этого — самая частая причина несовпадения координат. Например, страница A4, отсканированная с разрешением 130 DPI, имеет размер 1075×1520 пикселей: обе стороны меньше 1568 px, но она стоит 39 × 55 = 2145 визуальных токенов, поэтому Claude уменьшает её до 924×1307.

Затем Claude дополняет каждое изображение, изменённое или нет, отступами до следующего кратного 28 пикселям по нижнему и правому краям (в примере 924×1307 становится 924×1316). Отступы не содержат никакого содержимого: Claude воспринимает дополненное изображение, но содержимое страницы всегда занимает только изменённую область без отступов. Всегда нормализуйте или пересчитывайте по размерам после изменения размера, а не по размерам с отступами; деление на размеры с отступами слегка масштабирует каждую координату.

Измените размер изображения перед загрузкой

Самый надёжный подход — изменить размер изображения самостоятельно перед загрузкой, чтобы имеющееся у вас изображение было в точности тем, которое видит Claude, и координаты, возвращаемые Claude, не требовали преобразования.

Сначала проверьте, к какому уровню разрешения относится ваша модель (см. Разрешение и стоимость в токенах), и передайте соответствующие ограничения по стороне и токенам. Следующая эталонная реализация вычисляет точный размер, до которого Claude изменяет изображение:

import math


def count_image_tokens(width: int, height: int) -> int:
    """Visual tokens consumed by an image: one token per 28x28 pixel patch."""
    return math.ceil(width / 28) * math.ceil(height / 28)


def resized_size(
    width: int,
    height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[int, int]:
    """The size Claude resizes an image to before padding.

    Defaults are for the standard resolution tier. For high-resolution-tier
    models, use max_edge=2576 and max_tokens=4784. Returns (width, height).
    Images that already fit within the limits are returned unchanged.
    """

    def fits(w: int, h: int) -> bool:
        return (
            math.ceil(w / 28) * 28 <= max_edge
            and math.ceil(h / 28) * 28 <= max_edge
            and count_image_tokens(w, h) <= max_tokens
        )

    if fits(width, height):
        return (width, height)
    if height > width:
        resized_h, resized_w = resized_size(height, width, max_edge, max_tokens)
        return (resized_w, resized_h)

    # Бинарный поиск по длинной стороне: наибольший размер с сохранением пропорций,
    # который помещается.
    aspect_ratio = width / height
    lo, hi = 1, width  # lo always fits; hi never fits
    while lo + 1 < hi:
        mid = (lo + hi) // 2
        if fits(mid, max(round(mid / aspect_ratio), 1)):
            lo = mid
        else:
            hi = mid
    return (lo, max(round(lo / aspect_ratio), 1))


# Пример A4 из раздела «Как Claude изменяет размер и дополняет изображения»:
print(resized_size(1075, 1520))  # (924, 1307)

# Для изменения размера используйте вашу библиотеку изображений, например Pillow:
# image.resize(resized_size(*image.size))

1. Измените размер изображения до размеров, возвращённых вспомогательной функцией изменения размера. Если изображение уже укладывается в ограничения модели, функция возвращает его размеры без изменений, и изменение размера не требуется.
2. Отправьте изменённое изображение в API. Не добавляйте отступы самостоятельно. Claude сам добавляет отступы, и они не смещают начало координат.
3. В подсказке явно запросите пиксельные координаты. Например: «Верни точку нажатия для кнопки Submit в виде [x, y] в пиксельных координатах.»
4. Используйте возвращённые координаты напрямую с отправленным изображением. Если вам нужны нормализованные координаты, делите на размеры отправленного изображения, а не на размеры исходного изображения и не на размеры с отступами.

Превратите изменение размера в ошибку с помощью transformations

Предварительное изменение размера защищает ваши координаты лишь до тех пор, пока ваш конвейер продолжает выдавать правильные размеры. Новый источник изображений или переход на модель другого уровня разрешения могут незаметно вернуть изменение размера на стороне сервера. Чтобы превратить это незаметное расхождение в видимую ошибку, задайте необязательное поле transformations в блоке содержимого изображения в запросе Messages:

{
  "type": "image",
  "source": { "type": "base64", "media_type": "image/png", "data": "..." },
  "transformations": { "oversized_image": "error" }
}

Запрос, в котором помеченное изображение (любой блок, задающий "oversized_image": "error") было бы изменено в размере, отклоняется с ошибкой 400 invalid_request_error, в которой указаны размеры изображения и наибольшие подходящие размеры. Вызовет ли изображение отклонение, зависит от ограничений каждой модели, указанной в запросе: пример 1920×1080 ниже отклоняется моделью стандартного уровня, но укладывается в уровень высокого разрешения:

messages.0.content.0: image dimensions 1920x1080 exceed the maximum image size of a model named on this request and would be downsized to 1456x819; scale the image to at most 1456x819 or set the image's oversized_image setting to "downsize"

Измените размер до указанного целевого и отправьте повторно: целевой размер — это наибольший размер с пропорциями вашего изображения, который принимает каждая модель, указанная в запросе. Как помеченные изображения взаимодействуют с бета-функцией резервного переключения на стороне сервера, описано вместе с этой функцией; в любом режиме помеченное изображение никогда не передаётся в изменённом размере.

Настройка задаётся для каждого изображения отдельно. "oversized_image": "downsize" (значение по умолчанию, когда поле опущено) сохраняет автоматическое изменение размера, как описано на этой странице. Каждый блок изображения проверяется только по собственной настройке, поэтому в одном запросе можно сочетать изображения, размеры которых критически важны (снимок экрана, по которому вы будете нажимать), с изображениями, для которых изменение размера безвредно (логотип). Что эта настройка меняет и чего не меняет:

• Добавление отступов (которое никогда не отбрасывает содержимое), преобразование формата и исправление ориентации выполняются как обычно.
• Жёсткие ограничения (8000 px по длинной стороне и более строгое ограничение на изображение в запросах с множеством изображений) — это отдельные отклонения; эта настройка никогда не пропускает изображение мимо них.
• Изображения, переданные по URL или идентификатору файла, проверяются после получения их байтов; такие отклонения содержат то же сообщение без указания позиции в начале, поэтому они не указывают, какое изображение не прошло проверку; только встроенные изображения base64 называются в ошибке по позиции.
• Страницы PDF растеризуются на стороне сервера с размерами, которые вы не контролируете; блок document не принимает это поле (блок изображения, вложенный в содержимое документа, принимает его, как и любой другой).
• Помеченное изображение, размеры которого невозможно определить, отклоняется, а не пропускается: в таком отклонении сообщается, что исходные размеры изображения не удалось определить, а не приводится процитированное выше сообщение об изменении размера. Ни одно изображение, задающее "error", не попадает в модель в изменённом размере.

Эндпоинт Подсчёт токенов также учитывает transformations, отклоняя встроенное изображение точно так же, как это сделал бы Messages API, поэтому вы можете проверить, помещается ли встроенное изображение без изменения размера, ещё до запуска инференса. При подсчёте изображения, переданные по URL или идентификатору файла, отклоняются, а не загружаются, поэтому помеченное изображение из таких источников проверяется только при вызове Messages.

Пересчёт координат, когда предварительное изменение размера невозможно

Если вы не можете заранее изменить размер (например, когда изображение поступает из вышестоящей системы, которую вы не можете изменить), используйте вспомогательную функцию изменения размера из раздела Измените размер изображения перед загрузкой, чтобы восстановить размеры, которые видел Claude, а затем преобразуйте координаты, возвращённые Claude, в нормализованные координаты или обратно в координаты исходного изображения. Если изображение не выбирает вместо этого ошибку, Claude изменяет размер слишком больших изображений, а не отклоняет их, вплоть до ограничений запросов API. За пределами этих ограничений запрос вместо этого завершается ошибкой валидации. Передавайте ограничения уровня, соответствующие вызванной модели: ограничения неверного уровня восстанавливают неверные изменённые размеры и незаметно смещают каждую координату. Этот подход требует знания пиксельных размеров загруженного изображения, поэтому он не применим к загрузкам PDF.

Снимки экрана и увеличенные изображения, которые вы возвращаете наборам инструментов использования компьютера и использования браузера, являются исключением из автоматического изменения размера. API отклоняет изображение tool_result, превышающее ограничения модели, с ошибкой валидации вместо изменения его размера. Изменяйте размер таких изображений в своём приложении перед их возвратом, а затем масштабируйте координаты, возвращённые Claude, обратно к размерам вашего экрана.

# Эта функция вызывает resized_size из примера изменения размера на этой странице.
def to_relative_coordinates(
    x: float,
    y: float,
    original_width: int,
    original_height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[float, float]:
    """Map a pixel coordinate returned by Claude to relative coordinates in [0, 1].

    Pass the dimensions of the image you uploaded. For high-resolution-tier
    models, use max_edge=2576 and max_tokens=4784.
    """
    resized_w, resized_h = resized_size(
        original_width, original_height, max_edge, max_tokens
    )
    return (x / resized_w, y / resized_h)


# Угол таблицы, который Claude возвращает в (462, 653.5) на уменьшенной странице A4,
# отображается обратно на оригинал 1075x1520 так:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

Отступы добавляются только по нижнему и правому краям, поэтому начало координат не смещается и достаточно линейного пересчёта по каждой оси. Ограничьте возвращённые координаты изменёнными размерами перед пересчётом, чтобы точка, слегка выходящая за пределы изображения, не могла оказаться за пределами вашего оригинала.

Относительные координаты умножаются на размеры той поверхности, с которой вы работаете: исходного изображения, скана в полном разрешении или экрана. Когда вы работаете с экраном и пиксели снимка экрана отличаются от логических координат (дисплеи HiDPI), также делите на коэффициент масштабирования дисплея. Этот шаблон описан в руководстве по масштабированию для инструмента использования компьютера.

Следующие шаги