Cuadros Delimitadores (bbox)

bbox localiza dónde en la página original se originó un valor extraído — coordenadas que puede usar para resaltar o recortar esa región de la imagen.

bbox es un segundo paso opcional y facturado por separado, no algo que venga incluido con cada extracción. No se incluye automáticamente en una llamada normal a process ni en results a menos que lo solicite explícitamente — y, algo importante, también puede activarse automáticamente mediante una configuración a nivel de cuenta incluso si nunca llama usted mismo a los endpoints de bbox. Consulte "Facturación y configuración de cuenta" más abajo antes de asumir que su uso coincide solo con lo que solicitó explícitamente.

Activar la anotación

Una vez que un documento haya terminado de extraerse (status: "succeeded"), active el paso bbox explícitamente:

curl -X POST https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/bbox \
  -H "Authorization: Bearer $API_KEY"

Esto consume créditos y pone en cola un trabajo bbox (202 Accepted) — o, si un trabajo bbox para este documento ya está en ejecución por una llamada anterior a este mismo endpoint, devuelve 200 sin poner en cola ni cobrar de nuevo. Esta bandera already_running se refiere a un segundo trabajo bbox para el mismo documento, no a la extracción del documento — solo puede acceder a este endpoint en un documento que ya tenga status: "succeeded", por lo que la extracción en sí nunca es lo que "ya está en ejecución" aquí:

{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "group_batch_id": "bx_8a3c2e1f",
  "status": "processing",
  "already_running": false,
  "row_groups": 1
}

Este endpoint acepta un encabezado Idempotency-Key — consulte Idempotencia, ya que se trata de una acción de pago que consume créditos.

Verificación del estado y los resultados

curl https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/bbox \
  -H "Authorization: Bearer $API_KEY"

{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "exists": true,
  "status": "succeeded",
  "group_batch_id": "bx_8a3c2e1f",
  "rows": {
    "0": {
      "invoice_number": { "x1": 0.121, "y1": 0.084, "x2": 0.312, "y2": 0.108, "unit": "normalized" },
      "total_amount": { "x1": 0.702, "y1": 0.611, "x2": 0.881, "y2": 0.639, "unit": "normalized" }
    }
  }
}

exists: false significa que nunca se ha activado un trabajo de bbox para este documento; es un estado muy común y esperado, no un error. Las coordenadas son valores flotantes x1/y1/x2/y2 normalizados al rango 0–1 (esquinas superior izquierda e inferior derecha), independientes de las dimensiones reales en píxeles de la imagen original.

En lugar de consultar este endpoint, registre un webhook (consulte la guía de Webhooks) en el lote del documento; un trabajo de bbox que alcanza un estado terminal entrega un evento document.bbox_completed a esa misma URL de callback, junto con los eventos batch.completed que ya recibe. No hay un paso de registro separado específico para bbox; reutiliza el webhook existente del lote.

Obtención de bbox en línea con los resultados

En lugar de los endpoints independientes anteriores, también puede solicitar al endpoint de resultados del lote que complete los datos de bbox ya calculados con ?include=bbox:

curl "https://imagetotable.ai/api/v1/batches/260716-4K9P/results?include=bbox" \
  -H "Authorization: Bearer $API_KEY"

Al hacerlo, cada valor de campo en line_items cambia de forma, de un escalar simple a {"value": ..., "bbox": ...}, con bbox establecido en null si no se ha calculado nada para ese campo:

{ "invoice_number": { "value": "INV-1042", "bbox": { "x1": 0.121, "y1": 0.084, "x2": 0.312, "y2": 0.108, "unit": "normalized" } } }

?include=bbox solo lee datos que ya existen; nunca activa un nuevo trabajo de anotación facturable en su nombre. Si el bbox de un campo aún no se ha calculado, obtendrá null para ese campo, no un cargo implícito. Active la anotación explícitamente con POST .../bbox primero.

Campos que son completamente una ubicación

Algunos campos no son un fragmento de texto con una ubicación incidental; el propósito completo del campo es la ubicación (por ejemplo, un campo que solicita "ubicar la foto de retrato" en un documento de identidad). Para estos, el valor se devuelve como un objeto más completo independientemente de si solicitó ?include=bbox, ya que la ubicación es la respuesta, no metadatos opcionales sobre ella:

{
  "portrait_location": {
    "type": "image_region",
    "bbox": { "x1": 0.05, "y1": 0.12, "x2": 0.28, "y2": 0.44, "unit": "normalized" },
    "image_url": "https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/image?crop=0.03%2C0.10%2C0.30%2C0.46"
  }
}

image_url apunta a GET /documents/{document_id}/image?crop=... — un recorte JPEG real y recuperable de esa región (rellenado ligeramente más ancho que las coordenadas brutas para que un recorte ajustado tenga menos probabilidades de recortar parte de lo que deseaba), no solo cuatro números que tendría que recortar de la imagen original usted mismo. También puede llamar a ese endpoint directamente con su propio ?crop=x1,y1,x2,y2 (misma convención normalizada 0–1) en cualquier documento, ya sea que provenga o no de un trabajo de bbox.

Limitación conocida: las coordenadas son directas del modelo, no verificadas a nivel de píxel

Las coordenadas bbox provienen directamente del fundamento visual del modelo subyacente; no hay ningún paso de verificación a nivel de píxel que compruebe si un cuadro dado está dibujado de forma ajustada o holgada alrededor de su objetivo. En documentos simples y dispersos, esto suele ser lo suficientemente preciso como para usarlo directamente. En documentos complejos o densamente empaquetados — tablas con muchas columnas, formularios con campos muy espaciados — la precisión se degrada notablemente, y los cuadros pueden quedar demasiado ajustados, demasiado holgados u ocasionalmente hacer referencia al campo cercano incorrecto. No trate la salida de bbox como una fuente de recorte exacta y perfecta a nivel de píxel — si su flujo de trabajo depende de un recorte preciso (para OCR posterior, evidencia legal, etc.), verifique los resultados en lugar de confiar ciegamente en ellos, especialmente en diseños densos.

Los recortes de conveniencia de image_url (tanto para campos de ubicación pura como para sus propias llamadas ?crop= contra un cuadro derivado de bbox) se generan con una pequeña cantidad de relleno alrededor de las coordenadas informadas, para reducir la posibilidad de que un cuadro demasiado ajustado recorte contenido real — esto es una medida de indulgencia, no una corrección de precisión. Las coordenadas bbox brutas devueltas en el propio JSON son siempre exactamente lo que informó el modelo, sin relleno.

Facturación y configuración de la cuenta

El hecho de que se ejecute la anotación de bbox no depende al 100% de que usted mismo llame a los endpoints de bbox. Su cuenta tiene un ajuste — auto_annotate_bbox, configurado en la aplicación web, no a través de esta API — que, cuando está activado, activa automáticamente (y factura) un pase de bbox después de cada extracción completada, incluyendo las iniciadas a través de v1. Si su cuenta tiene este ajuste activado, se le puede facturar la anotación de bbox sin que usted llame nunca a POST .../bbox. Consulte Configuración de la cuenta y comportamiento de la API para obtener una visión completa de qué ajustes a nivel de cuenta la API permite o no anular por solicitud.