Zum Inhalt springen

Dateien hochladen

Das Hochladen erfolgt in drei Schritten: Anforderung einer Upload-Adresse, Senden der Datei und Bestätigung des Dokuments. Eine Upload-Adresse kann einmalig angefordert werden und ist bis zu 1 Stunde gültig.

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-Type: application/json
{
"filename": "report.docx",
"file_size": 45678
}
FeldTypErforderlichBeschreibung
filenameZeichenfolge✅Dateiname; der Server ermittelt den Dateityp anhand der Erweiterung
file_sizeGanzzahl✅Genauer Wert in Byte, größer als 0
mime_typeZeichenfolge—Optional; der Server verwendet es nicht

Antwort:

{
"document_id": "4q8mx2q9z1k7p6ra",
"upload_url": "https://upload.example/...",
"upload_headers": {
"Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"If-None-Match": "*"
},
"finalize_token": "short_lived_token",
"expires_in": 3600
}

Senden Sie eine PUT an upload_url mit den Rohdatei-Bytes als Nachrichtentext und übermitteln Sie jeden Header in upload_headers exakt wie angegeben.

Terminal-Fenster
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous response
curl --fail-with-body -X PUT "$UPLOAD_URL" \
-H "Content-Type: $UPLOAD_CONTENT_TYPE" \
-H "If-None-Match: *" \
--upload-file "report.docx"

Senden Sie in diesem Schritt nicht Ihren OmniDoc API-Schlüssel. Wenn die Adresse abläuft oder die Überweisung fehlschlägt, beantragen Sie einen neuen.

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-Type: application/json
{"finalize_token":"short_lived_token"}

Bei Erfolg wird das Dokument zurückgegeben:

{
"document": {
"id": "4q8mx2q9z1k7p6ra",
"basename": "report.docx",
"file_size": 45678,
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"created_at": "2026-10-01T12:00:00Z"
}
}

Erst nach der Bestätigung wird das Dokument in die Dateibibliothek übernommen und für Aufträge nutzbar.

filename dient ausschließlich der Anzeige; verwenden Sie es nicht als Pfad oder eindeutige Kennung. Der Server ersetzt ungültige Zeichen und erzeugt einen sicheren Downloadnamen für zu lange Namen.

StatusUrsache
400Ungültiger Dateiname oder -größe, oder die hochgeladene Größe weicht von der angeforderten ab.
401Anmeldeinformation oder finalize_token ungültig oder abgelaufen
403Das finalize_token gehört einem anderen Konto
410Die hochgeladene Datei wurde nicht gefunden (Übertragung unvollständig oder Adresse abgelaufen); bitte fordern Sie eine neue Adresse an.
413Überschreitet das Größenlimit pro Datei
415Nicht unterstütztes Format oder der Inhalt stimmt nicht mit der Erweiterung überein.
422Die Datei Office ist beschädigt oder strukturell unsicher.
429Zu viele Uploads
503Der Upload-Dienst ist vorübergehend nicht verfügbar; bitte versuchen Sie es später erneut.