Bruk Rivya TypeScript SDK-beta til å kalle Public API v1 for modeller, genereringer, filer, kreditter, webhooks og Chat, inkludert SSE-strømming.

Rivya tilbyr en betaversjon av TypeScript SDK for serverbaserte integrasjoner med den offentlige API-en.

SDK-en er en tynn klient over Rivya Public API v1. Den lavere kontrakten er fortsatt OpenAPI- og schema-kontrakt, og SDK-metoder må holde seg på linje med det schemaet.

SDK-et dokumenterer implementert klientatferd. Forespørsler krever fortsatt at Public API er aktivert for distribusjonen, at kontonøkkelen er gyldig, og at modellens aktive API-status tillater den forespurte operasjonen.

Status

Pakken vedlikeholdes for øyeblikket inne i dette repositoriet som en privat beta. Den publiseres ikke til npm før pakkenavn, metadata, changelog og release-prosess er uttrykkelig godkjent.

SDK-en støtter:

modellisting
oppretting og henting av asynkrone genereringer
opplasting og henting via Fil-API-et
henting av kredittsaldo
administrasjon av webhook-endepunkter, testleveringer, hendelseslisting, leveringslisting og hemmelighetsrotasjon
verifisering av webhook-signatur
ikke-streamende og streamende Chat completions, pluss API-opprettede chatøkter

Strømming av chat er tilgjengelig i denne private betaen gjennom serverbasert tolkning av SSE. Oppbevar hemmelige API-nøkler på serveren din.

Installer i dette repoet

Bruk den lokale pakkekilden mens SDK-en er i beta:

pnpm --dir packages/rivya-sdk typecheck

Applikasjonskode bør holde den hemmelige API-nøkkelen på serveren:

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

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

Ikke legg hemmelige API-nøkler i nettleserbundles, localStorage, analytics-hendelser, skjermbilder eller delte tickets.

List opp modeller

models.list er offentlig og krever ikke API-nøkkel:

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

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

Opprett en generering

Bruk generations.create for asynkron bilde-, video- eller lydgenerering:

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

Kontroller deretter status med jevne mellomrom via generations.retrieve:

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

Bruk Idempotency-Key for produksjonsforespørsler som skriver data. SDK-en eksponerer dette som idempotencyKey.

Last opp filer

Bruk files.upload for referansebilder, videoer eller lyd:

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

Bruk files.retrieve for å lese opplastede metadata igjen:

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

Når du bruker en fil i en generering, sender du de returnerte offentlige feltene gjennom 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
      }
    ]
  }
});

Hvert referansebilde for Image5 eller Grok Imagine Image 2.0 krever width, height, size_bytes og image_dimensions_token fra den opprinnelige modellbundne opplastingsresponsen. Et senere files.retrieve-kall kan returnere tokenet som null; last opp kildebildet på nytt i stedet for å gjette MIME-type, dimensjoner eller byte-størrelse. Layer Decomposition håndhever i tillegg sine geometrigrenser for ett bilde; Grok Image 2 godtar 1–5 signerte JPEG-, PNG- eller WebP-referanser for standard bilderedigering.

For en Video8-referansevideo bruker du video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes og video_metadata_token fra den opprinnelige modellbundne opplastingsresponsen som width, height, framesPerSecond, videoBitrateMbps, sizeBytes og videoMetadataToken. Behold durationSeconds og durationToken som et separat signert varighetsbevis. Hvis ett av tokenene mangler etter et senere files.retrieve-kall, må du laste opp kildevideoen på nytt.

Wan 3.0 bruker samme SDK-felttilordning i de gjensidig utelukkende scenene text, frames og reference. Last opp hver referanse med model: "wan-3-0-video"; bilder krever de signerte bildefeltene, videoer krever både signert varighet og videometadata, og lyd krever de opprinnelige mime_type, size_bytes, duration_seconds og duration_token. Angi seedance_scene, variant, resolution, aspect_ratio, duration, audio og valgfri seed i params. Intelligent varighet er -1, reserverer 30 sekunder og kan ikke kombineres med referansevideo; snarveier fra fil til video og fra lenke til video forblir utilgjengelige.

Sjekk kreditter

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

Administrer webhooks

Når webhooktilgang er aktivert for distribusjonen og kontoen, kan du opprette et webhook-endepunkt:

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

signing_secret returneres bare etter opprettelses- eller rotasjonskall. Lagre den på serveren din.

Andre webhook-hjelpere:

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

Verifiser leveringssignaturer før du stoler på webhook-payloads:

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

SDK-hjelperen bruker den samme HMAC-SHA256-kontrakten som er dokumentert i API-webhooks.

Chat

Bruk chat.completions.create for én ikke-streamende Chat API-runde:

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

Fortsett med den returnerte 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."
});

Les API-opprettede økter:

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

Bruk chat.completions.stream for å lese Server-Sent Events gjennom en asynkron iterator:

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 er bare for visning. Det lagrede resultatet er tilgjengelig etter message.completed, og kan leses senere med chat.sessions.retrieve.

Feil

SDK-en kaster RivyaAPIError for Public API-responser som ikke er 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 inkluderer HTTP-status, offentlig feilkode, melding, request id når tilgjengelig og et trygt delsett av response headers.

Validering

Kjør SDK-sjekkene før du behandler en endring som fullført:

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

pnpm sdk:check inkluderer en statisk kontraktsjekk og en runtime-sjekk uten nettverk for feilparsing, trygge feilheadere, idempotensheadere, Bearer auth, offentlig modellisting, Chat streaming SSE-parsing, Chat streaming error events og webhook-signaturverifisering.

Rivya TypeScript SDK