VberAI API, VberAI की AI क्षमताओं (आज: AI सुपर मैटिंग) को आपके ऐप्स, गेम्स और ऑटोमेशन पाइपलाइनों में एम्बेड करने के लिए एक RESTful HTTP API है। ऑथेंटिकेशन हस्ताक्षर-आधारित अनुरोधों के साथ API कुंजियों का उपयोग करता है; सामान्य त्रुटि कोड मानकीकृत हैं; प्रति-कॉल बिलिंग VberAI क्रेडिट में भुगतान की जाती है।
API v1
स्थिर
API दस्तावेज़
HTTP पर सीधे images जनरेट करें, backgrounds हटाएँ, और VberAI की AI pipelines चलाएँ — personal या enterprise API keys के साथ।
VberAI API उन्हीं AI pipelines को — background हटाना, super matting, image जनरेशन और अन्य — जो studio को चलाती हैं, सरल HTTP endpoints के रूप में उपलब्ध कराता है। किसी API key से प्रमाणीकरण करें, एक job सबमिट करें, और परिणाम वापस पढ़ें या उसे किसी webhook पर प्राप्त करें।
एक ही अनुरोध आकार
हर सेवा एक { input } body लेती है और एक task लौटाती है जिसे आप पोल कर सकते हैं या webhook द्वारा प्राप्त कर सकते हैं।
दो key प्रकार
एकल developers के लिए व्यक्तिगत keys, और server-to-server org उपयोग के लिए एंटरप्राइज़ keys।
पूर्वानुमेय बिलिंग
सबमिट पर क्रेडिट आरक्षित होते हैं और सफलता पर तय (settle) होते हैं; विफल jobs का स्वतः रिफंड हो जाता है।
यह कैसे काम करता है
1X-API-Key header में अपनी API key से प्रमाणीकरण करें।
2किसी सेवा को JSON { input } body के साथ एक job सबमिट करें।
3परिणाम को इनलाइन पढ़ें (sync सेवाएँ) या task को पोल करें / webhook प्राप्त करें (async सेवाएँ)।
bash
# 1. Submit a jobcurl-X POST https://api.vberai.com/api/ai/services/ai-image-bg-remove/execute \
-H"X-API-Key: vber_sk_YOUR_KEY" \
-H"Content-Type: application/json" \
-d'{"input": {"imageUrl": "https://example.com/photo.png"}}'# => { "data": { "taskId": "...", "status": "queued" } }# 2. Poll until status is "completed"curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H"X-API-Key: vber_sk_YOUR_KEY"
प्रमाणीकरण और API keys
हर अनुरोध X-API-Key header में भेजी गई API key से प्रमाणित होता है। key दो प्रकार की होती हैं, और वे अलग-अलग routes का उपयोग करती हैं — अपने key प्रकार के लिए गलत route चुनना 401 का सबसे आम कारण है।
API keys को passwords की तरह मानें। इन्हें केवल अपने backend से भेजें, लीक होने पर बदलें (rotate), और enterprise keys को खर्च सीमा (spending cap) के साथ सीमित करें।
व्यक्तिगत keys — vber_sk_
एकल developers के लिए। आपके account के API keys पृष्ठ से स्वयं-सेवा (self-service) रूप में बनाई जाती हैं (API access वाले plan की आवश्यकता होती है)। आपके व्यक्तिगत क्रेडिट से बिलिंग होती है। /ai/services और /ai/tasks routes का उपयोग करें।
एंटरप्राइज़ keys — vber_org_sk_
किसी संगठन द्वारा server-to-server उपयोग के लिए। संगठन के admin द्वारा enterprise portal में जारी की जाती हैं, और केवल उन सेवाओं तक सीमित होती हैं जिनके लिए आपका संगठन स्वीकृत है। आपके संगठन के क्रेडिट pool से बिलिंग होती है। /ai/org-services routes का उपयोग करें।
पहलू
व्यक्तिगत key
एंटरप्राइज़ key
Key उपसर्ग
vber_sk_
vber_org_sk_
Route उपसर्ग
/ai/services, /ai/tasks
/ai/org-services
कैसे प्राप्त करें
स्वयं-सेवा, account सेटिंग्स
Org admin, enterprise portal
बिलिंग किससे
व्यक्तिगत क्रेडिट
संगठन क्रेडिट
सीमाएँ
प्रति-मिनट / प्रति-दिन अनुरोध सीमाएँ
प्रति-संगठन समवर्तीता (concurrency) (कस्टम)
http
X-API-Key: vber_sk_... # personal key
X-API-Key: vber_org_sk_... # enterprise key
Base URL
text
https://api.vberai.com/api
अनुरोध और execution मोड
हर सेवा एक JSON body लेती है जिसमें एक input object होता है जो सेवा के parameters रखता है। आप परिणाम कैसे प्राप्त करते हैं, यह सेवा के execution मोड पर निर्भर करता है।
समकालिक (synchronous) सेवाएँ
तेज़ सेवाएँ (उदाहरण के लिए chat या text अनुवाद) अपना परिणाम उसी प्रतिक्रिया में HTTP 200 के साथ इनलाइन लौटाती हैं। कोई पोलिंग आवश्यक नहीं।
असमकालिक (asynchronous) सेवाएँ
भारी सेवाएँ (image जनरेशन, matting, background हटाना) HTTP 202 के साथ एक taskId लौटाती हैं। task को पोल करें या पूरा होने पर परिणाम किसी webhook पर प्राप्त करें।
व्यक्तिगत key
व्यक्तिगत keys प्रति सेवा एक ही endpoint का उपयोग करती हैं: POST /ai/services/{code}/execute। यह sync सेवाओं के लिए परिणाम इनलाइन (200) लौटाता है, या async सेवाओं के लिए एक task (202) — दोनों ही स्थितियों में वही endpoint।
एंटरप्राइज़ key
एंटरप्राइज़ keys दो endpoints का उपयोग करती हैं: sync सेवाओं के लिए /execute और async सेवाओं के लिए /execute-async। गलत वाला कॉल करने पर 400 लौटता है जो बताता है कि कौन-सा endpoint उपयोग करना है।
असमकालिक jobs एक taskId लौटाते हैं। task को तब तक पोल करें जब तक उसका status किसी टर्मिनल मान तक न पहुँच जाए, फिर परिणाम पढ़ें। आप कौन-सा route पोल करते हैं, यह आपके key प्रकार पर निर्भर करता है — इसे सही करना सबसे महत्वपूर्ण बात है।
कौन-सा route पोल करें
क्रिया
व्यक्तिगत key
एंटरप्राइज़ key
task status पोल करें
GET /ai/tasks/{taskId}
GET /ai/org-services/tasks/{taskId}
नए download URLs को पुनः साइन करें
status प्रतिक्रिया से पढ़ें
GET /ai/org-services/tasks/{taskId}/outputs
किसी task को रद्द करें
POST /ai/tasks/{taskId}/cancel
उपलब्ध नहीं
Batch status
GET /ai/tasks/batch-status
उपलब्ध नहीं
एंटरप्राइज़ keys को /ai/org-services route पोल करना ही चाहिए
किसी personal /ai/tasks route पर भेजी गई एंटरप्राइज़ key (vber_org_sk_) 401 INVALID_API_KEY लौटाती है — personal routes केवल personal keys स्वीकार करते हैं। एंटरप्राइज़ jobs को हमेशा /ai/org-services/tasks/{taskId} पर पोल करें। Cancel और batch-status केवल personal-key के लिए हैं।
Task statuses
एक task इन मानों से होकर गुजरता है। किसी टर्मिनल status तक पहुँचते ही पोलिंग बंद कर दें: completed, failed, cancelled या timeout।
जब status completed होता है, तो result.assets आउटपुट images रखता है। हर asset में एक url (एक pre-signed download लिंक जो समाप्त हो जाता है), एक mimeType और एक index होता है; width, height, size और expiresAt उपलब्ध होने पर दिखते हैं। URLs को तुरंत fetch करें — एंटरप्राइज़ keys /outputs endpoint से नए लिंक फिर से अनुरोध कर सकती हैं।
Idempotency आपको network त्रुटि के बाद किसी submission को सुरक्षित रूप से पुनः प्रयास करने देता है, बिना कोई डुप्लिकेट job बनाए या दो बार शुल्क लिए।
एंटरप्राइज़ keys
/execute-async पर एक वैकल्पिक Idempotency-Key header भेजें (एक मान जो आप जनरेट करते हैं, अधिकतम 200 अक्षर — UUID आदर्श है)। उसी key के साथ पुनः प्रयास करने पर नया task बनाने के बजाय मूल task लौटता है। server केवल डी-डुप्लिकेट करता है; यह आपके लिए key जनरेट नहीं करता।
व्यक्तिगत keys
व्यक्तिगत API-key अनुरोध फिलहाल किसी idempotency key का समर्थन नहीं करते। पुनः प्रयास केवल तभी करें जब आप पुष्टि कर लें कि पिछले अनुरोध ने कोई task नहीं बनाया (आपके प्राप्त taskId से पोल करके)।
पोलिंग के बजाय, आप VberAI से यह करवा सकते हैं कि जब कोई task किसी टर्मिनल status पर पहुँचे तो परिणाम आपके server पर POST कर दे।
webhook कॉन्फ़िगर करना
job सबमिट करते समय एक सार्वजनिक HTTPS webhookUrl (और एक वैकल्पिक webhookSecret) पास करें। एंटरप्राइज़ keys इन्हें body के शीर्ष स्तर से पढ़ती हैं; व्यक्तिगत keys इन्हें options से पढ़ती हैं।
signature की पुष्टि करना
यदि आप कोई webhookSecret सेट करते हैं, तो हर delivery में एक X-Webhook-Signature header होता है — कच्चे JSON payload का HMAC-SHA256, hex-encoded रूप में। payload पर भरोसा करने से पहले इसे अपने secret के साथ पुनः गणना करें और तुलना करें। Deliveries में एक X-Idempotency-Key (taskId + status) भी होता है ताकि आप डुप्लिकेट्स को अनदेखा कर सकें।
विफल deliveries को backoff के साथ कुछ बार पुनः प्रयास किया जाता है। स्वीकृति के लिए 2xx के साथ प्रतिक्रिया दें।
AI jobs में क्रेडिट खर्च होते हैं। व्यक्तिगत और एंटरप्राइज़ keys पर एक ही मूल्य-निर्धारण लागू होता है — केवल wallet अलग होता है: व्यक्तिगत keys आपके व्यक्तिगत क्रेडिट से खर्च करती हैं, एंटरप्राइज़ keys आपके संगठन के pool से।
आरक्षण, निपटान, रिफंड
job स्वीकार होने पर क्रेडिट आरक्षित होते हैं और पूरा होने पर सटीक राशि पर निपटाए (settle) जाते हैं। यदि कोई job विफल होता है या रद्द होता है, तो आरक्षण पूरा रिफंड हो जाता है — विफल job के लिए आपसे कभी शुल्क नहीं लिया जाता।
लागत की गणना कैसे होती है
लागत सेवा पर निर्भर करती है। कुछ सेवाएँ प्रति अनुरोध एक निश्चित राशि लेती हैं; अन्य आउटपुट रिज़ॉल्यूशन (प्रति-पिक्सेल) के साथ या सबसे लंबी edge के अनुसार बढ़ती हैं। job चलाने से पहले सटीक शुल्क का पूर्वावलोकन करने के लिए cost endpoint कॉल करें।
•प्रति अनुरोध — हर कॉल पर एक निश्चित राशि।
•प्रति पिक्सेल — आउटपुट width × height के साथ बढ़ता है।
•आयाम के अनुसार — आउटपुट की सबसे लंबी edge के अनुसार मूल्य।
दर-सीमन (rate limiting) key प्रकार के अनुसार भिन्न होता है। दोनों को backend में प्रति सेवा कॉन्फ़िगर किया जाता है — नीचे दिए गए मान तंत्र का वर्णन करते हैं, निश्चित संख्याओं का नहीं।
व्यक्तिगत keys — अनुरोध दर
व्यक्तिगत keys प्रति मिनट और प्रति दिन अनुरोधों द्वारा सीमित होती हैं, जो प्रति सेवा कॉन्फ़िगर होती हैं। हर प्रतिक्रिया में नीचे दिए गए headers होते हैं ताकि आप अपनी कॉल की गति नियंत्रित कर सकें।
Header
विवरण
X-RateLimit-Limit-Minute
प्रति मिनट अनुमत अनुरोध।
X-RateLimit-Remaining-Minute
वर्तमान मिनट window में शेष अनुरोध।
X-RateLimit-Limit-Day
प्रति दिन अनुमत अनुरोध।
X-RateLimit-Remaining-Day
वर्तमान दिन window में शेष अनुरोध।
कोई X-RateLimit-Reset header नहीं होता। 429 पर, प्रतिक्रिया body में retryAfter और resetIn शामिल होते हैं।
एंटरप्राइज़ keys — समवर्तीता (concurrency)
एंटरप्राइज़ keys अनुरोध दर से नहीं, बल्कि इससे सीमित होती हैं कि आपके संगठन के लिए एक साथ कितने jobs चल सकते हैं। यह सीमा प्रति संगठन कस्टम होती है (और असीमित भी हो सकती है); इसे पार करने पर 429 CONCURRENCY_LIMIT_EXCEEDED लौटता है। एंटरप्राइज़ प्रतिक्रियाओं में X-RateLimit headers नहीं होते।
हर प्रतिक्रिया में success, message और timestamp शामिल होते हैं। विफलता पर, एक error code समस्या की पहचान करता है। message टेक्स्ट के बजाय code के आधार पर शाखा (switch) बनाएँ — messages बदल सकते हैं और केवल अंग्रेज़ी में होते हैं।
code कहाँ स्थित होता है
एंटरप्राइज़ त्रुटियाँ एकरूप होती हैं: प्रमाणीकरण समस्याएँ code को data.code में रखती हैं, जबकि सेवा और बिलिंग समस्याएँ इसे शीर्ष-स्तरीय errorCode में रखती हैं। व्यक्तिगत त्रुटियाँ endpoint के अनुसार भिन्न होती हैं (शीर्ष-स्तरीय errorCode, data.code, या errors.code) — हर code के लिए बताए गए फ़ील्ड को पढ़ें।
HTTP status codes
Status
अर्थ
200
सफलता — परिणाम इनलाइन लौटाया गया।
202
स्वीकृत — एक async task बनाया गया; पोल करें या webhook की प्रतीक्षा करें।
400
गलत अनुरोध — अमान्य input, या सेवा के execution मोड के लिए गलत endpoint।
401
अनधिकृत — गायब, विकृत, या गलत-प्रकार की API key।
402
भुगतान आवश्यक — पर्याप्त क्रेडिट नहीं।
403
निषिद्ध — यह key या account इस सेवा का उपयोग नहीं कर सकता।
404
नहीं मिला — अज्ञात task, या ऐसा task जो आपका नहीं है।
429
बहुत अधिक अनुरोध — दर या समवर्तीता सीमा पार हो गई।
500
server त्रुटि — फिर से प्रयास करें; job (यदि कोई हो) रिफंड कर दिया जाता है।
सामान्य error codes
Code
स्थान
अर्थ
INSUFFICIENT_CREDITS
errorCode
job के लिए पर्याप्त व्यक्तिगत क्रेडिट नहीं।
INSUFFICIENT_ORG_CREDITS
errorCode
job के लिए पर्याप्त संगठन क्रेडिट नहीं।
ORG_API_KEY_REQUIRED
data.code
इस endpoint को एक एंटरप्राइज़ API key (X-API-Key) चाहिए।
INVALID_ORG_API_KEY
data.code
एंटरप्राइज़ key गायब, विकृत, या निरस्त है।
INVALID_API_KEY
data.code
API key का प्रारूप अमान्य है — अक्सर किसी personal route को एंटरप्राइज़ key के साथ कॉल किया गया (या इसके विपरीत)।
प्रति सेवा ठोस अनुरोध और प्रतिक्रिया विवरण। उदाहरण दोनों key प्रकार दिखाते हैं — अपनी key के लिए tab चुनें। इनके आधार बने concepts (पोलिंग, statuses, त्रुटियाँ, बिलिंग) के लिए ऊपर दिए गए गाइड देखें।
नीचे दी गई दो सेवाओं का पूरा दस्तावेज़ीकरण है। आपकी key जिन सेवाओं को कॉल कर सकती है उनकी पूरी, live सूची — और हर सेवा के parameter spec — के लिए catalog endpoints क्वेरी करें। यह आधिकारिक स्रोत है, क्योंकि उपलब्धता आपके plan और संगठन की स्वीकृतियों पर निर्भर करती है।
एंडपॉइंट
विवरण
GET /ai/services
आपकी key जिन सेवाओं तक पहुँच सकती है उन्हें सूचीबद्ध करें।