Använd betaversionen av Rivyas TypeScript SDK för att anropa det offentliga API v1 för modeller, genereringar, filer, krediter, webhooks och Chat, inklusive SSE-strömning.

Rivya tillhandahåller en betaversion av TypeScript SDK för serverbaserade integrationer med det offentliga API:et.

SDK:n är en tunn klient ovanpå Rivyas publika API v1. Det lägre kontraktet är fortfarande OpenAPI och schemakontrakt, och SDK-metoderna måste hålla sig i linje med det schemat.

SDK:n dokumenterar det implementerade klientbeteendet. Begäranden kräver fortfarande att det offentliga API:et är aktiverat för driftsmiljön, att kontonyckeln är giltig och att modellens aktuella API-status tillåter den begärda åtgärden.

Status

Paketet underhålls just nu i detta repo som en privat beta. Det publiceras inte till npm förrän paketnamn, metadata, changelog och releaseprocess är uttryckligen godkända.

SDK:n stöder:

modellista
skapa och hämta asynkrona generationer
Files API-uppladdning och hämtning
hämtning av kreditsaldo
hantering av webhook-destinationer, testleveranser, händelselista, leveranslista och byte av hemlighet
verifiering av webhooksignaturer
icke-streamande och streamande Chat completions, plus API-skapade chattsessioner

Chat-streaming är tillgänglig i denna privata beta via serverbaserad SSE-parsning. Håll hemliga API-nycklar på din server.

Installera i detta repo

Använd den lokala paketkällan medan SDK:n är i beta:

pnpm --dir packages/rivya-sdk typecheck

Applikationskod ska hålla den hemliga API-nyckeln på servern:

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

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

Placera inte hemliga API-nycklar i webbläsarbundles, localStorage, analys-events, skärmbilder eller delade ärenden.

Lista modeller

models.list är offentlig och kräver ingen API-nyckel:

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

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

Skapa en generation

Använd generations.create för asynkron bild-, video- eller ljudgenerering:

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

Polla sedan med generations.retrieve:

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

Använd Idempotency-Key för skrivbegäranden i produktion. SDK:n exponerar detta som idempotencyKey.

Ladda upp filer

Använd files.upload för referensbilder, videor eller ljud:

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

Använd files.retrieve för att läsa uppladdad metadata igen:

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

När du använder en fil i en generation skickar du de returnerade offentliga fälten 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
      }
    ]
  }
});

Varje referensbild för Image5 eller Grok Imagine Image 2.0 kräver width, height, size_bytes och image_dimensions_token från sitt ursprungliga modellbundna uppladdningssvar. Ett senare anrop till files.retrieve kan returnera token som null; ladda upp källbilden igen i stället för att gissa MIME-typ, mått eller byte-storlek. Layer Decomposition tillämpar dessutom sina geometrigränser för en enda bild; Grok Image 2 accepterar 1–5 signerade JPEG-, PNG- eller WebP-referenser för vanlig bildredigering.

För en Video8-referensvideo ska du använda video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes och video_metadata_token från det ursprungliga modellbundna uppladdningssvaret som width, height, framesPerSecond, videoBitrateMbps, sizeBytes och videoMetadataToken. Behåll durationSeconds och durationToken som ett separat signerat varaktighetsbevis. Ladda upp källvideon igen om något av tokenvärdena saknas vid ett senare files.retrieve.

Wan 3.0 använder samma SDK-fältmappning i sina ömsesidigt uteslutande scener text, frames och reference. Ladda upp varje referens med model: "wan-3-0-video"; bilder kräver de signerade bildfälten, videor kräver både signerad varaktighet och videometadata, och ljud kräver ursprungliga mime_type, size_bytes, duration_seconds och duration_token. Ange seedance_scene, variant, resolution, aspect_ratio, duration, audio och valfritt seed inuti params. Intelligent varaktighet är -1, reserverar 30 sekunder och kan inte kombineras med referensvideo; genvägar från fil till video och från länk till video förblir otillgängliga.

Kontrollera krediterna

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

Hantera webhooks

När webhookåtkomst är aktiverad för driftsmiljön och kontot skapar du en webhook-destination:

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 returneras bara efter create- eller rotate-anrop. Spara den på din server.

Andra webhook-hjälpare:

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

Verifiera leveranssignaturer innan du litar på webhookpayloads:

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-hjälparen använder samma HMAC-SHA256-kontrakt som dokumenteras i API-webhooks.

Chat

Använd chat.completions.create för en icke-streamande 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);

Fortsätt med det returnerade 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."
});

Läs API-skapade sessioner:

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

Använd chat.completions.stream för att konsumera Server-Sent Events som en async 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 är endast för visning. Det committade resultatet är tillgängligt efter message.completed och kan läsas senare med chat.sessions.retrieve.

Fel

SDK:n kastar RivyaAPIError för svar från det offentliga API:et som inte har 2xx-status:

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 innehåller HTTP-status, offentlig felkod, meddelande, begärans-ID när det finns och en säker delmängd av svarsrubrikerna.

Validering

Kör SDK-kontrollerna innan du betraktar en ändring som klar:

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

pnpm sdk:check omfattar en statisk kontraktskontroll och en nätverksfri körningskontroll för feltolkning, säkra fel- och idempotensrubriker, Bearer-autentisering, den offentliga modellistan, tolkning av SSE-strömning och felhändelser i Chat samt verifiering av webhooksignaturer.

Rivya TypeScript SDK