Box e imágenes: haz que Jev encuentre cosas en una imagen
En las cinco lecciones anteriores, el state solo contenía texto. Pero las necesidades reales de juicio a menudo están en las imágenes: ¿hay alguien en la foto del timbre?, ¿dónde está la firma en el formulario escaneado?, ¿en qué parte del fotograma está parado el pájaro en esta toma de la cámara de aves? Si le das este tipo de imagen a GPT, devuelve un párrafo descriptivo, pero lo que tú quieres son coordenadas que puedas recortar directamente y meter directo en un if.
Esta lección trata sobre Jev Box: dale una imagen y una frase, y devuelve los cuatro bordes del rectángulo mínimo que rodea al objetivo. En total, 10 minutos.
Primero lo claro: Images y Box son características experimentales. Las palabras oficiales las llaman dreamer-ready: aún no alcanzan el estándar de producción que se atreven a garantizar, y tanto el formato de solicitud como la precisión pueden cambiar entre versiones. Sirven muy bien para armar prototipos y validar ideas; para producción, evalúa tú mismo el riesgo.
Qué podrás hacer al terminar
- Poner una imagen en el state con
Imagedel SDK de Python y enviar tu primera solicitud Box con el encabezado Danger Zone - Interpretar la respuesta Box: qué fracción del ancho y alto de la imagen representa cada uno de los cuatro bordes
top/bottom/left/right, y convertirla de vuelta a coordenadas en píxeles para recortar el objetivo - Usar la
confidenceincluida en la respuesta Box para decidir si usar el cuadro tal cual, expandir los bordes antes de recortar, o cambiar a una mejor imagen y preguntar de nuevo - Usar una pregunta Noul como filtro previo para resolver el problema de que «Box no tiene una respuesta de 'no encontrado'»
- Explicar las restricciones de las solicitudes con imagen: formato, dimensiones, tamaño, y qué código de error obtendrás si te pasas de los límites
Tu dilema actual
- Si le pides a GPT que encuentre algo en una imagen, responde con un párrafo tipo «hacia la izquierda de la escena hay una taza» — tienes la dirección, pero no las coordenadas, y no puedes escribir el código de recorte
- Usar un modelo de detección especializado implicaría anotar datos, entrenar y ajustar parámetros; solo para ubicar una taza, no vale la pena
- Los modelos multimodales devuelven coordenadas en un formato distinto cada vez, y además tienes que escribir un analizador que cubra toda clase de respuestas creativas como «no se ve claro» o «no encontrado»
Cuándo usar esta técnica
Cuando necesitas:
- La posición de un objetivo en una imagen: una firma en un documento escaneado, una persona en la foto del timbre, un producto concreto en la foto de un estante
- Que la posición entre directo en el código: recortar la región objetivo y enviarla a OCR, dibujar cuadros de anotación, ordenar según los bordes
top - Preguntar juicio y localización a la vez: si lo que sostiene la persona es un paquete o una bolsa, si el objetivo está o no en la imagen
Y no quieres:
- Entrenar ni desplegar un modelo de visión dedicado
- Analizar descripciones de coordenadas en lenguaje natural que el modelo inventa a su antojo
- Montar toda una infraestructura para capacidades de visión ya en la fase de prototipo
🎒 Preparativos antes de empezar
- Haber completado State (estado): saber qué es el state y cómo las preguntas usan rutas con acentos graves para apuntar a sus campos
- Haber corrido con éxito la primera solicitud:
.venvtiene instaladotypesafe-sdkyTYPESAFE_API_KEYya está en las variables de entorno - Tener preparada una imagen donde buscar algo (el ejemplo oficial busca una taza en una foto de cocina; si no tienes, cualquier PNG/JPEG sirve — revisa primero las restricciones de tamaño del paso 1)
- Saber que Box requiere Jev 1.14 (
jev-latestya apunta a él, muy probablemente no tengas que cambiarlo); si quieres confirmarlo, consultamodelos y precios
Idea central
**Box responde «dónde». ** Posicionamiento oficial: Box es el cuarto tipo de pregunta (Choice elige opciones, Score asigna niveles, Noul decide sí/no), y también el primer tipo de pregunta de posición diseñado puramente para que «la salida sea datos». Dale una imagen y la frase «la taza de café de la imagen», y devuelve el rectángulo mínimo que rodea la taza de café.
La respuesta son cuatro bordes, y además son proporciones.
| Campo | Significado | Rango |
|---|---|---|
left / right | Distancia desde el borde izquierdo de la imagen, como proporción del ancho | 0–1, left < right |
top / bottom | distancia desde el borde superior de la imagen, como proporción de la altura | 0–1, top < bottom |
El origen está en la esquina superior izquierda: top: 0 es el borde superior de la imagen y bottom: 1 el inferior. Todo son proporciones en 0–1, lo que significa que la misma respuesta vale para cualquier tamaño de imagen—una foto de móvil de 4000×3000 y una miniatura de 400×300 delimitan la misma posición relativa. Para dibujar el recuadro o recortar, multiplica cada lado por el ancho y alto en píxeles de la imagen (paso 3).
Cómo entra la imagen en la solicitud: referencias + assets. Cada imagen se registra una vez en el assets del nivel superior de la solicitud y se obtiene una cadena de referencia; escribe esa referencia en cualquier lugar de state, instructions o criteria donde pueda aparecer una cadena, y el modelo recibirá la imagen ahí. Con HTTP directo se usan archivos multipart o base64; el SDK de Python genera las referencias por ti y sube los archivos automáticamente, Image(路径) se pone directamente en state y listo (paso 2).
Un interruptor: la cabecera de solicitud Danger Zone. Imágenes y Box están desactivados por defecto. Cada solicitud con imagen o Box debe incluir:
TypeSafe-Danger-Zone-Images: trueEn el SDK basta con pasar extra_headers (paso 2). Si se te olvida añadirla, la solicitud devuelve directamente 400.
Box puede mezclarse con otras preguntas. Igual que en lecciones anteriores: todas las preguntas se evalúan en paralelo sobre el mismo state, y añadir preguntas casi no aumenta el tiempo de respuesta.
Un rasgo clave: Box siempre devuelve un recuadro. No existe la respuesta «no lo encontré»—si no hay taza de café en la imagen, te devuelve cuatro lados igualmente. El método de control es añadir en la misma solicitud una Noul «¿hay una taza de café en la imagen?»; si la Noul dice que no, ignora ese recuadro (paso 5).
Sígueme
Paso 1: prepara una imagen que cumpla las restricciones e instala Pillow
Por qué: las restricciones de las solicitudes de imagen difieren de las de texto—tamaño, formato y peso están muy limitados; prepara la imagen según la lista primero para que la solicitud del paso 2 no devuelva 413 / 400.
Restricciones oficiales (images.md):
| Elemento | Restricción |
|---|---|
| Formato | PNG o JPEG, imagen estática (los PNG animados se rechazan) |
| Píxeles por lado | 280–1568; cualquier lado por debajo de 280 se rechaza |
| Píxeles totales | 78,400–2,458,624 (es decir, el área comprendida entre 280×280 y 1568×1568) |
| Archivo individual | ≤ 16 MiB |
| Cuerpo de la solicitud | ≤ 32 MiB (incluye todas las imágenes, el JSON y la estructura multipart) |
Tres cosas al preparar la imagen (directrices oficiales «Preparing images»):
- Escalar: comprime el lado más largo hasta 1568 píxeles como máximo. Una foto de móvil de 12 megapíxeles (1200×10⁴ píxeles) suele quedar en 1568×1176
- Enderezar: la API elimina todos los metadatos (EXIF, etc.) y no aplica la orientación EXIF—en el visor de imágenes aparece vertical, pero al modelo puede llegarle horizontal. Rota los píxeles mismos, no dependas del EXIF
- Cambiar formato: convierte primero GIF, WebP y HEIC a PNG o JPEG; el JPEG baseline estándar de 8-bit es el más fiable
Para dejar una imagen lista, con Pillow bastan tres líneas (enderezar + escalar + convertir a JPEG estándar):
from PIL import Image, ImageOps
with Image.open("photo.jpg") as original:
img = ImageOps.exif_transpose(original) # rotate the pixels upright
img.thumbnail((1568, 1568)) # longest side at most 1568, same aspect ratio
img.convert("RGB").save("photo-ready.jpg", "JPEG", quality=90)Si no tienes Pillow instalado, instálalo (luego también hará falta para Image.from_pil y el recorte):
.venv/bin/pip install pillowDeberías ver: photo-ready.jpg se genera correctamente; al abrirlo con un visor de imágenes, la orientación es correcta y la nitidez no se ha perdido.
- Mi imagen es PNG/JPEG, tiene 280–1568 píxeles por lado y la orientación ya está enderezada
Paso 2: envía la primera solicitud Jev Box con la Image del SDK de Python
Por qué: con HTTP directo hay que montar el multipart a mano, gestionar las referencias y convertir a base64; el SDK de Python (desde la v0.7.5 admite Image y Box) lo encapsula todo—pon el objeto Image en el contenido y la referencia se genera y el archivo se sube automáticamente.
Image admite cuatro formas de cargarlo:
| Forma | Escritura | Escenario |
|---|---|---|
| Ruta de archivo | Image(Path("kitchen.jpg")) | La más habitual |
| Bytes en bruto | Image(data) | Bytes obtenidos de un flujo de red o de una base de datos |
| Texto base64 | Image.from_base64(data_base64) | Recibir subidas de terceros |
| Objeto PIL | Image.from_pil(pil_image) | Enviar directamente tras recortar/escalar, ahorrando una escritura a disco; requiere typesafe-sdk[pil] |
Crea un archivo nuevo box_kitchen.py. Usa tu photo-ready.jpg y busca un objetivo en la imagen (el ejemplo oficial es una taza de café; cámbialo por algo que realmente aparezca en tu imagen):
from pathlib import Path
from typesafe_sdk import Box, Image, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state={"photo": Image(Path("photo-ready.jpg"))},
questions={
"target": Box(instructions="the coffee mug in `photo`"),
},
extra_headers={"TypeSafe-Danger-Zone-Images": "true"},
)
print(response.answers["target"].box)
print(response.answers["target"].confidence)Ejecuta:
.venv/bin/python box_kitchen.pyDeberías ver (los valores dependen de tu imagen y tu objetivo):
top=0.25 bottom=0.82 left=0.44 right=0.84
0.92Tres detalles:
Las preguntas Box solo tienen dos campos:
type(fijo"box") yinstructions(qué buscar y en qué imagen). No haycriteria—aquí no sirven opciones, niveles ni definiciones de sí/noinstructionsno tiene que ser una pregunta; basta una frase:"the coffee mug in`photo`"—la ruta entre comillas invertidas indica en qué imagen buscar (palabra oficial: It doesn't have to be a question)Image(Path(...))se coloca en state y el SDK genera automáticamente una referencia tipo UUID—con varias imágenes o estructuras anidadas no se mezclanObtuve cuatro números entre 0–1 y un confidence, sin ningún error 400
⚠️ Olvidar la cabecera Danger Zone hace que la solicitud devuelva directamente 400
Si la petición incluye una imagen o una pregunta Box, TypeSafe-Danger-Zone-Images: true no puede faltar. El error no se anda con rodeos: 400, y la causa queda bien clara. Quienes se conectan por HTTP directo tienen un ejemplo completo de multipart con curl en Referencia rápida de la API.
💡 Box requiere Jev 1.14
Jev 1.13 y 1.14 aceptan imágenes, pero las preguntas Box solo existen a partir de 1.14. jev-latest ya apunta a jev-1.14.0, así que basta con seguir el flujo normal; los proyectos que tengan fijado 1.13 y quieran usar Box deben actualizar el modelo primero.
Paso 3: leer los cuatro lados de la respuesta Box y convertirlos a coordenadas de píxeles
Por qué: las proporciones de 0–1 no sirven para dibujar el rectángulo ni para recortar directamente: hay que multiplicarlas por el tamaño en píxeles de tu imagen. El código oficial de «Reading a Box» hace exactamente eso.
Primero, la respuesta en bruto (quien use curl directo recibirá este JSON tal cual; el SDK obtiene la misma estructura):
{
"model": "jev-1.14.0",
"answers": {
"mug": {
"type": "box",
"box": {
"top": 0.25,
"bottom": 0.82,
"left": 0.44,
"right": 0.84
},
"confidence": 0.92
}
},
"usage": {"input_tokens": 290, "output_tokens": 21}
}Guía de lectura (supón que tu imagen es de 1568×1176):
| Campo | Valor | Conversión | Posición en píxeles |
|---|---|---|---|
left | 0.44 | 0.44 × 1568 | a 690px del borde izquierdo |
right | 0.84 | 0.84 × 1568 | a 1317px del borde izquierdo |
top | 0.25 | 0.25 × 1176 | a 294px del borde superior |
bottom | 0.82 | 0.82 × 1176 | a 964px del borde superior |
Código oficial de recorte (el crop de Pillow recibe coordenadas de píxeles en el orden left, top, right, bottom):
from PIL import Image
image = Image.open("photo-ready.jpg")
width, height = image.size
mug = response["answers"]["mug"]
edges = mug["box"]
box = (
round(edges["left"] * width),
round(edges["top"] * height),
round(edges["right"] * width),
round(edges["bottom"] * height),
)
image.crop(box).save("mug.jpg")Quien use el SDK puede copiarlo tal cual, solo cambiando mug = response["answers"]["mug"] por mug = response.answers["mug"] y edges = mug["box"] por edges = mug.box: el campo de la respuesta tiene la misma estructura.
Deberías ver: al abrir mug.jpg aparece justo el objetivo que preguntaste: la taza de café queda perfectamente enmarcada, casi sin fondo sobrante arriba, abajo o a los lados.
- Mi resultado de recorte encierra el objetivo y la conversión de los cuatro bordes no está invertida (izquierda/derecha multiplicado por el ancho, arriba/abajo multiplicado por la altura)
Paso 4: usar confidence para decidir entre recortar o revisar
Por qué: la respuesta Box incluye confidence (0–1, cuanto más alto, más certeza). Igual que en la lección anterior: confianza alta, úsala tal cual; confianza baja, revisa con más cuidado: si un rectángulo sale torcido, todo el pipeline posterior estará procesando datos erróneos.
La postura oficial: no hay un umbral recomendado, ajústalo probando con tus propias imágenes. Cuando el valor quede por debajo de tu umbral, la documentación oficial propone dos caminos:
| Enfoque | Cómo hacerlo | Cuándo usarlo |
|---|---|---|
| Pide de nuevo con una imagen mejor | Envía una versión más grande, o recorta la zona cercana al rectángulo, amplíala y repite la misma pregunta Box | La imagen original tiene baja resolución o el objetivo es demasiado pequeño |
| Primero expande los bordes, luego recorta | Desplaza un poco los cuatro lados hacia afuera antes de crop, manteniéndolos dentro de la imagen | Cuando el recorte no puede cortar ninguna parte del objetivo |
Código oficial de la expansión de bordes (PAD es la proporción de expansión hacia afuera por lado; cópialo tal cual y ajústalo a tu imagen):
PAD = 0.05 # Fraction of the image to add on each side. Tune for your images.
MIN_CONFIDENCE = 0.6 # Example threshold. Tune it on your own images.
if mug["confidence"] < MIN_CONFIDENCE:
edges = {
"left": max(0.0, edges["left"] - PAD),
"top": max(0.0, edges["top"] - PAD),
"right": min(1.0, edges["right"] + PAD),
"bottom": min(1.0, edges["bottom"] + PAD),
}Después recorta con este nuevo conjunto de edges como en el paso 3: el objetivo entra en mug.jpg junto con un margen alrededor; mejor que sobre un poco de fondo antes que cortar media asa de la taza.
Deberías ver: las respuestas con confidence alta se usan tal cual; las que quedan por debajo del umbral o terminan con el rectángulo un poco más grande, o siguen el camino de «ampliar y preguntar de nuevo».
- Definí un umbral de confidence para mis respuestas Box, y por debajo de él tengo una ruta de manejo clara (expandir bordes o preguntar de nuevo)
Paso 5: usar Noul como filtro de entrada y hacer preguntas mixtas en lote
Por qué: el problema de personalidad número 1: Box siempre devuelve un rectángulo, no existe un «no encontrado». Si el objetivo no está en la imagen, igualmente devuelve los cuatro lados. La solución de filtro ya está escrita en la documentación oficial: añadir una pregunta Noul a la misma petición.
El ejemplo oficial del registro de vacunas está configurado así (Noul pregunta «está o no», Box pregunta «dónde»):
questions = {
"mug_visible": Noul(instructions="Is there a coffee mug in `photo`?"),
"mug": Box(instructions="the coffee mug in `photo`"),
}En una frase: si Noul dice que no está, ignora el rectángulo de mug. Las dos preguntas se evalúan en paralelo, en una sola petición, y cada respuesta lleva su propio ID.
Otros tres trucos frecuentes de combinación, todos tomados de la guía oficial «Writing Box questions»:
| Escenario | Enfoque |
|---|---|
| Puede haber más de un objetivo en la imagen | Limítalo con texto a uno único: "the mug nearest the sink in `photo` " |
| El texto no deja claro cuántos hay | Añade al lado una pregunta Choice con opciones none / one / several; si la respuesta es several, divide la imagen en trozos y pregunta Box a cada uno por separado |
| Objetivo pequeño en una imagen grande | Usa primero Choice para elegir, entre varios tiles de la imagen, el tile donde está el objetivo, y luego pregunta Box sobre ese tile |
| Usar una imagen como referencia | Escribe el objetivo directamente en las instructions: "the person in `photo` who matches this badge photo: 9a21c7d3-badge" |
El último punto es la otra cara de las referencias de imagen: también se pueden poner imágenes en criteria e instructions. El ejemplo de búsqueda de perro de la documentación oficial usa justamente este mecanismo: la foto del perro encontrado va en el state, la foto del cartel de búsqueda se escribe directamente en la pregunta, y se pregunta «¿es el mismo perro?».
Deberías ver: en una sola petición conviven Noul y Box (y hasta se puede añadir Choice / Score), cada uno con su respuesta; cuando mug_visible es bajo, tu código simplemente omite el rectángulo de mug.
- Mi petición Box incluye una pregunta de filtro (Noul o Choice), y el «no encontrado» tiene una salida clara en el código
Punto de control ✅
- Sé que Images / Box es una característica experimental (dreamer-ready): el formato puede cambiar, la precisión puede cambiar, y oficialmente no se recomienda usarla directamente en producción
- Puedo explicar los cuatro bordes:
left/rightson proporciones del ancho,top/bottomson proporciones de la altura, y el origen está en la esquina superior izquierda - Ejecuté con éxito una solicitud con
TypeSafe-Danger-Zone-Images: truey puedo recortar el objetivo convirtiendo a píxeles - Mi respuesta de Box tiene un umbral de confidence; si está por debajo del umbral, amplío los bordes o cambio de imagen y vuelvo a preguntar
- Mi escenario de «no encontrado» tiene una puerta de control Noul / Choice, así que no tomo un cuadro vacío como válido
Advertencias de errores comunes
❌ La imagen está bien, pero la solicitud devuelve 400 / 413
400: Images are not turned on
413: The request is over a size limitAutoverificación de tres cosas:
- ¿Todas las solicitudes que llevan cualquier imagen o pregunta de Box incluyen el encabezado
TypeSafe-Danger-Zone-Images: true? (400) - ¿Las dimensiones de la imagen están fuera de los límites? Por lado 280–1568, píxeles totales 78,400–2,458,624, archivo individual ≤ 16 MiB——si se supera el límite se rechaza directamente, no se escala automáticamente (
413o400) - ¿Un lote de imágenes supera en total 32 MiB? La API reecodifica al procesar, la imagen procesada puede ser más grande que el archivo que enviaste——enviar muchas imágenes pequeñas también puede chocar con el límite (
413)
La documentación oficial también advierte: cuando una solicitud tiene varios problemas, el error solo reporta uno de ellos; revisa punto por punto contra la tabla de límites.
❌ Usar una foto tomada en vertical como imagen vertical
En el visor de imágenes se ve perfectamente en vertical, pero a los ojos del modelo es horizontal——la API elimina todos los metadatos (incluida la orientación EXIF) y no la aplica. Preguntas «la taza en la parte inferior de la imagen», y el modelo mira una taza dentro de una imagen horizontal.
Manera correcta: antes de enviar, usa ImageOps.exif_transpose para enderezar los píxeles mismos (las tres líneas de Pillow del paso 1). No te limites a cambiar los metadatos.
❌ El cuadro recortado no coincide con el objetivo
Primero comprueba si la conversión está invertida: arriba/abajo se multiplica por la altura, izquierda/derecha por el ancho; luego comprueba que el orden de parámetros de Pillow crop es (left, top, right, bottom). Si inviertes cualquiera de los dos, el cuadro se dispara fuera de la imagen o se tuerce a otra parte.
¿Todavía falla? Mira la confidence——los cuadros con baja confianza pueden salir desviados por naturaleza. Si está por debajo del umbral, primero amplía los bordes (el PAD del paso 4), o recorta la región, amplíala y vuelve a hacer la misma pregunta de Box.
❌ Una sola pregunta de Box para «las posiciones de todas las tazas de café»
Cada pregunta de Box devuelve un solo cuadro; es así por diseño. Para múltiples posiciones de múltiples objetivos: una pregunta separada por objetivo (enviadas en la misma solicitud); si no puedes distinguir objetivos del mismo tipo, añade Choice (none / one / several), y si la respuesta es several, divide en trozos y pregunta por separado. No metas «encuentra todas las X» en una sola instructions.
❌ El objetivo no está en la imagen, pero el cuadro aparece igual
Box no tiene «no encontrado». Si no hay taza en la imagen, la respuesta sigue siendo cuatro bordes——tu código de recorte recortará felizmente un trozo de fondo.
La manera correcta es la del paso 5: junto a ella añade una pregunta Noul ("Is there a coffee mug in `photo` ?"); si la probabilidad de Noul es baja, ignora ese cuadro. Los tres cookbooks oficiales——registros de vacunas, verificación de facturas, cámara de alimentación de aves——todos usan este patrón.
Técnicas avanzadas (opcional)
Tres formas de adjuntar referencias, según el escenario. Además de la referencia automática, el SDK ofrece dos controles más finos:
- El parámetro
assets——eliges tú el nombre de la referencia, con delimitadores que no colisionen fácilmente (el ejemplo oficial es<product>):state="Inspect this returned product: <product>"junto conassets={"<product>": Image(photo)} client.attach_assets——cuelga la imagen en el client ystr(asset)se incrusta en el texto:state=f"The customer says {photo} arrived scratched.". Es obligatorio usar el gestor de contextowith client.attach_assets(photo):; sinwithel SDK no puede mapear las referencias del texto de vuelta a los datos de la imagen (palabra por palabra de la advertencia oficial)
Enviar objetos PIL directamente, ahorrándose una escritura a disco. Tras recortar o escalar no hace falta guardar y volver a leer——Image.from_pil(pil_image) se envía directamente (JPEG se codifica con quality 95; imágenes con transparencia o paleta se envían con format="png"). Instalación: .venv/bin/pip install "typesafe-sdk[pil]". El cookbook oficial de OCR usa justamente este camino: buscar campos en la página completa, recortar la región, ampliarla y volver a preguntar en detalle sobre el recorte.
Ordenar documentos escaneados por el borde top. El truco del cookbook de registros de vacunas: un Box por línea, box["box"]["top"] menor va primero——solo con código se leen filas desordenadas como registros ordenados. El caso completo está en práctica con imágenes.
Las imágenes no tienen un precio aparte. Cada imagen se factura como tokens de entrada, al mismo precio que el texto; usage.input_tokens incluye los tokens de todas las imágenes. Las imágenes también ocupan longitud de contexto (64k por solicitud / 32k por pregunta)——meter demasiadas imágenes grandes provocará max_tokens_exceeded; los detalles están en modelos y precios.
El conjunto de respuestas del SDK. Box también se puede obtener desde response.boxes["target"]——es la entrada específica de Box para el mismo lote de respuestas que response.answers["target"].
Resumen de la lección
✅ Uso de Jev Box: Image en el state, Box(instructions=...) con una frase que diga qué buscar; con el encabezado de Danger Zone activado ya se puede preguntar.
✅ Leer la respuesta: los cuatro bordes son proporciones en 0–1 (left/right se multiplican por el ancho, top/bottom por la altura); la misma respuesta vale para cualquier tamaño de imagen.
✅ confidence: Box la trae de serie, no hay umbral oficial recomendado——si está por debajo de tu propia línea, amplía los bordes y recorta, o cambia a una mejor imagen y vuelve a preguntar.
✅ Puerta de control: Box siempre devuelve un cuadro; Noul pregunta «está o no», y si la respuesta es baja se ignora el cuadro.
✅ Característica experimental: dreamer-ready; el formato y la precisión pueden cambiar entre versiones, ideal para la fase de prototipo.
Repaso de los campos de configuración clave:
| Campo | Escritura recomendada | Descripción |
|---|---|---|
type | "box" | Valor fijo |
instructions | Una frase: qué buscar y en qué imagen | No tiene que ser una pregunta; no lleva criteria |
| Encabezado de solicitud | extra_headers={"TypeSafe-Danger-Zone-Images": "true"} | Obligatorio en toda solicitud con imagen/Box |
Image(...) | Ruta / bytes / from_base64 / from_pil | from_pil requiere typesafe-sdk[pil] |
| Dimensiones de imagen | Por lado 280–1568 píxeles, lado más largo ≤ 1568 | Enderezar primero (el EXIF no se aplica); superado el límite se rechaza directamente |
| Acceso a la respuesta | response.answers["id"].box / response.boxes["id"] | .box son los cuatro bordes, .confidence 0–1 |
Para ver el uso completo de Box en un proyecto real: Práctica con imágenes: leer documentos escaneados y verificar resultados de OCR——localización línea por línea de registros de vacunas, verificación campo por campo del OCR de facturas, registro de especies de una cámara para pájaros, tres cookbook con el flujo completo.
Preguntas frecuentes
¿Qué es Jev?
Jev es un modelo de evaluación proporcionado por TypeSafe que se invoca mediante API; no es un software local que deba instalarse. La versión usada en esta página es jev-1.14.0 (a la que jev-latest ya apunta); basta con enviar la petición con el SDK de Python typesafe-sdk, consultando el código del paso 2.
¿Cómo se despliega Jev?
Jev no requiere que lo despliegues tú mismo: se ejecuta en el servidor, y basta con instalar typesafe-sdk en .venv y configurar TYPESAFE_API_KEY en las variables de entorno para poder enviar peticiones. Esta es una de las razones por las que esta página lo recomienda: permite hacer localización de imágenes sin entrenar ni desplegar un modelo de visión dedicado.
¿Dónde se consultan los documentos oficiales de Jev?
Los límites y directrices oficiales para peticiones de imágenes están en images.md, citado en esta página; los detalles de versiones del modelo y de facturación se encuentran en Modelos y precios, y el ejemplo de curl multipart para conexión HTTP directa en Referencia rápida de la API.
¿Qué relación tiene Jev con los registros de vacunación?
Los registros de vacunación son un escenario de ejemplo del cookbook oficial: se usa Box para localizar línea por línea los registros de vacunación escaneados y luego, según box["box"]["top"], se ordenan las líneas desordenadas en un registro con secuencia. El caso completo se encuentra en Práctica con imágenes.
Avance de la próxima lección
Con esto ya cubrimos todo el uso de preguntas individuales: has repasado las cinco formas de preguntar (Choice / Score / Noul / confidence / Box). Ahora toca convertirlas en un sistema. Próxima lección: Flujos de trabajo eficientes: cuatro patrones de arquitectura junto con un coding agent.
Aprenderás:
- Patrón paralelo para preguntar un lote de preguntas en una sola solicitud: medición oficial de 12.2 veces menos coste y 10 veces más velocidad
- Enrutamiento con umbral de confianza: la respuesta te dice «qué es», y confidence te dice «si actuar»
- Puntuación combinada: descomponer juicios complejos en Score atómicos y fusionarlos con pesos en código
- Dejar que Claude Code instale el Agent Skill de TypeSafe para que escriba por ti el código que llama a Jev