Powered by

# URL-Datei-Import

Startet einen asynchronen Import: Die API lädt eine oder mehrere Dateien von presignten URLs herunter, extrahiert deren Text und legt daraus Dokumente samt Chunks an – entweder in einem neu erzeugten oder in einem bestehenden Korpus. Dies ist der programmatische Weg zu demselben Ergebnis, das im aiStudio über Neue Datenquelle einlesen erreicht wird.

Voraussetzungen für alle Anfragen (Basis-URL, Authorization- und kauz-chatbot-Header) finden Sie im Überblick . Grundbegriffe (Korpus/Dokument/Chunk, source) finden Sie im Datenimport-Überblick .

# Dateien identifizieren

Jede Datei wird als Paar aus presignedUrl (per GET abrufbare URL) und fileName übergeben.

Maximale Dateigröße: 100 MB pro Datei.

# POST /partner/v1/data-imports/extractions/url-files

Erzeugt ein neues Korpus und extrahiert die angegebenen Dateien hinein.

# Anfrage

Feld Typ Pflicht Beschreibung
corpusName string ja Name des neu anzulegenden Korpus.
urlFiles array ja Zu importierende Dateien, je presignedUrl und fileName.
extractionParams array nein Extraktions- und Chunking-Einstellungen je Dateiendung, siehe unten.

# Antwort

Feld Typ Beschreibung
dataImportId number ID zum Abfragen des Fortschritts.
corpusId string ID des neu angelegten Korpus. 
{
  "corpusName": "string",
  "urlFiles": [
    { "presignedUrl": "https://…", "fileName": "report.pdf" }
  ]
}
 
curl --location --request POST "https://example.kauz.ai/partner/v1/data-imports/extractions/url-files" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk" \
--header "Content-Type: application/json" \
--data-raw "{
   \"corpusName\":\"Produktdokumentation\",
   \"urlFiles\":[
      { \"presignedUrl\":\"https://storage.example.com/report.pdf?sig=…\", \"fileName\":\"report.pdf\" }
   ]
}"
 
{
  "dataImportId": 4711,
  "corpusId": "b3e2c1de-5f0b-4c1e-9d33-1b8a1f0c4e77"
}

# POST /partner/v1/data-imports/extractions/url-files/for-existing-corpus

Extrahiert die angegebenen Dateien in ein bestehendes Korpus.

# Anfrage

Feld Typ Pflicht Beschreibung
corpusId string ja ID des bestehenden "file"-Korpus.
urlFiles array ja Wie oben.
extractionParams array nein Wie oben.

# Antwort

dataImportId, corpusId (wie oben).

curl --location --request POST "https://example.kauz.ai/partner/v1/data-imports/extractions/url-files/for-existing-corpus" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk" \
--header "Content-Type: application/json" \
--data-raw "{
   \"corpusId\":\"b3e2c1de-5f0b-4c1e-9d33-1b8a1f0c4e77\",
   \"urlFiles\":[
      { \"presignedUrl\":\"https://storage.example.com/addendum.pdf?sig=…\", \"fileName\":\"addendum.pdf\" }
   ]
}"

# Erweiterte Extraktionsparameter (extractionParams)

Jeder Eintrag konfiguriert die Extraktion für eine Dateiendung. Ohne Angabe gelten die im aiStudio hinterlegten Standardeinstellungen .

