En god Rivya API-integration er ikke bare én request til én model.

De fleste reelle produktworkflows har en lille kæde: vælg den rigtige model, forbered inputtet, upload referencefiler når det er nødvendigt, indsend et job, følg status, håndter credits, og giv produktet besked, når resultatet er klar.

Denne artikel viser planlægningsformen. Brug Rivya API Quickstart til den korteste kørbare vej, og brug API-dokumentationen til præcise requestfelter.

Start med produktøjeblikket

Før du vælger endpoints, skal du beskrive produktøjeblikket i én sætning.

Eksempler:

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.

Den sætning forhindrer integrationen i at blive en løs samling API-kald.

Kortlæg workflowet før du skriver kode

Brug denne tabel, før du åbner requestskemaet.

Workflowtrin	Produktspørgsmål	API-område
Kontoadgang	Hvilken Rivya-konto ejer forbruget?	API Authentication
Modelvalg	Hvilket offentligt model-ID passer til dette job?	API Models
Referenceinput	Har modellen brug for uploadede medier?	Files API
Generering	Er dette et asynkront image-, video- eller audio-job?	Create Generation
Chat	Er dette et chat model turn i stedet for et generation job?	Chat API
Status	Hvordan ved produktet, at resultatet er klar?	Generation Status
Completion event	Skal et andet system modtage en signeret callback?	API Webhooks
Credits	Hvordan skal teamet forstå omkostningen?	API Credits

Workflowet skal være tydeligt nok til, at hvert API-område har en grund til at eksistere.

Trin 1: Opret en nøgle til integrationen

Opret en API key til den specifikke app, det miljø eller det workflow, der skal bruge den.

Undgå at bruge én nøgle til alt. Navngivning efter formål gør senere review lettere:

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

Læs API Authentication, før du gemmer nøglen. Den fulde secret vises én gang, så dit team bør straks gemme den i den rigtige server-side secret store.

Trin 2: Vælg modeller fra den offentlige API-liste

Hard-code ikke en model, bare fordi den virkede i en manuel test.

Brug API Models og Model API Reference til at bekræfte:

det offentlige model-ID
om den er tilgængelig gennem API'et
understøttet inputmode
forventninger til prompt og parametre
om Files API er påkrævet
kreditadfærd og readiness-noter

Det er her, mange integrationer bliver renere. En model, der er perfekt til en manuel Studio-test, er ikke nødvendigvis den rigtige første model til et automatiseret produktflow.

Trin 3: Beslut om Files API er del af første version

Hvis modellen kan køre fra tekstinput, så hold første version text-only.

Tilføj kun Files API, når workflowet virkelig har brug for referencemedier.

Når det gør, skal du definere:

hvilke filtyper produktet accepterer
hvem der ejer filoprydningstrinnet
hvad der sker, når upload fejler
hvordan de returnerede fildata sendes ind i modelparametre
om den samme fil skal genbruges eller uploades igen

Det forhindrer en skrøbelig filoplevelse i at blive skjult bag en generér-knap, der ser ren ud.

Trin 4: Indsend ét generation job

For image-, video- og audiogenerering er det normale mønster:

forbered model-ID, prompt og understøttede params
tilføj en idempotency key til sikre retries
indsend gennem generation endpointet
gem det offentlige task ID
poll status, indtil tasken når en terminal state

Brug Create Generation til requestformen og Generation Status til resulthåndtering.

Produktet bør behandle queued, processing, succeeded og failed som brugervendte states. Lad ikke brugere læse systemdetaljer eller gætte, hvorfor et job er langsomt.

Trin 5: Brug Chat API til chatmodeller

Chatmodeller bør bruge Chat API, ikke generation endpointet.

Det betyder noget, fordi chatarbejde har anden adfærd:

chat turns kan tilhøre API-oprettede sessions
non-streaming og SSE streaming giver forskellige brugeroplevelser
billedvedhæftninger bruger file IDs fra Files API
kreditafregning følger chat turnet i stedet for en almindelig asynkron mediatask

Hvis dit produkt har brug for et assistantsvar inde i sin egen grænseflade, kan Chat API være den rigtige vej. Hvis brugeren stadig udforsker idéer, kan Rivya Chat eller Studio være bedre.

Trin 6: Start med polling, og tilføj derefter webhooks

Til en første version er polling lettere at ræsonnere om.

Tilføj API Webhooks, når:

produktet har mange asynkrone jobs
ventende clients ikke bør poll'e direkte
downstream-systemer har brug for signerede completion events
retry- og duplikathåndtering allerede er designet

Webhook receivers bør være kedelige og strikte: verificer signaturen, accepter duplikatsikre events, opdater én produktrecord, og log kun det, der er sikkert at logge.

Trin 7: Gør credits synlige i produktet

Rivya API bruger de samme kontocredits som Studio.

Din integration bør beslutte, hvor meget af det der skal vises. Som minimum bør teamet vide:

hvilken konto der ejer API key'en
hvilket workflow der kan forbruge credits
hvad der sker, når credits er for lave
hvordan failed generation states forklares
hvor man sender nogen hen med kredit- og billing-spørgsmål

Brug API Credits, Credits & Billing in Rivya og How to Think About Rivya Credits, Packs, and Plans til den brugervendte wallet-model.

En lille første version

En god første version er bevidst begrænset.

For eksempel:

én API key
én valgt image model
ingen filupload endnu
én generation request
én status polling path
én simpel resultatpreview i dit produkt
én klar kreditfejlbesked

Den version beviser forbindelsen, før du tilføjer flere bevægelige dele.

En mere komplet version

Når første version virker, kan et fyldigere workflow tilføje:

Files API til referencebilleder eller videoer
modelspecifikke parameterkontroller
idempotency bundet til din produktrecord
signerede webhooks til completion
Chat API til assistant turns
en server-side event stream, hvor chat har brug for live output
admin- eller supportvisninger til failed jobs

Hver tilføjelse bør svare på et reelt produktbehov. Hvis den kun får demoen til at se større ud, så lad den blive ude.

Almindelige integrationsfejl

Undgå disse mønstre:

at starte med alle API-features på én gang
at skjule kreditforbrug for kontoejeren
at bruge Studio-only-antagelser i et API-flow
at behandle filuploads som en eftertanke
at retry generation requests uden idempotency
at bruge Chat API til jobs, der bør være asynkron generering
at bruge generation endpoints til chat turns
at logge fulde API keys, webhook secrets eller midlertidige fildetaljer

Det sikreste API-workflow er eksplicit om ejerskab, state og fejlhåndtering.

Hvor du går videre

Start fra Developers for den offentlige API-hub.
Brug Rivya API Quickstart til at køre den første request.
Brug API Models, før du vælger model-IDs.
Brug kun Files API, når modellen virkelig har brug for referencemedier.
Brug Chat API til chat turns og streaming chat responses.
Brug API Webhooks, når polling ikke længere er nok.
Hvis workflowet stadig har brug for menneskelig udforskning, så læs When to Use Rivya API Instead of Studio, før du automatiserer det.

Byg et multimodalt workflow med Rivya API