# Tâches et attente limitée

Consultez le statut, les crédits et les résultats, et attendez une tâche sans interrogations répétées.

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

## Consulter une tâche

`GET /jobs/{id}`, avec la portée `figures:read`, renvoie le même objet de tâche que la requête de création. Les tâches d’autres comptes et les identifiants inconnus renvoient tous deux `404 NOT_FOUND`. `GET /jobs?limit=10&cursor=…` liste vos tâches, les plus récentes d’abord ; de 1 à 20 par page, suivez `next_cursor`.

```json
{
  "id": "5f4a9a5e-fc45-4eae-9f9c-56b5f686cba5",
  "kind": "chart",
  "status": "succeeded",
  "created_at": "2026-10-14T11:20:05.000Z",
  "credits": { "reserved": 50, "charged": 50, "refunded": 0 },
  "outputs": [
    {
      "file_id": "0b7c…",
      "format": "png",
      "width": 2126,
      "height": 1417,
      "download_url": "https://scifig.ai/api/v1/files/0b7c…?exp=…&sig=…",
      "expires_at": "2026-10-14T12:21:40.000Z",
      "editor_url": "https://scifig.ai/app/datachart?conversation=…"
    }
  ],
  "error": null
}
```

`kind` vaut `image_generation`, `image_edit`, `image_upscale`, `image_conversion`, `chart` ou `flowchart`. Les réponses ne contiennent jamais votre description, vos entrées ou des identifiants internes.

| Champ du résultat | Présent | Signification |
| --- | --- | --- |
| file_id | always | À transmettre à un autre point d’accès ou à `GET /files/{file_id}` |
| format | always | Extension du fichier produit, par exemple `png`, `svg` ou `pdf` |
| width, height | Résultats PNG | Dimensions en pixels |
| download_url, expires_at | always | Lien signé, valable une heure |
| editor_url | tâches de graphique et de diagramme de flux | Ouvre le résultat dans son espace de travail sur le site ; les illustrations et conversions n’ont pas ce lien |

## Cycle des statuts

| status | Signification |
| --- | --- |
| queued | Acceptée, en attente de capacité |
| processing | En cours |
| succeeded | Terminée ; les `outputs` sont prêts et les crédits facturés |
| failed | Aucun résultat produit ; `error.code` indique la cause et la réservation est remboursée |
| canceled | Arrêtée avant la fin ; crédits remboursés |

| `error.code` d’une tâche échouée | Signification | Marche à suivre |
| --- | --- | --- |
| TASK_TIMED_OUT | La tâche a dépassé le délai et les crédits ont été remboursés. Une génération ou une modification d’illustration peut contenir `late_delivery_until` : le résultat peut encore arriver gratuitement jusqu’à cette échéance. | Continuez à consulter la tâche jusqu’à `late_delivery_until` ; sinon, envoyez une nouvelle requête avec une nouvelle clé |
| CONTENT_REJECTED | La politique de contenu a refusé le résultat pendant l’exécution ; les crédits ont été remboursés. Le même code est renvoyé avec `422` lorsque la requête elle-même est refusée à la création. | Modifiez la description ou l’entrée et utilisez une nouvelle clé |
| ADMISSION_INCOMPLETE | La tâche n’a jamais démarré, car une erreur permettant une nouvelle tentative l’a empêchée. Aucun crédit n’a été utilisé. | Envoyez la même requête avec le même Idempotency-Key |
| TASK_NOT_FOUND | La tâche a été admise, mais son exécution est désormais introuvable. | Envoyez une nouvelle requête avec une nouvelle clé |
| TASK_FAILED | La tâche a échoué et les crédits ont été remboursés. Tout échec de moteur sans code public propre devient `TASK_FAILED` ; le code du moteur se trouve dans `details.reason`. | Envoyez une nouvelle requête avec une nouvelle clé |
| INTERNAL_ERROR | La tâche a échoué sans indiquer de raison ; les crédits ont été remboursés. | Envoyez une nouvelle requête avec une nouvelle clé |

`succeeded`, `failed` et `canceled` sont définitifs, à une exception près : une génération ou modification d’illustration échouée avec `TASK_TIMED_OUT` contient `late_delivery_until`. Jusqu’à cette échéance, le résultat peut encore arriver gratuitement et la tâche passer à `succeeded` ; continuez à la consulter plutôt que d’en créer une nouvelle.

Si une tâche de la liste ne peut pas être lue, `GET /jobs` renvoie `503 SERVICE_UNAVAILABLE` avec `Retry-After: 3` ; réessayez la requête de liste. La tâche n’est pas remplacée par un résultat échoué.

## Attente limitée

- `Prefer: wait=N`, de 1 à 30, sur une requête de création retient la réponse jusqu’à l’état définitif de la tâche ou l’écoulement de N secondes. Les tâches définitives renvoient `200` ; celles encore en cours renvoient `202` avec `Location: /api/v1/jobs/{id}` et `Retry-After`.
- L’attente ne modifie pas la tâche : `202` n’est pas une erreur et la tâche continue après la réponse.
- N’interrogez pas `GET /jobs/{id}` plus souvent que `Retry-After`, soit 3 secondes. Les illustrations se terminent généralement en 20–90 secondes, les graphiques et diagrammes de flux en 30–120 secondes.
- Une tâche échouée peut aussi représenter une requête refusée : une création refusée avec une erreur telle que `402 INSUFFICIENT_CREDITS` ou `422 CONTENT_REJECTED` reste dans `GET /jobs` comme tâche `failed` avec ce code et sans crédits.
- Les intégrations serveur doivent enregistrer l’identifiant de tâche avant d’attendre, afin qu’une connexion interrompue ne crée jamais une seconde tâche.

## cURL

```bash
curl https://scifig.ai/api/v1/jobs/<job_id> \
  -H "Authorization: Bearer $SCIFIG_API_KEY"
```

## JavaScript

```javascript
const response = await fetch('https://scifig.ai/api/v1/jobs/<job_id>', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
  },
});
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.get(
    "https://scifig.ai/api/v1/jobs/<job_id>",
    headers=headers,
    timeout=60,
)
print(response.status_code, response.json())
```