API Fellowi robi teraz wideo: klucze, modele, pierwsze zapytanie

Jeszcze niedawno API Fellowi robiło jedną rzecz: tekst na wejściu, obraz na wyjściu. Teraz robi znacznie więcej. Tym samym kluczem powstają klipy wideo, wybierasz model i do obrazów, i do wideo, a API Console pokazuje każdy z nich z ceną, więc nikt nie musi zgadywać. Jeśli twój produkt potrzebuje obrazów albo krótkiego ruchu, a nie chcesz utrzymywać do tego własnych GPU, ten tekst jest dla ciebie.

Co się zmieniło, w skrócie

• Wideo na tym samym kluczu. Image-to-video, text-to-video i klipy według obrazów referencyjnych, z tym samym saldem i tą samą postacią zapytania co obrazy.
• Pole model. Szybszy, tańszy model do szkiców i mocniejszy do finalnego renderu. Przy obrazach możesz go pominąć i dostać dokładnie to, co zawsze dostawała starsza integracja, w tej samej cenie; zapytanie o wideo zawsze podaje model.
• Katalog czytelny dla kodu. GET /v1/api/models zwraca, co może wywołać twój klucz i ile to kosztuje, więc aplikacja może zbudować własny wybór modelu zamiast trzymać listę, która się zestarzeje.
• Skrót do samej integracji. Konsola ma przycisk „Copy for ChatGPT/Claude”, który kopiuje całą dokumentację naraz. Wklej ją do asystenta programisty i poproś o klienta w swoim języku.

Zdobądź klucz

Załóż darmowe konto, otwórz /api-console, nazwij klucz i go utwórz. Pełny klucz jest pokazywany dokładnie raz; potem konsola trzyma tylko podgląd, więc od razu skopiuj go do magazynu sekretów. Każde zapytanie wysyła go w nagłówku bearer:

Authorization: Bearer fk_live_your_key_here

Trzymaj jeden klucz na środowisko albo na produkt. Każdy klucz może mieć własny dzienny limit monet - to najprostszy sposób, by błąd w pętli testowej nie wydał całego salda przez noc.

Pierwszy obraz

Generowanie jest asynchroniczne. Wstawiasz je do kolejki, od razu dostajesz 202, a obraz przychodzi chwilę później:

POST /v1/api/images
Content-Type: application/json
Authorization: Bearer fk_live_your_key_here
Idempotency-Key: 7f1c2b90-order-4411

{
  "prompt": "a ceramic mug on a linen cloth, soft window light",
  "quality": "standard",
  "aspectRatio": "4:5"
}

Nagłówek Idempotency-Key jest ważniejszy, niż wygląda. Sieć gubi odpowiedzi; z tym nagłówkiem ponowienie tej samej próby zwraca to samo generowanie zamiast płacić dwa razy. Twórz go na każdą próbę, na przykład z własnego id zamówienia. Potem odpytuj, aż będzie gotowe, i pobierz wynik:

GET /v1/api/images/{id}          -> "queued" ... "succeeded"
GET /v1/api/images/{id}/content  -> the image bytes

quality, format, aspectRatio i płatne ulepszanie promptu są opcjonalne, a każda wartość domyślna to zachowanie API sprzed pojawienia się danej opcji. Dodaj kilka adresów obrazów referencyjnych w images, a zapytanie trafi do modelu edycji - tak postać albo produkt pozostaje rozpoznawalny między obrazami.

Wybór modelu

GET /v1/api/models

To zwraca modele obrazów i wideo dostępne dla twojego klucza, z cenami w monetach, a dla wideo z najdłuższym klipem, dostępnymi rozdzielczościami i informacją, czy potrzebna jest klatka startowa. Wybrany przekaż w model. Rozsądny wzór: tani model, gdy użytkownik próbuje, i mocniejszy dla wersji, którą zachowa. Aktualne liczby są też na stronie produktu, która czyta je z tego samego kodu, który pobiera monety.

Pierwszy klip

Image-to-video zaczyna się od kadru. Wyślij go raz i zachowaj id:

POST /v1/api/uploads
{ "imageBase64": "<your start frame, base64>" }

-> { "upload": { "id": "..." } }

Potem wstaw klip do kolejki tak samo jak obraz:

POST /v1/api/videos
Idempotency-Key: 7f1c2b90-clip-4411

{
  "model": "fellowi-image-to-video-turbo",
  "uploadId": "<id from /v1/api/uploads>",
  "prompt": "steam rises slowly from the mug, the camera drifts in",
  "durationSec": 5,
  "resolution": "720p",
  "generateAudio": false
}

Odpytuj GET /v1/api/videos/{id}, aż status będzie succeeded, i pobierz videoUrl. Klip powstaje w minutach, nie w sekundach, więc odpytuj spokojnie i uprzedź o tym użytkowników. Modele text-to-video w ogóle nie potrzebują wysyłki. Cena jest za sekundę klipu w wybranej rozdzielczości, a dźwięk i dodatkowe obrazy referencyjne dolicza się tam, gdzie model je obsługuje. Klipy przez API zawsze opłaca się monetami; limit planu Director działa tylko w webowym studiu wideo.

Wpięcie w prawdziwy produkt

• Klucz zostaje na serwerze. Nigdy nie wysyłaj go do przeglądarki ani aplikacji mobilnej. Twój backend woła nas, twój frontend woła twój backend.
• Traktuj to jak kolejkę zadań. Zapisz id generowania przy własnym rekordzie, odpytuj z workera i zachowaj własną kopię pliku, gdy się pojawi. Nasza kopia służy do dostarczenia, nie jako twoje archiwum.
• Porażka to normalny wynik. Nieudane generowanie samo zwraca monety i podaje jeden z czterech kodów: TIMEOUT, MODERATION_REJECTED, VENDOR_ERROR lub UNKNOWN. Pokaż dla każdego coś pomocnego i pozwól spróbować ponownie.
• Szanuj limit zapytań na klucz. To ochrona przed nadużyciami, a nie przydział, i widać ją przy każdym kluczu w konsoli. Prawdziwym sufitem jest saldo monet.

O cenach i zwrotach piszemy szerzej w tekście dlaczego API rozlicza się w monetach, a o treściach dla dorosłych w tym samym API w przewodniku po API do generowania postaci.

Czego nie robi

Webhooków jeszcze nie ma: odpytujesz. Nie ma darmowego poziomu: każde wywołanie kosztuje monety, w tej samej cenie co w studiu. Nie wyrenderuje tego, co odrzuca moderacja, a treści dla dorosłych nie należą na publiczne platformy, bez względu na to, czym jest twoja aplikacja. I choć nasz regulamin nie ogranicza komercyjnego użycia tego, co wygenerujesz, nie obiecujemy, że obraz jest unikalny albo wolny od wszelkich praw osób trzecich - traktuj go jak zdjęcie stockowe, którego nie zrobiłeś sam. Jeśli to pasuje do tego, co budujesz, zacznij od konsoli.