Gebruik de Rivya TypeScript SDK beta om Public API v1 aan te roepen voor modellen, generaties, bestanden, credits, webhooks en Chat inclusief SSE-streaming.

Rivya biedt een TypeScript SDK beta voor server-side Public API-integraties.

De SDK is een thin client bovenop Rivya Public API v1. Het lagere contract blijft OpenAPI- en schemacontract, en SDK-methoden moeten met dat schema uitgelijnd blijven.

De SDK documenteert geïmplementeerd clientgedrag. Verzoeken vereisen nog steeds een voor de deployment ingeschakelde openbare API, een geldige accountsleutel en een model waarvan de live API-status de gevraagde handeling toestaat.

Status

Het package wordt momenteel binnen deze repository onderhouden als private beta. Het wordt niet naar npm gepubliceerd totdat de packagenaam, metadata, changelog en het releaseproces expliciet zijn goedgekeurd.

De SDK ondersteunt:

modellenlijst tonen
asynchrone generatie aanmaken en ophalen
Files API uploaden en ophalen
creditsaldo ophalen
webhook endpoint management, testdeliveries, eventlijst, deliverylijst en secretrotatie
webhooksignatureverificatie
non-streaming en streaming Chat completions, plus API-aangemaakte chatsessies

Chat streaming is in deze private beta beschikbaar via server-side SSE-parsing. Houd geheime API-sleutels op je server.

Installeren in deze repo

Gebruik de lokale package source zolang de SDK in beta is:

pnpm --dir packages/rivya-sdk typecheck

Applicatiecode moet de geheime API-sleutel op de server bewaren:

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

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

Plaats geheime API-sleutels niet in browserbundles, localStorage, analytics-events, screenshots of gedeelde tickets.

Modellen tonen

models.list is publiek en vereist geen API-sleutel:

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

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

Een generatie aanmaken

Gebruik generations.create voor asynchrone beeld-, video- of audiogeneratie:

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

Poll daarna met generations.retrieve:

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

Gebruik Idempotency-Key voor productieschrijfrequests. De SDK stelt dit beschikbaar als idempotencyKey.

Bestanden uploaden

Gebruik files.upload voor referentieafbeeldingen, video's of 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);

Gebruik files.retrieve om geüploade metadata opnieuw te lezen:

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

Wanneer je een bestand in een generatie gebruikt, geef je de teruggegeven publieke velden door via params.referenceMediaItems:

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

Voor elke Image5- of Grok Imagine Image 2.0-referentieafbeelding zijn width, height, size_bytes en image_dimensions_token uit de oorspronkelijke modelgebonden uploadresponse vereist. Een latere aanroep van files.retrieve kan het token als null teruggeven; upload de bronafbeelding dan opnieuw in plaats van het MIME-type, de afmetingen of de bestandsgrootte te raden. Layer Decomposition dwingt bovendien de limiet van één afbeelding en de bijbehorende geometrische grenzen af; Grok Image 2 accepteert voor standaard beeldbewerking één tot vijf ondertekende JPEG-, PNG- of WebP-referenties.

Gebruik voor een Video8-referentievideo video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes en video_metadata_token uit de oorspronkelijke modelgebonden uploadresponse als width, height, framesPerSecond, videoBitrateMbps, sizeBytes en videoMetadataToken. Bewaar durationSeconds en durationToken als afzonderlijk ondertekend bewijs van de duur. Upload de bronvideo opnieuw als een van beide tokens ontbreekt bij een latere files.retrieve.

Wan 3.0 gebruikt dezelfde SDK-veldtoewijzing in de elkaar uitsluitende scènes text, frames en reference. Upload elke referentie met model: "wan-3-0-video"; afbeeldingen vereisen de ondertekende afbeeldingsvelden, video's vereisen zowel de ondertekende duur als videometadata en audio vereist de oorspronkelijke waarden mime_type, size_bytes, duration_seconds en duration_token. Stel seedance_scene, variant, resolution, aspect_ratio, duration, audio en de optionele seed in binnen params. Intelligente duur is -1, reserveert 30 seconden en kan niet met referentievideo worden gecombineerd; snelkoppelingen voor bestand-naar-video en link-naar-video blijven onbeschikbaar.

Credits controleren

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

Webhooks beheren

Wanneer webhooktoegang voor de deployment en het account is ingeschakeld, maak je een webhook endpoint aan:

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

De signing_secret wordt alleen na create- of rotate-calls teruggegeven. Bewaar die op je server.

Andere webhookhelpers:

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

Verifieer deliverysignatures voordat je webhookpayloads vertrouwt:

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

De SDK-helper gebruikt hetzelfde HMAC-SHA256-contract dat is gedocumenteerd in API-webhooks.

Chat

Gebruik chat.completions.create voor één non-streaming Chat API-turn:

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

Ga door met de teruggegeven session_id:

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

Lees API-aangemaakte sessies:

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

Gebruik chat.completions.stream om Server-Sent Events als async iterator te verwerken:

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

message.delta is alleen voor weergave. Het gecommitte resultaat is beschikbaar na message.completed en kan later worden gelezen met chat.sessions.retrieve.

Fouten

De SDK gooit RivyaAPIError voor non-2xx Public API-responses:

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 bevat de HTTP-status, publieke foutcode, message, request id wanneer beschikbaar en een veilige subset van responseheaders.

Validatie

Run de SDK-checks voordat je een wijziging als voltooid beschouwt:

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

pnpm sdk:check bevat een statische contractcheck en een no-network runtimecheck voor error parsing, veilige errorheaders, idempotencyheaders, Bearer auth, publieke modellenlijst, Chat streaming SSE parsing, Chat streaming error events en webhooksignatureverificatie.

Rivya TypeScript-SDK