ভালো Rivya API integration শুধু একটি model-এ একটি request পাঠানো নয়।

বাস্তব product workflow সাধারণত ছোট একটি chain: সঠিক model বাছা, input প্রস্তুত করা, দরকার হলে reference file upload করা, job submit করা, status দেখা, credits সামলানো এবং result ready হলে product-কে notify করা।

এই article planning shape দেখায়। সবচেয়ে ছোট runnable path-এর জন্য Rivya API Quickstart ব্যবহার করুন, আর exact request field-এর জন্য API docs দেখুন।

product moment দিয়ে শুরু করুন

endpoint বাছার আগে product moment এক বাক্যে লিখুন।

উদাহরণ:

seller listing brief submit করলে একটি product image draft তৈরি করুন।
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 করুন।

এই বাক্য integration-কে আলগা API call-এর collection হয়ে যাওয়া থেকে বাঁচায়।

কোড লেখার আগে workflow map করুন

request schema খোলার আগে এই table ব্যবহার করুন।

workflow ধাপ	product প্রশ্ন	API ক্ষেত্র
account access	কোন Rivya account usage-এর মালিক?	API Authentication
model choice	এই job-এর জন্য কোন public model ID মানায়?	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 এতটা পরিষ্কার হওয়া উচিত, যাতে প্রতিটি API area থাকার কারণ বোঝা যায়।

Step 1: integration-এর জন্য key তৈরি করুন

যে specific app, environment বা workflow key ব্যবহার করবে, তার জন্য API key তৈরি করুন।

একটি key সব কিছুর জন্য ব্যবহার করবেন না। purpose ধরে key নাম দিলে পরে 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 থেকে model বাছুন

manual test-এ কাজ করেছে বলে model hard-code করবেন না।

API Models এবং Model API Reference দিয়ে নিশ্চিত করুন:

public model ID
API দিয়ে available কি না
supported input mode
prompt এবং parameter expectation
Files API দরকার কি না
credit behavior এবং readiness note

এই ধাপে অনেক integration পরিষ্কার হয়। manual Studio test-এর জন্য perfect model automated product flow-এর সঠিক first model নাও হতে পারে।

Step 3: প্রথম version-এ Files API লাগবে কি না ঠিক করুন

model যদি text input দিয়ে run করতে পারে, first version text-only রাখুন।

workflow সত্যিই reference media চাইলে তবেই Files API যোগ করুন।

যোগ করলে আগে define করুন:

product কোন file kind accept করে
file cleanup step-এর মালিক কে
upload fail হলে কী হবে
returned file data model parameter-এ কীভাবে pass হবে
একই file reuse হবে নাকি আবার upload হবে

এতে fragile file experience একটি clean-looking generate button-এর আড়ালে লুকিয়ে থাকে না।

Step 4: একটি generation job submit করুন

image, video এবং audio generation-এর normal pattern হলো:

model ID, prompt এবং supported params প্রস্তুত করুন
safe retry-এর জন্য idempotency key যোগ করুন
generation endpoint দিয়ে submit করুন
public task ID save করুন
task terminal state-এ পৌঁছানো পর্যন্ত status poll করুন

request shape-এর জন্য Create Generation এবং result handling-এর জন্য Generation Status ব্যবহার করুন।

product-এর উচিত queued, processing, succeeded এবং failed-কে user-facing state হিসেবে treat করা। user-কে system detail পড়তে বা job ধীর কেন guess করতে দেবেন না।

Step 5: Chat model-এর জন্য Chat API ব্যবহার করুন

Chat model-এর জন্য Chat API ব্যবহার করা উচিত, generation endpoint নয়।

কারণ chat work-এর behavior আলাদা:

chat turn API-created session-এর অংশ হতে পারে
non-streaming এবং SSE streaming আলাদা user experience দেয়
image attachment Files API থেকে পাওয়া file ID ব্যবহার করে
credit settlement normal async media task নয়, chat turn অনুসরণ করে

আপনার product যদি নিজের interface-এ assistant answer দেখাতে চায়, Chat API সঠিক path হতে পারে। user এখনও idea explore করলে Rivya Chat বা Studio ভালো হতে পারে।

Step 6: polling দিয়ে শুরু করুন, তারপর webhook যোগ করুন

first version-এর জন্য polling বোঝা সহজ।

এই অবস্থায় API Webhooks যোগ করুন:

product-এ অনেক async job আছে
waiting client সরাসরি poll করা উচিত নয়
downstream system signed completion event চায়
retry এবং duplicate handling আগেই design করা

Webhook receiver boring এবং strict হওয়া উচিত: signature verify করা, duplicate-safe event accept করা, একটি product record update করা এবং শুধু safe log লেখা।

Step 7: product-এ credits visible করুন

Rivya API Studio-র মতো একই account credits ব্যবহার করে।

আপনার integration কতটা দেখাবে তা ঠিক করতে হবে। অন্তত team-এর জানা উচিত:

কোন account API key-এর মালিক
কোন workflow credits consume করতে পারে
credits খুব কম হলে কী হবে
failed generation state কীভাবে explain করা হবে
credit এবং billing question-এর জন্য user কোথায় যাবে

user-facing wallet model-এর জন্য API Credits, Credits & Billing in Rivya এবং How to Think About Rivya Credits, Packs, and Plans ব্যবহার করুন।

ছোট first version

ভালো first version ইচ্ছাকৃতভাবে limited হয়।

যেমন:

একটি API key
একটি selected image model
এখনও file upload নেই
একটি generation request
একটি status polling path
আপনার product-এ একটি simple result preview
একটি clear credit error message

এই version আরও moving part যোগ করার আগে connection প্রমাণ করে।

আরও complete version

first version কাজ করার পর fuller workflow যোগ করতে পারে:

reference image বা video-এর জন্য Files API
model-specific parameter control
আপনার product record-এর সঙ্গে tied idempotency
completion-এর জন্য signed webhooks
assistant turn-এর জন্য Chat API
chat live output চাইলে server-side event stream
failed job-এর জন্য admin বা support view

প্রতিটি addition বাস্তব product need-এর উত্তর দেবে। এটি শুধু demo বড় দেখালে বাদ দিন।

সাধারণ integration ভুল

এই pattern এড়িয়ে চলুন:

একসঙ্গে প্রতিটি API feature দিয়ে শুরু করা
account owner-এর কাছ থেকে credit usage লুকানো
API flow-তে Studio-only assumption ব্যবহার করা
file upload-কে afterthought ধরা
idempotency ছাড়া generation request retry করা
async generation হওয়া উচিত এমন job-এর জন্য Chat API ব্যবহার করা
chat turn-এর জন্য generation endpoint ব্যবহার করা
full API key, webhook secret বা temporary file detail log করা

সবচেয়ে নিরাপদ API workflow ownership, state এবং failure handling নিয়ে explicit থাকে।

এরপর কোথায় যাবেন

public API hub-এর জন্য Developers থেকে শুরু করুন।
প্রথম request চালাতে Rivya API Quickstart ব্যবহার করুন।
model ID বাছার আগে API Models ব্যবহার করুন।
model সত্যিই reference media চাইলে তবেই Files API ব্যবহার করুন।
chat turn এবং streaming chat response-এর জন্য Chat API ব্যবহার করুন।
polling যথেষ্ট না হলে API Webhooks ব্যবহার করুন।
workflow-তে এখনও human exploration দরকার হলে automate করার আগে When to Use Rivya API Instead of Studio পড়ুন।

Rivya API দিয়ে multimodal workflow তৈরি করুন