# API-Schnellstart — Ergebnisse in 5 Minuten

> Ein fünfminütiger, durchgängiger Rundgang durch die ImageToTable.ai v1 API: Holen Sie sich Ihren Schlüssel, laden Sie eine Rechnung hoch, starten Sie die Verarbeitung und rufen Sie die extrahierten JSON-Daten ab.

Dieser Leitfaden führt Sie durch den gesamten Ablauf – Schlüssel holen, Dokument hochladen, Verarbeitung starten, Ergebnisse abrufen – am Beispiel einer Rechnung. Falls Sie `curl` noch nicht installiert oder eine Umgebungsvariable für Ihren Schlüssel eingerichtet haben, lesen Sie zuerst [Umgebung einrichten](/developers/environment-setup).

## Schritt 1 — API-Schlüssel holen

Ihr API-Schlüssel befindet sich auf der [Profilseite Ihres Kontos](/profile/) unter API-Schlüssel. Die v1-API erfordert einen kostenpflichtigen Tarif (Basic oder höher) – Schlüssel des Free-Tarifs werden bei der Authentifizierung akzeptiert, aber jeder darauffolgende Aufruf gibt einen `plan_required`-Fehler zurück. Neu generierte Schlüssel haben das Format `itt_live_<64 Hex-Zeichen>`; exportieren Sie Ihren als Umgebungsvariable, damit er nicht fest in einem Skript codiert wird:

```bash
export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Schritt 2 — Dokument hochladen

`POST /api/v1/documents` akzeptiert entweder eine `file` (Multipart) oder eine `url`, die der Server für Sie abruft – übergeben Sie genau eines. `batch_name` ist optional – lassen Sie es weg und die API generiert einen für Sie (wird in der Antwort zurückgegeben). Alle Dokumente, die zusammen verarbeitet werden sollen, müssen denselben `batch_name` teilen. Dieses Beispiel verwendet `url` mit einer echten Beispielrechnung auf unserer eigenen Website, sodass es genau so ausführbar ist, ohne dass eine lokale Datei benötigt wird:

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/documents \
  -H "Authorization: Bearer $API_KEY" \
  -F "url=https://imagetotable.ai/static/samples/invoice.webp"
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/documents",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    data={"url": "https://imagetotable.ai/static/samples/invoice.webp"},
)
print(response.json())
```

**Javascript**

```javascript
const formData = new FormData();
formData.append("url", "https://imagetotable.ai/static/samples/invoice.webp");

const response = await fetch("https://imagetotable.ai/api/v1/documents", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
  body: formData,
});
console.log(await response.json());
```

