Caixas Delimitadoras (bbox)

bbox localiza onde na página original um valor extraído foi originado — coordenadas que você pode usar para destacar ou cortar aquela região da imagem.

bbox é uma segunda passagem opcional e faturada separadamente, não algo que vem gratuito com toda extração. Não é incluído automaticamente em uma chamada normal de process ou em results a menos que você solicite explicitamente — e, importante, também pode ser acionado automaticamente por uma configuração de conta mesmo que você nunca chame os endpoints bbox. Veja "Faturamento e configurações de conta" abaixo antes de assumir que seu uso corresponde apenas ao que você solicitou explicitamente.

Acionando anotação

Assim que um documento terminar a extração (status: "succeeded"), acione a passagem bbox explicitamente:

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

Isso gasta créditos e enfileira um job bbox (202 Accepted) — ou, se um job bbox para este documento já estiver em execução de uma chamada anterior a este mesmo endpoint, retorna 200 sem enfileirar ou cobrar novamente. Esta flag already_running é sobre um segundo job bbox para o mesmo documento, não sobre a extração do documento — você só pode acessar este endpoint em um documento que já está status: "succeeded", portanto a extração em si nunca é o que está "já em execução" aqui:

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

Este endpoint aceita um cabeçalho Idempotency-Key — veja Idempotência, já que esta é uma ação paga que gasta créditos.

Verificando status e 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 nenhum job de bbox foi acionado para este documento — um estado muito comum e esperado, não um erro. As coordenadas são floats x1/y1/x2/y2 normalizados no intervalo 0–1 (cantos superior esquerdo e inferior direito), independentes das dimensões reais em pixels da imagem original.

Em vez de consultar este endpoint repetidamente, registre um webhook (veja o Guia de Webhooks) no lote do documento — um job de bbox que atinge um status terminal entrega um evento document.bbox_completed para a mesma URL de callback, junto com quaisquer eventos batch.completed que ela já recebe. Não há uma etapa de registro separada para bbox especificamente; ele reutiliza o webhook existente do lote.

Obtendo bbox inline com os resultados

Em vez dos endpoints independentes acima, você também pode solicitar que o endpoint de resultados do lote preencha dados de bbox já calculados com ?include=bbox:

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

Ao fazer isso, cada valor de campo em line_items muda de um escalar simples para {"value": ..., "bbox": ...}, com bbox definido como null se nada foi calculado para aquele campo:

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

?include=bbox apenas lê dados que já existem — nunca aciona um novo job de anotação faturável em seu nome. Se o bbox de um campo ainda não foi calculado, você recebe null para ele, sem cobrança implícita. Acione a anotação explicitamente com POST .../bbox primeiro.

Campos que são inteiramente uma localização

Alguns campos não são um trecho de texto com uma localização incidental — o propósito inteiro do campo é a localização (por exemplo, um campo pedindo para "localizar a foto do retrato" em um documento de identidade). Para estes, o valor retorna como um objeto mais rico, independentemente de você ter solicitado ?include=bbox, já que a localização é a resposta, não metadados opcionais sobre ela:

{
  "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 aponta para GET /documents/{document_id}/image?crop=... — um JPEG cortado real e buscável daquela região (com um leve preenchimento além das coordenadas brutas para que um corte apertado tenha menos chance de cortar parte do que você queria), não apenas quatro números que você teria que recortar da imagem original. Você também pode chamar esse endpoint diretamente com seu próprio ?crop=x1,y1,x2,y2 (mesma convenção normalizada de 0–1) em qualquer documento, independentemente de ele ter vindo de um job bbox.

Limitação conhecida: coordenadas são diretas do modelo, não verificadas por pixel

As coordenadas bbox vêm diretamente da fundamentação visual do modelo subjacente — não há nenhuma etapa de verificação ao nível do pixel que verifique se uma determinada caixa está desenhada de forma apertada ou solta em torno de seu alvo. Em documentos simples e esparsos, isso geralmente é próximo o suficiente para uso direto. Em documentos complexos ou densamente preenchidos — tabelas com muitas colunas, formulários com campos muito próximos — a precisão degrada consideravelmente, e as caixas podem acabar muito apertadas, muito soltas ou, ocasionalmente, referenciar o campo errado próximo. Não trate a saída bbox como uma fonte de corte exata e perfeita ao nível do pixel — se seu fluxo de trabalho depende de corte preciso (para OCR downstream, evidência legal, etc.), verifique os resultados em vez de confiar cegamente, especialmente em layouts densos.

Os cortes de conveniência image_url (tanto para campos de localização pura quanto para suas próprias chamadas ?crop= contra uma caixa derivada de bbox) são gerados com uma pequena quantidade de preenchimento ao redor das coordenadas informadas, para reduzir a chance de um corte muito apertado cortar conteúdo real — esta é uma medida de tolerância, não uma correção de precisão. As coordenadas bbox brutas retornadas no próprio JSON são sempre exatamente o que o modelo informou, sem preenchimento.

Faturamento e configurações da conta

A execução da anotação de bbox não é determinada 100% por você chamar ou não os endpoints de bbox. Sua conta possui uma configuração — auto_annotate_bbox, definida no aplicativo web, não por meio desta API — que, quando ativada, aciona automaticamente (e fatura) uma passagem de bbox após toda extração concluída, inclusive aquelas iniciadas via v1. Se sua conta tiver essa configuração ativada, você pode ser faturado pela anotação de bbox sem nunca chamar POST .../bbox diretamente. Consulte Configurações da Conta e Comportamento da API para obter o panorama completo de quais configurações no nível da conta a API permite ou não que você substitua por solicitação.