Stapelklassifizierung
Stapelklassifizierungs-Endpunkt – klassifizieren Sie bis zu 1.000 Produkte in einer einzigen Anfrage mit Echtzeit-Fortschrittsanzeige.
Der Stapelklassifizierungs-Endpunkt ermöglicht es Ihnen, bis zu 1.000 Produkte in einer einzigen Anfrage zu klassifizieren. Wie bei der Einzelklassifizierung erfolgt die Verarbeitung asynchron mit Echtzeit-Fortschrittsanzeige.
Erstellen einer Stapelklassifizierung
POST
/v1/classify/batchBody-Parameter (JSON)
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
items | object[] | Ja | Liste der zu klassifizierenden Produkte (1 bis 1.000) |
items[].id | string | Nein | Benutzerdefinierte Kennung zur Zuordnung der Ergebnisse |
items[].content | string | Ja | Produktbeschreibung |
items[].image_urls | string[] | Nein | URLs zu Produktbildern |
locale | "fr" | "en" | "es" | Nein | Antwortsprache (Standard: "fr") |
Beispielanfrage
curl -X POST https://api.thetradehub.eu/v1/classify/batch \
-H "X-API-Key: th_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"id": "SKU-001",
"content": "Wireless Bluetooth headphones with active noise cancellation"
},
{
"id": "SKU-002",
"content": "Men organic cotton t-shirt, size L"
},
{
"id": "SKU-003",
"content": "Extra virgin olive oil, 750ml glass bottle, origin Spain"
}
],
"locale": "en"
}'import httpx
client = httpx.Client(
base_url="https://api.thetradehub.eu",
headers={"X-API-Key": "th_live_your_api_key"},
)
response = client.post("/v1/classify/batch", json={
"items": [
{"id": "SKU-001", "content": "Wireless Bluetooth headphones with active noise cancellation"},
{"id": "SKU-002", "content": "Men organic cotton t-shirt, size L"},
{"id": "SKU-003", "content": "Extra virgin olive oil, 750ml glass bottle, origin Spain"},
],
"locale": "en",
})
batch = response.json()
print(f"Batch created: {batch['id']} - {batch['total']} items")const response = await fetch("https://api.thetradehub.eu/v1/classify/batch", {
method: "POST",
headers: {
"X-API-Key": "th_live_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [
{ id: "SKU-001", content: "Wireless Bluetooth headphones with active noise cancellation" },
{ id: "SKU-002", content: "Men organic cotton t-shirt, size L" },
{ id: "SKU-003", content: "Extra virgin olive oil, 750ml glass bottle, origin Spain" },
],
locale: "en",
}),
});
const batch = await response.json();
console.log(`Batch created: ${batch.id} - ${batch.total} items`);Antwort (202 Accepted)
{
"id": "batch_f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"status": "processing",
"total": 3,
"completed": 0,
"failed": 0,
"progress": 0,
"created_at": "2026-02-24T10:30:00Z",
"updated_at": "2026-02-24T10:30:00Z"
}Status des Stapels abfragen
GET
/v1/classify/batch/{batch_id}Pfadparameter
| Parameter | Typ | Beschreibung |
|---|---|---|
batch_id | string (UUID) | Beim Erstellen zurückgegebene Stapelkennung |
Mögliche Status
| Status | Beschreibung |
|---|---|
processing | Der Stapel wird verarbeitet |
completed | Alle Elemente wurden verarbeitet |
partial | Der Stapel wurde abgeschlossen, aber einige Elemente sind fehlgeschlagen |
failed | Der gesamte Stapel ist fehlgeschlagen |
Beispiel für Abfrage (Polling)
curl https://api.thetradehub.eu/v1/classify/batch/batch_f1e2d3c4-b5a6-7890-abcd-ef1234567890 \
-H "X-API-Key: th_live_your_api_key"import httpx
import time
client = httpx.Client(
base_url="https://api.thetradehub.eu",
headers={"X-API-Key": "th_live_your_api_key"},
)
batch_id = "batch_f1e2d3c4-b5a6-7890-abcd-ef1234567890"
delay = 2
while True:
response = client.get(f"/v1/classify/batch/{batch_id}")
batch = response.json()
print(f"Fortschritt: {batch['progress'] * 100:.0f}% ({batch['completed']}/{batch['total']})")
if batch["status"] in ("completed", "partial"):
for item in batch["items"]:
if item["status"] == "completed":
hs = item["result"]["classification"]["rankings"][0]["hs_code"]
print(f" {item['id']} → {hs}")
else:
print(f" {item['id']} → Fehler: {item.get('error')}")
break
elif batch["status"] == "failed":
print(f"Stapel-Fehler: {batch.get('error')}")
break
time.sleep(delay)
delay = min(delay * 1.5, 10)const API_KEY = "th_live_your_api_key";
const batchId = "batch_f1e2d3c4-b5a6-7890-abcd-ef1234567890";
async function pollBatch(batchId) {
let delay = 2000;
while (true) {
const response = await fetch(
`https://api.thetradehub.eu/v1/classify/batch/${batchId}`,
{ headers: { "X-API-Key": API_KEY } }
);
const batch = await response.json();
console.log(`Fortschritt: ${Math.round(batch.progress * 100)}% (${batch.completed}/${batch.total})`);
if (batch.status === "completed" || batch.status === "partial") {
for (const item of batch.items) {
if (item.status === "completed") {
const hs = item.result.classification.rankings[0].hs_code;
console.log(` ${item.id} → ${hs}`);
} else {
console.log(` ${item.id} → Fehler: ${item.error}`);
}
}
return batch;
}
if (batch.status === "failed") {
throw new Error(batch.error);
}
await new Promise((r) => setTimeout(r, delay));
delay = Math.min(delay * 1.5, 10000);
}
}
const result = await pollBatch(batchId);Vollständige Antwort (Status: completed)
Jedes Element enthält die gleiche Ergebnisstruktur wie die Einzelklassifizierung.
{
"id": "batch_f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"status": "completed",
"total": 3,
"completed": 3,
"failed": 0,
"progress": 1.0,
"items": [
{
"id": "SKU-001",
"status": "completed",
"result": {
"classification": {
"rankings": [
{
"rank": 1,
"hs_code": "8518.30.00",
"description": "Kopfhörer und Ohrhörer",
"confidence": 0.94,
"gri_justification": "GIR 1 - Die Position 8518 umfasst speziell Kopfhörer und Ohrhörer.",
"validated": true
}
]
},
"text": "Basierend auf EU verbindlichen Zolltarifauskünften (vZTA) und der TARIC-Nomenklatur...",
"session_id": "sess_abc123"
}
},
{
"id": "SKU-002",
"status": "completed",
"result": {
"classification": {
"rankings": [
{
"rank": 1,
"hs_code": "6109.10.00",
"description": "T-Shirts und Unterhemden aus Baumwolle",
"confidence": 0.97,
"gri_justification": "GIR 1 - Das Produkt ist ein Baumwoll-T-Shirt, speziell unter Position 6109 erfasst.",
"validated": true
}
]
},
"text": "Klassifizierung unter Position 6109 für gestrickte Artikel...",
"session_id": "sess_def456"
}
},
{
"id": "SKU-003",
"status": "completed",
"result": {
"classification": {
"rankings": [
{
"rank": 1,
"hs_code": "1509.10.90",
"description": "Natives Olivenöl",
"confidence": 0.96,
"gri_justification": "GIR 1 - Position 1509 umfasst Olivenöl. Unterposition 1509.10: natives Öl.",
"validated": true
}
]
},
"text": "Klassifizierung unter Position 1509 für Olivenöle...",
"session_id": "sess_ghi789"
}
}
],
"created_at": "2026-02-24T10:30:00Z",
"updated_at": "2026-02-24T10:30:45Z"
}Antwortstruktur
| Feld | Typ | Beschreibung |
|---|---|---|
id | string | Eindeutige Stapelkennung |
status | string | Gesamtstatus des Stapels |
total | number | Gesamtanzahl der Elemente |
completed | number | Anzahl erfolgreich verarbeiteter Elemente |
failed | number | Anzahl fehlgeschlagener Elemente |
progress | number | Fertigstellungsgrad (0,0 bis 1,0) |
items | object[] | Ergebnisse je Element – gleiche Struktur wie bei der Einzelklassifizierung |
Persistente Ergebnisse
Ergebnisse sind dauerhaft zugänglich über denselben Endpunkt:
GET /v1/classify/batch/{batch_id}- Während der Verarbeitung / erste 24 Stunden — aus Cache, inklusive Live-Fortschritt
- Nach 24 Stunden — transparenter Fallback auf die Datenbank, vollständige Ergebnisse jederzeit verfügbar
Es ist nicht erforderlich, Ergebnisse clientseitig zu speichern. Sie können jeden vergangenen Stapel jederzeit mit der ursprünglichen batch_id abrufen.
Best Practices
| Empfehlung | Details |
|---|---|
| Stapelgröße | Maximal 1.000 Elemente pro Anfrage |
| Abfrageintervall (Polling) | Beginnen Sie mit 2 Sekunden Intervall, dann schrittweise erhöhen |
| Identifikatoren | Verwenden Sie items[].id zur Zuordnung mit Ihren Daten |
| Fehlerbehandlung bei Teilfehlern | Prüfen Sie den status jedes Elements in items |
| Timeout | Planen Sie 30 Sekunden + 5 Sekunden pro Element für große Stapel ein |
| Ergebnis-Speicherung | Nicht erforderlich – Ergebnisse sind dauerhaft über batch_id zugänglich |
Last updated on