Narzędzie wiersza poleceń (CLI)

Czym jest CLI

spicyapi to niewielki program, który uruchamiasz w terminalu, czyli w oknie, gdzie zamiast klikać przyciski, wpisujesz polecenia. Każde polecenie wykonuje jedną czynność: wyświetla modele, z których może korzystać twoje konto, mówi, ile będzie kosztować generacja, uruchamia generowanie obrazu albo wideo, czeka, aż się zakończy, i daje ci link do pobrania wyniku.

Nie piszesz żadnego kodu. Wpisujesz polecenie, naciskasz Enter i czytasz odpowiedź.

CLI dobrze się sprawdzi, gdy chcesz:

• wypróbować modele i porównać ceny, zanim ktokolwiek napisze integrację;
• generować obrazy albo wideo na własnym komputerze i zapisywać pliki;
• powtarzać ten sam rodzaj generacji bez przeklikiwania się za każdym razem przez stronę;
• sprawdzić dokładne ustawienia modelu, zanim zbudujesz na nim coś własnego.

CLI obsługuje generowanie obrazów i wideo. Modele tekstowe i modele czatu wywołuje się przez endpointy zgodne z API czatu, opisane na stronie Tekst i streaming.

Są jeszcze trzy inne oficjalne narzędzia. Wybierz CLI, jeśli chcesz samodzielnie wpisywać polecenia:

Piszesz w innym języku? Są też oficjalne SDK dla Pythona, Go, PHP i Javy.

Co możesz zrobić

W poleceniach powyżej słowo w nawiasach ostrych, takie jak <task-id>, oznacza „wstaw tu własną wartość”, bez nawiasów.

Zanim zaczniesz

Potrzebujesz czterech rzeczy: terminala, Node.js, klucza API i sposobu na uruchamianie CLI. Za pierwszym razem zajmuje to około dziesięciu minut.

node -v

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

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

Twój pierwszy wynik

W tym przewodniku wygenerujesz jeden obraz i go pobierzesz. Przy każdym kroku jest polecenie, mniej więcej to, co zobaczysz, i wyjaśnienie, co właśnie się stało. Twoje kwoty, identyfikatory i czasy będą inne.

spicyapi status

SpicyAPI is reachable — api.spicyapi.ai answered in 523 ms.

spicyapi balance

available: 12.34
held: 0.06
total: 12.40

spicyapi models list --modality image --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example image model",
      "modality": "image",
      "tasks": ["text-to-image"],
      "enabled": true,
      "available": true,
      "pricing": [
        { "variant": "", "unit": "per_image", "price": "0.03", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

{
  "model": "MODEL_ID_FROM_CATALOG",
  "enabled": true,
  "available": true,
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "9:16"] }
    },
    "additionalProperties": false
  }
}

cat > input.json <<'EOF'
{"prompt": "A paper lantern glowing on a rainy street at night, cinematic light"}
EOF

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: 0.03
maxCharge: 0.03
currency: USD
quantity: 1
unit: per_image
expiresAt: 2026-09-17T08:05:00Z

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z. Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241. Continue? [y/N]

Accepted: job_01k3m8x9q2z4v7n5p6r8s0t1w3
If waiting is interrupted: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
accepted: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","state":"queued","estimatedCost":"0.03","deadlineAt":"2026-09-17T08:30:00Z"}
task: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","model":"MODEL_ID_FROM_CATALOG","state":"succeeded","output":{"assets":[{"key":"tasks/…/result.png","url":"https://…","expiresAt":"2026-09-17T08:20:00Z","mime":"image/png","width":1024,"height":1024}]},"cost":"0.03","settled":true,…}

curl -L -o result.png "PASTE_THE_URL_HERE"

Jak czytać wynik polecenia

