Használd a Rivya TypeScript SDK bétáját a Public API v1 modell-, generálási, fájl-, kredit-, webhook- és Chat-funkcióinak hívásához, az SSE-adatfolyamot is beleértve.

A Rivya szerveroldali Public API-integrációkhoz kínálja a TypeScript SDK béta-verzióját.

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.

Az SDK a megvalósított kliensviselkedést dokumentálja. A kérésekhez továbbra is engedélyezett Public API, érvényes fiókkulcs és olyan modell kell, amelynek élő API-állapota engedi a kért műveletet.

Állapot

A csomagot jelenleg ebben a kódtárban tartják karban zárt bétaként. Nem jelenik meg az npm-en, amíg a csomagnév, a metaadatok, a változásnapló és a kiadási folyamat nem kap kifejezett jóváhagyást.

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-végpontok kezelése, tesztkézbesítések, események és kézbesítések listázása, valamint titokrotáció
webhook aláírás ellenőrzése
egyszerre visszaadott és adatfolyamos Chat-válaszok, valamint API-val létrehozott chatmunkamenetek

A Chat-adatfolyam ebben a zárt bétá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őcsomagokba, a localStorage-ba, analitikai eseményekbe, képernyőképekre vagy megosztott hibajegyekbe.

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 kérdezd le rendszeresen az állapotot 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-lite",
  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-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
      }
    ]
  }
});

Minden Image5 és Grok Imagine Image 2.0 referenciaképhez szükség van az eredeti, modellhez kötött feltöltési válasz width, height, size_bytes és image_dimensions_token értékére. Egy későbbi files.retrieve hívás a tokent null értékkel adhatja vissza; ilyenkor töltsd fel újra a forrásképet ahelyett, hogy kitalálnád a MIME-típust, a méreteket vagy a bájtban mért fájlméretet. A Layer Decomposition ezenfelül érvényesíti az egyetlen képre vonatkozó geometriai korlátait; a Grok Image 2 normál képszerkesztéshez egy–öt aláírt JPEG-, PNG- vagy WebP-referenciaképet fogad el.

Video8 referenciavideónál az eredeti, modellhez kötött feltöltési válasz video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes és video_metadata_token értékét használd width, height, framesPerSecond, videoBitrateMbps, sizeBytes és videoMetadataToken néven. A durationSeconds és durationToken maradjon külön aláírt időtartam-igazolás. Ha egy későbbi files.retrieve hívásnál bármelyik token hiányzik, töltsd fel újra a forrásvideót.

A Wan 3.0 ugyanazt az SDK-mezőleképezést használja az egymást kölcsönösen kizáró text, frames és reference módokban. Minden referenciát model: "wan-3-0-video" értékkel tölts fel; a képekhez aláírt képmezők, a videókhoz aláírt időtartam és videómetaadat, a hanghoz pedig az eredeti mime_type, size_bytes, duration_seconds és duration_token szükséges. A params mezőben állítsd be a seedance_scene, variant, resolution, aspect_ratio, duration, audio és opcionális seed értékét. Az intelligens időtartam értéke -1, 30 másodpercet foglal le, és nem kombinálható referenciavideóval; a file-to-video és link-to-video rövidítések továbbra sem érhetők el.

Kreditek ellenőrzése

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

Webhookok kezelése

Ha a webhook-hozzáférés engedélyezett az adott telepítésben és a fiókod számára, hozz létre webhook-végpontot:

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-kérések tartalmában:

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 egyszerre visszaadott Chat API-fordulóhoz:

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

Folytasd a visszakapott session_id értékkel:

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

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 a Server-Sent Events adatfolyam aszinkron iterátorként való feldolgozásához:

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

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-állapotot, a nyilvános hibakódot, az üzenetet, az elérhető kérésazonosítót, valamint a válaszfejlécek 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 futásidejű ellenőrzést tartalmaz a hibafeldolgozásra, a biztonságos hibafejlécekre, az idempotenciafejlécekre, a Bearer-hitelesítésre, a nyilvános modell-listázásra, a Chat SSE-adatfolyamának feldolgozására, az adatfolyamban érkező Chat-hibaeseményekre és a webhook-aláírások ellenőrzésére.

Rivya TypeScript SDK