Byg et multimodalt workflow med Rivya API

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.

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:

1. forbered model-ID, prompt og understøttede params

2. tilføj en idempotency key til sikre retries

3. indsend gennem generation endpointet

4. gem det offentlige task ID

5. 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:

1. én API key

2. én valgt image model

3. ingen filupload endnu

4. én generation request

5. én status polling path

6. én simpel resultatpreview i dit produkt

7. é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.