Feld Typ Pflicht Beschreibung
fileExtension string ja Dateiendung, für die dieser Eintrag gilt, z. B. pdf.
chunkingStrategy string ja Siehe Chunkingstrategien unten.
chunkSize number nein Ziel-Chunklänge in Token (bei fixed_length).
chunkOverlap number nein Überlappung zwischen Chunks.
chunkLevel number nein Struktur-Ebene, ab der neue Chunks gebildet werden (bei defined_chunk_level).
ignoreShortChunks boolean nein Kurze Chunks von der Antwortgenerierung ausschließen.
minimalChunkSize number nein Schwellenwert, ab dem ein Chunk als „kurz“ gilt.
includeFileName boolean nein Dateiname zusätzlich in das Embedding einfließen lassen.
csvDelimiter string nein Trennzeichen für csv-Dateien (Komma, Semikolon oder Tabulator).
imageAnalysis string nein no_image_analysis, analyse_separately oder analyse_as_one_page.
visionModel string nein Für die Bildanalyse zu verwendendes Modell.
imageProcessingDescriptions boolean nein Bildbeschreibungen erzeugen.
imageProcessingScannedText boolean nein Text aus gescannten Bildern extrahieren.
imageProcessingTablesAndDiagrams boolean nein Text aus Tabellen/Diagrammen in Bildern extrahieren.
imageDescriptionPrompt string nein Eigener Prompt für Bildbeschreibungen.
imageTableAndDiagramPrompt string nein Eigener Prompt für Tabellen/Diagramme in Bildern.

# Chunkingstrategien

Die Werte entsprechen weitgehend den im aiStudio wählbaren Strategien, siehe Crawling- und Chunkingstrategie bestimmen :

Wert Entspricht im aiStudio
fixed_length Feste Chunklänge
one_chunk_per_document Ein Chunk pro Dokument
one_chunk_per_page Ein Chunk pro Seite
text_structure Textstrukturbasiert
defined_chunk_level Chunking anhand eines vorgegebenen Struktur-Levels (chunkLevel) – im aiStudio nicht wählbar.
external Chunking wird extern vorgegeben, z. B. bei bereits vorstrukturierten Inhalten.
manual Chunk-Grenzen werden manuell vorgegeben. 
{
  "corpusName": "Produktdokumentation",
  "urlFiles": [
    { "presignedUrl": "https://…", "fileName": "report.pdf" }
  ],
  "extractionParams": [
    {
      "fileExtension": "pdf",
      "chunkingStrategy": "fixed_length",
      "chunkSize": 500,
      "chunkOverlap": 20
    }
  ]
}

# GET `/partner/v1/data-imports/

Fragt den Fortschritt eines laufenden oder abgeschlossenen Imports ab. Rufen Sie diesen Endpunkt wiederholt auf, bis alle Einträge in taskStates einen abschließenden Status erreicht haben.

# Anfrage

Parameter Typ Pflicht Beschreibung
dataImportId number ja Aus der Antwort des Start-Endpunkts.

# Antwort

Feld Typ Beschreibung
corpusId string Ziel-Korpus des Imports.
taskStates[] array Ein Eintrag je Datei, siehe unten.
documentStates[] array Bereits angelegte Dokumente, je name, size, url und numberOfChunks.

Felder je Eintrag in taskStates:

Feld Typ Beschreibung
status string pending, running, succeeded, failed, aborting, aborted oder timeout. succeeded, failed, aborted und timeout sind abschließend.
numberOfChunks number Anzahl der bisher aus dieser Datei erzeugten Chunks.
progress object step (aktueller Schritt), current/total (verarbeitete/gesamt Einheiten), description. Nur während der Verarbeitung vorhanden.
error string Fehlerursache, nur bei status: "failed".
fileMeta object name und optional size der Quelldatei. 
curl --location "https://example.kauz.ai/partner/v1/data-imports/4711/extractions/state" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk"
 
{
  "corpusId": "b3e2c1de-5f0b-4c1e-9d33-1b8a1f0c4e77",
  "taskStates": [
    {
      "status": "succeeded",
      "numberOfChunks": 18,
      "fileMeta": { "name": "report.pdf", "size": 204800 }
    }
  ],
  "documentStates": [
    { "name": "report.pdf", "size": 204800, "numberOfChunks": 18 }
  ]
}

# Fehlercodes dieses Endpunkts

Code Beschreibung
PA_ERR_1004 Datenimport nicht gefunden – dataImportId existiert nicht.
PA_ERR_1005 Text-Extraktion nicht gefunden.