Entegrasyon rehberleri · 2026-10-17
Jev 1.14 Box: görselde nesnenin konumunu API ile bulmak
Jev 1.14'ün Box sorusuyla bir görselde nesnenin konumunu bulun: typesafe/jev-1.14.0, assets, deneysel başlık, 0-1 arası kenarlar ve piksele çevirme.
Kısa yanıt: Box sorusu nesnenin dört kenarını döndürür
LLMTR (llmtr.com), farklı sağlayıcıların dil modellerine tek bir OpenAI uyumlu API ile erişim veren bir gateway'dir. Bir görselde bir nesnenin nerede olduğunu bulmak için TypeSafe'in Jev 1.14 modelini typesafe/jev-1.14.0 kimliğiyle, POST /v1/systemone uç noktasında bir Box sorusuyla çağırırsınız; temel adres https://llmtr.com/v1'dir. Yanıt, nesnenin çevresindeki kutunun dört kenarını görselin genişlik ve yüksekliğine oranla 0 ile 1 arasında verir.
Box, TypeSafe'in deneysel özelliklerindendir: sağlayıcı görselleri ve Box sorularını henüz üretime hazır saymaz ve istek biçiminin, yanıtların ve sınırların sürümler arasında değişebileceğini söyler. Box yalnızca Jev 1.14'te vardır ve her istekte TypeSafe-Danger-Zone-Images: true başlığı ister; LLMTR bu başlığı sağlayıcıya iletir. Model metin üretmez; 1 milyon girdi token'ı 0,042 $, çıktı 0 $'dır.
Bir görselde nesnenin konumu API ile nasıl bulunur?
Dört adım vardır. Görseli base64'e çevirip üst seviyedeki assets haritasına bir referans anahtarıyla ekleyin; format alanı png, jpg ya da jpeg olur ve data_base64 data: öneki taşımaz. Referansı durumun içine yazın, örneğin state alanında photo anahtarının değeri olarak; sağlayıcı görseli referansın geçtiği yere koyar. Box sorusunun instructions alanında aranan şeyi ve hangi görselde aranacağını adlandırın; TypeSafe'in örnekleri görsele ters tırnak içinde adıyla değinir. Son olarak isteği TypeSafe-Danger-Zone-Images: true başlığıyla gönderin.
Aşağıdaki Python örneği bir raf fotoğrafında kahve kupası arar. Aynı istekte bir noul sorusu da vardır ve kupanın görselde olup olmadığını sorar, çünkü Box her zaman bir kutu döndürür. Görsel durumda olduğu için iki soru da onu görür. Birden fazla soru aynı görsele bakıyorsa onu durumda bir kez listeleyin; referansı birden fazla yerde kullanmak görseli her seferinde yeniden ekler ve yeniden sayar. Kod kutuyu piksele çevirir; güven değeri yoksa ya da varlık olasılığı düşükse sonucu bulunamadı sayar.
Python requests ile typesafe/jev-1.14.0'a bir noul ve bir Box sorusu gönderip kutuyu piksele çeviren örnek.
import base64
import os
import requests
from PIL import Image
API_KEY = os.environ["LLMTR_API_KEY"]
PHOTO = "shelf.jpg" # JPEG or PNG, each side 280-1568 px
with open(PHOTO, "rb") as f:
data_base64 = base64.b64encode(f.read()).decode("ascii")
width, height = Image.open(PHOTO).size
response = requests.post(
"https://llmtr.com/v1/systemone",
headers={
"Authorization": f"Bearer {API_KEY}",
"TypeSafe-Danger-Zone-Images": "true",
},
json={
"model": "typesafe/jev-1.14.0",
"state": {"photo": "photo-1"},
"assets": {"photo-1": {"type": "image", "format": "jpg", "data_base64": data_base64}},
"questions": {
"has_mug": {"type": "noul", "instructions": "Is there a coffee mug in `photo`?"},
"mug": {"type": "box", "instructions": "the coffee mug in `photo`"},
},
},
timeout=60,
)
response.raise_for_status()
answers = response.json()["answers"]
mug = answers["mug"]
# 0.5 is an example threshold: tune it on your own images.
if answers["has_mug"]["noul"] < 0.5 or mug["confidence"] is None:
print("No reliable box: treat the mug as not found")
else:
box = mug["box"]
left, right = round(box["left"] * width), round(box["right"] * width)
top, bottom = round(box["top"] * height), round(box["bottom"] * height)
print(f"mug at x {left}-{right}, y {top}-{bottom}, confidence {mug['confidence']}")Yanıtı okumak: kenarlar, piksel ve confidence
Box yanıtındaki box alanı top, bottom, left ve right kenarlarını taşır. TypeSafe'e göre başlangıç noktası sol üst köşedir: (0, 0) sol üst, (1, 1) sağ alt köşedir; left ve right genişliğin, top ve bottom yüksekliğin oranıdır, left right'tan ve top bottom'dan küçüktür. Piksel değeri için kenarı görselin genişliği ya da yüksekliğiyle çarpın: 1200 x 800 piksellik bir görselde left 0,55 ise kutunun sol kenarı 660. pikseldedir.
Aşağıdaki örnek yanıt yukarıdaki isteğin biçimini gösterir; sayılar örnektir. confidence 0 ile 1 arasındadır ve TypeSafe'in API şemasına göre model güven değeri vermediğinde null döner. Eşikle karşılaştırmadan önce null'u kontrol edin ve null gelen kutuyu belirsiz sayın. TypeSafe henüz önerilen bir confidence eşiği yayımlamıyor; eşiği kendi görsellerinizle belirleyin. usage içindeki output_tokens sıfırdan büyük gelebilir, ama çıktının fiyatı 0 $'dır.
Örnek yanıt: alanlar TypeSafe'in belgelediği biçimdedir, sayılar örnektir.
{
"model": "typesafe/jev-1.14.0",
"answers": {
"has_mug": { "type": "noul", "noul": 0.93 },
"mug": {
"type": "box",
"box": { "top": 0.41, "bottom": 0.62, "left": 0.55, "right": 0.68 },
"confidence": 0.72
}
},
"usage": { "input_tokens": 1180, "output_tokens": 41 }
}Bulunamadı yanıtı yok: pratik uyarılar
Box'ın bulunamadı diye bir yanıtı yoktur. Aradığınız şey görselde olmasa da dört kenar döner; bu kutuyu gerçek bir konum gibi kullanırsanız kodunuz olmayan bir nesneye göre işlem yapar. TypeSafe'in önerdiği yol, aynı istekte nesnenin görselde olup olmadığını soran bir noul sorusu sormak ve noul düşükse kutuyu yok saymaktır. Örnek koddaki 0,5 eşiği örnektir.
Her Box sorusu tek bir hedef bulur ve her yanıt tek bir kutudur; birden fazla nesne için her biri için ayrı bir Box sorusu sorun. Görselde aynı türden birden çok nesne varsa istediğinizi tarif edin: soldaki kupa ya da kırmızı kapaklı kupa gibi. Kelimelerle ayıramıyorsanız TypeSafe, none, one ve several seçenekli bir choice sorusu eklemeyi ve cevap several ise görseli bölgelere ayırmayı önerir. Güveni düşük bir kutu için önerisi, görselin daha büyük bir sürümüyle ya da kutunun çevresinden daha yüksek çözünürlüklü bir kırpıntıyla yeniden sormak ya da kenarları noul sorularıyla kontrol etmektir. TypeSafe, çok büyük bir görselde birkaç düzine piksel genişliğindeki bir hedefin kaçabileceğini söyler; küçük hedefler için görseli göndermeden önce kırpın ya da parçalara bölün.
Görsel kuralları, sınırlar ve hata kodları
Görsel PNG ya da JPEG olmalı, her kenarı 280 ile 1568 piksel arasında kalmalı ve dosya en fazla 16 MiB olmalıdır; TypeSafe'e göre sınır dışındaki görsel küçültülmez, reddedilir. LLMTR görselleri yalnızca JSON gövdede data_base64 olarak kabul eder; multipart yükleme kabul edilmez ve istek gövdesi toplamda 24 MB ile sınırlıdır. Base64 kodlama dosyayı yaklaşık üçte bir büyütür. Listelediğiniz her görsele en az bir yerde değinmelisiniz.
16 MiB'ı aşan ya da PNG veya JPEG olmayan bir dosya, görebileceği bir görsel olmayan Box sorusu ve typesafe/jev kimliğine (Jev 1.13) gönderilen Box sorusu modele gitmeden 400 invalid_request döner. Başlık eksikse ya da görselin boyutları sınır dışındaysa 400 provider_error döner ve mesaj sorunu söyler. Görsel token'ları metinle aynı fiyattan girdi olarak sayılır ve usage.input_tokens içinde gelir. TypeSafe görsel token'ını tahmin etmek için bir rehberi henüz yayımlamadı; maliyeti kendi isteklerinizin usage değerinden izleyin.
| Kural | Değer |
|---|---|
| Model kimliği | typesafe/jev-1.14.0 |
| Gerekli başlık | TypeSafe-Danger-Zone-Images: true |
| Görsel biçimi | PNG ya da JPEG, data_base64 olarak |
| Görsel kenarı | 280-1568 piksel |
| Görsel dosyası | en fazla 16 MiB |
| İstek gövdesi | en fazla 24 MB |
| Girdi fiyatı (görsel dahil) | 0,042 $ / 1M token |
| Çıktı fiyatı | 0 $ / 1M token |
Jev 1.14 ile görselde nesnenin konumunu bulma
Görseli assets haritasına ekleyin, bir noul ve bir Box sorusu sorun ve kutuyu piksele çevirin.
- Hazırlık. Dashboard > API Anahtarları altında bir anahtar oluşturun, Dashboard > Faturalandırma'dan bakiye yükleyin ve her kenarı 280-1568 piksel olan bir PNG ya da JPEG seçin.
- İstek. Görseli assets haritasına data_base64 olarak ekleyin, referansını state içine yazın, bir noul ve bir Box sorusu tanımlayın ve isteği TypeSafe-Danger-Zone-Images: true başlığıyla typesafe/jev-1.14.0 için https://llmtr.com/v1/systemone adresine gönderin.
- Okuma. noul düşükse ya da confidence null ise kutuyu yok sayın; değilse kenarları görselin genişliği ve yüksekliğiyle çarparak piksele çevirin.
Sık sorulan sorular
Box sorusu hangi modelde çalışır?
LLMTR'de yalnızca typesafe/jev-1.14.0 (Jev 1.14) Box sorusunu yanıtlar ve istekte TypeSafe-Danger-Zone-Images: true başlığı gerekir. Box sorusu başka bir modele gönderilirse istek modele gitmeden 400 invalid_request döner.
Nesne görselde yoksa ne döner?
Yine bir kutu döner; Box'ın bulunamadı yanıtı yoktur. Aynı istekte nesnenin görselde olup olmadığını soran bir noul sorusu sorun ve olasılık düşükse kutuyu yok sayın.
Box koordinatları piksele nasıl çevrilir?
left ve right değerlerini görselin genişliğiyle, top ve bottom değerlerini yüksekliğiyle çarpın. Değerler sol üst köşeye göre 0 ile 1 arasındaki oranlardır.