Configurações da Conta e Comportamento da API
Parte do comportamento da sua conta é configurada uma vez, na página de configurações do perfil do aplicativo web — não por meio desta API. Esta página explica, para cada uma dessas configurações, exatamente como ela se manifesta na v1: se a API a segue incondicionalmente ou se permite substituí-la por requisição. Isso não é distribuído de forma esparsa pela documentação de endpoints individuais — está reunido aqui porque o comportamento transversal é fácil de perder se você ler apenas a página de referência de um endpoint por vez.
A regra geral
A v1 lê a configuração atual da sua conta diretamente e a aplica — não há um sistema de configuração em nível de API separado e (com uma exceção deliberada, abaixo) não há como substituir uma configuração da conta para uma única requisição. Isso é intencional: manter dois lugares independentes para configurar o mesmo comportamento (o aplicativo web e uma configuração de API paralela) inevitavelmente levaria a divergências, e o objetivo é que a mesma conta se comporte da mesma forma, independentemente de qual superfície — aplicativo web, esta API ou o Google Sheets Add-on — iniciou o processamento.
Configurações e seu comportamento na API
| Configuração | Comportamento no Web App | Comportamento na API v1 | Substituível por requisição? |
|---|---|---|---|
Anotação automática de bboxauto_annotate_bbox | Uma opção em nível de conta. Quando ativada, toda extração concluída aciona automaticamente uma passagem paga de anotação de bbox. | Seguido exatamente — lotes criados e processados via v1 obedecem a essa opção sem exceção. Se estiver ativada, pode haver cobrança pela anotação de bbox mesmo que o usuário nunca chame POST /documents/{document_id}/bbox diretamente. | Não. Não há forma em nível de requisição de ignorar ou forçar essa opção. |
Qualidade de processamentothinking_type | Uma configuração em nível de conta que escolhe um nível de velocidade/qualidade para o processamento. | A única exceção à regra acima. Quando quality é omitido em POST /batches/{batch_name}/process, o sistema usa a configuração atual da conta — mesmo comportamento do web app. Porém, também é possível passar quality: "fast" ou quality: "high" nessa requisição para substituí-la apenas naquela chamada. | Sim — a única configuração desta página que pode ser substituída por requisição. |
Retenção de dadosauto_delete / auto_delete_after | Uma configuração em nível de conta para excluir automaticamente imagens originais N dias após o processamento. | Seguido exatamente — documentos criados via v1 estão sujeitos à mesma política de retenção que qualquer arquivo enviado pelo web app. | Não. |
| Modo de processamento (interno rec_mode, exposto como mode) | O web app atualmente suporta extração em formato de tabela e conversão completa do documento para Word. | A v1 atualmente suporta apenas mode=table (extração de campos estruturados). A conversão completa do documento está planejada, mas ainda não disponível via API. | Não aplicável no momento — há apenas um valor disponível. Quando mais modos forem lançados, isso será uma adição pura, não uma mudança de comportamento no valor existente. |
Por que não simplesmente adicionar substituições em nível de requisição?
A anotação automática de bbox e a política de retenção são tratadas como governança em nível de conta, não como preferências por chamada — são o tipo de chave "ligado para tudo, ou desligado para tudo" onde permitir que uma única chamada de API se desvie silenciosamente da configuração vigente da conta criaria exatamente o problema de divergência entre duas fontes de configuração que este design evita. quality é diferente: qual nível de velocidade/qualidade faz sentido pode variar genuinamente de chamada para chamada (este lote precisa ser processado rapidamente, aquele precisa de máxima precisão), portanto é tratado como uma escolha operacional em vez de uma configuração de governança, e é aberto como a única substituição.