Entwickler
API-Referenz
Authentifizieren Sie sich mit einem Sitzungs- oder API-Schlüssel und verwenden Sie die implementierten Konto-, Angebots-, Instanz- und Abrechnungs-Endpunkte.
8 Min. Lesezeit · AktualisiertAuthentifizierung
Der Basispfad ist /api/v1. Browseranfragen verwenden das beim Anmelden erstellte HttpOnly-Sitzungscookie. Skripte können Authorization: Bearer gefolgt von einem aktiven API-Schlüssel verwenden. Schlüssel besitzen vollständige Kontoberechtigungen und werden bei der Erstellung einmalig angezeigt.
Die lokale UI verwendet gh_demo_-Schlüssel. Das Widerrufen eines Schlüssels verhindert sofort neue authentifizierte Anfragen mit diesem Schlüssel. Legen Sie Schlüssel nicht in URLs oder browser-seitige Bundles.
GET /api/v1/balance
Authorization: Bearer <your-api-key>
200 OK
{ "currency": "USD", "balanceCents": 50000, "derivedFrom": "ledger_entries" }Anfrage- und Wiederholungsregeln
POST- und PATCH-Bodys sind JSON-Objekte, mit Content-Type: application/json. Senden Sie {} für Aktionen ohne Parameter. Bodys sind auf 32 KiB Text begrenzt. Antworten verwenden Cache-Control: no-store.
Bereitstellung, manuelle Verlängerung und Rücknahme erfordern einen Idempotency-Key von 8–128 Zeichen. Verwenden Sie einen neuen Schlüssel für eine neue beabsichtigte Operation und denselben Schlüssel für deren Wiederholung. Verwenden Sie ihn niemals mit einem anderen Inhalt erneut. Eine Wiederholungsantwort enthält replayed: true.
Instanzangebote berechnen den aktuellen Katalogpreis, ohne Kapazität zu reservieren. Senden Sie expectedPriceCents bei der Bereitstellung; bei einer Abweichung wird 409 zurückgegeben, damit der Preis erneut geprüft werden kann.
POST /api/v1/instances
Content-Type: application/json
Idempotency-Key: <unique-operation-id>
Authorization: Bearer <your-api-key>
{
"sku": "nvidia-rtx-4090",
"gpuCount": 1,
"region": "dal",
"image": "pytorch",
"period": "week",
"options": [],
"sshKeyId": "<saved-key-id>",
"autoRenew": false,
"expectedPriceCents": 11000
}Implementierte Endpunkte
Alle Kontoressourcen sind auf ihren Eigentümer beschränkt. Der Verfügbarkeitsendpunkt ist öffentlich und stellt den Katalog-Snapshot bereit, keine Live-Hardware-Prüfung.
| Methode | Pfad nach /api/v1 | Zweck |
|---|---|---|
| POST | /auth/register · /auth/login | Benutzername + Passwort; Sitzung erstellen |
| POST | /auth/recover | Benutzername + ungenutzter Code + neues Passwort |
| POST | /auth/logout | Aktuelle Browsersitzung widerrufen |
| GET | /me · /balance · /ledger | Konto, Saldo und letzte 100 Einträge |
| GET / DELETE | /sessions · /sessions/:id | Aktive Sitzungen auflisten oder eine widerrufen |
| GET | /availability | Öffentlicher Katalog und regionaler Bestands-Schnappschuss |
| GET / POST | /deposit-quotes | Aktive Angebote auflisten oder eines mit asset + desiredUsdCents erstellen |
| POST | /demo/confirm-deposit | Angebots-ID; nur lokale Entwicklung |
| GET | /deposits · /withdrawals | Neueste 100 Datensätze für dieses Konto |
| POST | /withdrawals | Asset + Ziel + amountUsdCents; idempotent |
| POST | /instance-quotes | GPU, Anzahl, Region, Image, Zeitraum und Optionen |
| GET / POST | /instances | Zuweisungen auflisten oder bereitstellen; die Bereitstellung ist idempotent |
| POST | /instances/:id/start · stop · release · renew | Lebenszyklus-Aktion; Verlängerung ist idempotent |
| PATCH | /instances/:id/auto-renew | Setzen Sie enabled auf true oder false |
| GET / POST | /ssh-keys · /api-keys | Kontoschlüssel auflisten oder erstellen |
| DELETE | /ssh-keys/:id · /api-keys/:id | Einen Schlüssel widerrufen |
Fehler explizit behandeln
Fehler haben {error, message}: einen stabilen Code und eine lesbare Erklärung. 400 zeigt ungültige Eingaben an, 401 fehlende oder ungültige Authentifizierung, 403 einen abgelehnten Ursprung, 404 eine unbekannte oder nicht zugeordnete Ressource, 409 einen Guthaben/state/duplicate-Konflikt und 415 den falschen Inhaltstyp.
Erstellen Sie für ein abgelaufenes Einzahlungsangebot ein weiteres Angebot. Laden Sie bei geändertem Instanzstatus die Instanz neu, bevor Sie über eine weitere Aktion entscheiden. Verwenden Sie nach einer Netzwerkunterbrechung den Vorgangsschlüssel erneut, anstatt eine zweite Belastung zu erzeugen.