Kontoeinstellungen und API-Verhalten

Einige Verhaltensweisen Ihres Kontos werden einmalig in der Web-App auf der Seite mit den Profileinstellungen konfiguriert – nicht über diese API. Diese Seite erklärt für jede dieser Einstellungen genau, wie sie sich in v1 auswirkt: ob die API sie bedingungslos befolgt oder ob Sie sie pro Anfrage überschreiben können. Diese Informationen werden bewusst nicht über einzelne Endpunkt-Dokumentationen verteilt, sondern hier gesammelt, da das übergreifende Verhalten leicht übersehen wird, wenn man nur die Referenzseite eines Endpunkts liest.

Die allgemeine Regel

v1 liest die aktuelle Konfiguration Ihres Kontos direkt aus und wendet sie an – es gibt kein separates Konfigurationssystem auf API-Ebene und (mit einer bewussten Ausnahme, siehe unten) keine Möglichkeit, eine Kontoeinstellung für eine einzelne Anfrage zu überschreiben. Dies ist beabsichtigt: Die Aufrechterhaltung zweier unabhängiger Orte zur Konfiguration desselben Verhaltens (der Web-App und einer parallelen API-Konfiguration) würde zwangsläufig zu Abweichungen führen, und das Ziel ist, dass sich dasselbe Konto gleich verhält, unabhängig davon, welche Oberfläche – Web-App, diese API oder das Google Sheets-Add-on – die Verarbeitung angestoßen hat.

Einstellungen und ihr API-Verhalten

Einstellung	Verhalten in der Web-App	Verhalten in der v1-API	Pro Anfrage überschreibbar?
bbox Auto-Annotation `auto_annotate_bbox`	Ein Schalter auf Kontoebene. Wenn aktiviert, löst jede abgeschlossene Extraktion automatisch einen kostenpflichtigen bbox-Annotationsdurchlauf aus.	Wird exakt befolgt – Batches, die über v1 erstellt und verarbeitet werden, gehorchen diesem Schalter ausnahmslos. Wenn er aktiviert ist, kann Ihnen die bbox-Annotation berechnet werden, auch wenn Sie nie selbst `POST /documents/{document_id}/bbox` aufrufen.	Nein. Es gibt keine Möglichkeit auf Anfrageebene, dies zu überspringen oder zu erzwingen.
Verarbeitungsqualität `thinking_type`	Eine Einstellung auf Kontoebene zur Auswahl einer Geschwindigkeits-/Qualitätsstufe für die Verarbeitung.	Die eine Ausnahme von der obigen Regel. Wenn Sie `quality` bei `POST /batches/{batch_name}/process` weglassen, wird auf die aktuelle Einstellung Ihres Kontos zurückgegriffen – gleiches Verhalten wie in der Web-App. Sie können jedoch auch `quality: "fast"` oder `quality: "high"` in dieser Anfrage übergeben, um sie nur für diesen Aufruf zu überschreiben.	Ja – die einzige Einstellung auf dieser Seite, die Sie pro Anfrage überschreiben können.
Datenspeicherung `auto_delete` / `auto_delete_after`	Eine Einstellung auf Kontoebene zum automatischen Löschen von Originalbildern N Tage nach der Verarbeitung.	Wird exakt befolgt – Dokumente, die über v1 erstellt wurden, unterliegen derselben Aufbewahrungsrichtlinie wie alles, was über die Web-App hochgeladen wird.	Nein.
Verarbeitungsmodus (intern `rec_mode`, exponiert als `mode`)	Die Web-App unterstützt derzeit tabellarische Extraktion und Word-Konvertierung des gesamten Dokuments.	v1 unterstützt derzeit nur `mode=table` (strukturierte Feldextraktion). Die Konvertierung des gesamten Dokuments ist geplant, aber über die API noch nicht verfügbar.	Noch nicht anwendbar – es gibt nur einen Wert zur Auswahl. Wenn weitere Modi ausgeliefert werden, ist dies eine reine Erweiterung, keine Verhaltensänderung des bestehenden Werts.

Warum nicht einfach Überschreibungen auf Anfrageebene hinzufügen?

Die bbox Auto-Annotation und die Aufbewahrungsrichtlinie werden als Governance auf Kontoebene behandelt, nicht als Einstellungen pro Aufruf – es sind Schalter vom Typ „entweder für alles an oder für alles aus“. Würde man zulassen, dass ein einzelner API-Aufruf leise von der bestehenden Kontokonfiguration abweicht, entstünde genau das Problem der Abweichung zwischen zwei Konfigurationsquellen, das dieses Design vermeidet. quality ist anders: Welche Geschwindigkeits-/Qualitätsstufe sinnvoll ist, kann von Aufruf zu Aufruf tatsächlich variieren (dieser Batch muss schnell raus, jener benötigt maximale Genauigkeit). Daher wird es als betriebliche Entscheidung und nicht als Governance-Einstellung behandelt und als einzige Überschreibungsmöglichkeit freigegeben.