Rivya API to ścieżka deweloperska do używania możliwości modeli Rivya z własnego produktu, skryptu albo workflow.
Nie jest to osobny produkt względem Rivya Studio. Używa tej samej granicy konta, tego samego portfela kredytów i tej samej publicznej warstwy modeli, którą użytkownicy widzą w Rivya. Różnica dotyczy tego, jak zaczyna się praca: zamiast klikać przez Studio, twoja aplikacja wysyła żądania z kluczem API.
Jeśli potrzebujesz szczegółów endpointów, zacznij od Przegląd Rivya API i Szybki start Rivya API. Ten artykuł jest wyjaśnieniem na poziomie produktu: do czego służy API, gdzie pasuje i kiedy nie powinno być pierwszą ścieżką.
Krótka wersja
Rivya API v1 pozwala zalogowanemu kontu tworzyć API keys i wywoływać możliwości modeli Rivya spoza interfejsu webowego.
Obecna powierzchnia API obejmuje:
- odkrywanie modeli przez listę modeli API
- asynchroniczne zadania generowania obrazów, wideo i audio
- przesyłanie plików przez Files API dla modeli, które potrzebują mediów referencyjnych
- polling statusu generowania z publicznymi ID zadań
- sprawdzanie kredytów konta
- tury Chat API, w tym opcjonalny SSE streaming
- podpisane webhooks dla zakończenia generowania
- TypeScript SDK beta dla zespołów, które chcą wrappera klienta
Publiczny hub deweloperski to Developers. To najlepsze wejście, jeśli chcesz prowadzony przegląd, linki do ustawień API key i bezpieczny przepływ debuggera.
Dlaczego Rivya ma API
Studio jest użyteczne, gdy człowiek nadal wybiera modele, kształtuje prompty, przegląda wyniki i decyduje, co zrobić dalej.
API jest użyteczne, gdy ta decyzja zmieniła się w powtarzalny workflow produktowy albo operacyjny.
Typowe przykłady:
- produkt chce generować warianty obrazów po tym, jak użytkownik prześle brief
- workflow marketingowy musi tworzyć szkice wizualne ze strukturyzowanych danych kampanii
- narzędzie wewnętrzne musi wysyłać zadania wideo albo audio bez proszenia kogoś o otwarcie przeglądarki
- system wsparcia albo treści chce turę modelu chatu we własnym interfejsie
- usługa backendowa chce podpisanych callbacków po zakończeniu zadań generowania
W takich przypadkach Rivya API utrzymuje pracę połączoną z tym samym kontem Rivya, zamiast wymuszać osobny stack do rozliczeń, wyboru modeli i statusu zadań.
Czego API nie zastępuje
API nie zastępuje każdego powodu, aby używać Rivya bezpośrednio.
Użyj Przewodnik po Rivya Studio albo publicznych powierzchni pracy, gdy:
- prompt nadal potrzebuje ludzkiej eksploracji
- wybór modelu nie jest stabilny
- twórca musi wizualnie porównać wyniki
- projekt zależy od zapisanej historii i ręcznego przeglądu
- zespół nie zdecydował, który format wejścia i wyjścia powinien stać się powtarzalny
Użyj API, gdy workflow jest wystarczająco jasny, aby go zautomatyzować.
Ta granica ma znaczenie. Niejasne pytanie kreatywne zwykle najpierw należy do Studio. Znany przepływ produktowy z przewidywalnymi wejściami może przejść do API.
Główne elementy składowe
Myśl o API jak o sześciu połączonych częściach.
| Element | Co obsługuje | Gdzie czytać dalej |
|---|---|---|
| API keys | Dostęp server-to-server z twojego konta | Uwierzytelnianie API |
| Models | Publiczne ID modeli i informacje o gotowości | Modele API |
| Generations | Asynchroniczne zadania obrazów, wideo i audio | Utwórz generowanie |
| Files | Przesyłanie obrazów, wideo albo audio referencyjnych | Files API |
| Chat | Tury chatu non-streaming albo streaming | Chat API |
| Webhooks | Podpisane zdarzenia zakończenia dla zadań generowania | API Webhooks |
Dokumentacja API jest źródłem prawdy dla kształtu żądań i odpowiedzi. Ten artykuł ma pomóc ci zdecydować, której części potrzebujesz najpierw.
Jak działają kredyty
Użycie API pobiera środki z tego samego portfela kredytów konta Rivya co Studio.
Oznacza to, że API nie jest anonimowym proxy modeli. Żądanie należy do konta Rivya, używa klucza API utworzonego przez to konto i podąża za tą samą produktową granicą kredytów opisaną w Kredyty API.
Dla zespołów jest to użyteczne, bo eksperymenty w Studio i użycie API pozostają w jednym modelu operacyjnym. Możesz przetestować model ręcznie, a potem przenieść powtarzalną część do integracji bez tworzenia drugiej warstwy rozliczeń.
Jak pasują pliki
Niektóre modele mogą działać wyłącznie na tekście. Inne potrzebują obrazu, wideo albo pliku audio jako referencji.
W integracjach API takie referencje powinny przechodzić przez Files API. Upload tworzy zarządzany rekord pliku, który można przekazać do obsługiwanych parametrów modelu.
Praktyczna reguła jest prosta:
- jeśli model przyjmuje wejście text-only, zacznij od endpointu generowania
- jeśli model potrzebuje mediów referencyjnych, najpierw prześlij plik
- jeśli model chatu używa załączników obrazów, użyj Chat API i file IDs
Nie projektuj integracji wokół przepływów uploadu dostępnych tylko w przeglądarce ani zapisanych sesji Studio. API ma własną publiczną granicę plików z konkretnego powodu.
Gdzie pomagają webhooks
Polling jest najłatwiejszą pierwszą ścieżką integracji. Wyślij zadanie generowania, zapisz publiczne ID zadania i sprawdzaj status, aż zakończy się sukcesem albo błędem.
Webhooks stają się użyteczne, gdy integracja jest bardziej produkcyjna:
- nie chcesz, aby worker sprawdzał każde zadanie przez polling
- twoja aplikacja musi zaktualizować rekord po zakończeniu generowania
- chcesz podpisane zdarzenie, które można bezpiecznie ponawiać
- nieudane zadania muszą przejść do jasnej ścieżki odzyskiwania
Dla kontraktu podpisanych zdarzeń użyj API Webhooks. Utrzymaj odbiornik webhooka wąsko: weryfikuj podpisy, obsługuj zdarzenia duplikowane i unikaj umieszczania sekretów w logach.
Dobry pierwszy projekt API
Najlepszy pierwszy projekt API jest zwykle mały i konkretny.
Na przykład:
- utwórz API key w ustawieniach
- wywołaj listę modeli
- wybierz jeden dostępny model
- wyślij jedno zadanie generowania z idempotency key
- sprawdź endpoint statusu przez polling
- sprawdź kredyty przed i po
- dopiero potem dodaj Files API, Chat API albo Webhooks
Ta ścieżka daje działającą integrację bez mieszania wszystkich funkcji API w pierwszym teście.
Kiedy API jest złym punktem startowym
API prawdopodobnie nie jest właściwym pierwszym krokiem, gdy:
- zespół nie wybrał jeszcze rodziny modeli
- pożądany wynik zmienia się w każdym uruchomieniu
- prompt zależy od ręcznego smaku i przeglądu
- integracja ukrywałaby użycie kredytów przed osobami, które muszą je rozumieć
- produkt potrzebuje publicznego demo, zanim potrzebuje automatyzacji
W takich przypadkach zacznij od Image, Video, Audio, Chat albo AI Models. Gdy ścieżka stanie się powtarzalna, przenieś stabilną część do API.
Gdzie przejść dalej
- Otwórz Developers, aby zobaczyć publiczny hub API i debugger.
- Przeczytaj Szybki start Rivya API, aby wykonać pierwsze bezpieczne żądanie.
- Przeczytaj Uwierzytelnianie API, zanim umieścisz klucz na serwerze.
- Przeczytaj Modele API, zanim wybierzesz model IDs.
- Przeczytaj Kiedy używać Rivya API zamiast Studio, jeśli granica produktowa nadal jest niejasna.
- Przeczytaj Jak zbudować multimodalny workflow AI z Rivya API, gdy planujesz pełną integrację obrazu, wideo, audio albo chatu.
