OpenAPI i indeks endpointów
Kontrakt OpenAPI 3.1 do pobrania, wszystkie publiczne endpointy z odpowiednimi poradnikami, wspólne nagłówki żądań i produkcyjny adres API.
Publiczny kontrakt w formacie maszynowym jest dostępny jako OpenAPI 3.1 YAML. Użyj go do wygenerowania klienta lub sprawdzenia integracji względem aktualnych publicznych endpointów.
Produkcyjny adres API
https://api.spicyapi.ai jest jedynym produkcyjnym adresem bazowym wskazanym w OpenAPI przez servers[0].url. API zadań używa /api/v1; endpointy zgodności z protokołami używają /v1 i /v1beta.
Te API platformy umożliwiają wybór modelu, uzyskiwanie wycen i monitorowanie wydatków bez otwierania konsoli. Katalog modeli zawiera ceny twojego konta; gdy cena zależy od parametrów, pobierz wycenę dokładnych danych wejściowych. Historia zadań i użycie są ograniczone do klucza API, którym wykonujesz wywołanie. Tworzenie i rotacja kluczy oraz ustawienia budżetu pozostają w konsoli. Każda tabela odsyła do poradnika, który szczegółowo wyjaśnia dany endpoint.
API wyszukiwania modeli, cen i konta
| Metoda | Ścieżka | Przeznaczenie | Poradnik |
|---|---|---|---|
GET | /console/v1/catalog/models | Publiczny katalog do oceny oferty: bez klucza API, ceny standardowe, limit żądań według adresu źródłowego | Szybki start |
GET | /api/v1/models | Odczyt modeli dostępnych do wywołania, cen konta i opcjonalnych schematów | Katalog modeli |
GET | /api/v1/models/{model} | Odczyt jednego modelu i jego pełnego JSON Schema | Katalog modeli |
POST | /api/v1/jobs/quote | Wycena dokładnego żądania ważna przez pięć minut, bez tworzenia zadania i blokowania środków | Wyceny |
GET | /api/v1/chat/credit | Odczyt salda dostępnego, zablokowanego i łącznego | Rozliczenia |
GET | /api/v1/usage | Odczyt wywołań bieżącego klucza i rozliczonych wydatków w USD według daty i modelu | Rozliczenia |
API generowania i zadań
| Metoda | Ścieżka | Przeznaczenie | Poradnik |
|---|---|---|---|
GET | /api/v1/jobs | Historia zadań bieżącego klucza API z paginacją za pomocą kursora | Zadania |
POST | /api/v1/jobs/createTask | Utworzenie asynchronicznego zadania generowania | Zadania |
GET | /api/v1/jobs/recordInfo | Odczyt zadania utworzonego kluczem API użytym w wywołaniu | Zadania |
POST | /api/v1/jobs/retry | Utworzenie nowego zadania na podstawie zadania zakończonego błędem lub po upływie terminu; zachowana zgodność z historycznymi rekordami anulowania | Działania na zadaniach |
POST | /api/v1/jobs/purge | Zniszczenie plików wynikowych i promptu jednego zadania w stanie końcowym; rekord rozliczenia pozostaje bez zmian | Przechowywanie danych |
POST | /api/v1/jobs/stream | Uruchomienie modelu tekstowego i strumieniowanie odpowiedzi przez SSE | Tekst i strumieniowanie |
API mediów
| Metoda | Ścieżka | Przeznaczenie | Poradnik |
|---|---|---|---|
POST | /api/v1/common/upload-url | Wydanie biletu do bezpośredniego przesłania pliku multimedialnego | Media |
POST | /api/v1/files/{fileId}/commit | Weryfikacja i zatwierdzenie bezpośrednio przesłanego pliku; zwraca URI spicy:// gotowe do użycia w zadaniu | Media |
POST | /api/v1/files/import | Import pliku wag LoRA z linku, z opcjonalnym tokenem dostępu użytym jednorazowo i nigdy niezapisywanym; zwraca URI spicy:// gotowe do użycia w zadaniu | Wagi adaptera |
POST | /api/v1/common/download-url | Wydanie krótkotrwałego adresu do pobrania wyniku zadania (opcjonalne: zakończone zadania już zawierają taki adres) | Media |
POST | /api/v1/assets | Zapisanie pliku w bibliotece zasobów (wymagany Idempotency-Key) | Media |
GET | /api/v1/assets | Lista zapisanych zasobów (filtry favorite, collectionId, q; sortowanie przez sort) | Media |
GET | /api/v1/assets/usage | Plan, wykorzystanie i limity biblioteki zasobów | Media |
GET | /api/v1/assets/{assetId} | Pobranie jednego zasobu ze świeżym prywatnym linkiem podglądu | Media |
PATCH | /api/v1/assets/{assetId} | Zmiana nazwy zasobu lub jego flagi favorite | Media |
DELETE | /api/v1/assets/{assetId} | Usunięcie zasobu | Media |
GET | /api/v1/assets/entities | Lista postaci w bibliotece zasobów (tylko odczyt) | Media |
GET | /api/v1/assets/entities/{entityId} | Jedna postać z obrazami po kolei (tylko odczyt) | Media |
Uwierzytelnianie i wspólna struktura odpowiedzi
Każdy endpoint oprócz publicznego katalogu wymaga klucza API w nagłówku Authorization: Bearer sk-spicy-…; endpointy zgodności (/v1, /v1beta) akceptują również x-api-key, przesyłany przez SDK Anthropic, oraz x-goog-api-key, przesyłany przez SDK Google GenAI. Klucz w parametrach zapytania URL nigdy nie jest akceptowany. Zadania, ponowienia, operacje usuwania treści i linki pobierania są widoczne tylko dla klucza API, który utworzył zadanie; zobacz Uwierzytelnianie.
Odpowiedzi JSON API zadań mają wspólną strukturę {code,msg,data,request_id}; endpointy zgodności używają struktur właściwych dla swoich protokołów. Wynik zadania opisuje data.state, a nie zewnętrzne pole code. Zobacz Błędy.
Nagłówki żądań używane w różnych endpointach
| Nagłówek | Gdzie wysyłać | Przeznaczenie |
|---|---|---|
Authorization: Bearer … | Wszędzie oprócz publicznego katalogu | Twój klucz API |
Idempotency-Key | jobs/createTask, jobs/retry, jobs/stream, POST /v1/videos i endpointy tekstowe /v1 oraz /v1beta | Pozwala bezpiecznie powtórzyć żądanie po błędzie sieci. W endpointach zadań zwraca pierwotne zadanie; w endpointach tekstowych zapobiega ponownej opłacie, ale nie może zwrócić utraconej odpowiedzi. Zobacz Idempotencja |
X-Spicy-Retention | jobs/createTask, jobs/stream | Skraca czas przechowywania wyników i promptu tego zadania, w sekundach. Zobacz Przechowywanie danych |
Accept-Language | Dowolny endpoint | Język komunikatów o błędach; kody nigdy się nie zmieniają. Zobacz Błędy |
Korzystanie z pliku OpenAPI
- Wypróbuj żądania bez pisania kodu: zaimportuj plik OpenAPI z linku na początku strony do klienta API, takiego jak Postman, Insomnia lub Bruno, a następnie ustaw swój klucz API jako token Bearer. Pamiętaj, że tworzenie zadań jest płatne.
- Wygeneruj klienta: przekaż ten sam plik do generatora kodu OpenAPI 3.1 dla swojego języka.
Zmiany kontraktu
- Nie przechowuj parametrów modeli jako trwale zakodowanej migawki; odczytuj
inputSchemaz/models/{model}. - Toleruj nieznane pola odpowiedzi, ale nigdy nie zgaduj nieznanych pól żądania.
- Przed wydaniem używaj OpenAPI YAML do generowania kodu lub testów kontraktu.
Endpointy zgodności
| Metoda | Ścieżka | Protokół |
|---|---|---|
GET | /v1/models | Models |
POST | /v1/chat/completions | Chat Completions |
POST | /v1/responses | Responses |
POST | /v1/messages | Messages |
POST | /v1beta/models/{model}:generateContent | Gemini generateContent |
POST | /v1beta/models/{model}:streamGenerateContent | Gemini streamGenerateContent |
POST | /v1/videos | Videos |
GET | /v1/videos/{videoId} | Stan wideo |
GET | /v1/videos/{videoId}/content | Zawartość wideo |
Endpointy tekstowe opisuje Tekst i strumieniowanie; ich wycenę wyjaśniają Wyceny i zgodność.
Oficjalnym pakietem TypeScript jest @spicyapi/sdk. W przypadku Pythona i Go albo gdy nie możesz dodać zależności, poniższe gotowe do skopiowania klienty referencyjne wywołują te endpointy wyłącznie przy użyciu środowiska uruchomieniowego danego języka. Klient Python samodzielnie obsługuje cały proces zadania multimedialnego: przesłanie i zatwierdzenie pliku referencyjnego, potwierdzenie ceny wyceną, utworzenie zadania i odpytywanie do stanu końcowego, odczyt wyniku niezależnie od tego, czy są to pliki czy tekst, odświeżenie wygasłego linku do wyniku, późniejsze zniszczenie zapisanej treści oraz weryfikację podpisu webhooka. Klient Go obejmuje ten sam proces, z kontekstem w każdym wywołaniu i typowanym błędem odczytywanym przez errors.As. Klient TypeScript obsługuje tworzenie i ponawianie zadań, odczyty stanu oraz oczekiwanie z limitem czasu; do przesyłania plików i pozostałych operacji API w Node.js używaj SDK.
Klienty referencyjne do skopiowania
Przykłady bez zewnętrznych zależności: wyszukiwanie modeli, tworzenie zadania, ponowienie zadania zakończonego błędem, odczyt stanu, wszystkie stany końcowe, ograniczone oczekiwanie, idempotentność i obsługa błędów. Przyjętego zadania nie można już anulować.
To przykłady z dokumentacji, a nie opublikowane pakiety npm i PyPI ani moduły Go. Dziesięć minut to lokalny limit oczekiwania, a nie produkcyjne SLA.
Przechowywanie i usuwanie danych
Limity przechowywania platformy, krótsze okresy dla konta, skutki zmiany ustawień dla istniejących treści, usuwanie treści zadania i granice naszych zobowiązań.
Błędy
Wszystkie kody biznesowe, odpowiadające im statusy HTTP, sposoby rozwiązania problemów oraz błędy, przy których warto ponowić żądanie.