Référence API

Tâches et attente limitée

Name: SciFig
Author: SciFig

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

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.

{
  "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#

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

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#

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

PrécédentCréation et modification de diagrammes de flux SuivantCréditsL’API utilise vos crédits SciFig : un seul solde pour le site, l’API et MCP.