मॉडल, जनरेशन, फ़ाइलें, क्रेडिट, वेबहुक और SSE स्ट्रीमिंग वाली बातचीत के लिए सार्वजनिक API v1 कॉल करने हेतु Rivya TypeScript SDK का परीक्षण संस्करण इस्तेमाल करें।

Rivya सर्वर-पक्ष का सार्वजनिक API एकीकरण के लिए TypeScript SDK परीक्षण संस्करण देता है।

SDK, Rivya Public API v1 के ऊपर बना एक हल्का क्लाइंट है। निचले स्तर का एकीकरण अनुबंध OpenAPI और स्कीमा एकीकरण अनुबंध ही है, और SDK की विधियों को उसी स्कीमा के अनुरूप रहना चाहिए।

SDK लागू किए गए क्लाइंट व्यवहार को बताता है। अनुरोध के लिए व्यवस्था में सार्वजनिक API चालू होना, खाते की मान्य कुंजी और उपलब्ध API स्थिति में उस कार्रवाई की अनुमति देने वाला मॉडल जरूरी है।

स्थिति

पैकेज अभी इस कोड भंडार के भीतर निजी परीक्षण संस्करण के रूप में रखा गया है। पैकेज नाम, सहायक जानकारी, बदलाव का विवरण और रिलीज़ प्रक्रिया स्पष्ट रूप से स्वीकृत होने तक यह npm पर प्रकाशित नहीं है।

SDK समर्थन करता है:

मॉडल सूची
असिंक्रोनस जनरेशन बनाना और प्राप्त करना
Files API से अपलोड करना और जानकारी प्राप्त करना
क्रेडिट शेष प्राप्त करना
वेबहुक एंडपॉइंट प्रबंधन, परीक्षण डिलीवरी, इवेंट और डिलीवरी सूची तथा सीक्रेट बदलना
वेबहुक हस्ताक्षर सत्यापन
बिना स्ट्रीम और स्ट्रीमिंग चैट पूर्णताएं, साथ में API से बनाया गया चैट सत्र

बातचीत स्ट्रीमिंग इस निजी परीक्षण संस्करण में सर्वर-पक्ष पर SSE पार्सिंग के माध्यम से उपलब्ध है। गुप्त API कुंजियाँ अपने सर्वर पर रखें।

इस कोड भंडार में इंस्टॉल करें

SDK के परीक्षण संस्करण में रहते समय स्थानीय पैकेज स्रोत इस्तेमाल करें:

pnpm --dir packages/rivya-sdk typecheck

एप्लिकेशन कोड को गुप्त API कुंजी सर्वर पर रखनी चाहिए:

import { RivyaClient } from "@rivya/sdk";

const rivya = new RivyaClient({
  apiKey: process.env.RIVYA_API_KEY
});

गुप्त API कुंजियों को ब्राउज़र बंडल, localStorage, एनालिटिक्स घटनाओं, स्क्रीनशॉट या साझा सहायता टिकट में न रखें।

मॉडल सूची करें

models.list सार्वजनिक है और API कुंजी की जरूरत नहीं होती:

const models = await rivya.models.list();

for (const model of models.data) {
  console.log(model.id, model.api_status, model.supported_api_inputs);
}

निर्माण तैयार करें

असिंक्रोनस इमेज, वीडियो या ऑडियो जनरेशन के लिए generations.create इस्तेमाल करें:

const generation = await rivya.generations.create(
  {
    model: "z-image",
    prompt: "A clean editorial product image on a soft studio background",
    client_request_id: "order-123-preview"
  },
  {
    idempotencyKey: "order-123-preview"
  }
);

console.log(generation.id, generation.status);

फिर generations.retrieve से स्थिति पोल करें:

const current = await rivya.generations.retrieve(generation.id);
console.log(current.status, current.result?.primary_url);

जनरेशन लिखने वाले अनुरोध के लिए Idempotency-Key इस्तेमाल करें। SDK इसे idempotencyKey के रूप में उपलब्ध कराता है।

फाइलें अपलोड करें

संदर्भ चित्र, वीडियो या ध्वनि के लिए files.upload इस्तेमाल करें:

import { readFile } from "node:fs/promises";

const file = new Blob([await readFile("./reference.png")], {
  type: "image/png"
});

const uploaded = await rivya.files.upload({
  file,
  filename: "reference.png",
  kind: "image",
  model: "nano-banana-2-lite",
  client_request_id: "asset-123"
});

