Samouczek: z obrazu do wideo

Przygotuj konto, saldo i klucz API

Najpierw przejdź przez stronę Przygotuj konto. Na koniec będziesz mieć:

• konto SpicyAPI ze środkami na saldzie;
• klucz API, który zaczyna się od sk-spicy-;
• ten klucz zapisany w zmiennej środowiskowej o nazwie SPICY_API_KEY. Zmienna środowiskowa to nazwana wartość, którą terminal przekazuje uruchamianym przez siebie programom, dzięki czemu klucz nigdy nie musi pojawić się w poleceniu ani w twoim kodzie.

Sprawdź, czy klucz jest ustawiony w oknie terminala, którego używasz – bez wypisywania całego klucza:

echo "${SPICY_API_KEY:0:9}"

Co zobaczysz: sk-spicy-. Jeśli nic się nie wypisuje albo pojawia się błąd, klucz nie jest ustawiony w tym oknie; wróć do strony Przygotuj konto.

Umieść obraz w folderze roboczym

Utwórz folder na ten samouczek i otwórz w nim terminal. Każde polecenie z tej strony uruchamiasz z tego folderu i właśnie tu trafia każdy plik, który powstaje po drodze.

mkdir -p ~/spicy-video
cd ~/spicy-video

Skopiuj obraz do tego folderu i nazwij go start-frame.jpg (albo start-frame.png, jeśli to plik PNG; wtedy używaj tej nazwy wszędzie tam, gdzie ta strona pisze start-frame.jpg).

Jaki obraz dobrze sprawdzi się na start:

• Format i rozmiar: JPEG, PNG, WebP albo GIF, do 10 MiB (około 10 megabajtów). Model może mieć własne, ostrzejsze limity, które zobaczysz w kroku 1.
• Plik musi naprawdę być w tym formacie. SpicyAPI sprawdza zawartość pliku, a nie tylko jego nazwę. Zdjęcia z telefonów są często w formacie HEIC, a zmiana nazwy takiego pliku na .jpg go nie konwertuje. Najpierw otwórz zdjęcie i wyeksportuj je albo zapisz jako JPEG.
• Kształt: obraz staje się pierwszą klatką. Do poziomego wideo użyj poziomego obrazu, a do pionowego – pionowego; niektóre modele mają też ustawienie aspect_ratio.
• Prawa: użyj obrazu, z którego masz prawo korzystać.

Przygotuj wybrane narzędzie

npm install -g @spicyapi/cli
spicyapi --version

spicyapi balance

1. Wybierz model i przeczytaj jego ustawienia

Zrób to: wyświetl modele wideo z obrazu, z których może korzystać twoje konto, wybierz jeden, a potem sprawdź, jakie ustawienia przyjmuje.

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

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example video model",
      "modality": "video",
      "tasks": ["image-to-video"],
      "enabled": true,
      "available": true,
      "quantityField": "duration_seconds",
      "maxOutputDurationSeconds": 10,
      "taskTimeoutSeconds": 1800,
      "pricing": [
        { "variant": "720p", "unit": "per_second", "price": "…", "currency": "USD" },
        { "variant": "1080p", "unit": "per_second", "price": "…", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

Na co patrzeć na liście:

Jak czytać ustawienia. inputSchema to lista ustawień modelu zapisana w JSON Schema:

• required wymienia ustawienia, które musisz wysłać. W tego rodzaju modelach zawsze jest wśród nich image_url, a większość wymaga też prompt.
• properties wymienia każde ustawienie, które model przyjmuje. Każde ma type, opis description napisany prostym angielskim, a często też enum (jedyne dozwolone wartości), minimum i maximum oraz default (wartość używana, gdy pominiesz to ustawienie).
• W każdym ustawieniu x-ui zawiera wskazówki do wyświetlania. x-ui.affects_price: true oznacza, że zmiana tego ustawienia zmienia cenę.
• Niektóre modele dodają na najwyższym poziomie warunki, na przykład „jeśli wysyłasz A, musisz też wysłać B”. Jak je czytać, wyjaśnia strona Spicy Schema.
• examples zawiera kompletne dane wejściowe, które serwer już sprawdził – to bezpieczny punkt wyjścia.

Ustawienia, które spotkasz najczęściej. Nazwy są takie same we wszystkich modelach, ale każdy model przyjmuje tylko część z nich, z własnymi dozwolonymi wartościami:

Co się właśnie stało: odczytano katalog na żywo dla twojego konta, razem z twoimi cenami. Nie pobrano żadnej opłaty. Odczyt katalogu wlicza się do limitu żądań twojego konta, więc nie trzeba go powtarzać przed każdym wideo; zrób to ponownie, gdy zmieniasz model albo dostajesz 400.

2. Prześlij obraz

Zrób to: prześlij start-frame.jpg i skopiuj adres spicy://, który dostaniesz w odpowiedzi. Przesyłanie jest bezpłatne.

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

Co się właśnie stało: twój obraz został zapisany prywatnie dla twojego konta, sprawdzony (jego rzeczywisty format musi zgadzać się z zadeklarowanym typem) i dostał adres spicy://. Ten adres nie jest linkiem internetowym: może go używać tylko twoje konto i tylko w danych wejściowych zadania. Można go używać przez jeden dzień (zobacz expiresAt); potem prześlij obraz ponownie.

Jeśli przesyłanie się nie udaje:

3. Opisz wideo i sprawdź cenę

Zrób to: zapisz ustawienia w pliku o nazwie input.json, a potem poproś o wycenę.

Zapisz input.json. Zacznij od dwóch ustawień, które przyjmuje każdy model wideo z obrazu. W prompt wpisz własne zdanie, a wartość image_url zastąp wartością uri skopiowaną w kroku 2:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}

Ustawienia, które pominiesz, dostaną wartość default modelu. Jeśli chcesz wybrać je samodzielnie, dodaj tylko takie ustawienia, które wymienia properties twojego modelu, z wartościami, na które pozwala. Na przykład jeśli twój model wymienia duration_seconds i resolution i dopuszcza takie wartości:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5,
  "resolution": "720p"
}

