SciFig
Inizia gratis

Riferimento API

Processi e attesa limitata

Consulta stato, crediti e risultati e attendi un processo senza interrogazioni periodiche.

Visualizza in Markdown

Consulta un processo#

GET /jobs/{id}, con ambito figures:read, restituisce lo stesso oggetto di processo della richiesta di creazione. I processi di altri account e gli identificativi sconosciuti restituiscono entrambi 404 NOT_FOUND. GET /jobs?limit=10&cursor=… elenca i tuoi processi dal più recente; da 1 a 20 per pagina, segui 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 è image_generation, image_edit, image_upscale, image_conversion, chart o flowchart. Le risposte non includono mai la tua descrizione, gli input o identificativi interni.

Campo del risultatoPresenteSignificato
file_idalwaysPassalo a un altro endpoint o a GET /files/{file_id}
formatalwaysEstensione del file risultante, ad esempio png, svg o pdf
width, heightRisultati PNGDimensioni in pixel
download_url, expires_atalwaysLink firmato, valido per un’ora
editor_urlprocessi di grafici e diagrammi di flussoApre il risultato nel suo spazio di lavoro sul sito; illustrazioni e conversioni non hanno questo link

Ciclo degli stati#

statusSignificato
queuedAccettato, in attesa di capacità
processingIn esecuzione
succeededCompletato; gli outputs sono pronti e i crediti addebitati
failedNessun risultato prodotto; error.code indica il motivo e la riserva viene rimborsata
canceledInterrotto prima del completamento; crediti rimborsati
`error.code` di un processo fallitoSignificatoCosa fare
TASK_TIMED_OUTL’attività ha superato il tempo limite e i crediti sono stati rimborsati. Una generazione o modifica di illustrazione può includere late_delivery_until: fino a quel momento il risultato può ancora arrivare gratuitamente.Continua a consultare il processo fino a late_delivery_until; altrimenti invia una nuova richiesta con una nuova chiave
CONTENT_REJECTEDLa politica sui contenuti ha rifiutato il risultato durante l’esecuzione; i crediti sono stati rimborsati. Lo stesso codice viene restituito come 422 quando la richiesta stessa viene rifiutata alla creazione.Modifica la descrizione o l’input e usa una nuova chiave
ADMISSION_INCOMPLETEIl processo non è mai stato avviato perché un errore che consente un nuovo tentativo lo ha impedito. Nessun credito è stato usato.Invia la stessa richiesta con lo stesso Idempotency-Key
TASK_NOT_FOUNDIl processo è stato ammesso, ma la relativa attività non è più reperibile.Invia una nuova richiesta con una nuova chiave
TASK_FAILEDL’attività non è riuscita e i crediti sono stati rimborsati. Ogni errore del motore senza un codice pubblico proprio diventa TASK_FAILED; il codice del motore è in details.reason.Invia una nuova richiesta con una nuova chiave
INTERNAL_ERRORL’attività non è riuscita senza indicare il motivo; i crediti sono stati rimborsati.Invia una nuova richiesta con una nuova chiave

succeeded, failed e canceled sono definitivi, con un’eccezione: una generazione o modifica di illustrazione fallita con TASK_TIMED_OUT include late_delivery_until. Fino a quel momento il risultato può ancora arrivare gratuitamente e il processo passare a succeeded; continua a consultarlo invece di crearne uno nuovo.

Se un processo nell’elenco non può essere letto, GET /jobs restituisce 503 SERVICE_UNAVAILABLE con Retry-After: 3; riprova la richiesta dell’elenco. Quel processo non viene sostituito con un risultato fallito.

Attesa limitata#

  • Prefer: wait=N, da 1 a 30, su una richiesta di creazione trattiene la risposta finché il processo è definitivo o trascorrono N secondi. I processi definitivi restituiscono 200; quelli ancora in esecuzione restituiscono 202 con Location: /api/v1/jobs/{id} e Retry-After.
  • L’attesa non cambia il processo: 202 non è un errore e il processo continua dopo la risposta.
  • Interroga GET /jobs/{id} non più spesso di Retry-After, cioè 3 secondi. Le illustrazioni terminano solitamente in 20–90 secondi, grafici e diagrammi di flusso in 30–120 secondi.
  • Un processo fallito può rappresentare anche una richiesta rifiutata: una creazione rifiutata con un errore come 402 INSUFFICIENT_CREDITS o 422 CONTENT_REJECTED rimane in GET /jobs come processo failed con quel codice e senza crediti.
  • Le integrazioni server devono salvare l’identificativo del processo prima di attendere, così una connessione interrotta non causa mai un secondo processo.

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())
PrecedenteCreazione e modifica di diagrammi di flussoSuccessivoCreditiL’API usa i tuoi crediti SciFig: un solo saldo per sito, API e MCP.