Dobra integracja Rivya API to nie tylko jedno request do jednego modelu.

Większość realnych product workflows ma mały łańcuch: wybierz właściwy model, przygotuj input, w razie potrzeby upload reference files, submit job, obserwuj status, obsłuż credits i powiadom product, gdy result jest gotowy.

Ten artykuł pokazuje planning shape. Użyj Szybki start Rivya API dla najkrótszej runnable path, a API docs dla dokładnych request fields.

Zacznij Od Product Moment

Przed wyborem endpoints opisz product moment jednym zdaniem.

Przykłady:

Create a product image draft when a seller submits a listing brief.
Generate a short video concept after a campaign manager approves a still direction.
Send a chat turn inside an internal research tool and stream the response back to the user.
Upload a reference image, submit a supported model request, and notify the user when the result is ready.

To zdanie zapobiega temu, aby integration stała się luźnym zbiorem API calls.

Zmapuj Workflow Przed Pisaniem Kodu

Użyj tej tabeli przed otwarciem request schema.

Krok workflow	Pytanie produktowe	Obszar API
Account access	Które konto Rivya owns the usage?	Uwierzytelnianie API
Model choice	Który public model ID pasuje do tego job?	Modele API
Reference input	Czy model potrzebuje uploaded media?	Files API
Generation	Czy to async image, video albo audio job?	Utwórz generowanie
Chat	Czy to chat model turn zamiast generation job?	Chat API
Status	Jak product dowie się, że result jest ready?	Status generowania
Completion event	Czy inny system powinien dostać signed callback?	API Webhooks
Credits	Jak zespół zrozumie cost?	Kredyty API

Workflow powinien być na tyle jasny, aby każdy API area miał powód istnienia.

Krok 1: Utwórz Key Dla Integracji

Utwórz API key dla konkretnej app, environment albo workflow, który będzie go używać.

Unikaj używania jednego key do wszystkiego. Nazywanie keys według purpose ułatwia późniejszy review:

production-image-workflow
staging-video-tests
internal-chat-assistant
webhook-smoke-test

Przeczytaj Uwierzytelnianie API, zanim zapiszesz key. Full secret jest pokazany tylko raz, więc zespół powinien od razu zapisać go we właściwym server-side secret store.

Krok 2: Wybierz Models Z Public API List

Nie hard-code modelu tylko dlatego, że zadziałał w manual test.

Użyj Modele API i Referencja modeli API, aby potwierdzić:

public model ID
czy jest dostępny przez API
supported input mode
oczekiwania wobec prompt i parameters
czy Files API jest wymagane
credit behavior i readiness notes

Tutaj wiele integrations staje się czystszych. Model idealny do manual Studio test może nie być właściwym first model dla automated product flow.

Krok 3: Zdecyduj, Czy Files API Jest Częścią Pierwszej Wersji

Jeśli model może działać z text input, utrzymaj pierwszą wersję jako text-only.

Dodaj Files API tylko wtedy, gdy workflow naprawdę potrzebuje reference media.

Gdy tak jest, zdefiniuj:

jakie file kinds product akceptuje
kto owns the file cleanup step
co się dzieje, gdy upload fails
jak returned file data jest przekazywane do model parameters
czy ten sam file powinien być reused, czy uploaded again

To zapobiega ukryciu kruchego file experience za czysto wyglądającym generate button.

Krok 4: Submit One Generation Job

Dla image, video i audio generation normalny pattern wygląda tak:

przygotuj model ID, prompt i supported params
dodaj idempotency key dla safe retries
submit przez generation endpoint
zapisz public task ID
poll status, aż task osiągnie terminal state

Użyj Utwórz generowanie dla request shape i Status generowania dla result handling.

Product powinien traktować queued, processing, succeeded i failed jako user-facing states. Nie każ users read system details ani zgadywać, dlaczego job jest slow.

Krok 5: Użyj Chat API Dla Chat Models

Chat models powinny używać Chat API, nie generation endpoint.

To ma znaczenie, bo chat work ma inne behavior:

chat turns mogą należeć do API-created sessions
non-streaming i SSE streaming mają różne user experiences
image attachments używają file IDs z Files API
credit settlement podąża za chat turn zamiast zwykłym async media task

Jeśli product potrzebuje assistant answer we własnym interface, Chat API może być właściwą ścieżką. Jeśli user nadal eksploruje ideas, Rivya Chat albo Studio może być lepsze.

Krok 6: Zacznij Od Polling, Potem Dodaj Webhooks

Dla pierwszej wersji polling jest łatwiejszy do zrozumienia.

Dodaj API Webhooks, gdy:

product ma wiele async jobs
waiting clients nie powinny poll directly
downstream systems potrzebują signed completion events
retry i duplicate handling są już zaprojektowane

Webhook receivers powinny być nudne i ścisłe: verify signature, przyjmuj duplicate-safe events, update one product record i loguj tylko to, co safe to log.

Krok 7: Uczyń Credits Widocznymi W Produkcie

Rivya API używa tych samych account credits co Studio.

Twoja integration powinna zdecydować, ile z tego pokazać. Minimum, jakie zespół powinien znać:

które account owns the API key
który workflow może consume credits
co się dzieje, gdy credits są too low
jak failed generation states są wyjaśniane
gdzie wysłać kogoś z pytaniami o credit i billing

Użyj Kredyty API, Przewodnik po kredytach i rozliczeniach Rivya i Jak Myśleć O Rivya Credits, Packs I Plans dla user-facing wallet model.

Mała First Version

Dobra first version jest celowo ograniczona.

Na przykład:

one API key
jeden wybrany model obrazu
jeszcze bez uploadu plików
one generation request
one status polling path
one simple result preview w twoim product
jeden jasny komunikat błędu dotyczący kredytów

Ta first version udowadnia connection przed dodaniem większej liczby moving parts.

Bardziej Kompletna Wersja

Po tym, jak pierwsza wersja działa, pełniejszy workflow może dodać:

Files API dla reference images albo videos
kontrolki parametrów specyficzne dla modelu
idempotency powiązane z twoim product record
signed webhooks dla completion
Chat API dla assistant turns
server-side event stream tam, gdzie chat potrzebuje live output
admin albo support views dla failed jobs

Każdy dodatek powinien odpowiadać na real product need. Jeśli tylko sprawia, że demo wygląda większe, zostaw go poza zakresem.

Częste Integration Mistakes

Unikaj tych pattern:

zaczynanie od wszystkich funkcji API naraz
ukrywanie credit usage przed account owner
używanie Studio-only assumptions w API flow
traktowanie file uploads jako afterthought
ponawianie żądań generacji bez idempotencji
używanie Chat API dla jobs, które powinny być async generation
używanie generation endpoints dla chat turns
logowanie full API keys, webhook secrets albo temporary file details

Najbezpieczniejszy API workflow jasno mówi o ownership, state i failure handling.

Dokąd Przejść Dalej

Zacznij od Developers, aby wejść do public API hub.
Użyj Szybki start Rivya API, aby uruchomić first request.
Użyj Modele API przed wyborem model IDs.
Użyj Files API tylko wtedy, gdy model naprawdę potrzebuje reference media.
Użyj Chat API dla chat turns i streaming chat responses.
Użyj API Webhooks, gdy polling przestaje wystarczać.
Jeśli workflow nadal potrzebuje human exploration, przeczytaj Kiedy używać Rivya API zamiast Studio, zanim go zautomatyzujesz.

Zbuduj Multimodal Workflow Z Rivya API