Gebruik de Rivya TypeScript SDK beta om Public API v1 aan te roepen voor modellen, generaties, bestanden, credits, webhooks en Chat inclusief SSE-streaming.

Rivya biedt een TypeScript SDK beta voor server-side Public API-integraties.

De SDK is een thin client bovenop Rivya Public API v1. Het lagere contract blijft OpenAPI- en schemacontract, en SDK-methoden moeten met dat schema uitgelijnd blijven.

Status

Het package wordt momenteel binnen deze repository onderhouden als private beta. Het wordt niet naar npm gepubliceerd totdat de packagenaam, metadata, changelog en het releaseproces expliciet zijn goedgekeurd.

De SDK ondersteunt:

modellenlijst tonen
asynchrone generatie aanmaken en ophalen
Files API uploaden en ophalen
creditsaldo ophalen
webhook endpoint management, testdeliveries, eventlijst, deliverylijst en secretrotatie
webhooksignatureverificatie
non-streaming en streaming Chat completions, plus API-aangemaakte chatsessies

Chat streaming is in deze private beta beschikbaar via server-side SSE-parsing. Houd geheime API-sleutels op je server.

Installeren in deze repo

Gebruik de lokale package source zolang de SDK in beta is:

pnpm --dir packages/rivya-sdk typecheck

Applicatiecode moet de geheime API-sleutel op de server bewaren:

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

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

Plaats geheime API-sleutels niet in browserbundles, localStorage, analytics-events, screenshots of gedeelde tickets.

Modellen tonen

models.list is publiek en vereist geen API-sleutel:

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

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

Een generatie aanmaken

Gebruik generations.create voor asynchrone beeld-, video- of audiogeneratie:

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

Poll daarna met generations.retrieve:

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

Gebruik Idempotency-Key voor productieschrijfrequests. De SDK stelt dit beschikbaar als idempotencyKey.

Bestanden uploaden

Gebruik files.upload voor referentieafbeeldingen, video's of audio:

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

Gebruik files.retrieve om geüploade metadata opnieuw te lezen:

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

Wanneer je een bestand in een generatie gebruikt, geef je de teruggegeven publieke velden door via 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
      }
    ]
  }
});

Credits controleren

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

Webhooks beheren

Maak een webhook endpoint aan:

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

De signing_secret wordt alleen na create- of rotate-calls teruggegeven. Bewaar die op je server.

Andere webhookhelpers:

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

Verifieer deliverysignatures voordat je webhookpayloads vertrouwt:

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

De SDK-helper gebruikt hetzelfde HMAC-SHA256-contract dat is gedocumenteerd in API-webhooks.

Chat

Gebruik chat.completions.create voor één non-streaming Chat API-turn:

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

Ga door met de teruggegeven session_id:

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

Lees API-aangemaakte sessies:

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

Gebruik chat.completions.stream om Server-Sent Events als async iterator te verwerken:

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 is alleen voor weergave. Het gecommitte resultaat is beschikbaar na message.completed en kan later worden gelezen met chat.sessions.retrieve.

Fouten

De SDK gooit RivyaAPIError voor non-2xx Public API-responses:

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 bevat de HTTP-status, publieke foutcode, message, request id wanneer beschikbaar en een veilige subset van responseheaders.

Validatie

Run de SDK-checks voordat je een wijziging als voltooid beschouwt:

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

pnpm sdk:check bevat een statische contractcheck en een no-network runtimecheck voor error parsing, veilige errorheaders, idempotencyheaders, Bearer auth, publieke modellenlijst, Chat streaming SSE parsing, Chat streaming error events en webhooksignatureverificatie.

Rivya TypeScript-SDK