Umgebungseinrichtung

Diese Seite richtet sich an alle, die noch nie eine HTTP-API über ein Terminal aufgerufen haben. Wenn Sie bereits mit curl und Umgebungsvariablen vertraut sind, springen Sie direkt zu Schnellstart.

Client installieren

Sie benötigen ein Tool, das eine HTTP-Anfrage mit benutzerdefinierten Headern senden kann. Zwei gängige Optionen:

• curl – ein Befehlszeilen-Tool, das auf macOS und Linux meist bereits installiert ist. Überprüfen Sie dies mit curl --version in einem Terminal. Unter Windows installieren Sie es über curl.se/windows oder nutzen Sie curl, das in Git Bash / WSL enthalten ist. Jedes Beispiel in dieser Dokumentation ist zuerst als curl-Befehl geschrieben.
• Postman (oder Insomnia) – eine grafische App zum Erstellen und Speichern von Anfragen, nützlich, wenn Sie lieber durch ein Formular klicken als Shell-Befehle schreiben. Installieren Sie es von postman.com/downloads und erstellen Sie dann jedes curl-Beispiel auf dieser Seite nach, indem Sie die URL, Methode, Header und den Body in eine neue Anfrage kopieren.

Verwendung der Python-Beispiele

Jedes Codebeispiel auf dieser Seite hat einen Python-Reiter, der auf der beliebten requests-Bibliothek basiert – kein offizielles ImageToTable.ai SDK (wir veröffentlichen keins; es handelt sich um einfache HTTP-Aufrufe mit einem beliebigen Standard-Client). Sie benötigen:

• Python 3.8+ – überprüfen Sie dies mit python3 --version. Holen Sie es sich von python.org/downloads, falls es fehlt.
• requests – nicht Teil der Standardbibliothek, installieren Sie es zuerst:

  pip install requests

  (oder pip3 install requests, je nach System).

Die Exportbeispiele, die die heruntergeladene Datei (xlsx/docx) parsen, verwenden außerdem openpyxl / python-docx – nur erforderlich, wenn Sie diese spezifischen Beispiele nachvollziehen, installieren Sie sie mit pip install openpyxl python-docx.

Verwendung der JavaScript-Beispiele

Der JavaScript-Tab verwendet die native fetch-API – keine Bibliothek muss installiert werden – setzt aber eine einigermaßen aktuelle Laufzeitumgebung voraus:

• Node.js 20+ bei serverseitiger Ausführung – prüfen Sie mit node --version. Die Beispiele verwenden await auf oberster Ebene und das globale crypto.randomUUID(), beides benötigt ein aktuelles Node; bei Node 18 (inzwischen End-of-Life) ist crypto außerhalb von CommonJS/REPL nicht zuverlässig global verfügbar, und diese Beispiele können mit einem verwirrenden Fehler crypto is not defined fehlschlagen, der nichts mit Ihrem API-Key zu tun hat. Laden Sie eine aktuelle Version von nodejs.org herunter.
• Oder fügen Sie das Snippet einfach in die DevTools-Konsole eines Browsers ein – jeder moderne Browser unterstützt dieselben APIs (fetch, FormData, crypto.randomUUID()) nativ, keine Installation erforderlich.

API-Key abrufen

Ihr API-Key wird auf der Profilseite Ihres Kontos ausgestellt. Die v1 API ist für kostenpflichtige Tarife (Basic und höher) verfügbar; die Verwendung mit einem Free-Tarif-Key gibt einen plan_required-Fehler zurück (keinen fehlenden Authentifizierungsfehler), da der Key selbst gültig ist – er darf nur noch nicht die v1 API verwenden.

API-Key als Umgebungsvariable speichern

Fügen Sie Ihren Key nicht direkt in einen Befehl ein, den Sie möglicherweise teilen, screenshotten oder in die Versionsverwaltung einchecken. Exportieren Sie ihn stattdessen in Ihre Shell-Sitzung und referenzieren Sie ihn in jeder Anfrage als $API_KEY – jedes Beispiel auf dieser Seite setzt voraus, dass diese Variable existiert:

export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Dies gilt nur für Ihre aktuelle Terminalsitzung. Für eine dauerhaftere Lösung fügen Sie dieselbe Zeile der Startdatei Ihrer Shell hinzu (~/.bashrc, ~/.zshrc oder entsprechend) – oder, wenn Sie ein Skript schreiben, laden Sie sie aus einer .env-Datei / einem Secrets-Manager, anstatt sie im Quellcode fest zu codieren.

Testanfrage senden

Bestätigen Sie Ihren Key und die Einrichtung, bevor Sie zu echten Dokumenten übergehen:

curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"

Ein funktionierender Key in einem kostenpflichtigen Tarif gibt Ihre Kontozusammenfassung zurück (Tarif, Rolle, verfügbare Credits). Bei allem anderen siehe die Fehlerbehebungs-Checkliste unten.

Fehlerbehebungs-Checkliste

Jeder v1-Fehler wird als JSON mit type/code/message zurückgegeben – die vollständige Liste finden Sie in der Anleitung Fehlerbehandlung. Die schnellsten ersten Überprüfungen für eine Anfrage, die nicht funktioniert:

• Erhalten Sie missing_api_key? Prüfen Sie, ob der Header exakt Authorization: Bearer <key> lautet – das Wort Bearer, ein einzelnes Leerzeichen, dann der Key. Ein fehlendes Leerzeichen oder ein überflüssiges Anführungszeichen in $API_KEY führt beides zu diesem Fehler.
• Erhalten Sie invalid_api_key? Der Key stimmt mit keinem Konto überein oder das Konto ist deaktiviert. Kopieren Sie ihn erneut von Ihrer Profilseite – Keys sind lang und beim Kopieren leicht zu kürzen.
• Erhalten Sie plan_required? Ihr Key ist gültig, aber Ihr Konto befindet sich im Free-Tarif. Führen Sie ein Upgrade auf Basic oder höher durch, um v1 zu nutzen.
• Erhalten Sie einen Verbindungsfehler, keine JSON-Antwort? Überprüfen Sie, ob die URL mit https://imagetotable.ai/api/v1/ beginnt und dass Sie -X POST (oder das richtige Verb) für Endpunkte verwenden, die dies erfordern – eine GET-Anfrage an einen POST-only-Endpunkt erreicht die Route überhaupt nicht.
• Laden Sie eine Datei hoch und erhalten einen unerwarteten Fehler? Multipart-Datei-Uploads benötigen -F "file=@/pfad/zur/datei.jpg" (cURLs Form-Upload-Flag), nicht -d oder einen rohen JSON-Body – diese Verwechslung ist der häufigste Upload-Fehler. Das führende @ teilt cURL mit, diesen Pfad als echte Datei auf Ihrem eigenen Rechner zu lesen – es ist keine URL, und die Datei muss bereits dort existieren, bevor Sie den Befehl ausführen. Wenn Sie keine lokale Datei zur Hand haben, überspringen Sie dies vollständig: Übergeben Sie stattdessen ein url-Feld anstelle von file, und der Server holt sie für Sie ab – siehe Schnellstart.
• Erhalten Sie rate_limit_exceeded? Siehe Ratenbegrenzungen – die Grenzen gelten pro Konto, nicht pro erwartetem Anfragetyp, sodass ein Burst von Polling-Aufrufen dieselbe Grenze auslösen kann wie ein Burst von Uploads.