# Crediti

L’API usa i tuoi crediti SciFig: un solo saldo per sito, API e MCP.

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

## Consulta il saldo

`GET /credits`, con ambito `figures:read`, restituisce il saldo, i crediti riservati dai processi in esecuzione, il piano e i suoi limiti delle attività:

```json
{
  "balance": 2950,
  "reserved": 100,
  "granted_scopes": ["figures:read", "figures:generate"],
  "plan": "plus",
  "plan_level": 2,
  "limits": { "concurrent_tasks": 5, "tasks_per_hour": 200 },
  "top_up_url": "https://scifig.ai/pricing?utm_source=api"
}
```

- `plan` è `free`, `starter`, `plus` o `pro`. Un account con saldo positivo di crediti acquistati in pacchetti viene trattato come `pro` finché il saldo dura.
- `tasks_per_hour` è 200 per tutti i piani; `concurrent_tasks` dipende dal piano.
- `top_up_url` include `utm_source=api` per le richieste dirette all’API e `utm_source=mcp` per quelle effettuate tramite il server MCP.
- `granted_scopes` elenca le autorizzazioni delle credenziali attuali: `figures:read` e, quando consentito, `figures:generate`.

`GET /pricing` restituisce tutti i prezzi senza autenticazione; i prezzi su queste pagine provengono dalla stessa tabella. Non esiste un piano API separato: acquista crediti o un abbonamento sulla [pagina dei prezzi](/it/pricing).

## Ciclo di vita della riserva

- Creare un processo ne riserva il prezzo in modo atomico; due richieste non possono mai spendere gli stessi crediti.
- Senza crediti sufficienti, la risposta è `402 INSUFFICIENT_CREDITS` con `details.top_up_url`: non viene riservato né eseguito nulla. La richiesta rifiutata rimane in `GET /jobs` come processo fallito con quell’errore e ripetere la sua chiave restituisce la stessa risposta.
- Un processo riuscito addebita la riserva esattamente una volta; un processo fallito o annullato la restituisce integralmente. I tentativi interni non riservano altri crediti e ripetere un `Idempotency-Key` riutilizza la riserva iniziale.
- Ogni processo riporta `credits.reserved`, `credits.charged` e `credits.refunded`, letti dal registro contabile.
- I crediti vengono usati nello stesso ordine del sito: prima quelli che scadono prima e, per ultimi, quelli dei pacchetti, che non scadono.

## cURL

```bash
curl https://scifig.ai/api/v1/credits \
  -H "Authorization: Bearer $SCIFIG_API_KEY"
```

## JavaScript

```javascript
const response = await fetch('https://scifig.ai/api/v1/credits', {
  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/credits",
    headers=headers,
    timeout=60,
)
print(response.status_code, response.json())
```