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

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

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

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

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

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

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

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

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

Ограничение токенов также может вызвать изменение размера, даже когда ни одна сторона не превышает ограничение по стороне. Упущение этого — самая частая причина смещённых координат. Например, страница A4, отсканированная с разрешением 130 DPI, имеет размер 1075×1520 пикселей: обе стороны меньше 1 568 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 for each 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" (значение по умолчанию, когда поле опущено) сохраняет автоматическое изменение размера, описанное на этой странице. Каждый блок изображения проверяется только по его собственной настройке, поэтому в одном запросе можно сочетать изображения, размеры которых важны (снимок экрана, на котором вы будете нажимать), с изображениями, для которых изменение размера безвредно (логотип). Что настройка меняет и чего не меняет:

• Дополнение (которое никогда не отбрасывает содержимое), преобразование формата и коррекция ориентации выполняются как обычно.
• Жёсткие ограничения (8 000 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), также делите на коэффициент масштабирования дисплея. Этот шаблон описан в руководстве по масштабированию для инструмента использования компьютера.

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