Használd a Rivya TypeScript SDK betát a Public API v1 hívására modellekhez, generálásokhoz, fájlokhoz, kreditekhez, webhookokhoz és Chathez, SSE streaminggel együtt.

A Rivya TypeScript SDK betát biztosít szerveroldali Public API integrációkhoz.

Az SDK vékony kliens a Rivya Public API v1 felett. Az alacsonyabb szintű szerződés továbbra is az OpenAPI és séma szerződés, az SDK-metódusoknak pedig ehhez a sémához kell igazodniuk.

Állapot

A csomag jelenleg ebben a repóban van karbantartva privát betaként. Nem kerül publikálásra npm-re, amíg a csomagnév, metaadatok, változásnapló és release folyamat nincs kifejezetten jóváhagyva.

Az SDK ezt támogatja:

modell-listázás
aszinkron generálás létrehozása és lekérése
Files API feltöltés és lekérés
kredit-egyenleg lekérése
webhook endpoint kezelés, tesztkézbesítések, eseménylistázás, kézbesítéslistázás és titokrotáció
webhook aláírás ellenőrzése
nem streamelt és streamelt Chat completions, valamint API-val létrehozott chatmunkamenetek

A Chat streaming ebben a privát betában szerveroldali SSE feldolgozáson keresztül érhető el. A titkos API-kulcsokat tartsd a szervereden.

Telepítés ebben a repóban

Használd a helyi csomagforrást, amíg az SDK beta állapotban van:

pnpm --dir packages/rivya-sdk typecheck

Az alkalmazáskód tartsa a titkos API-kulcsot a szerveren:

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

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

Ne tegyél titkos API-kulcsokat böngésző bundle-ökbe, localStorage-ba, analitikai eseményekbe, képernyőképekre vagy megosztott ticketekbe.

Modellek listázása

A models.list nyilvános, és nem igényel API-kulcsot:

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

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

Generálás létrehozása

Használd a generations.create metódust aszinkron kép-, videó- vagy hanggeneráláshoz:

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

Ezután pollolj a generations.retrieve metódussal:

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

Éles írási kérésekhez használj Idempotency-Key headert. Az SDK ezt idempotencyKey néven teszi elérhetővé.

Fájlok feltöltése

Használd a files.upload metódust referencia képekhez, videókhoz vagy hangokhoz:

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

Használd a files.retrieve metódust a feltöltött metaadatok újraolvasásához:

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

Amikor fájlt használsz egy generálásban, a visszakapott nyilvános mezőket add át a params.referenceMediaItems alatt:

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

Kreditek ellenőrzése

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

Webhookok kezelése

Webhook endpoint létrehozása:

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

A signing_secret csak létrehozás vagy rotáció után kerül visszaadásra. Tárold a szervereden.

További webhook segédfüggvények:

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

Ellenőrizd a kézbesítési aláírásokat, mielőtt megbíznál a webhook payloadokban:

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

Az SDK segédfüggvény ugyanazt a HMAC-SHA256 szerződést használja, amelyet az API webhooks dokumentál.

Chat

Használd a chat.completions.create metódust egy nem streamelt Chat API fordulóhoz:

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

Folytasd a visszakapott session_id értékkel:

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

API-val létrehozott munkamenetek olvasása:

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

Használd a chat.completions.stream metódust Server-Sent Events async iterátorként való fogyasztásához:

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

A message.delta csak megjelenítésre szolgál. A véglegesített eredmény a message.completed után érhető el, és később a chat.sessions.retrieve metódussal olvasható.

Hibák

Az SDK RivyaAPIError hibát dob nem 2xx Public API válaszoknál:

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

A RivyaAPIError tartalmazza a HTTP státuszt, a nyilvános hibakódot, az üzenetet, az elérhető request id-t, valamint a válaszheaderek biztonságos részhalmazát.

Validálás

Futtasd az SDK ellenőrzéseit, mielőtt egy módosítást késznek tekintesz:

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

A pnpm sdk:check statikus szerződésellenőrzést és hálózat nélküli runtime ellenőrzést tartalmaz hibafeldolgozásra, biztonságos hibaheaderekre, idempotenciaheaderekre, Bearer authra, nyilvános modell-listázásra, Chat streaming SSE feldolgozásra, Chat streaming hibaeseményekre és webhook aláírás-ellenőrzésre.

Rivya TypeScript SDK