Gunakan Rivya TypeScript SDK versi beta untuk memanggil Public API v1 bagi model, pembuatan konten, berkas, kredit, webhook, dan Chat, termasuk streaming SSE.

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

SDK ini adalah ringan klien di atas Rivya Public API v1. Kontrak tingkat lebih rendah tetap Kontrak OpenAPI dan Skema, dan metode SDK harus tetap selaras dengan skema tersebut.

SDK mendokumentasikan perilaku klien yang telah diterapkan. Permintaan tetap memerlukan Public API aktif untuk penerapan, kunci akun yang valid, dan model dengan status API langsung yang mengizinkan operasi 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
unggahan dan pengambilan Files API
pengambilan saldo kredit
pengelolaan webhook titik akhir, pengujian deliveries, peristiwa daftar produk, pengiriman daftar produk, dan rahasia rotation
verifikasi tanda tangan webhook
Chat completions non-aliran langsung dan aliran langsung, plus sesi chat yang dibuat API

Chat aliran langsung tersedia dalam private beta ini melalui parsing SSE sisi server. Simpan API kunci rahasia di server Anda.

Instal Dalam Repo Ini

Gunakan sumber package lokal saat SDK masih beta:

pnpm --dir packages/rivya-sdk typecheck

Kode aplikasi harus menyimpan API kunci rahasia di server:

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

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

Jangan menaruh API kunci rahasia di browser bundles, localStorage, peristiwa analytics, screenshot, atau tiket bersama.

Daftar Model

models.list bersifat publik dan tidak membutuhkan API kunci:

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 pemeriksaan berkala dengan generations.retrieve:

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

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

Unggah 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-lite",
  client_request_id: "asset-123"
});

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

Gunakan files.retrieve untuk membaca ulang metadata unggahan:

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

Saat memakai berkas dalam generasi, kirim kolom publik yang dikembalikan melalui 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
      }
    ]
  }
});

Setiap gambar referensi Image5 atau Grok Imagine Image 2.0 memerlukan width, height, size_bytes, dan image_dimensions_token dari respons unggahan asli yang terikat ke model. Pemanggilan files.retrieve berikutnya dapat mengembalikan token sebagai null; unggah ulang gambar sumber dan jangan menebak jenis MIME, dimensi, atau ukuran byte. Layer Decomposition juga menerapkan batas geometrinya untuk satu gambar; Grok Image 2 menerima satu hingga lima referensi JPEG, PNG, atau WebP bertanda tangan untuk pengeditan gambar standar.

Untuk video referensi Video8, gunakan video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, dan video_metadata_token dari respons unggahan asli yang terikat ke model sebagai width, height, framesPerSecond, videoBitrateMbps, sizeBytes, dan videoMetadataToken. Pertahankan durationSeconds dan durationToken sebagai bukti durasi bertanda tangan yang terpisah. Jika salah satu token tidak tersedia pada pemanggilan files.retrieve berikutnya, unggah ulang video sumber.

Wan 3.0 menggunakan pemetaan kolom SDK yang sama pada mode text, frames, dan reference yang saling eksklusif. Unggah setiap referensi dengan model: "wan-3-0-video"; gambar memerlukan kolom gambar bertanda tangan, video memerlukan durasi dan metadata video bertanda tangan, sedangkan audio memerlukan mime_type, size_bytes, duration_seconds, dan duration_token asli. Atur seedance_scene, variant, resolution, aspect_ratio, duration, audio, serta seed opsional di dalam params. Durasi cerdas adalah -1, mereservasi 30 detik, dan tidak dapat digabungkan dengan video referensi; pintasan berkas-to-video dan link-to-video tetap tidak tersedia.

Periksa Kredit

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

Kelola Webhooks

Ketika akses webhook aktif untuk penerapan dan akun, buat titik akhir webhook:

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 membuat 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 tanda tangan pengiriman 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-aliran langsung:

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

Lanjutkan dengan session_id yang dikembalikan:

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

Baca sesi 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 asinkron iterator:

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 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 kesalahan publik, message, permintaan id jika tersedia, dan subset respons-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 kesalahan, header kesalahan aman, header idempotensi, Bearer auth, pencantuman model publik, parsing SSE Chat aliran langsung, peristiwa kesalahan Chat aliran langsung, dan verifikasi tanda tangan webhook.

Rivya TypeScript SDK