VberAI API — डेवलपर्स के लिए RESTful रेफ़रेंस

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 का स्वतः रिफंड हो जाता है।

यह कैसे काम करता है

  1. 1X-API-Key header में अपनी API key से प्रमाणीकरण करें।
  2. 2किसी सेवा को JSON { input } body के साथ एक job सबमिट करें।
  3. 3परिणाम को इनलाइन पढ़ें (sync सेवाएँ) या task को पोल करें / webhook प्राप्त करें (async सेवाएँ)।
bash
# 1. Submit a job
curl -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 उपयोग करना है।
json
{
  "input": {
    "imageUrl": "https://example.com/photo.png"
  },
  "webhookUrl": "https://your-server.com/hook"
}
bash
HTTP 200  # sync: result inline
HTTP 202  # async: { "taskId": "...", "status": "queued" }

पोलिंग और परिणाम

असमकालिक 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 statusGET /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।

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

परिणाम पढ़ना

जब status completed होता है, तो result.assets आउटपुट images रखता है। हर asset में एक url (एक pre-signed download लिंक जो समाप्त हो जाता है), एक mimeType और एक index होता है; width, height, size और expiresAt उपलब्ध होने पर दिखते हैं। URLs को तुरंत fetch करें — एंटरप्राइज़ keys /outputs endpoint से नए लिंक फिर से अनुरोध कर सकती हैं।

bash
# personal
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"

# enterprise
curl https://api.vberai.com/api/ai/org-services/tasks/{taskId} \
  -H "X-API-Key: vber_org_sk_YOUR_ORG_KEY"

पूर्ण हुआ task

json
{
  "success": true,
  "data": {
    "taskId": "6a97e277a148c970dd545f40",
    "serviceCode": "super-matting",
    "status": "completed",
    "creditsEstimated": 10,
    "creditsActual": 10,
    "outputCount": 1,
    "result": {
      "type": "images",
      "assets": [
        {
          "index": 0,
          "url": "https://assets.vberai.org/tmp/user-assets/.../0.png?signature=...",
          "mimeType": "image/png",
          "expiresAt": "2026-01-22T10:30:12.000Z"
        }
      ]
    },
    "completedAt": "2026-01-15T10:30:12.000Z"
  }
}

Idempotency

Idempotency आपको network त्रुटि के बाद किसी submission को सुरक्षित रूप से पुनः प्रयास करने देता है, बिना कोई डुप्लिकेट job बनाए या दो बार शुल्क लिए।

एंटरप्राइज़ keys

/execute-async पर एक वैकल्पिक Idempotency-Key header भेजें (एक मान जो आप जनरेट करते हैं, अधिकतम 200 अक्षर — UUID आदर्श है)। उसी key के साथ पुनः प्रयास करने पर नया task बनाने के बजाय मूल task लौटता है। server केवल डी-डुप्लिकेट करता है; यह आपके लिए key जनरेट नहीं करता।

व्यक्तिगत keys

व्यक्तिगत API-key अनुरोध फिलहाल किसी idempotency key का समर्थन नहीं करते। पुनः प्रयास केवल तभी करें जब आप पुष्टि कर लें कि पिछले अनुरोध ने कोई task नहीं बनाया (आपके प्राप्त taskId से पोल करके)।

http
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Webhooks

पोलिंग के बजाय, आप 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 के साथ प्रतिक्रिया दें।
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

किसी webhook की पुष्टि करें (Node.js)

javascript
import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return signature === expected;
}

