Słownik

Ta dokumentacja używa słów technicznych, bo produktem jest API. Ta strona wyjaśnia każde z nich prostym językiem, w kolejności alfabetycznej. Każde hasło ma trzy części: co słowo znaczy ogólnie, co znaczy w SpicyAPI i na której stronie są pełne szczegóły.

Inne strony linkują prosto do haseł, więc jeśli gdzieś indziej zatrzyma cię jakieś słowo, najpewniej znajdziesz je tutaj. Szerszy obraz daje strona Jak działa SpicyAPI.

Adres bazowy (base URL)

Stała, początkowa część każdego adresu, którego używa API. Wpisujesz ją raz w kodzie albo w ustawieniach narzędzia, a każde żądanie dokleja za nią własną ścieżkę.

W SpicyAPI: są dwa.

Żądania w formacie Google Gemini trafiają na https://api.spicyapi.ai/v1beta. Oficjalne biblioteki Anthropic i Google GenAI same dokładają część z numerem wersji, więc dla nich ustawiasz samo https://api.spicyapi.ai.

Zobacz: Szybki start · Tekst i streaming

Agent Skill

Folder pisemnych instrukcji, które asystent programistyczny AI czyta, zanim zabierze się do pracy – coś jak instrukcja stanowiskowa wręczona nowej osobie w zespole. Nie zawiera żadnego programu i sam z siebie nic nie robi.

W SpicyAPI: oficjalny Skill, opublikowany jako @spicyapi/skill, uczy asystentów takich jak Claude Code, Codex czy Cursor poprawnego korzystania ze SpicyAPI: czytania katalogu na żywo zamiast zgadywania, pokazywania ci ceny przed płatną pracą, ponownego używania kluczy idempotentności i niewklejania nigdy twojego klucza API do kodu. Zainstalujesz go poleceniem npx skills add spicyapi-ai/spicy-skill. Dobrze działa razem z serwerem MCP.

Zobacz: Agent Skill

API

Skrót od application programming interface, czyli interfejsu programowania aplikacji: ustalony zestaw żądań, które jeden program może wysłać do drugiego, oraz odpowiedzi, które dostaje z powrotem. Strona internetowa powstaje po to, żeby klikali w nią ludzie, a API – po to, żeby wywoływały je programy.

W SpicyAPI: przez API każde narzędzie dociera do modeli. Playground, CLI, serwer MCP i SDK wysyłają na api.spicyapi.ai te same rodzaje żądań, które może wysłać twój własny kod.

Zobacz: OpenAPI i spis endpointów

Blokada, rozliczenie i zwolnienie

Trzy etapy płacenia za zadanie. Blokada to pieniądze odłożone na bok, ale jeszcze niewydane – tak jak kwota, którą hotel blokuje na twojej karcie.

W SpicyAPI:

• Blokada: gdy zadanie zostaje przyjęte, jego szacowany koszt (estimatedCost) jest odkładany z twojego salda i widnieje jako held. To jeszcze nie jest opłata, a zarazem najwięcej, ile to zadanie może kiedykolwiek kosztować.
• Rozliczenie: gdy zadanie się powiedzie, płacisz za to, co faktycznie zużyło, nigdy więcej niż wynosi blokada. Wszystko, co zostanie, wraca do dostępnego salda. settled: true w zadaniu oznacza, że kwota w cost jest ostateczna.
• Zwolnienie: Nieudane lub wygasłe zadania zwykle zwalniają całą blokadę. Niektóre odmowy dotyczące treści są płatne według zaakceptowanej wyceny, wyłącznie gdy strona modelu wyraźnie wskazuje ten wyjątek. Sprawdź settled i cost, aby poznać ostateczną kwotę.

Zobacz: Rozliczenia

Callback

Inna nazwa webhooka. W SpicyAPI adres podaje się w polu callBackUrl przy tworzeniu zadania.

CLI

Skrót od command-line interface, czyli interfejsu wiersza poleceń: program, którego używasz, wpisując polecenia w terminalu, zamiast klikać przyciski.

