Gunakan beta SDK TypeScript Rivya untuk memanggil Public API v1 bagi model, penjanaan, fail, kredit, webhook dan Chat termasuk penstriman SSE.

Rivya menyediakan beta SDK TypeScript untuk integrasi Public API sebelah pelayan.

SDK ini ialah klien nipis di atas Rivya Public API v1. Kontrak peringkat bawah masih berpandukan Kontrak OpenAPI dan Schema, dan kaedah SDK mesti kekal selaras dengan schema itu.

Status

Pakej ini sedang diselenggara di dalam repositori ini sebagai private beta. Ia tidak diterbitkan ke npm sehingga nama pakej, metadata, changelog dan proses keluaran diluluskan secara jelas.

SDK menyokong:

penyenaraian model
cipta dan dapatkan semula penjanaan tak segerak
muat naik dan dapatkan semula Files API
dapatkan semula baki kredit
pengurusan endpoint webhook, delivery ujian, penyenaraian acara, penyenaraian delivery dan putaran secret
pengesahan tandatangan webhook
Chat completions bukan penstriman dan penstriman, serta sesi chat yang dicipta API

Penstriman Chat tersedia dalam private beta ini melalui penguraian SSE sebelah pelayan. Simpan API key rahsia pada pelayan anda.

Pasang Dalam Repo Ini

Gunakan sumber pakej setempat semasa SDK masih dalam beta:

pnpm --dir packages/rivya-sdk typecheck

Kod aplikasi harus menyimpan API key rahsia pada pelayan:

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

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

Jangan letakkan API key rahsia dalam bundle pelayar, localStorage, acara analitik, tangkapan skrin atau tiket kongsi.

Senaraikan Model

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

Cipta Penjanaan

Gunakan generations.create untuk penjanaan imej, video atau audio tak segerak:

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

Kemudian tinjau 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 produksi. SDK mendedahkan ini sebagai idempotencyKey.

Muat Naik Fail

Gunakan files.upload untuk imej, video atau audio rujukan:

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 metadata yang telah dimuat naik sekali lagi:

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

Apabila menggunakan fail dalam penjanaan, hantar medan awam 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
      }
    ]
  }
});

Semak Kredit

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

Urus Webhooks

Cipta endpoint 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 selepas panggilan create atau rotate. Simpan pada pelayan 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 });

Sahkan tandatangan 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 menggunakan kontrak HMAC-SHA256 yang sama seperti didokumenkan dalam Webhook API.

Chat

Gunakan chat.completions.create untuk satu giliran Chat API bukan penstriman:

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

Teruskan 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 sesi yang dicipta API:

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

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

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 paparan. Hasil yang disahkan tersedia selepas message.completed, dan boleh dibaca kemudian dengan chat.sessions.retrieve.

Ralat

SDK membaling RivyaAPIError untuk respons Public API bukan 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 merangkumi status HTTP, kod ralat awam, mesej, request id jika tersedia dan subset response-header yang selamat.

Pengesahan

Jalankan semakan SDK sebelum menganggap perubahan selesai:

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

pnpm sdk:check merangkumi semakan kontrak statik dan semakan runtime tanpa rangkaian untuk penguraian ralat, header ralat selamat, header idempotency, Bearer auth, penyenaraian model awam, penguraian SSE penstriman Chat, acara ralat penstriman Chat dan pengesahan tandatangan webhook.

SDK TypeScript Rivya