models, generations, files, credits, webhooks और SSE streaming सहित Chat के लिए Public API v1 call करने हेतु Rivya TypeScript SDK beta इस्तेमाल करें.

Rivya server-side Public API integrations के लिए TypeScript SDK beta देता है।

SDK Rivya Public API v1 के ऊपर एक thin client है। Lower-level contract OpenAPI and Schema Contract ही रहता है, और SDK methods को उसी schema के साथ aligned रहना चाहिए।

Status

Package अभी इस repository के अंदर private beta के रूप में maintained है। Package name, metadata, changelog और release process स्पष्ट रूप से approve होने तक यह npm पर published नहीं है।

SDK support करता है:

model listing
asynchronous generation create और retrieve
Files API upload और retrieve
credit balance retrieval
webhook endpoint management, test deliveries, event listing, delivery listing और secret rotation
webhook signature verification
non-streaming और streaming Chat completions, साथ में API-created chat sessions

Chat streaming इस private beta में server-side SSE parsing के माध्यम से available है। Secret API keys अपने server पर रखें।

इस Repo में Install करें

SDK beta में रहते समय local package source इस्तेमाल करें:

pnpm --dir packages/rivya-sdk typecheck

Application code को secret API key server पर रखनी चाहिए:

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

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

Secret API keys को browser bundles, localStorage, analytics events, screenshots या shared tickets में न रखें।

Models list करें

models.list public है और API key की जरूरत नहीं होती:

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

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

Generation create करें

asynchronous image, video या audio generation के लिए 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 से poll करें:

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

Production write requests के लिए Idempotency-Key इस्तेमाल करें। SDK इसे idempotencyKey के रूप में expose करता है।

Files upload करें

reference images, videos या audio के लिए 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",
  client_request_id: "asset-123"
});

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

Uploaded metadata फिर से पढ़ने के लिए files.retrieve इस्तेमाल करें:

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

Generation में file इस्तेमाल करते समय returned public fields को params.referenceMediaItems के माध्यम से pass करें:

await rivya.generations.create({
  model: "nano-banana-2",
  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
      }
    ]
  }
});

Credits check करें

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

Webhooks manage करें

Webhook endpoint create करें:

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 केवल create या rotate calls के बाद return होता है। इसे अपने server पर store करें।

Other webhook helpers:

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 });

Webhook payloads पर भरोसा करने से पहले delivery signatures verify करें:

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 helper वही HMAC-SHA256 contract इस्तेमाल करता है जो API Webhooks में documented है।

Chat

एक non-streaming Chat API turn के लिए chat.completions.create इस्तेमाल करें:

const completion = await rivya.chat.completions.create(
  {
    model: "gpt-5-2-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);

Returned session_id से continue करें:

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

API-created sessions पढ़ें:

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

Server-Sent Events को async iterator की तरह consume करने के लिए chat.completions.stream इस्तेमाल करें:

const stream = await rivya.chat.completions.stream(
  {
    model: "gpt-5-2-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 केवल display के लिए है। Committed result message.completed के बाद available होता है, और बाद में chat.sessions.retrieve से read किया जा सकता है।

Errors

Non-2xx Public API responses के लिए SDK RivyaAPIError throw करता है:

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 status, public error code, message, available होने पर request id, और safe response-header subset शामिल होते हैं।

Validation

किसी change को complete मानने से पहले SDK checks run करें:

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

pnpm sdk:check में static contract check और no-network runtime check शामिल है, जो error parsing, safe error headers, idempotency headers, Bearer auth, public model listing, Chat streaming SSE parsing, Chat streaming error events और webhook signature verification को cover करता है।

Rivya TypeScript SDK