W SpicyAPI: polecenie spicyapi, opublikowane jako @spicyapi/cli, pozwala bez pisania kodu wyświetlać listę modeli, sprawdzać ceny, tworzyć zadania obrazu i wideo, czekać na nie i pobierać wyniki. Pieniądze kosztują tylko tasks create i tasks retry, a oba polecenia najpierw pytają o zgodę. CLI wymaga Node.js w wersji 22.13 lub nowszej; możesz je uruchomić bez instalowania, przez npx @spicyapi/cli.

Zobacz: Narzędzie wiersza poleceń (CLI)

Endpoint

Jedno konkretne żądanie, które przyjmuje API, określone metodą HTTP (na przykład GET do odczytu albo POST do wysyłania) i ścieżką.

W SpicyAPI: na przykład POST /api/v1/jobs/createTask uruchamia generację, a GET /api/v1/jobs/recordInfo odczytuje zadanie. Pełny adres to adres bazowy, a za nim ścieżka.

Zobacz: OpenAPI i spis endpointów

Identyfikator modelu (model ID)

Dokładna nazwa, którą wysyłasz, żeby wybrać model.

W SpicyAPI: identyfikatory mają postać publisher/model/task: kto stworzył model, który to model i wersja oraz co robi dany endpoint. Endpointy edycji obrazu kończą się na edit. Zawsze kopiuj identyfikator z katalogu na żywo (GET /api/v1/models, spicyapi models list albo listModels()), nigdy z pamięci ani ze strony internetowej, bo modele przybywają, są wstrzymywane i wycofywane. Przykłady w tej dokumentacji mają MODEL_ID_FROM_CATALOG tam, gdzie powinien stać prawdziwy identyfikator; wysłanie samego tego symbolu zastępczego kończy się błędem.

Zobacz: Katalog modeli i schematy

JSON

Tekstowy format danych strukturalnych, złożony z nazw i wartości w nawiasach klamrowych. Używa go niemal każde API, bo odczyta go każdy język programowania.

W SpicyAPI: żądania i odpowiedzi są w formacie JSON. Minimalne żądanie zadania wygląda tak:

{ "model": "MODEL_ID_FROM_CATALOG", "input": { "prompt": "A paper lantern on a rainy street at night" } }

MODEL_ID_FROM_CATALOG zastępuje prawdziwy identyfikator modelu wzięty z katalogu na żywo. Kwoty pieniężne zawsze przesyła się jako tekst, na przykład "0.008", żeby żadna kwota nie została przypadkiem zaokrąglona.

Zobacz: Szybki start

Katalog

Lista dostępnych modeli wraz z cenami i danymi wejściowymi, które przyjmuje każdy z nich.

W SpicyAPI: ta sama lista istnieje w dwóch wersjach.

• Publiczny katalog nie wymaga konta ani klucza. To on jest widoczny na spicyapi.ai/explore i to on wraca z GET /console/v1/catalog/models. Służy do przeglądania i porównywania.
• Katalog uwierzytelniony, czyli GET /api/v1/models wywołane z twoim kluczem API, to jedyne wiarygodne źródło informacji o tym, które modele twój klucz może wywołać w tej chwili i po jakich cenach twojego konta. Przed płatną pracą wybierz pozycję, w której zarówno enabled, jak i available mają wartość true.

Polecenie CLI spicyapi models list, metoda SDK listModels() i narzędzie MCP spicyapi_models_list czytają katalog uwierzytelniony.

Zobacz: Katalog modeli i schematy

Klucz API

Tajny ciąg znaków, który dowodzi, że żądanie pochodzi od ciebie. Traktuj go jak hasło, którego używają programy.

W SpicyAPI: klucze zaczynają się od sk-spicy- i tworzy się je na stronie Klucze API w konsoli. Klucz jest pokazywany tylko raz; jeśli go zgubisz, utwórz nowy. Każde żądanie przesyła klucz w nagłówku Authorization: Bearer. Trzymaj klucze na własnym komputerze albo serwerze – nigdy na stronie internetowej, w aplikacji mobilnej, w publicznym repozytorium, na zrzucie ekranu ani w czacie. Każdy klucz może mieć własne limity wydatków, listę dozwolonych modeli i listę dozwolonych adresów IP.

