Deweloperzy
Dokumentacja API
Uwierzytelnij się za pomocą sesji lub klucza API i korzystaj z zaimplementowanych punktów końcowych konta, wyceny, instancji i rozliczeń.
8 min czytania · ZaktualizowanoUwierzytelnianie
Ścieżka bazowa to /api/v1. Żądania przeglądarki używają pliku cookie sesji HttpOnly utworzonego przy logowaniu. Skrypty mogą używać Authorization: Bearer, po którym następuje aktywny klucz API. Klucze mają pełne uprawnienia konta i są wyświetlane raz podczas tworzenia.
Lokalny interfejs używa kluczy gh_demo_. Unieważnienie klucza natychmiast uniemożliwia nowe uwierzytelnione żądania z jego użyciem. Nie umieszczaj kluczy w adresach URL ani w pakietach po stronie przeglądarki.
GET /api/v1/balance
Authorization: Bearer <your-api-key>
200 OK
{ "currency": "USD", "balanceCents": 50000, "derivedFrom": "ledger_entries" }Zasady żądań i ponawiania
Treści żądań POST i PATCH to obiekty JSON, z nagłówkiem Content-Type: application/json. Dla akcji bez parametrów wyślij {}. Treści są ograniczone do 32 KiB tekstu. Odpowiedzi używają Cache-Control: no-store.
Wdrożenie, ręczne odnowienie i wycofanie wymagają nagłówka Idempotency-Key o długości 8–128 znaków. Użyj nowego klucza dla nowej zamierzonej operacji i ponownie użyj tego samego klucza przy jej ponowieniu. Nigdy nie używaj go ponownie z inną treścią. Odpowiedź na ponowienie zawiera replayed: true.
Wyceny instancji obliczają bieżącą cenę katalogową bez rezerwowania pojemności. Podczas wdrażania wyślij expectedPriceCents; niezgodność zwróci 409, aby można było ponownie sprawdzić cenę.
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
}Zaimplementowane punkty końcowe
Wszystkie zasoby konta są ograniczone do ich właściciela. Punkt końcowy dostępności jest publiczny i udostępnia migawkę katalogu, a nie sondę sprzętową na żywo.
| Metoda | Ścieżka po /api/v1 | Cel |
|---|---|---|
| POST | /auth/register · /auth/login | Nazwa użytkownika + hasło; utwórz sesję |
| POST | /auth/recover | Nazwa użytkownika + nieużywany kod + nowe hasło |
| POST | /auth/logout | Unieważnij bieżącą sesję przeglądarki |
| GET | /me · /balance · /ledger | Konto, saldo i najnowsze 100 wpisów |
| GET / DELETE | /sessions · /sessions/:id | Wyświetl aktywne sesje lub unieważnij jedną z nich |
| GET | /availability | Katalog publiczny i migawka stanów regionalnych |
| GET / POST | /deposit-quotes | Wyświetl aktywne wyceny lub utwórz nową z parametrami asset + desiredUsdCents |
| POST | /demo/confirm-deposit | Identyfikator wyceny; tylko rozwój lokalny |
| GET | /deposits · /withdrawals | Ostatnie 100 rekordów dla tego konta |
| POST | /withdrawals | Zasób + miejsce docelowe + amountUsdCents; idempotentne |
| POST | /instance-quotes | GPU, liczba, region, obraz, okres i opcje |
| GET / POST | /instances | Wyświetl alokacje lub wdróż; wdrożenie jest idempotentne |
| POST | /instances/:id/start · stop · release · renew | Akcja cyklu życia; odnowienie jest idempotentne |
| PATCH | /instances/:id/auto-renew | Ustaw enabled na true lub false |
| GET / POST | /ssh-keys · /api-keys | Wyświetl lub utwórz klucze konta |
| DELETE | /ssh-keys/:id · /api-keys/:id | Unieważnij klucz |
Obsługuj błędy jawnie
Błędy mają strukturę {error, message}: stabilny kod i czytelne wyjaśnienie. 400 oznacza nieprawidłowe dane wejściowe, 401 brak lub nieprawidłowe uwierzytelnienie, 403 odrzucone pochodzenie, 404 nieznany lub nienależący do Ciebie zasób, 409 konflikt salda/state/duplicate, a 415 nieprawidłowy typ treści.
W przypadku wygasłej wyceny depozytu utwórz kolejną wycenę. W przypadku zmiany stanu instancji przeładuj instancję przed podjęciem decyzji o kolejnym działaniu. Po przerwie w sieci użyj ponownie klucza operacji zamiast tworzyć drugą opłatę.