एक अच्छा Rivya API integration सिर्फ एक model को एक request भेजना नहीं होता।

ज्यादातर real product workflows में एक छोटी chain होती है: सही model चुनना, input prepare करना, जरूरत हो तो reference files upload करना, task submit करना, status watch करना, credits handle करना और result ready होने पर product को notify करना।

यह article planning shape दिखाता है। Shortest runnable path के लिए Rivya API Quickstart use करें, और exact request fields के लिए API docs use करें।

Product moment से शुरू करें

Endpoints चुनने से पहले product moment को एक sentence में describe करें।

Examples:

Seller listing brief submit करे तो product image draft create करें।
Campaign manager still direction approve करे तो short video concept generate करें।
Internal research tool में chat turn भेजें और response user को stream करें।
Reference image upload करें, supported model request submit करें और result ready होने पर user को notify करें।

यह sentence integration को loose API calls की collection बनने से रोकता है।

Code लिखने से पहले workflow map करें

Request schema खोलने से पहले इस table का use करें।

Workflow step	Product question	API area
Account access	Usage किस Rivya account के पास रहेगा?	API Authentication
Model choice	कौन सा public model ID इस task में fit बैठता है?	API Models
Reference input	क्या model को uploaded media चाहिए?	Files API
Generation	क्या यह async image, video या audio task है?	Create Generation
Chat	क्या यह generation task के बजाय chat model turn है?	Chat API
Status	Product को result ready होने का पता कैसे चलेगा?	Generation Status
Completion event	क्या दूसरे system को signed callback चाहिए?	API Webhooks
Credits	Team cost को कैसे समझेगी?	API Credits

Workflow इतना clear होना चाहिए कि हर API area के पास मौजूद होने का reason हो।

Step 1: Integration के लिए key create करें

उस specific app, environment या workflow के लिए API key create करें जो इसे use करेगा।

हर चीज के लिए one key use करने से बचें। Keys को purpose से name करने पर बाद में review आसान होता है:

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

Key store करने से पहले API Authentication पढ़ें। Full secret सिर्फ एक बार shown होता है, इसलिए आपकी team को इसे तुरंत सही server-side secret store में save करना चाहिए।

Step 2: Public API list से models चुनें

किसी model को सिर्फ इसलिए hard-code न करें कि वह manual test में काम कर गया था।

API Models और Model API Reference से confirm करें:

public model ID
क्या यह API through available है
supported input mode
prompt और parameter expectations
क्या Files API required है
credit behavior और readiness notes

यहां कई integrations cleaner हो जाते हैं। Manual Studio test के लिए perfect model automated product flow का right first model नहीं भी हो सकता।

Step 3: Decide करें कि first version में Files API चाहिए या नहीं

अगर model text input से run कर सकता है, तो first version text-only रखें।

Files API तभी add करें जब workflow को सच में reference media चाहिए।

जब चाहिए, define करें:

product कौन से file kinds accept करता है
file cleanup step किसके पास है
upload fail होने पर क्या होता है
returned file data model parameters में कैसे pass होता है
same file reuse होगी या फिर upload होगी

इससे fragile file experience clean-looking generate button के पीछे hide नहीं होता।

Step 4: One generation task submit करें

Image, video और audio generation के लिए normal pattern यह है:

model ID, prompt और supported params prepare करें
safe retries के लिए idempotency key add करें
generation endpoint से submit करें
public task ID save करें
task terminal state तक पहुंचे, तब तक status poll करें

Request shape के लिए Create Generation और result handling के लिए Generation Status use करें।

Product को queued, processing, succeeded और failed को user-facing states की तरह treat करना चाहिए। Users से system details पढ़वाएं नहीं, और उन्हें यह guess न करने दें कि task slow क्यों है।

Step 5: Chat models के लिए Chat API use करें

Chat models को Chat API use करना चाहिए, generation endpoint नहीं।

यह इसलिए matter करता है क्योंकि chat work का behavior अलग होता है:

chat turns API-created sessions से belong कर सकते हैं
non-streaming और SSE streaming की user experience अलग होती है
image attachments Files API से मिले file IDs use करते हैं
credit settlement normal async media task के बजाय chat turn follow करता है

अगर product को अपने interface के अंदर assistant answer चाहिए, Chat API right path हो सकता है। अगर user अभी ideas explore कर रहा है, Rivya Chat या Studio बेहतर हो सकता है।

Step 6: Polling से शुरू करें, फिर webhooks add करें

First version के लिए polling reason करना आसान है।

API Webhooks तब add करें जब:

product के पास कई async jobs हों
waiting clients को direct poll नहीं करना चाहिए
downstream systems को signed completion events चाहिए
retry और duplicate handling पहले से designed हो

Webhook receivers boring और strict होने चाहिए: signature verify करें, duplicate-safe events accept करें, one product record update करें और सिर्फ safe loggable details log करें।

Step 7: Credits को product में visible बनाएं

Rivya API Studio वाले same account credits use करता है।

आपका integration decide करे कि इसमें से कितना दिखाना है। Minimum पर team को पता होना चाहिए:

API key किस account के पास है
कौन सा workflow credits consume कर सकता है
credits too low होने पर क्या होता है
failed generation states कैसे explain होती हैं
credit और billing questions के लिए user को कहां भेजना है

User-facing wallet model के लिए API Credits, Credits & Billing in Rivya और How to Think About Rivya Credits, Packs, and Plans use करें।

Small first version

एक अच्छा first version intentionally limited होता है।

उदाहरण:

one API key
one selected image model
अभी file upload नहीं
one generation request
one status polling path
आपके product में one simple result preview
one clear credit error message

यह version ज्यादा moving parts add करने से पहले connection prove करता है।

More complete version

First version काम करने के बाद fuller workflow ये add कर सकता है:

reference images या videos के लिए Files API
model-specific parameter controls
आपके product record से tied idempotency
completion के लिए signed webhooks
assistant turns के लिए Chat API
जहां chat को live output चाहिए, वहां server-side event stream
failed jobs के लिए admin या support views

हर addition real product need answer करे। अगर वह सिर्फ demo को बड़ा दिखाता है, तो उसे छोड़ दें।

Common integration mistakes

इन patterns से बचें:

हर API feature से एक साथ start करना
account owner से credit usage hide करना
API flow में Studio-only assumptions use करना
file uploads को afterthought की तरह treat करना
idempotency के बिना generation requests retry करना
Chat API को उन jobs के लिए use करना जिन्हें async generation होना चाहिए
chat turns के लिए generation endpoints use करना
full API keys, webhook secrets या temporary file details log करना

Safest API workflow ownership, state और failure handling के बारे में explicit होता है।

आगे कहां जाएं

Public API hub के लिए Developers से start करें।
First request run करने के लिए Rivya API Quickstart use करें।
Model IDs select करने से पहले API Models use करें।
Files API तभी use करें जब model को सच में reference media चाहिए।
Chat turns और streaming chat responses के लिए Chat API use करें।
Polling enough न रहे तो API Webhooks use करें।
अगर workflow को अभी भी human exploration चाहिए, automate करने से पहले When to Use Rivya API Instead of Studio पढ़ें।

Rivya API के साथ multimodal workflow बनाएं