Zobacz: Uwierzytelnianie · Przygotuj konto

Klucz idempotentności

Etykieta, którą wymyślasz dla jednej porcji pracy, żeby dwukrotne wysłanie tego samego żądania wykonało tę pracę tylko raz. Słowo „idempotentny” oznacza, że powtórzenie czynności nie wywołuje już żadnego dodatkowego skutku.

W SpicyAPI: wysyłasz ją w nagłówku Idempotency-Key, gdy tworzysz albo ponawiasz zadanie, na przykład order-8814-render-1. Jeśli połączenie zostanie zerwane i nie wiesz, czy zadanie ruszyło, wyślij w ciągu 24 godzin to samo żądanie z tym samym kluczem idempotentności i tym samym kluczem API: dostaniesz z powrotem pierwotne zadanie i nie zapłacisz dwa razy. Dla każdej nowej porcji pracy użyj nowego klucza. Ponowne użycie klucza z innym żądaniem jest odrzucane z kodem 409. Klucz może mieć do 128 znaków.

Zobacz: Idempotentność

Kod błędu

Krótka, stała wartość, która mówi programowi, co poszło nie tak, żeby mógł zareagować bez czytania treści komunikatu.

W SpicyAPI: są dwa rodzaje.

• code w strukturze odpowiedzi opisuje samo żądanie. 200 oznacza powodzenie; inne wartości to między innymi 400 (nieprawidłowe żądanie), 401 (problem z kluczem), 40201 (za niskie saldo), 40202 (osiągnięty limit wydatków) i 429 (zbyt wiele żądań). To kod biznesowy, bardziej szczegółowy niż wysyłany razem z nim status HTTP.
• errorCode pojawia się w zadaniu, które zostało przyjęte, ale potem się nie powiodło. Przyjmuje jedną z dziewięciu wartości: invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset albo upstream_failed.

Towarzyszące im komunikaty, msg i errorMessage, są przeznaczone dla ludzi: ich brzmienie może się zmieniać i mogą wracać w wybranym przez ciebie języku. Programy powinny rozgałęziać logikę wyłącznie po kodach.

Zobacz: Błędy

Limit wydatków

Pułap wydatków ustawiony z wyprzedzeniem, żeby pomyłka albo wyciek klucza nie mogły wyczerpać całego salda.

W SpicyAPI: każdy klucz API może mieć limit dzienny, miesięczny i łączny w dolarach amerykańskich, ustawiany przez ciebie; nowe klucze nie mają żadnego, dopóki go nie dodasz. Zespoły mogą dodać budżety dzienne i miesięczne, a platforma ma własny limit dzienny. Zadanie, które przekroczyłoby którykolwiek z nich, jest odrzucane z kodem 40202, zanim ruszy, i nic nie zostaje pobrane. Limity dzienne odnawiają się o 00:00 UTC, a miesięczne pierwszego dnia miesiąca; limity łączne nie odnawiają się nigdy. Wpisanie 0 oznacza brak limitu na danym poziomie.

Zobacz: Rozliczenia · Uwierzytelnianie

Limit żądań (rate limit)

Górna granica liczby żądań, które możesz wysłać w określonym czasie, żeby jeden program, który wymknął się spod kontroli, nie przeciążył usługi.

W SpicyAPI: natywne API domyślnie dopuszcza 1000 żądań na 10 sekund na konto. Osobno liczone są odczyty i osobno zapisy, a każda z tych dwóch pul jest wspólna dla wszystkich kluczy konta. Odpytywanie liczy się jako odczyt, więc nawet intensywne odpytywanie nie zablokuje wysyłania zadań. Po przekroczeniu puli dostajesz 429 z nagłówkiem Retry-After, który mówi, ile sekund odczekać. Limit liczy żądania, a nie zadania: zadania, które już trwają, go nie zużywają.

