Nutze das Rivya TypeScript-SDK in der Betaphase, um Public API v1 für Modelle, Generierungen, Dateien, Credits, Webhooks und Chat einschließlich SSE-Übertragung aufzurufen.

Rivya stellt ein TypeScript-SDK in der Betaphase für serverseitige Public-API-Integrationen bereit.

Das SDK ist ein schlanker Client für Rivya Public API v1. Die zugrunde liegende Grundlage bleibt der OpenAPI- und Schema-Vertrag, und SDK-Methoden müssen weiterhin diesem Schema entsprechen.

Das SDK dokumentiert das implementierte Clientverhalten. Anfragen erfordern weiterhin eine für die Bereitstellung aktivierte Public API, einen gültigen Kontoschlüssel und ein Modell, dessen aktueller API-Status den gewünschten Vorgang erlaubt.

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 Generierungen erstellen und abrufen
Dateien über die Datei-API hochladen und abrufen
Credit-Guthaben abrufen
Verwaltung von Webhook-Endpunkten, Testzustellungen, Ereignis- und Zustelllisten sowie Rotation von Geheimnissen
Webhook-Signaturprüfung
vollständige und per SSE übertragene Chatantworten sowie über die API erstellte Chatsitzungen

Die SSE-Übertragung von Chatantworten ist in dieser privaten Betaphase über serverseitige SSE-Verarbeitung verfügbar. Bewahre geheime API-Schlüssel auf deinem Server auf.

In diesem Repo installieren

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

pnpm --dir packages/rivya-sdk typecheck

Der Anwendungscode sollte den geheimen API-Schlüssel 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);
}

Generierung erstellen

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

const generation = await rivya.generations.create(
  {
    model: "z-image",
    prompt: "Ein klares redaktionelles Produktbild vor einem weichen Studiohintergrund",
    client_request_id: "order-123-preview"
  },
  {
    idempotencyKey: "order-123-preview"
  }
);

console.log(generation.id, generation.status);

Frage den Status anschließend regelmäßig mit generations.retrieve ab:

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 Audiodateien:

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 Generierung nutzt, gib die zurückgegebenen öffentlichen Felder über params.referenceMediaItems weiter:

await rivya.generations.create({
  model: "nano-banana-2-lite",
  prompt: "Gestalte dieses Produktfoto für eine klare redaktionelle Katalogseite neu",
  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 Antwort beim Hochladen. Ein späterer Aufruf von files.retrieve kann für das 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 eine bis fünf 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 Antwort beim Hochladen 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 eines 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

Wenn der Webhook-Zugriff für Bereitstellung und Konto aktiviert ist, erstelle einen Webhook-Endpunkt:

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 Aufrufen zum Erstellen oder Rotieren 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 Zustellungssignaturen, bevor du Webhook-Nutzdaten 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 eine vollständige Antwort auf eine Nachricht über die Chat API:

const completion = await rivya.chat.completions.create(
  {
    model: "claude-sonnet-5-chat",
    message: "Erstelle einen knappen Einführungsplan für eine neue Produktbildkampagne",
    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: "claude-sonnet-5-chat",
  session_id: completion.session_id,
  message: "Mache daraus jetzt eine Ausführungscheckliste mit fünf Schritten."
});

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 mit einem asynchronen Iterator zu verarbeiten:

const stream = await rivya.chat.completions.stream(
  {
    model: "claude-sonnet-5-chat",
    message: "Erstelle einen knappen Einführungsplan für eine neue Produktbildkampagne",
    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, Anfrage-ID, sofern verfügbar, und eine sichere Teilmenge der Antwortkopfzeilen.

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 Laufzeitprüfung ohne Netzwerkzugriff für Fehlerverarbeitung, sichere Fehlerkopfzeilen, Idempotenzkopfzeilen, Bearer-Authentifizierung, öffentliche Modellauflistung, SSE-Verarbeitung im Chat, Fehlerereignisse bei der Chatübertragung und die Prüfung von Webhook-Signaturen.

Rivya TypeScript SDK