• Zwykły wynik pokazuje jedną parę name: value w każdej linii. Wartości złożone z kilku części, takie jak output czy retention, są wypisywane jako JSON w jednej linii.
• --json wypisuje całą odpowiedź jako JSON z wcięciami. Działa z każdym poleceniem, przed nazwą polecenia albo po niej: spicyapi --json balance i spicyapi balance --json robią to samo.
• Wyniki trafiają na standardowe wyjście, a komunikaty na wyjście błędów. Ceny, klucz idempotentności, linie Accepted: i błędy to komunikaty. Dlatego spicyapi --json tasks get <task-id> > task.json zapisuje w task.json tylko wynik, a komunikaty nadal widać na ekranie.
• Błędy wyglądają tak: Error: <what went wrong> (request req_…), zwykle z linią Next: poniżej, która mówi, co zrobić. Z --json błąd jest jednoliniowym obiektem JSON z polami error, type, status, code i requestId, bez linii Next:. Gdy klucz nie jest ustawiony, type ma wartość MissingApiKeyError. Kontaktując się ze wsparciem, podaj wartość req_….
• Kwoty to sumy w dolarach amerykańskich zapisane zwykłym tekstem, bez znaku $, na przykład 0.03.
• Czasy są w UTC. Z na końcu 2026-09-17T08:05:00Z oznacza UTC.
• Kod wyjścia wynosi 0, gdy polecenie się powiedzie, i jest różny od 0, gdy się nie powiedzie – skrypty mogą to sprawdzać.

Opis poleceń

Każde polecenie ma też wbudowaną pomoc: dodaj --help, na przykład spicyapi tasks create --help.

Opcje globalne i zmienne środowiskowe

Te opcje działają z każdym poleceniem.

status

Co robi: sprawdza, czy SpicyAPI działa i czy jest osiągalne z twojego komputera.

spicyapi status

Bez opcji. Nie wymaga klucza. Bezpłatne.

Wynik: jedno zdanie. SpicyAPI is reachable — … answered in … ms. oznacza, że wszystko jest w porządku. could not be reached oznacza, że twój komputer nie dostał żadnej odpowiedzi: sprawdź sieć albo proxy. is not healthy albo reports it is not ready oznacza problem po naszej stronie; bieżące incydenty są wymienione na status.spicyapi.ai.

Z --json widzisz surowe wyniki sprawdzeń. Liczy się odpowiedź operational: true; pozycja readiness ze statusem 404 jest na publicznym adresie normalna.

docs search

Co robi: znajduje stronę dokumentacji na dany temat. Przeszukuje mały indeks wbudowany w CLI, więc działa bez klucza i bez łączenia się ze SpicyAPI. Każdy wynik prowadzi do strony w tej dokumentacji, docs.spicyapi.ai.

spicyapi docs search [words] [--limit <count>]

spicyapi docs search retention

slug: retention
title: Retention and destruction
summary: What the platform caps are, how far down you can dial them, how to destroy a task's content, and what we cannot promise.
keywords: ["privacy","delete","storage","retention","per-request retention","purge","destroy"]
url: https://docs.spicyapi.ai/docs/retention

Gdy wyników jest kilka, są wypisywane jeden po drugim, a każdy zaczyna się od slug:. Jeśli nic nie pasuje, polecenie o tym informuje i mimo to kończy się kodem wyjścia 0:

No documentation matched "refnd". Try fewer or different words, or run `spicyapi docs search` without words to browse pages.

Z --json brak wyników daje pustą listę, []. Bezpłatne.

models list

Co robi: wyświetla modele, które twoje konto może dziś wywołać, z cenami, jakie płaci twoje konto.

spicyapi models list [options]

spicyapi models list --modality video --task image-to-video --json

Wynik: total i items. Używaj --json, bo bez tej opcji wszystkie pozycje są wypisywane w jednej linii. Najbardziej przydatne pola każdej pozycji:

Bezpłatne. Pobieranie listy modeli wlicza się do limitu żądań twojego konta, więc nie ma potrzeby uruchamiać go przed każdą generacją.

models get

Co robi: pokazuje pełny opis jednego modelu, łącznie z ustawieniami, które przyjmuje.

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

Wynik: te same pola co w models list, a do tego inputSchema. W inputSchema przeczytaj required (ustawienia, które musisz wysłać), properties (każde dozwolone ustawienie i jego typ), enum (jedyne dozwolone wartości), minimum i maximum (granice liczb) oraz default (wartość używana, gdy pominiesz ustawienie). Pozycje o nazwie x-ui to wskazówki do budowania formularzy; możesz je zignorować. Bezpłatne.