Zobacz: Limity żądań

MCP

Skrót od Model Context Protocol: otwarty standard, który pozwala asystentom AI wczytywać dodatkowe umiejętności, zwane narzędziami, z małych programów nazywanych serwerami MCP.

W SpicyAPI: oficjalny serwer @spicyapi/mcp działa na twoim własnym komputerze i daje asystentom takim jak Claude, Cursor, VS Code czy Codex 15 narzędzi SpicyAPI: przeglądanie modeli, wyceny, tworzenie zadań, przesyłanie plików i pobieranie wyników. Uruchomienie, ponowienie albo zniszczenie zadania zatrzymuje się i prosi o potwierdzenie ciebie, pokazując cenę, jeśli jakaś jest; asystent nie może odpowiedzieć za ciebie. Serwer wymaga Node.js w wersji 22.13 lub nowszej.

Zobacz: Serwer MCP

Modalność

Rodzaj mediów, z którymi pracuje model.

W SpicyAPI: każda pozycja katalogu ma pole modality, na przykład image, video albo text, oraz listę tasks, na przykład text-to-image albo image-to-video. Według nich możesz filtrować katalog, na przykład GET /api/v1/models?modality=video&task=image-to-video.

Zobacz: Katalog modeli i schematy

Node.js

Bezpłatny program, który uruchamia JavaScript poza przeglądarką. Wiele narzędzi dla programistów jest napisanych w JavaScripcie i wymaga, żeby był zainstalowany.

W SpicyAPI: SDK, CLI i serwer MCP wymagają Node.js w wersji 22.13 lub nowszej; instalator, z którego korzysta Skill, wymaga wersji 22.20 lub nowszej. Zainstaluj wersję LTS z nodejs.org, a potem sprawdź ją w terminalu poleceniem node --version. Node.js nie jest potrzebny do Playgroundu ani wtedy, gdy wywołujesz API z innego języka.

Zobacz: CLI: zanim zaczniesz

npm i npx

npm to menedżer pakietów dostarczany z Node.js: pobiera i instaluje pakiety JavaScriptu. Dołączony do niego npx uruchamia pakiet bez trwałej instalacji.

W SpicyAPI: cztery narzędzia dla Node.js to pakiety npm: @spicyapi/sdk, @spicyapi/cli, @spicyapi/mcp i @spicyapi/skill. Na przykład npm install @spicyapi/sdk dodaje SDK dla TypeScriptu do projektu, a npx @spicyapi/cli status jednorazowo uruchamia CLI bez instalowania. SDK dla Pythona, Go, PHP i Javy instaluje się natomiast narzędziami ich własnych ekosystemów; zobacz stronę każdego z nich.

Zobacz: SDK dla TypeScriptu · Narzędzie wiersza poleceń (CLI)

Odpytywanie (polling)

Pytanie serwera raz za razem, czy coś już się skończyło, zamiast czekania, aż sam da znać.

W SpicyAPI: zadanie odpytujesz przez GET /api/v1/jobs/recordInfo?taskId=…, dopóki jego stan nie przestanie być queued albo running. Przed pierwszym sprawdzeniem odczekaj 2–3 sekundy, każdą kolejną przerwę wydłużaj mniej więcej 1,5 raza, aż do 10–15 sekund, i przestań czekać w terminie, który sam sobie wyznaczysz. Przerwanie czekania nie zatrzymuje zadania. Odpytywanie wlicza się do limitu żądań, więc na produkcji lepiej użyć webhooka.

Zobacz: Zadania asynchroniczne

Playground

Formularz na stronie internetowej, w którym możesz wypróbować model bez pisania kodu: wypełniasz pola i naciskasz przycisk.

W SpicyAPI: każda strona modelu na spicyapi.ai ma kartę Playground. Bez konta możesz wypełnić formularz i zobaczyć żądanie, które z niego powstaje; uruchomienie wymaga zalogowania i środków na saldzie. Każde uruchomienie najpierw pokazuje szacowany koszt, jest rozliczane jak wywołanie API i pojawia się w sekcji Logi w konsoli.

