Gunakan beta Rivya TypeScript SDK untuk memanggil Public API v1 bagi models, generations, files, credits, webhooks, dan Chat termasuk streaming SSE.

Rivya menyediakan beta TypeScript SDK untuk integrasi Public API sisi server.

SDK ini adalah thin client di atas Rivya Public API v1. Kontrak tingkat lebih rendah tetap Kontrak OpenAPI dan Schema, dan metode SDK harus tetap selaras dengan schema tersebut.

Status

Package saat ini dikelola di dalam repository ini sebagai private beta. Package belum dipublikasikan ke npm sampai nama package, metadata, changelog, dan proses release disetujui secara eksplisit.

SDK mendukung:

pencantuman model
pembuatan dan pengambilan generasi asinkron
upload dan pengambilan Files API
pengambilan saldo credits
pengelolaan webhook endpoint, test deliveries, event listing, delivery listing, dan secret rotation
verifikasi signature webhook
Chat completions non-streaming dan streaming, plus session chat yang dibuat API

Chat streaming tersedia dalam private beta ini melalui parsing SSE sisi server. Simpan API key secret di server Anda.

Instal Dalam Repo Ini

Gunakan source package lokal saat SDK masih beta:

pnpm --dir packages/rivya-sdk typecheck

Kode aplikasi harus menyimpan API key secret di server:

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

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

Jangan menaruh API key secret di browser bundles, localStorage, event analytics, screenshot, atau tiket bersama.

Daftar Model

models.list bersifat publik dan tidak membutuhkan 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);
}

Membuat Generasi

Gunakan generations.create untuk generasi gambar, video, atau audio asinkron:

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

Lalu polling dengan generations.retrieve:

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

Gunakan Idempotency-Key untuk request tulis production. SDK mengeksposnya sebagai idempotencyKey.

Upload File

Gunakan files.upload untuk gambar, video, atau audio referensi:

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

Gunakan files.retrieve untuk membaca ulang metadata upload:

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

Saat memakai file dalam generasi, kirim field publik yang dikembalikan melalui params.referenceMediaItems:

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

Periksa Credits

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

Kelola Webhooks

Buat webhook endpoint:

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 hanya dikembalikan setelah create atau rotate calls. Simpan di server Anda.

Helper webhook lain:

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

Verifikasi signature delivery sebelum mempercayai payload webhook:

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

Helper SDK memakai kontrak HMAC-SHA256 yang sama dengan yang didokumentasikan di API Webhooks.

Chat

Gunakan chat.completions.create untuk satu turn Chat API non-streaming:

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

Lanjutkan dengan session_id yang dikembalikan:

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

Baca session yang dibuat API:

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

Gunakan chat.completions.stream untuk memakai Server-Sent Events sebagai async iterator:

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 hanya untuk tampilan. Hasil committed tersedia setelah message.completed, dan dapat dibaca nanti dengan chat.sessions.retrieve.

Error

SDK melempar RivyaAPIError untuk respons Public API non-2xx:

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 menyertakan HTTP status, kode error publik, message, request id jika tersedia, dan subset response-header yang aman.

Validasi

Jalankan pemeriksaan SDK sebelum menganggap perubahan selesai:

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

pnpm sdk:check mencakup pemeriksaan kontrak statis dan pemeriksaan runtime tanpa jaringan untuk parsing error, header error aman, header idempotensi, Bearer auth, pencantuman model publik, parsing SSE Chat streaming, event error Chat streaming, dan verifikasi signature webhook.

Rivya TypeScript SDK