Riferimento API

Ottenere la Propria Chiave API

L’API GPUnex Le consente di gestire le istanze GPU, controllare i saldi e automatizzare i flussi di lavoro senza utilizzare la dashboard web. Prima di effettuare qualsiasi richiesta API, è necessario generare una chiave API.

1. Acceda al Suo account GPUnex e navighi alla pagina Profilo o al pannello impostazioni della Dashboard.

2. Apra la sezione Chiavi API. Cerchi la scheda o la card Chiavi API nelle impostazioni del Suo account.

3. Clicchi su “Crea Nuova Chiave API”. Le verrà chiesto di assegnare alla chiave un nome descrittivo. Scelga qualcosa di significativo che identifichi lo scopo della chiave — ad esempio, “Server di Produzione”, “Pipeline CI/CD” o “Sviluppo Locale”. Questo facilita la gestione di più chiavi in seguito.

4. Copi immediatamente la Sua chiave API. Una volta generata, la chiave verrà mostrata una sola volta. La copi e la conservi in un luogo sicuro come un gestore di password o un vault di segreti crittografato. Non sarà possibile visualizzare nuovamente la chiave completa dopo questo passaggio.

5. Comprenda l’ambito e la revoca delle chiavi. Ogni chiave API è associata al Suo account e ne eredita i permessi. Può creare più chiavi per diverse applicazioni o ambienti. Se una chiave viene compromessa o non è più necessaria, può revocarla in qualsiasi momento dalla sezione Chiavi API. La revoca di una chiave è immediata e permanente — tutte le richieste che utilizzano quella chiave verranno rifiutate.

Autenticazione

Tutte le richieste all’API GPUnex devono includere un header Authorization con la Sua chiave API utilizzando lo schema Bearer token.

Formato dell’header:

Authorization: Bearer YOUR_API_KEY

Se la chiave API è mancante, non valida o revocata, l’API restituirà una risposta 401 Unauthorized:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key. Please check your Authorization header."
}

Si assicuri che la Sua chiave sia inclusa in ogni richiesta. L’API non supporta l’autenticazione basata su sessione o cookie.

Endpoint Principali

L’API GPUnex è organizzata secondo risorse RESTful. Tutti gli endpoint utilizzano l’URL base https://api.gpunex.com/v1. Di seguito un riepilogo degli endpoint principali disponibili.

Tutte le risposte sono restituite in formato JSON. Le richieste riuscite restituiscono un codice di stato 200 OK per le richieste GET e un codice di stato 201 Created per le richieste POST che creano risorse.

Esempio: Creazione di un’Istanza

Per creare una nuova istanza GPU, invii una richiesta POST a /v1/instances con un body JSON che specifichi la configurazione desiderata.

Richiesta:

Parametri del body della richiesta:

Esempio di risposta (201 Created):

{
  "id": "inst_7f3a9b2c4d1e",
  "status": "provisioning",
  "gpu_model": "A100_80GB",
  "framework": "pytorch-2.3",
  "region": "us-east-1",
  "ssh_command": null,
  "hourly_rate": "1.89",
  "currency": "USDC",
  "created_at": "2026-02-15T14:32:07Z"
}

L’istanza avrà inizialmente lo stato provisioning. Una volta che la GPU è stata allocata e l’ambiente è pronto, lo stato cambierà in running e il campo ssh_command verrà popolato con la Sua stringa di connessione. Il provisioning richiede tipicamente tra 30 secondi e 2 minuti a seconda della disponibilità.

Esempio: Verifica dello Stato dell’Istanza

Una volta creata un’istanza, può verificarne lo stato attuale in qualsiasi momento interrogando l’endpoint dell’istanza con il suo ID.

Richiesta:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.gpunex.com/v1/instances/inst_7f3a9b2c4d1e

Esempio di risposta (200 OK):

{
  "id": "inst_7f3a9b2c4d1e",
  "status": "running",
  "gpu_model": "A100_80GB",
  "framework": "pytorch-2.3",
  "region": "us-east-1",
  "ssh_command": "ssh [email protected] -p 2222",
  "ip_address": "203.0.113.42",
  "hourly_rate": "1.89",
  "currency": "USDC",
  "uptime_seconds": 3847,
  "total_cost": "2.02",
  "created_at": "2026-02-15T14:32:07Z",
  "started_at": "2026-02-15T14:33:15Z"
}

Valori di stato:

Limiti di Frequenza e Best Practice

Limiti di Frequenza

L’API GPUnex applica limiti di frequenza per garantire un utilizzo equo e la stabilità della piattaforma. I limiti attuali sono:

• Endpoint generali: 120 richieste al minuto per chiave API.
• Creazione di istanze: 10 richieste al minuto per chiave API.
• Saldo e endpoint in sola lettura: 300 richieste al minuto per chiave API.

Se supera il limite di frequenza, l’API restituirà una risposta 429 Too Many Requests con un header Retry-After che indica quanti secondi attendere prima di riprovare.

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 12 seconds.",
  "retry_after": 12
}

Best Practice

Segua queste linee guida per mantenere la Sua integrazione sicura e affidabile.

1. Non esponga mai le chiavi API nel codice lato client. Non incorpori la Sua chiave API nel JavaScript eseguito nel browser, nel codice sorgente di app mobili o in qualsiasi repository accessibile pubblicamente. Le chiavi API dovrebbero essere utilizzate solo in applicazioni lato server dove non possono essere ispezionate dagli utenti finali.

2. Utilizzi le variabili d’ambiente. Conservi la Sua chiave API in una variabile d’ambiente anziché codificarla direttamente nei file sorgente. Ad esempio:

   export GPUNEX_API_KEY="your_api_key_here"

   Quindi la riferisca nel Suo codice:

   curl -H "Authorization: Bearer $GPUNEX_API_KEY" https://api.gpunex.com/v1/instances

3. Ruoti le chiavi periodicamente. Come best practice di sicurezza, generi una nuova chiave API ogni 90 giorni e revochi quella vecchia. Questo limita l’impatto nel caso in cui una chiave venga divulgata inavvertitamente.

4. Utilizzi chiavi separate per ambienti separati. Crei chiavi API distinte per sviluppo, staging e produzione. In questo modo, la revoca di una chiave non influisce sugli altri ambienti.

5. Gestisca gli errori con eleganza. Verifichi sempre i codici di stato HTTP nella Sua applicazione. Implementi una logica di retry con backoff esponenziale per le risposte 429 e 5xx. Non ripeta le richieste per errori 4xx diversi da 429 — questi indicano un problema con la richiesta stessa.

6. Monitori il Suo utilizzo. Tenga traccia del volume delle Sue chiamate API e della spesa per le istanze. Utilizzi l’endpoint /v1/balance per monitorare programmaticamente il Suo saldo USDC e impostare avvisi se scende al di sotto di una soglia.