Zobacz: Jak działa SpicyAPI

Plik wynikowy (asset) i adres URL wyniku

Asset to jeden plik wytworzony przez zadanie, na przykład obraz albo wideo. Adres URL wyniku to adres internetowy, z którego ten plik pobierasz.

W SpicyAPI: zakończone zadanie wymienia swoje pliki w output.assets[]. Każdy z nich ma url, z którego pobierzesz go bezpośrednio, bez klucza API, a także expiresAt, mime (typ pliku) i informacje o rozmiarze. Link działa około 20 minut; żeby dostać nowy, zapytaj o zadanie ponownie. Sam plik przechowujemy najwyżej około 14 dni, więc zapisz kopię wszystkiego, czego potrzebujesz. Asset oznaczony pending: true jest jeszcze zapisywany (spróbuj ponownie za kilka sekund); oznaczony unavailable: true zniknął na dobre.

Zobacz: Zadania asynchroniczne · Media

Podpis (HMAC)

Kod obliczony z wiadomości i wspólnego sekretu, dzięki któremu odbiorca może sprawdzić, że wiadomość jest prawdziwa i nie została zmieniona po drodze. HMAC to standardowa metoda obliczania takiego kodu.

W SpicyAPI: każde dostarczenie webhooka niesie nagłówek X-Webhook-Signature: HMAC-SHA256 z identyfikatora zadania, czasu dostarczenia i skrótu dokładnej treści żądania, obliczony twoim kluczem podpisującym webhooki. Ten klucz generujesz albo wymieniasz na stronie Webhooki w konsoli i jest on pokazywany tylko w tym momencie; jeśli nie masz jego kopii, wymień go tam. Sprawdź podpis, zanim zaufasz dostarczeniu – funkcją verifyWebhook z SDK albo poleceniem spicyapi webhooks verify – i odrzucaj dostarczenia, których znacznik czasu różni się od bieżącego czasu o więcej niż pięć minut.

Zobacz: Webhooki

Przechowywanie danych

Jak długo zapisane dane są przechowywane, zanim zostaną usunięte.

W SpicyAPI:

Na stronie Ochrona danych w konsoli możesz skrócić czas przechowywania wygenerowanych plików, przesłanych plików i tekstu promptu, a dla pojedynczego zadania – nagłówkiem X-Spicy-Retention; treść możesz też w każdej chwili zniszczyć przez trwałe usunięcie. Żadne ustawienie nie wydłuża tych terminów.

Zobacz: Przechowywanie i usuwanie danych

Przestrzeń robocza i zespół

Wspólne miejsce, w którym kilka osób korzysta z tych samych kluczy, zadań i budżetów w ramach jednego konta.

W SpicyAPI: przestrzeń robocza zespołu ma członków z rolami: owner, admin, developer, billing i readonly. Każdy członek widzi podsumowania zadań i zużycie; owner, admin i developer widzą dodatkowo dane wejściowe i wyniki zadań. Za nowe zadania zespołu płaci konto właściciela, a członkowie nigdy nie widzą jego prywatnego salda ani płatności. Zespoły mogą ustawiać budżety dzienne i miesięczne.

Zobacz: Konsola i zespoły

Przesyłanie plików (upload)

Wysłanie pliku z twojego komputera na serwer, żeby dało się go tam wykorzystać.

W SpicyAPI: model, który przyjmuje obraz, wideo albo dźwięk, może je dostać na trzy sposoby: jako publiczny link HTTPS do pliku, jako mały obraz osadzony w żądaniu w postaci data URI (do 1 MiB) albo jako przesłany plik. Przesyłanie ma trzy kroki: poproś o bilet (POST /api/v1/common/upload-url), wyślij plik pod adres z biletu, a potem go zatwierdź (POST /api/v1/files/{fileId}/commit). Zatwierdzenie zwraca adres spicy://, który wpisujesz w pole wejściowe modelu. Można go używać przez jeden dzień. Obrazy mogą mieć do 10 MiB, a dźwięk i wideo – do 90 MiB i 600 sekund. uploadFile() w SDK, spicyapi files upload i serwer MCP wykonują wszystkie trzy kroki za ciebie.

