# Processi e attesa limitata

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

Fonte: https://scifig.ai/it/docs/api/jobs

## 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`.

```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` è `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 risultato | Presente | Significato |
| --- | --- | --- |
| file_id | always | Passalo a un altro endpoint o a `GET /files/{file_id}` |
| format | always | Estensione del file risultante, ad esempio `png`, `svg` o `pdf` |
| width, height | Risultati PNG | Dimensioni in pixel |
| download_url, expires_at | always | Link firmato, valido per un’ora |
| editor_url | processi di grafici e diagrammi di flusso | Apre il risultato nel suo spazio di lavoro sul sito; illustrazioni e conversioni non hanno questo link |

## Ciclo degli stati

| status | Significato |
| --- | --- |
| queued | Accettato, in attesa di capacità |
| processing | In esecuzione |
| succeeded | Completato; gli `outputs` sono pronti e i crediti addebitati |
| failed | Nessun risultato prodotto; `error.code` indica il motivo e la riserva viene rimborsata |
| canceled | Interrotto prima del completamento; crediti rimborsati |

| `error.code` di un processo fallito | Significato | Cosa fare |
| --- | --- | --- |
| TASK_TIMED_OUT | L’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_REJECTED | La 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_INCOMPLETE | Il 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_FOUND | Il processo è stato ammesso, ma la relativa attività non è più reperibile. | Invia una nuova richiesta con una nuova chiave |
| TASK_FAILED | L’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_ERROR | L’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

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