> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Riferimento API

> URL di base, endpoint, risposte, errori e limiti d’uso.

## Panoramica

Questa pagina riassume connessione, endpoint, risposte, errori e limiti comuni dell’API Developer Platform. Recupera schemi e prezzi aggiornati dei singoli strumenti con `GET /tools`.

## URL di base e header

Aggiungi tutti i percorsi a questo URL di base.

```text theme={null}
https://api.noimosai.com/noimosToolBridge
```

Autentica con una chiave Developer Platform. Specifica Content-Type per i corpi JSON.

```http theme={null}
Authorization: Bearer nmp_...
Content-Type: application/json
```

L’esecuzione a pagamento richiede anche questo header.

```http theme={null}
Idempotency-Key: request-unique-id
```

## Endpoint

Questi sono i principali endpoint pubblici.

| Metodo e percorso | Autorizzazione richiesta | Uso |
| - | - | - |
| `GET /tools/project` | `project:read` | Consultare organizzazione e progetto della chiave |
| `GET /tools/usage` | `usage:read` | Consultare richieste contabilizzate e costi del mese UTC corrente |
| `GET /tools` | `tools:read` | Recuperare strumenti, schemi, esempi, disponibilità e prezzi |
| `POST /tools/quote` | `tools:read` | Ottenere gratuitamente la prenotazione massima stimata per l’input |
| `POST /tools/upload` | `tools:execute` | Conservare privatamente nel progetto gli input espliciti |
| `POST /tools/{tool}` | `tools:execute` | Prenotare il limite e registrare attività a pagamento |
| `GET /tools/executions` | `executions:read` | Elencare le esecuzioni del progetto |
| `GET /tools/executions/{id}` | `executions:read` | Recuperare stato, risultati e costo definitivo |
| `POST /tools/executions/{id}/cancel` | `tools:execute` | Richiedere l’annullamento |
| `GET /tools/executions/{id}/artifacts/{artifactId}/download` | `executions:read` | Ottenere un URL temporaneo per il file generato |

Filtra `GET /tools/executions` con `limit`, `before`, `status` e `tool`. `limit` accetta 1–100, con valore predefinito 20.

## Catalogo strumenti

`data` di `GET /tools` contiene versione prezzi, valuta, disponibilità di esecuzione e strumenti del catalogo.

Ogni strumento fornisce:

* `name` — Nome usato nell’URL e nel corpo di esecuzione
* `description` e `category` — Uso e classificazione
* `available` — Se i servizi esterni necessari sono configurati e lo strumento è disponibile
* `inputSchema` e `example` — JSON Schema di input ed esempio
* `models` — Modelli selezionabili con esempi, disponibilità e prezzi per modello
* `price` — Costo minimo, unità di fatturazione e descrizione dei prezzi

`available: true` non garantisce l’esecuzione. Si applicano anche `executionEnabled`, autorizzazioni, saldo e limiti mensili.

## Formato delle risposte

Le risposte riuscite contengono di norma il risultato in `data`.

```json theme={null}
{
  "data": {}
}
```

Gli errori contengono stato e messaggio in `error`.

```json theme={null}
{
  "error": {
    "status": "PERMISSION_DENIED",
    "message": "platform_api_key_scope_required"
  }
}
```

Tutte le risposte usano `Cache-Control: no-store`. Non salvare chiavi, risultati o URL temporanei nelle cache condivise.

## Gestire gli errori

Verifica la causa secondo lo stato prima di ritentare.

| HTTP | Significato | Azione |
| - | - | - |
| `200` | Lettura riuscita o stessa esecuzione completata | Elaborare `data` |
| `202` | Attività asincrona accettata | Salvare ID e attendere almeno cinque secondi |
| `400` | Input, preventivo o stato non valido | Verificare catalogo e preventivo |
| `401` | Autenticazione fallita | Verificare Authorization, scadenza e revoca |
| `403` | Accesso negato | Verificare permessi di chiave e progetto |
| `404` | Endpoint, operazione o artefatto non disponibile | Verificare percorso, disponibilità e scadenza |
| `409` | Chiave di idempotenza usata per un’altra richiesta | Verificare corpo e chiave originali; evitare un’altra esecuzione |
| `429` | Limite richieste, saldo o tetto mensile raggiunto | Verificare limite e saldo interessati |
| `503` | Esecuzione o servizio esterno temporaneamente indisponibile | Verificare l’accettazione del lavoro a pagamento prima di ritentare |

## Limiti d’uso

Considera questi limiti nel client.

| Risorsa | Limite |
| - | - |
| Richiesta JSON normale | 64 KiB in UTF-8 |
| File caricato | 12 MiB |
| Formati accettati | JPEG, PNG, WAV, MP3, MP4 |
| Richieste | 120 per chiave API in ogni finestra fissa di un minuto |
| Intervallo di consultazione | Almeno cinque secondi |
| Passaggi per esecuzione | Fino a 20 |
| Conservazione file generati | 30 giorni |
| Validità URL di download | Fino a cinque minuti |

Contano catalogo, preventivi, caricamenti, esecuzioni, interrogazioni e tentativi successivi. Evita interrogazioni troppo frequenti per prevenire risposte 429.

## Caricare gli input

Per immagini, audio o video locali, invia tipo MIME e dati Base64 a `POST /tools/upload`.

```json theme={null}
{
  "mimeType": "audio/wav",
  "data": "BASE64_DATA"
}
```

La risposta fornisce un `id` usabile come `fileId`, formato, dimensione, SHA-256 e scadenza. Passalo a campi come `source` secondo il catalogo. Contenuti identici nello stesso progetto restituiscono lo stesso ID; la conservazione non si prolunga dal primo caricamento.

## Pagine correlate

Consulta queste pagine per autenticazione ed esecuzione.

* [Autenticare le richieste](https://docs.noimosai.com/it/developers/api/authentication.md)
* [Gestire esecuzione e fatturazione](https://docs.noimosai.com/it/developers/api/execution-and-billing.md)
* [Documentazione](https://platform.noimosai.com/docs)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.