console.log(uploaded.id, uploaded.url);

अपलोड का मेटाडेटा दोबारा पढ़ने के लिए files.retrieve इस्तेमाल करें:

const sameFile = await rivya.files.retrieve(uploaded.id);
console.log(sameFile.mime_type, sameFile.duration_token);

जनरेशन में फ़ाइल इस्तेमाल करते समय लौटाए गए सार्वजनिक फ़ील्ड को params.referenceMediaItems में भेजें:

await rivya.generations.create({
  model: "nano-banana-2-lite",
  prompt: "Restyle this product photo for a clean editorial catalog page",
  params: {
    referenceMediaItems: [
      {
        url: uploaded.url,
        kind: uploaded.kind,
        name: uploaded.file_name,
        mimeType: uploaded.mime_type,
        durationSeconds: uploaded.duration_seconds ?? undefined,
        durationToken: uploaded.duration_token ?? undefined,
        width: uploaded.video_width ?? uploaded.width ?? undefined,
        height: uploaded.video_height ?? uploaded.height ?? undefined,
        sizeBytes: uploaded.video_file_size_bytes ?? uploaded.size_bytes,
        imageDimensionsToken: uploaded.image_dimensions_token ?? undefined,
        framesPerSecond: uploaded.frames_per_second ?? undefined,
        videoBitrateMbps: uploaded.video_bitrate_mbps ?? undefined,
        videoMetadataToken: uploaded.video_metadata_token ?? undefined
      }
    ]
  }
});

हर Image5 और Grok Imagine Image 2.0 संदर्भ इमेज के लिए मूल, मॉडल से बंधे अपलोड जवाब का width, height, size_bytes और image_dimensions_token जरूरी है। बाद में files.retrieve कॉल करने पर टोकन null हो सकता है; MIME प्रकार, आयाम या बाइट आकार का अनुमान लगाने के बजाय स्रोत इमेज दोबारा अपलोड करें। Layer Decomposition में एक इमेज की ज्यामितीय सीमाएं भी लागू होती हैं। Grok Image 2 सामान्य इमेज संपादन के लिए साइन किए हुए 1–5 JPEG, PNG या WebP संदर्भ स्वीकार करता है।

Video8 संदर्भ वीडियो के लिए मूल, मॉडल से बंधे अपलोड जवाब के video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes और video_metadata_token को क्रमशः width, height, framesPerSecond, videoBitrateMbps, sizeBytes और videoMetadataToken के रूप में इस्तेमाल करें। अलग हस्ताक्षरित अवधि प्रमाण के रूप में durationSeconds और durationToken भी बनाए रखें। बाद में files.retrieve पर दोनों में से कोई टोकन न मिले तो स्रोत वीडियो दोबारा अपलोड करें।

Wan 3.0 अपने परस्पर अलग text, frames और reference दृश्यों में वही SDK फ़ील्ड मानचित्र इस्तेमाल करता है। हर संदर्भ को model: "wan-3-0-video" के साथ अपलोड करें; चित्र के प्रमाणित फ़ील्ड, वीडियो की प्रमाणित अवधि और मेटाडेटा दोनों, तथा ऑडियो के मूल mime_type, size_bytes, duration_seconds और duration_token जरूरी हैं। params के भीतर seedance_scene, variant, resolution, aspect_ratio, duration, audio और वैकल्पिक seed रखें। बुद्धिमान अवधि -1 है, 30 सेकंड के क्रेडिट आरक्षित करती है और संदर्भ वीडियो के साथ इस्तेमाल नहीं हो सकती; फ़ाइल-से-वीडियो और लिंक-से-वीडियो छोटे रास्ते उपलब्ध नहीं हैं।

क्रेडिट जांचें

const credits = await rivya.credits.retrieve();
console.log(credits.current_credits);

वेबहुक प्रबंधित करें

व्यवस्था और खाता के लिए वेबहुक पहुंच चालू हो, तभी वेबहुक समापन बिंदु बनाएं:

const endpoint = await rivya.webhooks.create({
  name: "Production webhook",
  url: "https://example.com/rivya/webhook",
  event_types: ["generation.succeeded", "generation.failed"]
});

console.log(endpoint.id, endpoint.signing_secret);

signing_secret केवल तैयार या घूमता कॉल के बाद लौटाता है होता है। इसे अपने सर्वर पर स्टोर करें।

