# Dateien

Eingaben hochladen und Ergebnisse herunterladen.

Quelle: https://scifig.ai/de/docs/api/files

## Hochladen

`POST /files` akzeptiert `multipart/form-data` und erfordert den Berechtigungsbereich `figures:generate`. Es gibt `201` mit `file_id`, `purpose`, `content_type`, `size_bytes`, `expires_at` und `created_at` zurück.

| Feld | Typ | Erforderlich | Standard | Regeln |
| --- | --- | --- | --- | --- |
| file | file | ja | — | Siehe die Limits je Verwendungszweck unten |
| purpose | string | nein | `image` | `image`, `mask` oder `flowchart_attachment` |

| Verwendungszweck | Akzeptiert | Verwendet für |
| --- | --- | --- |
| image | PNG, JPEG oder WebP bis 20 MB; Prüfung anhand des Inhalts, nicht des Namens | Bearbeitung, Texterkennung, Vergrößerung, Konvertierung, Referenzbilder |
| mask | PNG bis 8 MB; Weiß markiert den neu zu zeichnenden Bereich | `POST /images/edits` |
| flowchart_attachment | Formate des FlowChart-Arbeitsbereichs, bis 32 MB | `POST /flowcharts/generations` |

Uploads können 24 Stunden lang verwendet werden. Danach ist die `file_id` unbekannt: `400 INVALID_REQUEST`, `FILE_NOT_FOUND`. Sie dienen ausschließlich als Eingaben, erscheinen nie in Auftragsantworten und werden niemandem freigegeben.

Uploads zählen zu denselben Uploadlimits wie auf der Website. Bei Überschreitung lautet die Antwort `429 RATE_LIMITED` mit `Retry-After` und `details.reason` gleich `UPLOAD_RATE_LIMITED` pro Minute oder `UPLOAD_DAILY_LIMIT_REACHED` pro Tag für Flussdiagrammanhänge.

Ein Upload kann einen optionalen `Idempotency-Key`-Header mit 1–255 sichtbaren ASCII-Zeichen senden. Dasselbe Konto, derselbe Schlüssel und `purpose` verweisen immer auf eine `file_id`: Eine Wiederholung gibt die erste Datei mit `201` zurück, ohne erneuten Upload oder Verbrauch des Uploadlimits. Derselbe Schlüssel und `purpose` mit anderen Bytes führen zu `409 IDEMPOTENCY_CONFLICT`. Ohne Header erstellt jeder Upload eine neue Datei. Ist der Upload abgelaufen, führt eine Wiederholung zu `400 INVALID_REQUEST` mit `details.reason = FILE_EXPIRED`; laden Sie die Datei mit einem neuen Schlüssel erneut hoch.

## Herunterladen

Jedes Auftragsergebnis hat eine `download_url`, die ohne Zugangsdaten eine Stunde lang funktioniert. Fragen Sie den Auftrag erneut ab, um einen neuen Link zu erhalten. `GET /files/{file_id}` lädt mit Ihren Zugangsdaten jede Ihrer Dateien herunter. Dateien werden stets als Anhänge ausgeliefert.

Eine signierte `download_url` gibt nach Ablauf oder bei Veränderung `404 NOT_FOUND` zurück. Sämtliche Links eines gesperrten oder in Löschung befindlichen Kontos funktionieren auf dieselbe Weise nicht mehr.

| Ergebnis | Verwendbar für |
| --- | --- |
| PNG oder JPEG | Jeden Bildendpunkt: Bearbeitung, Texterkennung, Vergrößerung, Konvertierung, Referenzbilder |
| WebP | Bearbeitung, Texterkennung, Vergrößerung, SVG-Vektorisierung und Referenzbilder; keine Konvertierung in PNG, PDF, TIFF oder PPTX |
| Flussdiagramm-SVG | `POST /images/conversions` in PNG, PDF, TIFF oder PPTX |
| PDF, TIFF, EPS, PPTX, sonstiges SVG | Keine weitere Verwendung; nur Download |

Eine Konvertierungsquelle größer als 20 MB, etwa eine 8K-Vergrößerung, wird mit `400 INVALID_REQUEST` und `FILE_TOO_LARGE` abgelehnt.

## cURL

```bash
curl -X POST https://scifig.ai/api/v1/files \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -F "file=@figure.png" \
  -F "purpose=image"
```

## JavaScript

```javascript
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.set('file', new Blob([await readFile('figure.png')]), 'figure.png');
form.set('purpose', 'image');

const response = await fetch('https://scifig.ai/api/v1/files', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
  },
  body: form,
});
const result = await response.json();
console.log(response.status, result);
```

## Python

```python
import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
}
response = requests.post(
    "https://scifig.ai/api/v1/files",
    headers=headers,
    files={"file": open("figure.png", "rb")},
    data={"purpose": "image"},
    timeout=60,
)
print(response.status_code, response.json())
```