Brug betaudgaven af Rivya TypeScript SDK til at kalde Public API v1 for modeller, genereringer, filer, kreditter, webhooks og chat, inklusive SSE-streaming.

Rivya tilbyder en betaversion af TypeScript SDK'et til serverbaserede integrationer med den offentlige API.

SDK'en er en tynd klient oven på Rivya Public API v1. Den lavere kontrakt forbliver OpenAPI- og schema-kontrakt, og SDK-metoder skal blive ved med at være på linje med det schema.

SDK-et dokumenterer implementeret klientadfærd. Anmodninger kræver stadig, at Public API er aktiveret for installationen, at kontonøglen er gyldig, og at modellens aktive API-status tillader den ønskede handling.

Status

Pakken vedligeholdes aktuelt inde i dette repository som en private beta. Den publiceres ikke til npm, før pakkenavn, metadata, changelog og releaseproces er eksplicit godkendt.

SDK'en understøtter:

modelliste
oprettelse og hentning af asynkrone generationer
upload og hentning via Fil-API-et
hentning af kreditsaldo
styring af webhookslutpunkter, testleveringer, hændelseslister, leveringslister og rotation af hemmeligheder
verificering af webhook-signaturer
chatsvar med og uden streaming samt API-oprettede chatsessioner

Streaming af chat er tilgængelig i denne private beta gennem SSE-fortolkning på serversiden. Opbevar hemmelige API-nøgler på din server.

Installer i dette repo

Brug den lokale pakkekilde, mens SDK'en er i beta:

pnpm --dir packages/rivya-sdk typecheck

Applikationskode bør holde den hemmelige API-nøgle på serveren:

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

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

Læg ikke hemmelige API-nøgler i browser bundles, localStorage, analytics-events, screenshots eller delte tickets.

List modeller

models.list er offentlig og kræver ikke en API-nøgle:

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

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

Opret en generation

Brug generations.create til asynkron billed-, video- eller audiogenerering:

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

Kontrollér derefter status med jævne mellemrum via generations.retrieve:

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

Brug Idempotency-Key til skrivende produktionsanmodninger. SDK'et stiller dette til rådighed som idempotencyKey.

Upload filer

Brug files.upload til referencebilleder, videoer eller 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);

Brug files.retrieve til at læse uploadede metadata igen:

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

Når en fil bruges i en generation, skal de returnerede offentlige felter sendes gennem 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 referencebillede til Image5 eller Grok Imagine Image 2.0 kræver width, height, size_bytes og image_dimensions_token fra det oprindelige modelbundne uploadsvar. Et senere kald til files.retrieve kan returnere tokenet som null; upload kildebilledet igen i stedet for at gætte MIME-type, dimensioner eller filstørrelse. Layer Decomposition håndhæver desuden sine geometriske grænser for ét billede; Grok Image 2 accepterer 1–5 signerede JPEG-, PNG- eller WebP-referencer til standard billedredigering.

For en Video8-referencevideo skal du bruge video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes og video_metadata_token fra det oprindelige modelbundne uploadsvar som width, height, framesPerSecond, videoBitrateMbps, sizeBytes og videoMetadataToken. Bevar durationSeconds og durationToken som et separat signeret varighedsbevis. Hvis et af tokenene mangler ved et senere files.retrieve, skal du uploade kildevideoen igen.

Wan 3.0 bruger samme SDK-felttilknytning på tværs af de gensidigt udelukkende scener text, frames og reference. Upload hver reference med model: "wan-3-0-video"; billeder kræver de signerede billedfelter, videoer kræver både signeret varighed og videometadata, og lyd kræver de oprindelige mime_type, size_bytes, duration_seconds og duration_token. Angiv seedance_scene, variant, resolution, aspect_ratio, duration, audio og valgfri seed i params. Intelligent varighed er -1, reserverer 30 sekunder og kan ikke kombineres med referencevideo; genveje fra fil til video og fra link til video forbliver utilgængelige.

Tjek kreditter

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

Administrer webhooks

Når webhookadgang er aktiveret for installationen og kontoen, kan du oprette et webhook-endpoint:

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 kun efter create- eller rotate-kald. Gem den på din server.

Andre webhook-hjælpere:

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

Verificer delivery-signaturer, 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-helperen bruger den samme HMAC-SHA256-kontrakt, som er dokumenteret i API Webhooks.

Chat

Brug chat.completions.create til én Chat API-besked uden streaming:

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æt med det returnerede 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-oprettede sessioner:

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

Brug chat.completions.stream til at læse Server-Sent Events via 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 kun til visning. Det committed resultat er tilgængeligt efter message.completed og kan læses senere med chat.sessions.retrieve.

Fejl

SDK'en kaster RivyaAPIError for ikke-2xx Public API-svar:

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 indeholder HTTP-status, offentlig fejlkode, besked, anmodnings-ID når det findes, og et sikkert udvalg af svarheadere.

Validering

Kør SDK-kontrollerne, før en ændring behandles som færdig:

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

pnpm sdk:check omfatter en statisk kontraktkontrol og en kørsel uden netværk, der kontrollerer fejltolkning, sikre fejlheadere, idempotensheadere, Bearer-godkendelse, den offentlige modelliste, SSE-fortolkning ved chatstreaming, fejlhændelser ved chatstreaming og kontrol af webhooksignaturer.

Rivya TypeScript SDK