Zobacz: Media

request_id

Identyfikator, który serwer dołącza do pojedynczego żądania, żeby dało się je potem odnaleźć w logach.

W SpicyAPI: każda natywna odpowiedź zawiera request_id (na przykład req_01k3…), przesyłany też w nagłówku X-Request-Id – zarówno przy powodzeniu, jak i przy błędzie. Zapisuj go w swoich logach i podawaj, gdy kontaktujesz się ze wsparciem. W webhooku w wersji 2 request_id identyfikuje natomiast samo dostarczenie (whd_…) i nie zmienia się, gdy dostarczenie jest ponawiane.

Zobacz: Błędy · Webhooki

Saldo

Pieniądze na twoim koncie, z których opłacasz generacje.

W SpicyAPI: przedpłacone saldo w dolarach amerykańskich, bez kredytów ani punktów. To, co wpłacasz, nigdy nie wygasa; środki promocyjne mają własny termin ważności. Środki dodajesz na stronie Rozliczenia w konsoli. GET /api/v1/chat/credit zwraca trzy kwoty zapisane jako tekst, na przykład "128.42": available (do wydania), held (zablokowane na trwające zadania) i total. Niektóre konta mają też przyznane środki promocyjne albo zatwierdzony kredyt, pokazywane w osobnym rozbiciu. Nie ma darmowego progu: nowe konta zaczynają od zera.

Zobacz: Rozliczenia · Przygotuj konto

Schemat wejścia (input schema)

Czytelny dla maszyn opis tego, jakie pola może zawierać żądanie, jakiego typu jest każde z nich i jakie wartości są dozwolone.

W SpicyAPI: każdy model ma własne inputSchema, zapisane w JSON Schema. Wymienia ono pola, które możesz umieścić w input, takie jak prompt, image_url czy duration_seconds, wraz z ich ograniczeniami i wartościami domyślnymi. Serwer sprawdza każde żądanie względem tego schematu i już jedno nieznane pole oznacza błąd 400. Playground buduje formularz z tego samego schematu, a examples w katalogu to kompletne dane wejściowe, które już przeszły tę kontrolę.

Zobacz: Katalog modeli i schematy · Spicy Schema

SDK

Skrót od software development kit, czyli zestawu narzędzi programistycznych: gotowa biblioteka kodu, którą dodajesz do własnego programu, żeby nie budować każdego żądania ręcznie.

W SpicyAPI: oficjalnych SDK jest pięć — @spicyapi/sdk dla TypeScriptu i JavaScriptu w Node.js oraz po jednym dla Pythona, Go, PHP i Javy. Każde zajmuje się kluczem, czekaniem na zadania, ponowieniami, przesyłaniem plików i sprawdzaniem webhooków, dzięki czemu kilka wywołań prowadzi zadanie od wysłania aż do wyniku. Wszystkie działają wyłącznie na serwerach, nie w przeglądarkach ani w aplikacjach mobilnych, i żadne nie obsługuje modeli czatu.

Zobacz: SDK dla TypeScriptu · SDK dla Pythona · SDK dla Go · SDK dla PHP · SDK dla Javy

Stan końcowy

Stan ostateczny: gdy zadanie go osiągnie, już nigdy się nie zmieni.

W SpicyAPI: każdy stan zadania inny niż queued i running jest końcowy: succeeded, failed, expired, a w starszych zapisach także canceled. Sprawdzaj warunek „nie queued i nie running”, zamiast wyliczać stany końcowe – wtedy twój kod będzie działał dalej, jeśli dojdzie nowy stan. Webhooki są wysyłane dopiero wtedy, gdy zadanie osiągnie stan końcowy. Trwale usunąć treść można tylko z zakończonych zadań, a ponowić można zadania failed i expired.

Zobacz: Zadania asynchroniczne

Stan zadania

Miejsce, w którym zadanie znajduje się w swoim cyklu życia.

