Configuración de la cuenta y comportamiento de la API
Parte del comportamiento de su cuenta se configura una sola vez, en la página de ajustes del perfil de la aplicación web, no a través de esta API. Esta página explica, para cada uno de esos ajustes, exactamente cómo se manifiesta en v1: si la API lo sigue de forma incondicional o si permite anularlo por solicitud. Esta información no se distribuye deliberadamente entre las documentaciones de endpoints individuales, sino que se recopila aquí porque el comportamiento transversal es fácil de pasar por alto si solo se lee la página de referencia de un endpoint a la vez.
La regla general
v1 lee directamente la configuración actual de su cuenta y la aplica. No existe un sistema de configuración separado a nivel de API y (con una excepción deliberada, más abajo) no hay forma de anular un ajuste de la cuenta para una sola solicitud. Esto es intencional: mantener dos lugares independientes para configurar el mismo comportamiento (la aplicación web y una configuración de API paralela) inevitablemente terminaría desincronizándose, y el objetivo es que la misma cuenta se comporte de la misma manera sin importar qué superficie —aplicación web, esta API o el complemento de Google Sheets— haya iniciado el procesamiento.
Configuraciones y su comportamiento en la API
| Configuración | Comportamiento en la web | Comportamiento en la API v1 | ¿Se puede anular por solicitud? |
|---|---|---|---|
Anotación automática de bboxauto_annotate_bbox | Un interruptor a nivel de cuenta. Cuando está activado, cada extracción completada activa automáticamente una pasada de anotación de bbox de pago. | Se sigue exactamente: los lotes creados y procesados a través de v1 obedecen este interruptor sin excepción. Si está activado, se le puede facturar la anotación de bbox incluso si nunca llama a POST /documents/{document_id}/bbox usted mismo. | No. No hay forma a nivel de solicitud de omitirlo o forzarlo. |
Calidad de procesamientothinking_type | Una configuración a nivel de cuenta que elige un nivel de velocidad/calidad para el procesamiento. | La única excepción a la regla anterior. Cuando omite quality en POST /batches/{batch_name}/process, se recurre a la configuración actual de su cuenta (mismo comportamiento que en la web). Pero también puede pasar quality: "fast" o quality: "high" en esa solicitud para anularla solo para esa llamada. | Sí — la única configuración de esta página que puede anular por solicitud. |
Retención de datosauto_delete / auto_delete_after | Una configuración a nivel de cuenta para eliminar automáticamente las imágenes originales N días después del procesamiento. | Se sigue exactamente: los documentos creados a través de v1 están sujetos a la misma política de retención que cualquier archivo subido mediante la web. | No. |
| Modo de procesamiento (interno rec_mode, expuesto como mode) | La web actualmente admite extracción en formato tabla y conversión completa del documento a Word. | v1 actualmente solo admite mode=table (extracción de campos estructurados). La conversión completa del documento está planificada pero aún no disponible a través de la API. | No aplica todavía — solo hay un valor para elegir. Cuando se implementen más modos, será una adición pura, no un cambio de comportamiento al valor existente. |
¿Por qué no añadir simplemente anulaciones a nivel de solicitud?
La anotación automática de bbox y la política de retención se tratan como gobernanza a nivel de cuenta, no como preferencias por llamada: son el tipo de interruptor de «activado para todo o desactivado para todo» donde permitir que una llamada API se desvíe silenciosamente de la configuración vigente de la cuenta crearía exactamente el problema de desviación entre dos fuentes de configuración que este diseño evita. quality es diferente: qué nivel de velocidad/calidad tiene sentido puede variar genuinamente de una llamada a otra (este lote necesita salir rápido, aquel necesita máxima precisión), por lo que se trata como una decisión operativa en lugar de un ajuste de gobernanza, y se habilita como la única anulación.