balance

Co robi: pokazuje, ile pieniędzy jest dostępnych na twoim koncie.

spicyapi balance

Bez opcji. Bezpłatne.

Wynik: available (kwota, którą możesz teraz wydać), held (środki zablokowane na zadania, które jeszcze trwają) i total, wszystko w dolarach amerykańskich. Może też zawierać funding, które rozbija saldo na środki przedpłacone i środki promocyjne, łącznie z tym, kiedy środki promocyjne wygasają i za które modele płacą. Nie musisz sprawdzać salda przed każdą generacją: tasks create robi to za ciebie.

usage

Co robi: pokazuje, ile generacji uruchomił bieżący klucz API i ile kosztowały, w podziale na dni i modele.

spicyapi usage [--from <date>] [--to <date>]

spicyapi usage --from 2026-09-01 --to 2026-10-01

To obejmuje cały wrzesień: --to to pierwszy dzień, który nie jest uwzględniany. Pomiń obie opcje, żeby zobaczyć ostatnie siedem dni łącznie z dzisiejszym.

Wynik: from, to, currency, totalCalls, totalSpend, a potem days (dla każdego dnia: calls, succeeded, failed, spend) i models (te same liczby dla każdego modelu). totalSpend liczy tylko ostateczne opłaty. days i models opisują te same zadania na dwa sposoby, więc ich nie sumuj. Dane dla całego konta, a nie jednego klucza, znajdziesz w konsoli na stronie Zużycie.

Bezpłatne. Polecenie jest ograniczone do 30 wywołań na minutę, więc używaj go do sprawdzania sum, a nie w pętli.

tasks quote

Co robi: mówi dokładnie, ile kosztowałaby jedna generacja, bez jej uruchamiania i bez blokowania jakichkolwiek środków.

spicyapi tasks quote --model <model> --input-file <path>

Wynik: quoteId, model, estimatedCost, maxCharge, currency, quantity (na przykład liczba rozliczanych sekund), unit i expiresAt. Wycena jest ważna pięć minut.

Bezpłatne, bez potwierdzenia. Używaj tego polecenia, żeby porównywać modele albo ustawienia. Nie musisz uruchamiać go przed tasks create, które pobiera własną wycenę.

tasks create

Co robi: uruchamia generowanie obrazu albo wideo. To kosztuje. CLI zawsze najpierw pokazuje cenę i pyta o zgodę.

spicyapi tasks create --model <model> --input-file <path> [options]

Co się dzieje, po kolei:

1. CLI odczytuje twoje dane wejściowe i sprawdza, czy są obiektem JSON. Jeśli nie podano danych wejściowych, zatrzymuje się w tym miejscu.
2. Jeśli nikt nie może odpowiedzieć na pytanie, na przykład w skrypcie, a nie przekazano --yes, zatrzymuje się w tym miejscu.
3. Pobiera wycenę i wypisuje szacowaną opłatę, maksymalną opłatę, termin wygaśnięcia wyceny i klucz idempotentności.
4. Pyta Continue? [y/N]. Dalej przechodzi tylko po y albo yes. Domyślna odpowiedź to nie.
5. Tworzy zadanie po wycenionej cenie. Szacowana kwota zostaje zablokowana na twoim saldzie i jest zarazem najwyższą kwotą, jaką zadanie może kosztować.
6. Bez --wait wypisuje idempotencyKey, taskId, state (queued), estimatedCost i deadlineAt, a potem kończy działanie. Z --wait od razu wypisuje Accepted: <task-id> i polecenie do odzyskania zadania, czeka, a potem wypisuje idempotencyKey, accepted i zakończone task.

deadlineAt to najpóźniejszy moment, w którym zadanie może się zakończyć, zanim przejdzie w stan expired. To nie jest termin wygaśnięcia linku do pobrania ani plików.

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

W macOS i Linuksie dane wejściowe możesz też podać bezpośrednio w poleceniu:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-json '{"prompt": "A paper lantern on a rainy street"}'

