# Fichiers

Importer les entrées et télécharger les résultats.

Source : https://scifig.ai/fr/docs/api/files

## Importer

`POST /files` accepte `multipart/form-data` et exige la portée `figures:generate`. Il renvoie `201` avec `file_id`, `purpose`, `content_type`, `size_bytes`, `expires_at` et `created_at`.

| Champ | Type | Obligatoire | Valeur par défaut | Règles |
| --- | --- | --- | --- | --- |
| file | file | oui | — | Voir les limites par usage ci-dessous |
| purpose | string | non | `image` | `image`, `mask` ou `flowchart_attachment` |

| Usage | Accepté | Utilisé pour |
| --- | --- | --- |
| image | PNG, JPEG ou WebP jusqu’à 20 MB, vérifié d’après le contenu et non le nom | Modifications, détection de texte, agrandissements, conversions, images de référence |
| mask | PNG jusqu’à 8 MB ; le blanc indique la zone à redessiner | `POST /images/edits` |
| flowchart_attachment | Formats de l’espace de travail FlowChart, jusqu’à 32 MB | `POST /flowcharts/generations` |

Les fichiers importés peuvent être utilisés pendant 24 heures ; ensuite, leur `file_id` est inconnu : `400 INVALID_REQUEST`, `FILE_NOT_FOUND`. Ils servent uniquement d’entrées : ils n’apparaissent jamais dans les réponses des tâches et ne sont partagés avec personne.

Les importations sont comptées dans les mêmes limites que sur le site. Au-delà, la réponse est `429 RATE_LIMITED` avec `Retry-After` et `details.reason` égal à `UPLOAD_RATE_LIMITED` par minute ou `UPLOAD_DAILY_LIMIT_REACHED` par jour pour les pièces jointes de diagrammes de flux.

Une importation peut envoyer un en-tête facultatif `Idempotency-Key` de 1 à 255 caractères ASCII visibles. Un même compte, une même clé et un même `purpose` correspondent toujours à un seul `file_id` : une répétition renvoie le premier fichier avec `201`, sans nouvelle importation ni consommation du quota. La même clé et le même `purpose` avec des octets différents renvoient `409 IDEMPOTENCY_CONFLICT`. Sans cet en-tête, chaque importation crée un nouveau fichier. Si le fichier importé a expiré, une répétition renvoie `400 INVALID_REQUEST` avec `details.reason = FILE_EXPIRED` ; importez-le à nouveau avec une nouvelle clé.

## Télécharger

Chaque résultat de tâche possède un `download_url` utilisable sans identifiants pendant une heure ; consultez à nouveau la tâche pour obtenir un nouveau lien. `GET /files/{file_id}` avec vos identifiants télécharge n’importe lequel de vos fichiers. Les fichiers sont toujours servis en pièces jointes.

Un `download_url` signé renvoie `404 NOT_FOUND` après expiration ou modification ; tous les liens d’un compte banni ou en cours de suppression cessent également de fonctionner ainsi.

| Résultat | Peut être transmis à |
| --- | --- |
| PNG ou JPEG | Tous les points d’accès d’image : modifications, détection de texte, agrandissements, conversions, images de référence |
| WebP | Modifications, détection de texte, agrandissements, vectorisation SVG et images de référence ; pas les conversions PNG, PDF, TIFF ou PPTX |
| SVG de diagramme de flux | `POST /images/conversions` vers PNG, PDF, TIFF ou PPTX |
| PDF, TIFF, EPS, PPTX, autres SVG | Aucun : téléchargement uniquement |

Une source de conversion de plus de 20 MB, par exemple un agrandissement 8K, est refusée avec `400 INVALID_REQUEST` et `FILE_TOO_LARGE`.

## 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())
```