Koordinat dan bounding box

Claude dapat menemukan dan memberi label pada wilayah suatu gambar (misalnya, mengembalikan “bounding box” (kotak pembatas) untuk tabel, bidang formulir, elemen bagan, atau komponen UI). Panduan ini membahas bagaimana Claude mengubah ukuran gambar sebelum memprosesnya dan cara bekerja dengan koordinat piksel yang dikembalikannya, sehingga kotak dan titik selaras dengan gambar asli Anda.

Anda akan membutuhkan ini untuk pipeline OCR, ekstraksi formulir, penguraian bagan, penentuan lokasi elemen UI, dan tugas apa pun di mana Anda bertindak pada wilayah tertentu dari suatu gambar. Untuk pengiriman gambar, format yang didukung, dan batas resolusi per model, lihat Vision.

Koordinat mengikuti konvensi gambar standar: titik asal (0, 0) adalah sudut kiri atas gambar, dengan x bertambah ke kanan dan y bertambah ke bawah. Koordinat yang dikembalikan Claude adalah posisi piksel dalam gambar yang diproses Claude: gambar Anda setelah Claude mengubah ukurannya agar sesuai dengan resolusi native model (lihat Cara Claude mengubah ukuran dan menambahkan padding pada gambar). Untuk mendapatkan koordinat yang dapat langsung Anda gunakan, ubah ukuran gambar Anda terlebih dahulu agar koordinat terpetakan satu-ke-satu ke gambar yang Anda miliki (lihat Ubah ukuran gambar Anda sebelum mengunggah), atau skalakan ulang koordinat yang dikembalikan Claude (lihat Skalakan ulang koordinat ketika Anda tidak dapat mengubah ukuran terlebih dahulu).

Bagaimana Claude mengubah ukuran dan menambahkan padding pada gambar

Claude mencari ukuran terbesar yang mempertahankan rasio aspek dan memenuhi kedua batas gambar model:

1. Batas sisi: tidak ada sisi yang melebihi panjang sisi maksimum (1.568 px pada tingkat standar, 2.576 px pada tingkat resolusi tinggi).
2. Batas token visual: biaya token gambar ⌈width / 28⌉ × ⌈height / 28⌉ tidak melebihi anggaran token visual model (1.568 token pada tingkat standar, 4.784 pada tingkat resolusi tinggi).

Lihat Resolusi dan biaya token untuk mengetahui model mana yang berada di tingkat mana.

Untuk hampir semua foto dan tangkapan layar, batas token visual adalah yang menentukan ukuran akhir. Batas tepi hanya berlaku untuk gambar memanjang seperti panorama atau tangkapan layar ponsel yang tinggi. Hitung ukurannya dengan implementasi referensi alih-alih menskalakan ke panjang tepi secara manual: tangkapan layar 1920×1080 diubah ukurannya menjadi 1456×819, bukan 1568×882, dan mengasumsikan batas tepi akan membuat setiap koordinat meleset cukup jauh dari target.

Batas token juga dapat memicu pengubahan ukuran ketika tidak ada sisi yang melebihi batas sisi. Mengabaikan hal ini adalah penyebab paling umum koordinat yang tidak sejajar. Misalnya, halaman A4 yang dipindai pada 130 DPI berukuran 1075×1520 piksel: kedua sisi di bawah 1.568 px, tetapi biayanya 39 × 55 = 2145 token visual, sehingga Claude mengubah ukurannya menjadi 924×1307.

Claude kemudian menambahkan padding pada setiap gambar, baik yang diubah ukurannya maupun tidak, hingga kelipatan 28 piksel berikutnya pada tepi bawah dan kanan (924×1307 menjadi 924×1316 dalam contoh). Padding tidak berisi konten: Claude melihat gambar yang diberi padding, tetapi konten halaman hanya menempati wilayah hasil pengubahan ukuran tanpa padding. Selalu normalisasi atau skalakan ulang berdasarkan dimensi hasil pengubahan ukuran, bukan dimensi dengan padding; membagi dengan dimensi dengan padding akan menskalakan setiap koordinat dengan sedikit penyimpangan.

Ubah ukuran gambar Anda sebelum mengunggah