Gdy czekanie kończy się błędem (a nie przez Ctrl + C), ostatnie linie powtarzają wszystko, czego potrzebujesz, więc nie musisz przewijać do linii Accepted::

Error: task job_01k3m8x9q2z4v7n5p6r8s0t1w3 did not reach a terminal state within 600000ms
Task job_01k3m8x9q2z4v7n5p6r8s0t1w3 was accepted and may still be running; only the wait stopped.
Recover: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3
To replay the same request without creating a second task, reuse --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241.

Jeśli błąd ma znane rozwiązanie, na przykład 429 albo błąd serwera, pod spodem pojawia się jeszcze linia Next:. Z --json te same informacje są w obiekcie błędu jako taskId, idempotencyKey i recover.

tasks wait

Co robi: czeka na zadanie, które już zostało uruchomione, aż się zakończy.

spicyapi tasks wait <task-id> [options]

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000

Wynik: zakończone zadanie, z tymi samymi polami co w tasks get, gdy jego stan to succeeded, failed albo expired. Jeśli zadanie się powiodło, ale jego pliki są jeszcze kopiowane, polecenie czeka jeszcze chwilę.

Jeśli limit czasu się skończy, zobaczysz Error: task … did not reach a terminal state within 600000ms. To nie jest niepowodzenie: zadanie wciąż trwa. Poczekaj ponownie, w razie potrzeby z dłuższym --wait-timeout-ms. Przerwanie czekania nigdy nie anuluje zadania. Bezpłatne.

tasks get

Co robi: pokazuje bieżący stan jednego zadania: jego stan, koszt, linki do wyników i to, kiedy jego treść zostanie usunięta.

spicyapi tasks get <task-id>

Użyj tego samego klucza API, którym utworzono zadanie: inny klucz dostanie odpowiedź „nie znaleziono”.

Pola wyniku:

Zwykły wynik kończy się podsumowaniem prostym językiem, na przykład Outputs expire: … albo Content: Destroyed — you removed the outputs …. Każde wywołanie zwraca świeże linki do pobrania. Bezpłatne.

tasks list

Co robi: wyświetla zadania utworzone bieżącym kluczem API, po jednej stronie naraz.

spicyapi tasks list [options]

spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --state failed

Wynik: items (każda pozycja z taskId, model, state, cost, settled, createdAt, deadlineAt i completedAt), hasMore i nextCursor. Jeśli hasMore ma wartość true, uruchom to samo polecenie jeszcze raz, z tymi samymi --from i --to, dodając --cursor z wartością nextCursor. Lista nie zawiera linków do pobrania; dla wybranego zadania użyj tasks get. Bezpłatne.

tasks retry

Co robi: uruchamia ponownie zadanie w stanie failed albo expired, jako nowe zadanie z nowym identyfikatorem. To kosztuje.

spicyapi tasks retry <task-id> [options]

Polecenie pyta Retry source task … Continue? [y/N]. W odróżnieniu od tasks create nie pokazuje ceny, zanim zapyta. Nowe zadanie jest rozliczane według aktualnej ceny modelu, więc jeśli cena ma dla ciebie znaczenie, najpierw sprawdź ją poleceniem spicyapi models get <model>.

Wynik: idempotencyKey, nowy taskId, sourceTaskId (zadanie pierwotne), state, estimatedCost (zablokowana kwota) i deadlineAt.

• Ponowić można tylko zadania failed i expired, a także starsze zadania canceled. Żeby dostać inną wersję udanego wyniku, użyj tasks create.
• Pierwotne dane wejściowe są używane bez zmian, więc ponowienie pomaga tylko wtedy, gdy niepowodzenie było przejściowe. Najpierw sprawdź errorCode; zobacz Ponów nieudane zadanie i Błędy.
• Jeśli dane wejściowe wskazywały przesłany plik, który już wygasł, ponowienie się nie powiedzie; prześlij plik ponownie i użyj tasks create.
• Ponowienie zachowuje ustawienie przechowywania z pierwotnego zadania.
• Jeśli tasks create straciło połączenie, zanim pojawił się identyfikator zadania, to nie jest nieudane zadanie. Zamiast tego wykonaj kroki z sekcji Wróć do zadania po przerwanym czekaniu.

