Configurações da Conta e Comportamento da API
Parte do comportamento da conta é configurada uma única vez — a maior parte na página de configurações do perfil do aplicativo web, com uma exceção (nível de modelo, abaixo) definida apenas pela equipe do ImageToTable.ai — e 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 deliberadamente não está distribuído pelos documentos de endpoints individuais — está reunido aqui porque o comportamento transversal é fácil de passar despercebido se apenas a página de referência de um endpoint for lida por vez.
A regra geral
A v1 lê a configuração atual da conta diretamente e a aplica — não há um sistema de configuração separado na camada da API e (com uma exceção deliberada, abaixo) nenhuma forma de substituir uma configuração da conta em uma única requisição. Isso é intencional: manter dois lugares independentes para configurar o mesmo comportamento (o aplicativo web e uma configuração paralela da API) inevitavelmente levaria a divergências, e o objetivo é que a mesma conta se comporte da mesma forma independentemente da superfície — aplicativo web, esta API ou o complemento do Google Sheets — que iniciou o processamento.
Configurações e seu comportamento na API
| Configuração | Comportamento no app web | Comportamento na API v1 | Pode ser substituída por requisição? |
|---|---|---|---|
anotação automática de bboxauto_annotate_bbox | Um controle em nível de conta. Quando ativado, 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 esse controle sem exceção. Se estiver ativado, pode haver cobrança pela anotação de bbox mesmo que POST /documents/{document_id}/bbox nunca seja chamado diretamente. | Não. Não há como pular ou forçar em nível de requisiçã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 aplicativo web. Mas também é possível passar quality: "fast" ou quality: "high" nessa requisição para substituir a configuração 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 upload feito pelo aplicativo web. | Não. |
| Modo de processamento (interno rec_mode, exposto como mode) | O aplicativo web atualmente suporta extração em formato de tabela e conversão completa do documento para Word. | O 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 ainda — há apenas um valor para escolher. Quando mais modos forem lançados, será uma adição pura, não uma mudança de comportamento no valor existente. |
Nível de modelomodel_tier | Em qual modelo de IA as extrações de uma conta são executadas e quanto custa cada documento processado: Standard (1 crédito, o padrão para todas as contas), Advanced (3 créditos) ou Premium (6 créditos). Atribuído pela equipe do ImageToTable.ai — não há seletor de nível nas configurações da conta. | Seguido exatamente. POST /batches/{batch_name}/process deduz créditos conforme a taxa do nível atual da conta, sem possibilidade de solicitar um nível diferente para uma única chamada. O nível é fixado no momento em que esse endpoint é chamado — um documento já enfileirado mantém o nível (e o custo de créditos) com o qual foi cobrado, mesmo que o nível da conta mude antes de esse documento terminar o processamento, e é reembolsado nesse mesmo nível fixado se for posteriormente cancelado ou falhar. Consulte Uso da conta para saber como uma cobrança não Standard aparece no extrato de créditos. | Não. Mais rigoroso do que todas as outras linhas desta página: não é nem mesmo uma configuração de conta self-service no aplicativo web, portanto não há nada para ler e espelhar por requisição — a v1 não tem parâmetro de nível em nenhum lugar. |
Por que não adicionar apenas 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 interruptor "ligado para tudo, ou desligado para tudo" em que permitir que uma única chamada de API se desvie silenciosamente da configuração vigente da conta criaria exatamente o problema de duas fontes de configuração divergentes 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 enviado rápido, aquele precisa de máxima precisão), então é tratado como uma escolha operacional em vez de uma configuração de governança, e aberto como a única substituição.
O nível de modelo vai além de "sem substituição por requisição" — ele nem sequer é uma configuração de conta self-service. As outras linhas desta página são coisas que o usuário configura na página de configurações do perfil e a v1 simplesmente espelha; o nível de modelo é uma taxa que a equipe do ImageToTable.ai atribui com base na carga de trabalho que uma conta está realmente executando, já que isso muda diretamente o custo de cada documento. Expô-lo como algo que um chamador poderia alterar por requisição (ou até mesmo por conta, sem assistência) permitiria que um único valor incorreto multiplicasse silenciosamente a fatura de um lote em 3x ou 6x sem nenhuma etapa de confirmação no meio — a versão de "créditos são dinheiro real" do mesmo problema de divergência que o restante desta página evita.