app.post("/hook", (req, res) => {
  const sig = req.header("X-Webhook-Signature");
  if (!verify(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  // req.body: { taskId, serviceCode, status, ... }
  res.status(200).end();
});

क्रेडिट और बिलिंग

AI jobs में क्रेडिट खर्च होते हैं। व्यक्तिगत और एंटरप्राइज़ keys पर एक ही मूल्य-निर्धारण लागू होता है — केवल wallet अलग होता है: व्यक्तिगत keys आपके व्यक्तिगत क्रेडिट से खर्च करती हैं, एंटरप्राइज़ keys आपके संगठन के pool से।

आरक्षण, निपटान, रिफंड

job स्वीकार होने पर क्रेडिट आरक्षित होते हैं और पूरा होने पर सटीक राशि पर निपटाए (settle) जाते हैं। यदि कोई job विफल होता है या रद्द होता है, तो आरक्षण पूरा रिफंड हो जाता है — विफल job के लिए आपसे कभी शुल्क नहीं लिया जाता।

लागत की गणना कैसे होती है

लागत सेवा पर निर्भर करती है। कुछ सेवाएँ प्रति अनुरोध एक निश्चित राशि लेती हैं; अन्य आउटपुट रिज़ॉल्यूशन (प्रति-पिक्सेल) के साथ या सबसे लंबी edge के अनुसार बढ़ती हैं। job चलाने से पहले सटीक शुल्क का पूर्वावलोकन करने के लिए cost endpoint कॉल करें।

  • •प्रति अनुरोध — हर कॉल पर एक निश्चित राशि।
  • •प्रति पिक्सेल — आउटपुट width × height के साथ बढ़ता है।
  • •आयाम के अनुसार — आउटपुट की सबसे लंबी edge के अनुसार मूल्य।
bash
curl -X POST https://api.vberai.com/api/ai/services/super-matting/cost \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"width": 1024, "height": 768}}'
json
{
  "success": true,
  "data": {
    "estimatedCredits": 10,
    "pricingType": "custom",
    "pricingMode": "dimension",
    "sufficient": true
  }
}

दर सीमाएँ

दर-सीमन (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 नहीं होते।

http
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997

त्रुटियाँ

हर प्रतिक्रिया में 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बहुत अधिक अनुरोध — दर या समवर्तीता सीमा पार हो गई।
500server त्रुटि — फिर से प्रयास करें; job (यदि कोई हो) रिफंड कर दिया जाता है।

सामान्य error codes

Codeस्थानअर्थ
INSUFFICIENT_CREDITSerrorCodejob के लिए पर्याप्त व्यक्तिगत क्रेडिट नहीं।
INSUFFICIENT_ORG_CREDITSerrorCodejob के लिए पर्याप्त संगठन क्रेडिट नहीं।
ORG_API_KEY_REQUIREDdata.codeइस endpoint को एक एंटरप्राइज़ API key (X-API-Key) चाहिए।
INVALID_ORG_API_KEYdata.codeएंटरप्राइज़ key गायब, विकृत, या निरस्त है।
INVALID_API_KEYdata.codeAPI key का प्रारूप अमान्य है — अक्सर किसी personal route को एंटरप्राइज़ key के साथ कॉल किया गया (या इसके विपरीत)।
API_SERVICE_NOT_ALLOWEDerrorCodeआपका संगठन इस सेवा के लिए स्वीकृत नहीं है।
ORG_DISABLEDdata.codeसंगठन का account निष्क्रिय है।
CONCURRENCY_LIMIT_EXCEEDEDerrorCodeआपके संगठन के लिए बहुत अधिक समवर्ती jobs।
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCodeयह सेवा बाहरी API पर उपलब्ध नहीं है।
TASK_NOT_FOUNDerrorCodeइस key के लिए ऐसा कोई task नहीं है।
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

API दस्तावेज़

प्रति सेवा ठोस अनुरोध और प्रतिक्रिया विवरण। उदाहरण दोनों key प्रकार दिखाते हैं — अपनी key के लिए tab चुनें। इनके आधार बने concepts (पोलिंग, statuses, त्रुटियाँ, बिलिंग) के लिए ऊपर दिए गए गाइड देखें।

उपलब्ध सेवाएँ

नीचे दी गई दो सेवाओं का पूरा दस्तावेज़ीकरण है। आपकी key जिन सेवाओं को कॉल कर सकती है उनकी पूरी, live सूची — और हर सेवा के parameter spec — के लिए catalog endpoints क्वेरी करें। यह आधिकारिक स्रोत है, क्योंकि उपलब्धता आपके plan और संगठन की स्वीकृतियों पर निर्भर करती है।

एंडपॉइंटविवरण
GET /ai/servicesआपकी key जिन सेवाओं तक पहुँच सकती है उन्हें सूचीबद्ध करें।
GET /ai/external/services/{code}/specकिसी एक सेवा के लिए parameter spec प्राप्त करें।
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"