اچھی Rivya API integration صرف ایک model کو ایک request بھیجنا نہیں ہے۔

زیادہ تر real product workflows میں ایک چھوٹی chain ہوتی ہے: صحیح model choose کریں، input prepare کریں، ضرورت ہو تو reference files upload کریں، job submit کریں، status watch کریں، credits handle کریں، اور result ready ہونے پر product کو notify کریں۔

یہ article planning shape دکھاتا ہے۔ shortest runnable path کے لیے Rivya API Quickstart استعمال کریں، اور exact request fields کے لیے API docs استعمال کریں۔

product moment سے شروع کریں

endpoints choose کرنے سے پہلے product moment کو ایک sentence میں describe کریں۔

Examples:

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.

یہ sentence integration کو loose API calls کے collection میں بدلنے سے روکتا ہے۔

code لکھنے سے پہلے workflow map کریں

request schema کھولنے سے پہلے یہ table استعمال کریں۔

Workflow step	Product question	API area
Account access	کون سا Rivya account usage own کرتا ہے؟	API Authentication
Model choice	کون سا public model ID اس job کے fit ہے؟	API Models
Reference input	کیا model کو uploaded media چاہیے؟	Files API
Generation	کیا یہ async image، video، یا audio job ہے؟	Create Generation
Chat	کیا یہ generation job کے بجائے 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 کے exist کرنے کی reason ہو۔

step 1: integration کے لیے key بنائیں

specific app، environment، یا workflow کے لیے API key بنائیں جو اسے use کرے گا۔

ہر چیز کے لیے ایک key استعمال کرنے سے بچیں۔ keys کو purpose کے حساب سے name کرنے سے later review آسان ہوتا ہے:

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

key store کرنے سے پہلے API Authentication پڑھیں۔ full secret صرف ایک بار دکھایا جاتا ہے، اس لیے team کو اسے فوراً صحیح server-side secret store میں save کرنا چاہیے۔

step 2: public API list سے models choose کریں

صرف اس لیے model hard-code نہ کریں کہ manual test میں کام کر گیا تھا۔

API Models اور Model API Reference استعمال کر کے confirm کریں:

public model ID
آیا یہ API کے ذریعے available ہے
supported input mode
prompt اور parameter expectations
آیا Files API required ہے
credit behavior اور readiness notes

یہاں بہت سی integrations clean ہو جاتی ہیں۔ جو model manual Studio test کے لیے perfect ہو، وہ automated product flow کے لیے right first model نہ بھی ہو سکتا ہے۔

step 3: decide کریں Files API first version کا حصہ ہے یا نہیں

اگر model text input سے run کر سکتا ہے، تو first version text-only رکھیں۔

Files API صرف تب add کریں جب workflow کو واقعی reference media چاہیے۔

جب چاہیے ہو، define کریں:

product کون سی file kinds accept کرتا ہے
file cleanup step کون own کرتا ہے
upload fail ہونے پر کیا ہوتا ہے
returned file data model parameters میں کیسے pass کیا جاتا ہے
آیا same file reuse ہونی چاہیے یا دوبارہ upload

یہ clean-looking generate button کے پیچھے fragile file experience چھپنے سے بچاتا ہے۔

step 4: ایک generation job 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 کریں
status poll کریں جب تک task terminal state تک نہ پہنچ جائے

request shape کے لیے Create Generation اور result handling کے لیے Generation Status استعمال کریں۔

product کو queued، processing، succeeded، اور failed کو user-facing states سمجھنا چاہیے۔ users سے system details پڑھوانے یا guess کروانے کی ضرورت نہ رکھیں کہ job slow کیوں ہے۔

step 5: chat models کے لیے Chat API استعمال کریں

Chat models کو generation endpoint نہیں بلکہ Chat API استعمال کرنا چاہیے۔

یہ اس لیے matter کرتا ہے کہ chat work کا behavior مختلف ہے:

chat turns API-created sessions سے belong کر سکتے ہیں
non-streaming اور SSE streaming کے user experiences مختلف ہوتے ہیں
image attachments Files API کے file IDs استعمال کرتے ہیں
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 کو directly poll نہیں کرنا چاہیے
downstream systems کو signed completion events چاہیے ہوں
retry اور duplicate handling پہلے ہی designed ہو

Webhook receivers boring اور strict ہونے چاہئیں: signature verify کریں، duplicate-safe events accept کریں، ایک product record update کریں، اور صرف وہ log کریں جو log کرنا safe ہو۔

step 7: product میں credits visible بنائیں

Rivya API Studio جیسے same account credits استعمال کرتی ہے۔

آپ کی integration کو decide کرنا چاہیے کہ اس میں سے کتنا show کرنا ہے۔ کم از کم team کو یہ معلوم ہونا چاہیے:

API key کون سا account own کرتا ہے
کون سا workflow credits consume کر سکتا ہے
credits بہت کم ہونے پر کیا ہوتا ہے
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 استعمال کریں۔

small first version

اچھا first version جان بوجھ کر limited ہوتا ہے۔

For example:

one API key
one selected image model
no file upload yet
one generation request
one status polling path
one simple result preview in your product
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 چھپانا
API flow میں Studio-only assumptions استعمال کرنا
file uploads کو afterthought سمجھنا
idempotency کے بغیر generation requests retry کرنا
ایسے jobs کے لیے Chat API استعمال کرنا جو async generation ہونے چاہئیں
chat turns کے لیے generation endpoints استعمال کرنا
full API keys، webhook secrets، یا temporary file details log کرنا

سب سے safe API workflow ownership، state، اور failure handling کے بارے میں explicit ہوتا ہے۔

آگے کہاں جائیں

public API hub کے لیے Developers سے شروع کریں۔
first request run کرنے کے لیے Rivya API Quickstart استعمال کریں۔
model IDs select کرنے سے پہلے API Models استعمال کریں۔
Files API صرف تب استعمال کریں جب model کو واقعی reference media چاہیے۔
chat turns اور streaming chat responses کے لیے Chat API استعمال کریں۔
جب polling کافی نہ رہے تو API Webhooks استعمال کریں۔
اگر workflow کو ابھی بھی human exploration چاہیے، تو automate کرنے سے پہلے When to Use Rivya API Instead of Studio پڑھیں۔

Rivya API کے ساتھ multimodal workflow بنائیں