tasks purge

Co robi: trwale usuwa wygenerowane media zakończonego zadania, dane wyniku (zapisane dane, które zwróciło zadanie), prompt i inny tekst wejściowy – od razu, zamiast czekać, aż wygasną.

spicyapi tasks purge <task-id> [--yes]

Zadania, które jest jeszcze w stanie queued albo running, nie da się trwale usunąć. Nie da się go też anulować – nie ma polecenia ani API do anulowania – więc poczekaj, aż się zakończy, poleceniem spicyapi tasks wait <task-id>, a potem je usuń.

Polecenie wyjaśnia, co zostanie usunięte, i prosi o potwierdzenie, bo tej operacji nie da się cofnąć. Najpierw pobierz wszystko, co chcesz zachować.

Wynik: taskId, contentState (purged), purgedAt, contentRemovedBy (user), billingRetained (zawsze true) i mediaDeletionPending, a po nich linia, która wymienia, co zostało zniszczone, i mówi, że zapisane media znikną w ciągu mniej więcej minuty. Jeśli contentState nadal ma wartość present, tym razem nic nie zostało usunięte; spróbuj ponownie później.

Bezpłatne i nie jest zwrotem pieniędzy: wpis w księdze rozliczeń, pobrana kwota, model, stan, znaczniki czasu i identyfikator żądania pozostają w zapisach. Zobacz Przechowywanie i usuwanie danych.

files upload

Co robi: przesyła plik z twojego komputera, na przykład obraz startowy do generacji wideo z obrazu, i daje ci adres spicy://, który wpisujesz w dane wejściowe.

spicyapi files upload <path> [--content-type <type>]

Obsługiwane są obrazy .jpg, .jpeg, .png, .webp i .gif do 10 MiB, wideo .mp4 i .webm oraz dźwięk .mp3 i .wav do 90 MiB i 600 sekund. Model może ustawić własne, niższe limity.

spicyapi files upload ./start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z
width: 1280
height: 720

Wynik: skopiuj wartość uri dokładnie tak, jak została wypisana, do ustawienia pliku w modelu, często image_url. Można jej używać do expiresAt, zwykle przez jeden dzień. Potem prześlij plik ponownie. Przesyłanie jest bezpłatne.

files download-url

Co robi: tworzy nowy link do pobrania wyniku zakończonego zadania. Wypisuje link; nie zapisuje pliku.

spicyapi files download-url <task-id> [--key <key>]

Wynik: key, url i expiresAt. Link działa około 20 minut; otwórz go w przeglądarce albo pobierz plik przez curl. Zadanie, które jeszcze się nie powiodło, daje odpowiedź „nie znaleziono”. Jeśli plik jest jeszcze kopiowany, dostajesz błąd konfliktu; poczekaj kilka sekund i spróbuj ponownie. Gdy pliki zadania zostały już usunięte, nowego linku nie da się utworzyć. Bezpłatne.

webhooks verify

Co robi: jeśli masz serwer, który odbiera callbacki SpicyAPI (zobacz --callback-url), to polecenie sprawdza, czy jeden zapisany callback jest prawdziwy i niezmieniony. Działa w całości na twoim komputerze i nie wymaga klucza API.

spicyapi webhooks verify --body-file <path> --timestamp <seconds> --signature <base64> --payload-version <version>

Wynik: po udanym sprawdzeniu payload (treść callbacku), payloadVersion, taskId, deliveryId (wersja 2) i timestamp. Jeśli cokolwiek się nie zgadza, polecenie wypisuje błąd i kończy się niezerowym kodem wyjścia. Bezpłatne.

Klucz podpisujący powstaje automatycznie przy rejestracji, ale jego wartość nigdy nie jest pokazywana. Żeby dostać klucz, który da się skopiować, otwórz w konsoli stronę Webhooki i kliknij Wygeneruj (albo Wymień, jeśli klucz jest już skonfigurowany). Nowy klucz jest pokazywany tylko raz. Wymiana działa natychmiast, bez okresu przejściowego: stary klucz od razu przestaje podpisywać. Zobacz Webhooki.