Haben Sie eine lokale Datei? Ersetzen Sie `url` durch ein Multipart-`file`-Feld – siehe [Dokument hochladen](/developers/reference/documents#upload-a-document) in der Referenz für die vollständige Parameterliste inklusive `batch_name`, `template_id` und `password`.

Die Antwort gibt die ID des neuen Dokuments und den Batch zurück, in dem es gelandet ist – speichern Sie `batch_name`, Sie werden ihn in den nächsten beiden Schritten benötigen:

```json
{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "batch_name": "260716-4K9P",
  "remaining_batch_capacity": 199
}
```

Das Hochladen eines mehrseitigen PDFs anstelle eines Bildes funktioniert genauso, nur dass `document_id` als *Array* zurückkommt – ein Dokument pro Seite – da jede Seite unabhängig verarbeitet wird.

## Schritt 3 – Verarbeitung starten

`POST /api/v1/batches/{batch_name}/process` startet die Extraktion. Sie können es auf eine gespeicherte [Vorlage](/developers/reference/templates-fields) über `template_id` verweisen oder – wie hier – die gewünschten Felder direkt mit `fields` für einen einmaligen Durchlauf angeben:

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": [
          {"name": "invoice_number"},
          {"name": "invoice_date"},
          {"name": "vendor_name"},
          {"name": "total_amount"}
        ]
      }'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/process",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "fields": [
            {"name": "invoice_number"},
            {"name": "invoice_date"},
            {"name": "vendor_name"},
            {"name": "total_amount"},
        ]
    },
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: [
      { name: "invoice_number" },
      { name: "invoice_date" },
      { name: "vendor_name" },
      { name: "total_amount" },
    ],
  }),
});
console.log(await response.json());
```

Dies zieht sofort Credits ab (ein Dokument pro Aufruf) und stellt das/die Dokument(e) zur Hintergrundverarbeitung in die Warteschlange:

```json
{
  "batch_name": "260716-4K9P",
  "queued": 1,
  "quality": "fast",
  "webhook_registered": false
}
```

Lassen Sie `fields` und `template_id` ganz weg, und die API leitet stattdessen selbst passende Spaltennamen ab. `quality` ist ebenfalls optional – lassen Sie es weg, und die Verarbeitung fällt auf die Geschwindigkeits-/Qualitätseinstellung Ihres Kontos zurück (siehe [Kontoeinstellungen und API-Verhalten](/developers/guides/account-settings)). `webhook_registered: false` bedeutet hier nur, dass dieser spezielle Aufruf kein `webhook_url` enthielt – es heißt nicht, dass für diesen Batch kein Webhook registriert ist; siehe die [Batch-Referenz](/developers/reference/batches#start-processing-a-batch), falls Sie einen separat über `PUT .../webhook` registrieren.

## Schritt 4 — Ergebnisse abrufen

Die Verarbeitung erfolgt asynchron — rufen Sie `GET /api/v1/batches/{batch_name}` ab, bis `all_done` `true` ist (einige Sekunden für ein einzelnes Dokument), oder registrieren Sie einen [Webhook](/developers/guides/webhooks) anstatt zu polln. Der vollständige Lebenszyklus wird im [Async Task Model](/developers/guides/async-model)-Leitfaden beschrieben.

Sobald der Vorgang abgeschlossen ist, rufen Sie die umgeformten Ergebnisse ab:

**cURL**

```bash
curl https://imagetotable.ai/api/v1/batches/260716-4K9P/results \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/results",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/results", {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

Das Antwort-JSON ist nie sprachabhängig — die Struktur ändert sich nicht je nach Client, der die Anfrage gesendet hat:

```json
{
  "batch_name": "260716-4K9P",
  "status": "succeeded",
  "created_at": "2026-07-16T09:12:03Z",
  "started_at": "2026-07-16T09:12:05Z",
  "completed_at": "2026-07-16T09:12:14Z",
  "documents": [
    {
      "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
      "filename": "invoice.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03Z",
      "started_at": "2026-07-16T09:12:05Z",
      "completed_at": "2026-07-16T09:12:14Z",
      "line_items": [
        {
          "invoice_number": "INV-1042",
          "invoice_date": "2026-06-30",
          "vendor_name": "Acme Supply Co.",
          "total_amount": "1,284.50"
        }
      ]
    }
  ]
}
```

`completed_at` wird gesetzt, sobald ein Dokument (oder auf Batch-Ebene jedes Dokument im Batch) einen Endzustand erreicht — `succeeded`, `failed` oder `canceled`. Es bleibt `null`, solange es noch `queued` oder `processing` ist, und auf Batch-Ebene bleibt es ebenfalls `null`, bis *alle* Dokumente im Batch abgeschlossen sind, auch wenn einige bereits früher fertig waren.

## Nächste Schritte

Weiterführend: Lesen Sie [Async Task Model](/developers/guides/async-model) für den vollständigen Status-Lebenszyklus, [Webhooks](/developers/guides/webhooks), um benachrichtigt zu werden anstatt abzufragen, und die [API-Referenz](/developers/reference/) für die vollständige Parameterliste jedes Endpunkts.

---

Source: https://imagetotable.ai/de/developers/quickstart