ماڈلز، تخلیقات، فائلوں، کریڈٹس، ویب ہکس اور SSE ترسیل سمیت Chat کے لیے Public API v1 پکارنے کو Rivya TypeScript SDK بیٹا استعمال کریں۔

Rivya سرور پر Public API انضمام کے لیے TypeScript SDK بیٹا فراہم کرتا ہے۔

SDK، Rivya Public API v1 کے اوپر ایک ہلکی سطح ہے۔ بنیادی معاہدہ OpenAPI اور خاکہ معاہدہ ہی رہتا ہے، اور SDK کے طریقوں کو اسی خاکے کے مطابق ہونا چاہیے۔

SDK نافذ شدہ صارف رویہ بیان کرتا ہے۔ درخواست کے لیے متعلقہ تنصیب میں Public API فعال، اکاؤنٹ کی درست کلید موجود اور منتخب ماڈل کی براہِ راست API حالت مطلوبہ کارروائی کی اجازت دینے والی ہونی چاہیے۔

حالت

یہ پیکج فی الحال اسی مخزن میں نجی بیٹا کے طور پر برقرار رکھا جاتا ہے۔ نام، متعلقہ معلومات، تبدیلیوں کی فہرست اور اجرا کا عمل واضح طور پر منظور ہونے تک اسے npm پر شائع نہیں کیا جاتا۔

SDK ان کاموں کی معاونت کرتا ہے:

ماڈلز کی فہرست
غیر ہم وقت تخلیق بنانا اور حاصل کرنا
Files API سے اپ لوڈ اور حاصل کرنا
کریڈٹ میزان حاصل کرنا
ویب ہک نقطۂ رسائی کا انتظام، آزمائشی ترسیل، واقعات اور ترسیلات کی فہرست، نیز خفیہ قدر بدلنا
ویب ہک کے دستخط کی تصدیق
غیر مسلسل اور مسلسل Chat جوابات، نیز API سے بنی گفتگو کی نشستیں

اس نجی بیٹا میں سرور پر SSE پڑھنے کے ذریعے Chat کی مسلسل ترسیل دستیاب ہے۔ خفیہ 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: "نرم اسٹوڈیو پس منظر پر مصنوعات کی صاف ادارتی تصویر",
    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: "مصنوعات کی اس تصویر کو صاف ادارتی فہرستی صفحے کے لیے نئے اسلوب میں بنائیں",
  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 ویب ہکس میں درج ہے۔

Chat

غیر مسلسل Chat API مرحلے کے لیے chat.completions.create استعمال کریں:

const completion = await rivya.chat.completions.create(
  {
    model: "claude-sonnet-5-chat",
    message: "مصنوعات کی نئی تصویری مہم کے اجرا کا مختصر منصوبہ لکھیں",
    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: "اب اسے عمل کی پانچ مرحلوں والی جانچ فہرست میں بدلیں۔"
});

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: "مصنوعات کی نئی تصویری مہم کے اجرا کا مختصر منصوبہ لکھیں",
    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 Public 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 حالت، عوامی خرابی رمز، پیغام، دستیاب ہونے پر درخواست کا شناختی نمبر اور جوابی سرناموں کا محفوظ محدود مجموعہ شامل ہوتا ہے۔

توثیق

تبدیلی مکمل سمجھنے سے پہلے SDK کی جانچ چلائیں:

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

pnpm sdk:check میں جامد معاہدے کی جانچ اور بغیر نیٹ ورک کی عملی جانچ شامل ہے۔ یہ خرابی پڑھنے، محفوظ خرابی سرناموں، یکساں نتیجہ دینے والے سرناموں، Bearer توثیق، عوامی ماڈل فہرست، Chat SSE ترسیل پڑھنے، Chat ترسیل کی خرابی کے واقعات اور ویب ہک دستخط کی تصدیق کا احاطہ کرتی ہے۔

Rivya TypeScript SDK