Riferimento API

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.

https://api.noimosai.com/noimosToolBridge

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

Authorization: Bearer nmp_...
Content-Type: application/json

L’esecuzione a pagamento richiede anche questo header.

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.

{
  "data": {}
}

Gli errori contengono stato e messaggio in error.

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

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

Primi passi

API

CLI

Server MCP

Panoramica

URL di base e header

Endpoint

Catalogo strumenti

Formato delle risposte

Gestire gli errori

Limiti d’uso

Caricare gli input

Pagine correlate

​Panoramica

​URL di base e header

​Endpoint

​Catalogo strumenti

​Formato delle risposte

​Gestire gli errori

​Limiti d’uso

​Caricare gli input

​Pagine correlate

Panoramica

URL di base e header

Endpoint

Catalogo strumenti

Formato delle risposte

Gestire gli errori

Limiti d’uso

Caricare gli input

Pagine correlate