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

Jedes Referenzbild für Image5 oder Grok Imagine Image 2.0 benötigt width, height, size_bytes und image_dimensions_token aus der ursprünglichen modellgebundenen Upload-Antwort. Ein späterer Aufruf von files.retrieve kann für den Token null zurückgeben. Lade das Quellbild erneut hoch, statt MIME-Typ, Abmessungen oder Dateigröße zu erraten. Layer Decomposition erzwingt zusätzlich seine Grenzen für genau ein Bild und dessen Geometrie; Grok Image 2 akzeptiert für die standardmäßige Bildbearbeitung 1–5 signierte JPEG-, PNG- oder WebP-Referenzen.

Verwende für ein Video8-Referenzvideo video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes und video_metadata_token aus der ursprünglichen modellgebundenen Upload-Antwort als width, height, framesPerSecond, videoBitrateMbps, sizeBytes und videoMetadataToken. Bewahre durationSeconds und durationToken als separaten signierten Dauernachweis auf. Lade das Quellvideo erneut hoch, wenn bei einem späteren files.retrieve einer der Token fehlt.

Wan 3.0 verwendet für seine sich gegenseitig ausschließenden Szenen text, frames und reference dieselbe SDK-Feldzuordnung. Lade jede Referenz mit model: "wan-3-0-video" hoch; Bilder benötigen die signierten Bildfelder, Videos sowohl signierte Dauer als auch Videometadaten und Audio die ursprünglichen Werte mime_type, size_bytes, duration_seconds und duration_token. Setze seedance_scene, variant, resolution, aspect_ratio, duration, audio und optional seed in params. Intelligente Dauer ist -1, reserviert 30 Sekunden und kann nicht mit Referenzvideo kombiniert werden; Datei-zu-Video- und Link-zu-Video-Kurzpfade bleiben nicht verfügbar.

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