Zapisz plik w folderze roboczym:

cat > input.json <<'EOF'
{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}
EOF

Używaj zwykłych, prostych cudzysłowów ("), a nie drukarskich, i nie stawiaj przecinka po ostatnim ustawieniu.

Pobierz wycenę:

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

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

Co się właśnie stało: SpicyAPI sprawdziło twoje dane wejściowe względem ustawień modelu i wyceniło dokładnie to żądanie. Nic nie zostało uruchomione i nie pobrano żadnej opłaty. estimatedCost to kwota, która zostanie zablokowana, jeśli uruchomisz generację teraz, a maxCharge to najwięcej, ile może to kosztować. quantity i unit pokazują, za co płacisz, na przykład za 5 sekund.

Wycena jest ważna pięć minut i tylko dla dokładnie tych danych wejściowych. Zmień długość albo rozdzielczość i wyceń ponownie, żeby porównać ceny. Wycena przeprowadza te same kontrole co uruchomienie zadania, więc problemy wychodzą na jaw tutaj, bez żadnych kosztów: 400 oznacza, że dane wejściowe nie pasują do ustawień modelu (popraw input.json według kroku 1), a 40201 – że saldo nie pokryłoby tej kwoty. Pozostałe kody wymienia krok 7.

4. Uruchom generację

Klucz idempotentności, prostymi słowami. To etykieta jednego wideo, coś jak numer zamówienia. Jeśli połączenie się zerwie i nie wiesz, czy wideo ruszyło, wyślij to samo żądanie jeszcze raz z tą samą etykietą: SpicyAPI zwróci zadanie, które już uruchomiło, zamiast uruchamiać drugie i pobierać za nie opłatę. Etykieta działa przez 24 godziny z tym samym kluczem API. Do innego wideo użyj nowej etykiety: ta sama etykieta z innymi danymi wejściowymi zostanie odrzucona z kodem 409. Więcej na stronie Idempotentność.

Zrób to:

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

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

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
taskId: job_01k3m8x9q2z4v7n5p6r8s0t1w3
state: queued
estimatedCost: …
deadlineAt: 2026-09-17T08:35:00Z

Co się właśnie stało: SpicyAPI przyjęło generację, która jest teraz zadaniem, i zablokowało kwotę estimatedCost na twoim saldzie. To zarazem najwięcej, ile to wideo może kosztować. state: queued oznacza, że zadanie czeka na swoją kolej. deadlineAt to najpóźniejszy moment, w którym może się zakończyć; jeśli do tego czasu nie będzie gotowe, kończy się stanem expired i nie pobiera się za nie żadnej opłaty. deadlineAt to nie jest termin wygaśnięcia twoich plików.

Przekazanie wyceny oznacza: „przyjmij to tylko po cenie, którą mi pokazano”. Jeśli w międzyczasie zmieniła się cena albo dane wejściowe, żądanie zostanie odrzucone z kodem 40901, zamiast zablokować inną kwotę. CLI robi to za ciebie.

Jeśli połączenie zostało zerwane, a identyfikator zadania się nie pojawił, nie zaczynaj po prostu od nowa z nową etykietą – to utworzyłoby drugie wideo i pobrało za nie opłatę. Powtórz żądanie z tą samą etykietą:

• CLI: spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key <the value you copied> (zamiast <the value you copied> wklej skopiowaną wcześniej wartość Idempotency-Key). Zobacz Wróć do zadania po przerwanym czekaniu.
• SDK: uruchom jeszcze raz node generate.mjs --yes; skrypt ponownie użyje idempotency-key.txt.
• HTTP: uruchom jeszcze raz blok „Uruchom wideo”; on też ponownie używa idempotency-key.txt.

Jeśli krok 4 został odrzucony, nic nie zostało utworzone i nie pobrano żadnej opłaty; przyczynę i sposób naprawy znajdziesz w kroku 7.

5. Poczekaj na wideo

Zrób to: sprawdzaj zadanie, aż się zakończy. Wideo powstaje zwykle w kilka minut.

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

{
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "state": "succeeded",
  "output": {
    "assets": [
      {
        "key": "tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4",
        "url": "https://…",
        "expiresAt": "2026-09-17T08:40:00Z",
        "mime": "video/mp4",
        "durationSeconds": 5,
        "width": 1280,
        "height": 720,
        "bytes": 4839211
      }
    ]
  },
  "cost": "…",
  "settled": true
}

Co się właśnie stało: twoje narzędzie co kilka sekund pytało SpicyAPI o zadanie. Stany to queued (czeka), running (trwa generowanie), a potem jeden stan końcowy: succeeded, failed albo expired. Po powodzeniu plik jest kopiowany do własnego magazynu SpicyAPI, co zajmuje jeszcze kilka sekund; do tego czasu wynik pokazuje pending: true. Kwota cost jest ostateczna, gdy settled ma wartość true.

• Zamknięcie terminala albo naciśnięcie Ctrl + C nie anuluje zadania. Przerywa tylko czekanie. Zachowaj identyfikator zadania i powtórz ten krok później.
• Nie sprawdzaj częściej niż co kilka sekund. Sprawdzanie zadania korzysta z osobnego limitu odczytów konta i nie zużywa limitu uruchamiania zadań; zobacz Limity żądań.
• W aplikacji albo na serwerze zamiast pytać, pozwól, żeby SpicyAPI samo dało znać, kiedy zadanie jest gotowe: zobacz Powiadomienie zamiast czekania.

6. Pobierz i zachowaj wideo

Zrób to: zdobądź świeży link do pobrania i zapisz plik na swoim komputerze.

spicyapi files download-url job_01k3m8x9q2z4v7n5p6r8s0t1w3

key: tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4
url: https://…
expiresAt: 2026-09-17T08:52:00Z

curl -L -o my-video.mp4 "PASTE_THE_URL_HERE"

Co się właśnie stało: każdy wynik ma bezpośredni link do pobrania. Link działa przez około 20 minut i nie wymaga klucza API; nigdy nie doklejaj do niego swojego klucza. Gdy wygaśnie, zapytaj ponownie o zadanie (albo użyj files download-url), żeby dostać nowy.

7. Gdy coś pójdzie nie tak

Problemy są dwóch rodzajów i każdy z nich obsługuje się inaczej.

Żądanie zostaje odrzucone. Polecenie albo wywołanie od razu kończy się błędem. Nic nie zostało utworzone i nie pobrano żadnej opłaty. Komunikat mówi, dlaczego, a błąd zawiera code i identyfikator żądania (req_…), który podajesz, kontaktując się ze wsparciem.

Zadanie kończy się niepowodzeniem. Zadanie zostało przyjęte, ale kończy się stanem failed albo expired zamiast succeeded. Zadanie pokazuje errorCode, który mówi, dlaczego tak się stało, i errorMessage z dokładniejszym opisem słownym. 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ę.

Odczytaj je:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Potem zdecyduj, co zrobić, na podstawie errorCode, a nie brzmienia komunikatu:

Każdą inną wartość traktuj tak jak upstream_failed. Pełna lista jest na stronie Błędy.

Uruchom nieudane zadanie ponownie. Ponowienie tworzy nowe zadanie z tym samym modelem i tymi samymi danymi wejściowymi, po bieżącej cenie modelu. Kosztuje, tak jak krok 4, i zachowuje pierwotne dane wejściowe: jeśli korzystały one z przesłanego pliku, który już wygasł, prześlij go ponownie i zamiast ponowienia uruchom nowe zadanie.

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

Ponowić można tylko zadania failed i expired. Jeśli chcesz inną wersję wideo, które się udało, wróć do kroku 3 z nową etykietą. Przyjętego zadania nie da się anulować. Więcej na stronie Nieodwracalność zadań i ponowienia.