अन्य वेबहुक सहायक विधियां:

await rivya.webhooks.list();
await rivya.webhooks.retrieve(endpoint.id);
await rivya.webhooks.update(endpoint.id, { status: "disabled" });
await rivya.webhooks.test(endpoint.id);
await rivya.webhooks.rotateSecret(endpoint.id);
await rivya.webhooks.deliveries.list(endpoint.id, { limit: 20 });
await rivya.webhookEvents.list({ limit: 20 });

वेबहुक पेलोड पर भरोसा करने से पहले वितरण हस्ताक्षरों की पुष्टि करें:

import { verifyRivyaWebhookSignature } from "@rivya/sdk";

const ok = await verifyRivyaWebhookSignature({
  rawBody,
  timestamp: request.headers.get("rivya-webhook-timestamp") || "",
  signatureHeader: request.headers.get("rivya-webhook-signature") || "",
  signingSecret: process.env.RIVYA_WEBHOOK_SIGNING_SECRET || ""
});

if (!ok) {
  throw new Error("Invalid Rivya webhook signature");
}

SDK की सहायक विधि वही HMAC-SHA256 एकीकरण अनुबंध इस्तेमाल करती है जो API वेबहुक में दर्ज है।

बातचीत

एक बिना स्ट्रीम वाला बातचीत API बातचीत का दौर के लिए chat.completions.create इस्तेमाल करें:

const completion = await rivya.chat.completions.create(
  {
    model: "claude-sonnet-5-chat",
    message: "Write a concise launch plan for a new product image campaign",
    client_request_id: "chat-001"
  },
  {
    idempotencyKey: "chat-001"
  }
);

console.log(completion.session_id, completion.message.content);

लौटाए गए session_id से आगे बढ़ें:

await rivya.chat.completions.create({
  model: "claude-sonnet-5-chat",
  session_id: completion.session_id,
  message: "Now turn that into a 5-step execution checklist."
});

API-तैयार किया गया सत्र पढ़ें:

await rivya.chat.sessions.list({ limit: 20 });
await rivya.chat.sessions.retrieve(completion.session_id);

सर्वर से भेजी गई घटनाओं को अतुल्यकालिक इटरेटर की तरह पढ़ने के लिए chat.completions.stream इस्तेमाल करें:

const stream = await rivya.chat.completions.stream(
  {
    model: "claude-sonnet-5-chat",
    message: "Write a concise launch plan for a new product image campaign",
    client_request_id: "chat-stream-001"
  },
  {
    idempotencyKey: "chat-stream-001"
  }
);

for await (const event of stream) {
  if (event.event === "message.delta") {
    process.stdout.write(event.data.delta);
  }

  if (event.event === "message.completed") {
    console.log(event.data.message.id);
  }
}

message.delta केवल स्क्रीन पर दिखाने के लिए है। अंतिम नतीजा message.completed के बाद उपलब्ध होता है और उसे बाद में chat.sessions.retrieve से पढ़ा जा सकता है।

त्रुटियां

2xx से अलग सार्वजनिक API जवाब मिलने पर SDK RivyaAPIError त्रुटि देता है:

import { RivyaAPIError } from "@rivya/sdk";

try {
  await rivya.generations.retrieve("task_missing");
} catch (error) {
  if (error instanceof RivyaAPIError) {
    console.log(error.status, error.code, error.requestId);
  }
}

RivyaAPIError में HTTP स्थिति, सार्वजनिक त्रुटि कोड, संदेश, उपलब्ध होने पर अनुरोध ID और जवाब के सुरक्षित हेडर का सीमित समूह शामिल होता है।

सत्यापन

किसी बदलाव को पूरा मानने से पहले SDK जाँच चलाएँ:

pnpm sdk:check
pnpm --dir packages/rivya-sdk typecheck
pnpm content:api-docs

pnpm sdk:check में स्थिर एकीकरण अनुबंध और बिना नेटवर्क वाली रनटाइम जांच शामिल हैं। इनमें त्रुटि पार्सिंग, सुरक्षित त्रुटि हेडर, idempotency हेडर, Bearer प्रमाणीकरण, सार्वजनिक मॉडल सूची, चैट स्ट्रीमिंग SSE पार्सिंग, चैट स्ट्रीम त्रुटि इवेंट और वेबहुक हस्ताक्षर सत्यापन शामिल हैं।

Rivya TypeScript SDK गाइड