Nutze die Rivya TypeScript SDK-Beta, um Public API v1 für Modelle, Generationen, Dateien, Credits, Webhooks und Chat inklusive SSE-Streaming aufzurufen.

Rivya stellt eine TypeScript SDK-Beta für serverseitige Public-API-Integrationen bereit.

Das SDK ist ein dünner Client über Rivya Public API v1. Der niedrigere Vertrag bleibt der OpenAPI- und Schema-Vertrag, und SDK-Methoden müssen mit diesem Schema ausgerichtet bleiben.

Status

Das Package wird aktuell in diesem Repository als private Beta gepflegt. Es wird nicht auf npm veröffentlicht, bis Package-Name, Metadaten, Changelog und Release-Prozess ausdrücklich freigegeben sind.

Das SDK unterstützt:

Modellauflistung
asynchrone Generation erstellen und abrufen
Files API Upload und Abruf
Credit-Guthaben abrufen
Webhook-Endpoint-Verwaltung, Test-Deliveries, Event-Liste, Delivery-Liste und Secret-Rotation
Webhook-Signaturprüfung
nicht streamende und streamende Chat Completions sowie API-erstellte Chat-Sessions

Chat-Streaming ist in dieser privaten Beta über serverseitiges SSE-Parsing verfügbar. Halte geheime API Keys auf deinem Server.

In diesem Repo installieren

Nutze die lokale Package-Quelle, solange das SDK in Beta ist:

pnpm --dir packages/rivya-sdk typecheck

Anwendungscode sollte den geheimen API Key auf dem Server halten:

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

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

Lege geheime API Keys nicht in Browser-Bundles, localStorage, Analytics-Events, Screenshots oder geteilten Tickets ab.

Modelle auflisten

models.list ist öffentlich und benötigt keinen 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);
}

Generation erstellen

Nutze generations.create für asynchrone Bild-, Video- oder Audiogenerierung:

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

Danach mit generations.retrieve pollen:

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

Nutze Idempotency-Key für produktive Schreibanfragen. Das SDK stellt dies als idempotencyKey bereit.

Dateien hochladen

Nutze files.upload für Referenzbilder, Videos oder 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);

Nutze files.retrieve, um hochgeladene Metadaten erneut zu lesen:

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

Wenn du eine Datei in einer Generation nutzt, gib die zurückgegebenen öffentlichen Felder über params.referenceMediaItems weiter:

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 prüfen

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

Webhooks verwalten

Webhook-Endpoint erstellen:

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

Das signing_secret wird nur nach Create- oder Rotate-Aufrufen zurückgegeben. Speichere es auf deinem Server.

Weitere Webhook-Helfer:

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

Verifiziere Delivery-Signaturen, bevor du Webhook-Payloads vertraust:

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

Der SDK-Helfer nutzt denselben HMAC-SHA256-Vertrag, der in API Webhooks dokumentiert ist.

Chat

Nutze chat.completions.create für einen nicht streamenden 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);

Mit der zurückgegebenen session_id fortsetzen:

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-erstellte Sessions lesen:

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

Nutze chat.completions.stream, um Server-Sent Events als Async Iterator zu konsumieren:

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 ist nur für die Anzeige gedacht. Das gespeicherte Ergebnis ist nach message.completed verfügbar und kann später mit chat.sessions.retrieve gelesen werden.

Fehler

Das SDK wirft RivyaAPIError für Public-API-Antworten außerhalb von 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 enthält HTTP-Status, öffentlichen Fehlercode, Nachricht, Request-ID wenn verfügbar und eine sichere Teilmenge der Response-Header.

Validierung

Führe die SDK-Prüfungen aus, bevor du eine Änderung als abgeschlossen behandelst:

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

pnpm sdk:check umfasst eine statische Vertragsprüfung und eine No-Network-Runtime-Prüfung für Error Parsing, sichere Error Headers, Idempotency Headers, Bearer Auth, öffentliche Modellauflistung, Chat-Streaming-SSE-Parsing, Chat-Streaming-Error-Events und Webhook-Signaturprüfung.

Rivya TypeScript SDK