Gotowe przepisy

Wygeneruj obraz

spicyapi models list --modality image --json
spicyapi models get MODEL_ID_FROM_CATALOG --json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Wybierz identyfikator z wyniku pierwszego polecenia, zbuduj input.json z ustawień pokazanych przez drugie, a potem uruchom trzecie i potwierdź, wpisując y. Każdy krok wyjaśnia przewodnik Twój pierwszy wynik.

Zamień obraz w wideo

spicyapi models list --modality video --task image-to-video --json
spicyapi models get MODEL_ID_FROM_CATALOG --json

spicyapi files upload ./start-frame.jpg

{
  "prompt": "Slow push-in, rain running down the window",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5
}

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait --wait-timeout-ms 1800000

Przesłanego obrazu można używać przez jeden dzień. Potem prześlij go ponownie.

Wróć do zadania po przerwanym czekaniu

Zadanie wykonuje się dalej, nawet jeśli terminal zostanie zamknięty, sieć się rozłączy, komputer przejdzie w stan uśpienia albo skończy się czas czekania. To, jak do niego wrócisz, zależy od tego, co widać na ekranie:

• Widać Accepted: job_… albo linię Recover: pod błędem. Masz identyfikator zadania. Poczekaj ponownie albo po prostu sprawdź zadanie:

  spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000
  spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

• Widać tylko linię Idempotency-Key:, na przykład dlatego, że połączenie zerwało się podczas tworzenia zadania. Uruchom to samo polecenie jeszcze raz, z tym samym modelem i tymi samymi danymi wejściowymi, i dodaj ten klucz:

  spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241 --wait

  CLI znowu pokaże cenę i zapyta o zgodę, ale jeśli pierwsza próba została przyjęta, SpicyAPI zwróci to samo zadanie, zamiast uruchamiać drugie i za nie pobierać opłatę. Działa to przez 24 godziny z tym samym kluczem API. Jeśli pierwsza próba w ogóle nie dotarła, zadanie powstanie teraz, jeden raz.

• Nie masz żadnej z tych informacji. Wyświetl ostatnie zadania i znajdź właściwe po czasie i modelu:

  spicyapi --json tasks list --limit 10

Ponów nieudane zadanie

Najpierw sprawdź, dlaczego zadanie się nie powiodło:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Potem przeczytaj errorCode. 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ę. tasks retry wysyła te same dane wejściowe jeszcze raz, więc pomaga tylko wtedy, gdy przyczyna była przejściowa:

Pełna lista jest na stronie Błędy.

Gdy ponowienie ma sens, uruchom je. Tworzy ono nowe zadanie i pobiera za nie opłatę:

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

Wyeksportuj zużycie

Zapisz w pliku zużycie bieżącego klucza z jednego miesiąca:

spicyapi --json usage --from 2026-09-01 --to 2026-10-01 > usage-2026-09.json

Plik zawiera sumy dzienne i sumy dla poszczególnych modeli. Żeby dostać listę zadanie po zadaniu, zapisz w ten sam sposób wynik spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100, przechodząc do kolejnych stron za pomocą nextCursor, dopóki hasMore ma wartość true. Dane dla całego konta i faktury są w konsoli.

Uruchom CLI ze skryptu

W skrypcie nikt nie odpowie na Continue? [y/N], więc płatne polecenia odmawiają działania, jeśli nie dodasz --yes. Gdy go dodajesz:

• najpierw pobierz wycenę i sprawdź cenę w skrypcie;
• każdej generacji nadaj własny, stały --idempotency-key, na przykład poster-2026-09-17-v1, żeby dwukrotne uruchomienie skryptu nie obciążyło cię dwa razy;
• dodaj --json i odczytaj state z wyniku: polecenie zakończone kodem wyjścia 0 nie musi oznaczać, że zadanie się powiodło;
• ustaw limity wydatków klucza w konsoli.

spicyapi --json tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key poster-2026-09-17-v1 --yes --wait > result.json

Koszty, potwierdzenia i bezpieczeństwo