W SpicyAPI:

Starsze zapisy mogą też pokazywać canceled, którego nowe zadania nigdy nie osiągają. Każdy stan inny niż queued i running traktuj jako stan końcowy.

Zobacz: Zadania asynchroniczne

Status HTTP

Trzycyfrowa liczba na początku każdej odpowiedzi internetowej, która ogólnie mówi, jak poszło żądanie. 2xx oznacza, że się udało, 4xx – że coś było nie tak z żądaniem, a 5xx – że problem wystąpił po stronie serwera.

W SpicyAPI: utworzenie zadania odpowiada 202 Accepted, co oznacza przyjęcie zadania, a nie jego zakończenie. Natywne odpowiedzi niosą też bardziej szczegółowy biznesowy code: na przykład za niskie saldo to HTTP 402 z code równym 40201. W swoim kodzie rozgałęziaj logikę po jednym z nich i trzymaj się tego wyboru.

Zobacz: Błędy

Streaming (SSE)

Wysyłanie odpowiedzi kawałek po kawałku, w miarę jak powstaje, przez jedno otwarte połączenie – zamiast całej naraz na końcu. SSE, skrót od server-sent events, to popularny format internetowy służący właśnie do tego.

W SpicyAPI: modele tekstowe mogą przesyłać odpowiedź słowo po słowie przez endpointy zgodne (na przykład stream: true w /v1/chat/completions) albo przez natywne POST /api/v1/jobs/stream. Każdy protokół oznacza koniec strumienia na swój sposób. Wcześniejsze zamknięcie połączenia sprawia, że przestajesz odbierać tekst, ale nie zatrzymuje modelu, a zużycie i tak zostaje rozliczone. Tekst ze streamingu nie jest zapisywany, więc później nie da się go pobrać ponownie.

Zobacz: Tekst i streaming

Struktura odpowiedzi (envelope)

Stałe zewnętrzne opakowanie, w które włożona jest każda odpowiedź, dzięki czemu program zawsze wie, gdzie szukać.

W SpicyAPI: odpowiedzi natywnego API (pod /api/v1) wyglądają tak:

{ "code": 200, "msg": "success", "data": {}, "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2" }

code to kod biznesowy (200 oznacza powodzenie), msg to komunikat czytelny dla człowieka, data zawiera odpowiedź i przy niepowodzeniu jest całkowicie pomijane, a request_id identyfikuje to żądanie. Endpointy zgodne z OpenAI, Anthropic i Gemini używają zamiast tego struktur określonych przez własne protokoły.

Zobacz: Błędy

Terminal

Okno tekstowe, w którym wpisujesz polecenia i uruchamiasz je klawiszem Enter. W macOS to aplikacja Terminal; w Windows użyj PowerShell; w większości środowisk graficznych Linuksa otworzysz go skrótem Ctrl + Alt + T. Nie myl go ze stanem końcowym, który po angielsku nazywa się terminal state.

W SpicyAPI: terminala używasz do uruchamiania CLI, do instalowania narzędzi Node.js, takich jak serwer MCP czy Skill, i do wypróbowywania przykładów z curl z tej dokumentacji.

Zobacz: CLI: zanim zaczniesz

Trwałe usunięcie treści (purge)

Nieodwracalne usunięcie zapisanej treści na żądanie, zamiast czekania, aż wygaśnie.

W SpicyAPI: POST /api/v1/jobs/purge (albo Trwale usuń wyniki w Logach w konsoli, spicyapi tasks purge, purgeTask()) usuwa wygenerowane pliki zakończonego zadania, jego wynik i tekst promptu z danych wejściowych. Zapis rozliczeniowy zostaje: kwota, model, stan, znaczniki czasu i request_id. Trwałe usunięcie to nie anulowanie i niczego nie zwraca, a cofnąć go nie można. Działa tylko dla zakończonych zadań.

Zobacz: Przechowywanie i usuwanie danych

Webhook

