Dateien

Zwei Routen lesen Dateien mit demselben Parser, denselben Optionen und demselben Ergebnis:

Route	Funktion	Größe
`POST /namespaces/:namespace/files`	Speichert die Datei als ein durchsuchbares Dokument; eine Suche nennt die Seite, Folie oder Zeilen, die antworten	Bis zu 512 MiB und 5.000 Seiten
`POST /parse`	Gibt die Datei als Markdown zurück; speichert nichts	Bis zu 20 MiB

Scans und Bilder werden per OCR gelesen, egal wie viele Seiten es sind. Unterstützte Formate: Dateitypen.

Eine Datei hochladen

POST /namespaces/:namespace/files Senden Sie die Bytes der Datei als Body, als Dateiteil eines Multipart-Formulars oder als JSON {"url": "https://..."}, damit Conare sie abruft.

curl "https://api.conare.ai/namespaces/reports/files?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -F file=@report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const reports = conare.namespace("reports");
const file = await reports.uploadFile(await readFile("report.pdf"), "report.pdf", {
  metadata: { site: "north-pit" },
});

Response

{
  "file_id": "report.pdf",
  "name": "report.pdf",
  "type": "pdf",
  "state": "ready",
  "source_id": "src_01139ca8ca59f2556f65b60e",
  "uploaded_at": 1792618822534,
  "pages": 2,
  "ids": ["src_01139ca8ca59f2556f65b60e:report.pdf"],
  "ocr_failed": [],
  "ocr_pending": [],
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

Die Antwort wartet bis zu wait Sekunden, bis die Datei gelesen ist: 200, wenn sie ready oder failed ist, sonst 202, solange sie gelesen wird.

Optionen

Query-Parameter, für beide Routen, sofern nicht anders angegeben.

Option	Typ	Funktion
`name`	string	Der Name der Datei, bis zu 4.096 Zeichen; seine Endung unterscheidet `.csv`, `.tsv` und `.md` von Text
`id`	string	Nur Upload. Die ID der Datei, das Ende der ID ihres Dokuments; standardmäßig `name`, wobei andere Zeichen durch `-` ersetzt werden
`type`	string	`pdf`, `docx`, `pptx`, `xlsx`, `csv`, `png`, … (alle); sonst aus den Bytes, dann aus dem Namen ermittelt
`user`	string	Nur Upload. Wem die Datei gehört; das Löschen des Benutzers löscht sie
`metadata`	string	Nur Upload. Ein JSON-Objekt, das in die Metadaten des Dokuments kopiert wird
`pages`	string	Zu lesende Seiten, Folien oder Frames, etwa `1-20,25` oder `5-`
`password`	string	Öffnet eine geschützte PDF-, Word-, PowerPoint- oder Excel-Datei, bis zu 20 MiB
`layout`	boolean, Standard `false`	Jeder per OCR gelesene Teil enthält zusätzlich `blocks`: die Bereiche seiner Seite (Felder)
`wait`	Sekunden, Standard 60	Wie lange vor `202` auf das Lesen gewartet wird, bis zu 300; `0` antwortet sofort

Ein Content-Type wie application/pdf gibt ebenfalls den Typ an.
wait: true entspricht 60; die Antwort kommt immer innerhalb von 105 Sekunden. Bei Uploads antwortet false, sobald der Text gespeichert ist, mit ocr_pending.
Eine Seite außerhalb von pages wird weder gelesen noch per OCR erfasst; pages bei einer Datei ohne Seiten ergibt 400.

Vollständiges Schema: Eine Datei hochladen.

Antwort

Feld	Bedeutung
`file_id`, `name`, `type`	Die verwendete ID, der Name und der erkannte Typ (`image` für jedes Bildformat)
`state`	`queued`, `parsing`, `ocr` (OCR liest noch `ocr_pending`), `ready` oder `failed` mit `error`
`source_id`	Die Dateiquelle des Namespace; die ID des Dokuments beginnt damit
`ids`	Das eine Dokument der Datei, `["<source_id>:<file_id>"]`, sobald `ready`
`uploaded_at`	Unix-Millisekunden
`result`	`unchanged`, wenn dieselbe Datei mit demselben Namen, denselben Metadaten und Optionen schon hochgeladen wurde; nichts wird erneut gelesen
`pages`	Die Seiten einer PDF oder die Frames eines Bildes
`ocr_failed`	Seiten, die OCR nach mehreren Versuchen nicht lesen konnte; laden Sie erneut hoch, um sie zu wiederholen
`markdown`, `parts`, `without_text`	Das Ergebnis

images_without_text, pages_without_text, pages_ocr, images_ocr, sheets, slides und slides_without_text sind veraltet: parts und without_text sagen dasselbe aus.

Eine Datei prüfen

GET /namespaces/:namespace/files/:id Gibt den neuesten Upload der Datei mit denselben Feldern zurück; fragen Sie ihn nach einem 202 regelmäßig ab.

curl https://api.conare.ai/namespaces/reports/files/report.pdf \
  -H "Authorization: Bearer $CONARE_API_KEY"

const file = await reports.getFile("report.pdf");

Option	Typ	Funktion
`user`	string	Der Benutzer, für eine mit `user` hochgeladene Datei

Vollständiges Schema: Eine Datei lesen.

Gespeicherte Dokumente

Eine Datei ist ein Dokument, <source_id>:<file_id>; ihre Seiten, Folien, Tabellenzeilen, Abschnitte und Bilder sind seine Teile.

Wo	Was Sie erhalten
Suche	Eine Seite einer PDF oder eines Bildes, eine Folie oder ein Zeilenbereich einer Tabelle ist ein eigener Treffer, ID `<source_id>:<file_id>$<part>`: `$page-3`, `$slide-4`, `$<sheet>-1`
Suche in einer Text-, Markdown- oder Word-Datei	Ein Treffer, die Datei `<source_id>:<file_id>`, mit ihren Passagen von überall in ihr
Die `metadata` eines Treffers	Wo sein Teil oder seine erste Passage steht, nach den Schlüsseln unten
`GET /namespaces/:namespace/documents/:id`	Mit der ID der Datei der Text der ganzen Datei, eine Leerzeile zwischen den Seiten; mit der ID eines Teils nur dieser Teil

Wo ein Teil steht

Datei	Position in den Metadaten
PDF	`page`
Word, Text, Markdown	`part`, `heading` und bei Text `lines`
PowerPoint	`slide`
Excel, CSV, TSV	`sheet`, `rows`
Bild	`page` und `frame`
Ein Bild in Word	`image`, `heading`
Ein Bild auf einer Folie	`slide`, `image`
Ein Diagramm in einer Tabelle	`sheet`

Das Dokument hat außerdem file, file_id, file_type, uploaded_at, die metadata des Uploads und ocr: true, wenn OCR es gelesen hat. Eine früher hochgeladene Datei kann noch ein Dokument pro Teil sein, etwa <source_id>:<file_id>:page-1, bis sie erneut hochgeladen wird.

Ziel	Vorgehen
Eine Datei ersetzen	Laden Sie sie erneut mit derselben ID hoch
Sicher wiederholen	Dieselbe Datei mit demselben Namen, denselben Metadaten und Optionen antwortet `unchanged`, ganz ohne `Idempotency-Key`
Eine Datei durchsuchen	Filtern Sie nach `{ "file_id": "report.pdf" }`
Eine Seite durchsuchen	Filtern Sie nach `{ "file_id": "report.pdf", "page": 3 }`
Benutzer trennen	Laden Sie mit `user` hoch, suchen Sie mit `user`
Das Original löschen	Es bleibt erhalten, bis der Namespace oder sein Benutzer gelöscht wird

Eine Datei parsen

POST /parse Gibt die Datei als Markdown zurück und speichert nichts; jeder Schlüssel kann parsen, auch ein Nur-Modelle-Schlüssel.

curl "https://api.conare.ai/parse?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/parse \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const out = await conare.parse(await readFile("report.pdf"), { name: "report.pdf" });
if (out.state === "parsing") console.log(await conare.getParse(out.id));

Response

{
  "id": "prs_76149e8db2be257fa8a0ac01",
  "state": "done",
  "type": "pdf",
  "name": "report.pdf",
  "pages": 2,
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

Option	Typ	Funktion
`url`	string	In einem JSON-Body: eine `https`-URL unter einer öffentlichen Adresse, innerhalb von 60 Sekunden abgerufen, bis zu 20 MiB
`name`, `type`, `pages`, `password`, `layout`, `wait`		Wie beim Upload

Der Body umfasst bis zu 20 MiB, und OCR liest bis zu 100 Seiten; spätere Seiten behalten ihre Textebene.
Um eine JSON-Datei zu parsen, senden Sie sie als text/plain.

Vollständiges Schema: Eine Datei parsen.

Einen Parse-Vorgang abrufen

GET /parse/:id Ein Parse-Vorgang, der mit 202 (state: "parsing") geantwortet hat, wird 24 Stunden aufbewahrt: Rufen Sie ihn ab, bis state den Wert done hat, oder failed mit seinem error.

curl

curl https://api.conare.ai/parse/prs_0e631c59528ac4f7424dc776 \
  -H "Authorization: Bearer $CONARE_API_KEY"

Vollständiges Schema: Einen Parse-Vorgang lesen.

Ergebnis

Feld	Bedeutung
`markdown`	Die gesamte Datei; jede Seite, Folie und Tabelle beginnt mit `<!-- page 3 -->`, `<!-- slide 4 -->` oder `<!-- sheet "Q3" -->`
`parts`	In Lesereihenfolge, jeweils mit `locator`, `markdown`, `ocr` und `confidence`
`parts[].locator`	`{"page": 3}`, `{"slide": 4, "image": 1}`, `{"sheet": "Q3", "rows": "2-41"}` oder `{"part": 2, "heading": "..."}`
`parts[].ocr`	Per OCR aus dem Bild der Seite gelesen, nicht aus ihrer Textebene
`parts[].confidence`	Die Sicherheit der OCR, 0 bis 1; `null`, wenn OCR keine angab (die meisten digital erstellten Seiten)
`without_text`	`pages`, `slides` und `images` ohne Text, jedes Bild mit seinem `reason`

Die Regeln für das Markdown stehen unter Dateitypen.

Fehler

Fehler	Wann
`400 invalid_request`	Eine Option ist ungültig: `pages` bei einer Datei ohne Seiten, `wait` über 300, `metadata`, das kein JSON-Objekt ist, eine URL, die nicht `https` unter einer öffentlichen Adresse ist
`400 fetch_failed`	Die URL hat nicht mit `200` und der Datei geantwortet
`404 parse_not_found`	Kein Parse-Vorgang mit dieser ID hat in den letzten 24 Stunden mit `202` geantwortet
`409 file_replaced`	Die Datei wurde gelöscht, während die Antwort wartete
`409 user_purging`	Der Benutzer wird gerade gelöscht
`413 payload_too_large`	Über 512 MiB (Upload) oder 20 MiB (Parsen oder mit `password`)
`415 unsupported_file`	Kein unterstützter Typ oder nicht der angegebene `type`; die Meldung nennt das Format zum Speichern
`422 password_protected`	Die Datei hat ein Passwort: Senden Sie es als `password`
`422 unreadable_file`	Die Datei ist beschädigt
`422 no_text`	Keine Seite, Tabelle, Folie, kein Absatz und kein Bild enthält Text
`503 files_unavailable`	Dateien können gerade nicht gespeichert werden; versuchen Sie es später erneut

Eine Datei mit über 5.000 Seiten, Tabellen oder Folien endet als failed mit too_large.

Erste Schritte

Grundlagen

Synchronisierung

Modelle

Tools

Dateien

Eine Datei hochladen

Optionen

Antwort

Eine Datei prüfen

Gespeicherte Dokumente

Wo ein Teil steht

Eine Datei parsen

Einen Parse-Vorgang abrufen

Ergebnis

Fehler

​Eine Datei hochladen

​Optionen

​Antwort

​Eine Datei prüfen

​Gespeicherte Dokumente

​Wo ein Teil steht

​Eine Datei parsen

​Einen Parse-Vorgang abrufen

​Ergebnis

​Fehler

Eine Datei hochladen

Optionen

Antwort

Eine Datei prüfen

Gespeicherte Dokumente

Wo ein Teil steht

Eine Datei parsen

Einen Parse-Vorgang abrufen

Ergebnis

Fehler