Pendekatan paling andal adalah mengubah ukuran gambar sendiri sebelum mengunggah, sehingga gambar yang Anda miliki persis sama dengan gambar yang diproses Claude dan koordinat yang dikembalikan Claude tidak memerlukan konversi.

Pertama, periksa tingkat resolusi model Anda (lihat Resolusi dan biaya token) dan berikan batas tepi dan token yang sesuai. Implementasi referensi berikut menghitung ukuran persis yang digunakan Claude saat mengubah ukuran gambar:

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)

    # Pencarian biner di sepanjang sisi panjang untuk ukuran terbesar yang menjaga
    # rasio aspek dan masih muat.
    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))


# Contoh A4 dari "Bagaimana Claude mengubah ukuran dan menambahkan padding pada gambar":
print(resized_size(1075, 1520))  # (924, 1307)

# Untuk menerapkan resize, gunakan pustaka gambar Anda, misalnya Pillow:
# image.resize(resized_size(*image.size))

1. Ubah ukuran gambar ke dimensi yang dikembalikan oleh helper pengubah ukuran. Jika gambar sudah sesuai dengan batas model, helper mengembalikan dimensinya tanpa perubahan dan tidak diperlukan pengubahan ukuran.
2. Kirim gambar yang telah diubah ukurannya ke API. Jangan menambahkan padding sendiri. Claude menangani padding, dan padding tidak menggeser titik asal koordinat.
3. Dalam prompt Anda, minta koordinat piksel secara eksplisit. Misalnya: “Kembalikan titik klik untuk tombol Submit sebagai [x, y] dalam koordinat piksel.”
4. Gunakan koordinat yang dikembalikan secara langsung terhadap gambar yang Anda kirim. Jika Anda memerlukan koordinat yang dinormalisasi, bagi dengan dimensi gambar yang Anda kirim, bukan dengan dimensi gambar asli dan bukan dengan dimensi dengan padding.

Ubah pengubahan ukuran menjadi error dengan transformations

Mengubah ukuran terlebih dahulu hanya melindungi koordinat Anda selama pipeline Anda terus menghasilkan ukuran yang tepat. Sumber gambar baru atau peralihan ke model pada tingkat resolusi yang berbeda dapat secara diam-diam memunculkan kembali pengubahan ukuran di sisi server. Untuk mengubah penyimpangan diam-diam itu menjadi error yang terlihat, atur field opsional transformations pada blok konten gambar dalam permintaan Messages:

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

Permintaan yang gambar bertandanya (blok apa pun yang mengatur "oversized_image": "error") akan diubah ukurannya ditolak dengan 400 invalid_request_error yang menyebutkan dimensi gambar dan dimensi terbesar yang muat. Apakah sebuah gambar memicu penolakan bergantung pada batas setiap model yang disebutkan dalam permintaan: contoh 1920×1080 berikut ditolak oleh model tingkat standar tetapi muat dalam tingkat resolusi tinggi:

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"

Skalakan ulang ke target yang dilaporkan dan kirim ulang: target adalah ukuran terbesar, pada rasio aspek gambar Anda, yang diterima oleh setiap model yang disebutkan dalam permintaan. Bagaimana gambar bertanda berinteraksi dengan beta fallback sisi server dijelaskan bersama fitur tersebut; dalam setiap mode, gambar bertanda tidak pernah disajikan dalam keadaan diubah ukurannya.

Setiap gambar memiliki pengaturannya sendiri. "oversized_image": "downsize" (default ketika field dihilangkan) mempertahankan pengubahan ukuran otomatis seperti yang dijelaskan di halaman ini. Setiap blok gambar hanya diperiksa terhadap pengaturannya sendiri, sehingga satu permintaan dapat mencampur gambar yang dimensinya penting (screenshot yang akan Anda klik) dengan gambar yang aman diubah ukurannya (logo). Apa yang diubah dan tidak diubah oleh pengaturan ini:

• Padding (yang tidak pernah membuang konten), konversi format, dan koreksi orientasi berjalan seperti biasa.
• Batas keras (8.000 px pada sisi terpanjang, dan batas per gambar yang lebih ketat pada permintaan dengan banyak gambar) adalah penolakan terpisah; pengaturan ini tidak pernah meloloskan gambar melampaui batas tersebut.
• Gambar yang disediakan melalui URL atau ID file diperiksa setelah byte-nya diambil; penolakan tersebut membawa pesan yang sama tanpa posisi di awal, sehingga tidak mengidentifikasi gambar mana yang gagal; hanya gambar base64 yang disematkan yang disebutkan berdasarkan posisi dalam error.
• Halaman PDF dirasterisasi di sisi server pada dimensi yang tidak Anda kendalikan; blok document tidak menerima field ini (blok gambar yang bersarang di dalam konten dokumen menerimanya seperti blok lainnya).
• Gambar bertanda yang dimensinya tidak dapat ditentukan akan ditolak alih-alih diteruskan: penolakan tersebut melaporkan bahwa dimensi sumber gambar tidak dapat ditentukan, bukan pesan pengubahan ukuran yang dikutip sebelumnya. Tidak ada gambar yang mengatur "error" yang mencapai model dalam keadaan diubah ukurannya.

Endpoint Penghitungan token juga mematuhi transformations, menolak gambar yang disematkan persis seperti yang dilakukan Messages API, sehingga Anda dapat memeriksa apakah gambar yang disematkan muat tanpa diubah ukurannya, sebelum menjalankan inferensi. Penghitungan menolak gambar yang diberikan melalui URL atau ID file alih-alih mengambilnya, sehingga gambar bertanda dari sumber tersebut hanya diperiksa pada saat Messages.

Skalakan ulang koordinat ketika Anda tidak dapat mengubah ukuran terlebih dahulu

Jika Anda tidak dapat mengubah ukuran terlebih dahulu (misalnya, ketika gambar berasal dari sistem upstream yang tidak dapat Anda ubah), gunakan helper pengubah ukuran dari Ubah ukuran gambar Anda sebelum mengunggah untuk memperoleh kembali dimensi gambar yang diproses Claude, lalu petakan koordinat yang dikembalikan Claude ke koordinat yang dinormalisasi atau kembali ke gambar asli Anda. Kecuali sebuah gambar memilih error gambar berukuran berlebih, Claude mengubah ukuran gambar yang terlalu besar alih-alih menolaknya, hingga batas permintaan API. Di luar batas tersebut, permintaan gagal dengan error validasi. Berikan batas tingkat yang sesuai dengan model yang Anda panggil: batas tingkat yang salah akan menghasilkan dimensi hasil pengubahan ukuran yang salah dan diam-diam menggeser setiap koordinat. Pendekatan ini memerlukan pengetahuan tentang dimensi piksel gambar yang Anda unggah, sehingga tidak berlaku untuk unggahan PDF.

Tangkapan layar dan gambar zoom yang Anda kembalikan ke toolset penggunaan komputer dan penggunaan browser merupakan pengecualian dari pengubahan ukuran otomatis. API menolak gambar tool_result yang melebihi batas model dengan error validasi alih-alih mengubah ukurannya. Ubah ukuran gambar tersebut di aplikasi Anda sebelum mengembalikannya, lalu skalakan koordinat yang dikembalikan Claude kembali ke dimensi layar Anda.

# Helper ini memanggil resized_size dari contoh resize di halaman ini.
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)


# Sudut tabel yang Claude kembalikan di (462, 653.5) pada halaman A4 yang di-resize
# dipetakan kembali ke gambar asli 1075x1520 seperti ini:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

Padding hanya diterapkan pada tepi bawah dan kanan, sehingga titik asal tidak bergeser dan penskalaan ulang linear per sumbu sudah cukup. Batasi (clamp) koordinat yang dikembalikan ke dimensi hasil pengubahan ukuran sebelum menskalakan ulang, sehingga titik yang sedikit di luar gambar tidak dapat terpetakan di luar gambar asli Anda.

Koordinat relatif dikalikan dengan permukaan apa pun tempat Anda bertindak: gambar asli, pindaian resolusi penuh, atau layar. Ketika Anda bertindak pada layar dan piksel tangkapan layar berbeda dari koordinat logis (layar HiDPI), bagi juga dengan faktor skala tampilan. Panduan penskalaan alat penggunaan komputer membahas pola tersebut.

Langkah selanjutnya