Adres na twoim własnym serwerze, który inna usługa wywołuje, gdy coś się wydarzy, żeby nie trzeba było o to ciągle pytać. Nazywany też callbackiem.

W SpicyAPI: przy tworzeniu zadania wpisz w callBackUrl publiczny adres HTTPS. Gdy zadanie osiągnie stan końcowy, SpicyAPI wyśle tam żądanie POST z tą samą treścią, którą zwróciłoby recordInfo, podpisane twoim kluczem podpisującym webhooki. Odpowiedz dowolnym statusem 2xx w ciągu 15 sekund; w przeciwnym razie dostarczenie jest ponawiane – łącznie najwyżej osiem prób w ciągu mniej więcej dziewięciu godzin – a ze strony Webhooki w konsoli możesz je wysłać ponownie. Samo rozpoczęcie zadania nie wywołuje żadnego powiadomienia. Adresy lokalne, takie jak http://localhost:3000, nie mogą odbierać webhooków, więc gdy pracujesz na własnym komputerze, korzystaj z odpytywania.

Zobacz: Webhooki

Wycena

Cena obliczona z góry dla jednego, dokładnie określonego żądania.

W SpicyAPI: POST /api/v1/jobs/quote przyjmuje tę samą treść, którą wysyła się przy tworzeniu zadania, i zwraca estimatedCost, maxCharge oraz expiresAt, nie tworząc zadania i nie blokując środków. Nic nie kosztuje i jest ważna pięć minut. Jeśli wyślesz zadanie ze zwróconymi quoteId i expectedCost, a żądanie albo cena się zmieniły, wysyłka zostanie odrzucona z kodem 40901, zamiast zostać rozliczona po innej kwocie. CLI i serwer MCP same pobierają wycenę przed utworzeniem zadania.

Zobacz: Wyceny i zgodność protokołów

Zadanie

Jedna porcja pracy wykonywana w tle: przekazujesz ją, a wynik odbierasz później.

W SpicyAPI: każda generacja obrazu lub wideo jest zadaniem. POST /api/v1/jobs/createTask je przyjmuje i zwraca identyfikator zadania zaczynający się od job_; potem odpytujesz zadanie albo dostajesz webhook, gdy się zakończy. Przez API zadanie można odczytać tylko tym samym kluczem API, który je utworzył; strona Logi w konsoli pokazuje wszystkie zadania twojego konta. Przyjętego zadania nie da się anulować.

Zobacz: Zadania asynchroniczne · Nieodwracalność zadań i ponowienia

Zgodność z OpenAI

Przyjmowanie żądań w tym samym formacie co API OpenAI, dzięki czemu oprogramowanie napisane pod OpenAI działa po zmianie samego adresu i klucza.

W SpicyAPI: modele tekstowe możesz wywoływać przez POST /v1/chat/completions i POST /v1/responses w formacie OpenAI, POST /v1/messages w formacie Anthropic oraz /v1beta/models/… w formacie Google Gemini – wszędzie tym samym kluczem API. Oficjalną bibliotekę openai skieruj na https://api.spicyapi.ai/v1. Każdy model tekstowy działa w każdym z tych formatów. Te endpointy naliczają cenę obowiązującą w chwili przyjęcia żądania i nie przyjmują wyceny, więc ustaw na kluczu limity wydatków.

Zobacz: Tekst i streaming

Zmienna środowiskowa

Nazwana wartość, którą terminal przekazuje każdemu uruchamianemu przez siebie programowi. Pozwala programowi odczytać ustawienie, na przykład tajny klucz, bez wpisywania tej wartości do pliku albo do polecenia.

W SpicyAPI: SDK, CLI, serwer MCP i przykłady kodu w tej dokumentacji odczytują klucz API ze zmiennej o nazwie SPICY_API_KEY. Żeby ustawić ją w bieżącym oknie terminala:

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

To ustawienie przepada po zamknięciu okna. Na stronie CLI znajdziesz instrukcję, jak ustawić je na stałe i jak je sprawdzić bez wypisywania całego klucza.

Zobacz: CLI: zanim zaczniesz · Przygotuj konto