Które polecenia kosztują. Tylko tasks create i tasks retry. Ceny są w dolarach amerykańskich. Wycenianie, wyświetlanie list, sprawdzanie, przesyłanie, pobieranie i usuwanie są bezpłatne.

Najpierw cena. tasks quote wycenia żądanie, niczego nie uruchamiając. tasks create pobiera własną wycenę i pokazuje Estimated charge oraz maximum charge, zanim zapyta o zgodę. Gdy zadanie zostaje przyjęte, szacowana kwota zostaje zablokowana (held) i jest zarazem najwyższą kwotą, jaką możesz zapłacić. Gdy zadanie się powiedzie, płacisz za to, co faktycznie powstało, nigdy więcej niż wynosi ta kwota, a reszta wraca na twoje saldo.

Potwierdzenie. Continue? [y/N] oznacza, że odpowiedź brzmi nie, dopóki nie wpiszesz y. --yes odpowiada za ciebie, więc używaj tej opcji dopiero wtedy, gdy znasz cenę. Jeśli CLI działa w miejscu, gdzie nie może zapytać, na przykład w skrypcie albo z danymi przekazanymi potokiem, a --yes nie podano, odmawia działania, zamiast przyjąć, że odpowiedź brzmi „tak”. tasks purge pyta w ten sam sposób, bo usunięcia nie da się cofnąć. tasks retry też pyta, ale nie pokazuje wcześniej ceny.

Klucz idempotentności, prostymi słowami. To etykieta jednej generacji, coś jak numer zamówienia. Każde tasks create i tasks retry go wypisuje. Jeśli połączenie z internetem się zerwie i nie wiesz, czy generacja ruszyła, uruchom to samo polecenie jeszcze raz z --idempotency-key i wypisaną wartością: dostaniesz z powrotem pierwotne zadanie i nie zapłacisz dwa razy. Etykieta działa przez 24 godziny z tym samym kluczem API. Nie używaj jej ponownie do innej generacji: ten sam klucz z innymi danymi wejściowymi zostanie odrzucony.

Bez anulowania. Przyjętego zadania nie da się anulować. Ctrl + C, zamknięcie terminala albo unieważnienie klucza przerywają tylko czekanie; zadanie się kończy i jest normalnie rozliczane.

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ę.

Pobierz to, co chcesz zachować. Pliki wyników są przechowywane najwyżej przez około 14 dni albo krócej, jeśli tak mówi ustawienie konta albo --retention, a potem są usuwane na dobre. Linki do pobrania działają około 20 minut, ale dopóki plik istnieje, zawsze możesz poprosić o nowy. Przesłanych plików można używać przez jeden dzień. Tekst promptu jest domyślnie wymazywany po 30 dniach. Zapisy rozliczeniowe są zachowywane. Zobacz Przechowywanie i usuwanie danych.

Limity wydatków. Każdy klucz może mieć dzienny, miesięczny i łączny limit wydatków, ustawiany na stronie Klucze API. Nowe klucze nie mają limitu, dopóki go nie ustawisz. Zadanie, które przekroczyłoby limit, jest odrzucane, zanim ruszy.

Twój klucz. CLI odczytuje klucz wyłącznie z SPICY_API_KEY, nigdy go nie wypisuje, a we wskazówkach przy błędach pokazuje najwyżej jego pierwsze dziewięć znaków (sk-spicy-).

Więcej szczegółów: Rozliczenia, Idempotentność, Nieodwracalność zadań i ponowienia.

Rozwiązywanie problemów

Znajdź komunikat, który widzisz. Błędy zwracane przez SpicyAPI kończą się na (request req_…); jeśli kontaktujesz się ze wsparciem, podaj tę wartość, ale nigdy nie wysyłaj swojego klucza.

Każdy kod błędu jest wyjaśniony na stronie Błędy, a kroki naprawcze – na stronie Rozwiązywanie problemów i przywracanie działania.

Kod źródłowy

Pakiet jest na licencji MIT i powstaje otwarcie pod adresem github.com/spicyapi-ai/spicy-cli. Tam przeczytasz kod każdego polecenia z tej strony, zgłosisz zachowanie inne niż opisane i zaproponujesz zmianę.

Co dalej