Použijte soukromou zkušební verzi Rivya TypeScript SDK k volání veřejného API v1 pro modely, generování, soubory, kredity, webhooky a chat včetně SSE streamování.

Rivya poskytuje soukromou zkušební verzi TypeScript SDK pro serverové integrace s veřejným API.

SDK je tenký klient nad veřejným API Rivya v1. Základním kontraktem zůstává OpenAPI a kontrakt schématu a metody SDK musí zůstat sladěné s tímto schématem.

SDK popisuje implementované chování klienta. Požadavky stále vyžadují zapnuté veřejné API, platný klíč účtu a model, jehož aktuální API stav dovoluje požadovanou operaci.

Stav

Balíček je nyní v tomto repozitáři udržován jako soukromá zkušební verze. Na npm nebude zveřejněn, dokud nebudou výslovně schváleny název balíčku, metadata, přehled změn a proces vydání.

SDK podporuje:

výpis modelů
vytvoření a načtení asynchronního generování
nahrání a načtení přes Files API
načtení zůstatku kreditů
správu koncových bodů webhooků, testovací doručení, výpis událostí, výpis doručení a rotaci tajemství
ověření podpisu webhooku
nestreamovaná a streamovaná Chat completions a chatové relace vytvořené přes API

Streamování chatu je v této soukromé zkušební verzi dostupné přes serverové zpracování SSE. Tajné API klíče držte na svém serveru.

Instalace v tomto repozitáři

Dokud je SDK v betě, používejte lokální zdroj balíčku:

pnpm --dir packages/rivya-sdk typecheck

Aplikační kód by měl držet tajný API klíč na serveru:

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

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

Nevkládejte tajné API klíče do browser bundle, localStorage, analytických událostí, screenshotů ani sdílených tiketů.

Výpis modelů

models.list je veřejný a nevyžaduje API klíč:

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

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

Vytvoření generování

Použijte generations.create pro asynchronní generování obrázku, videa nebo audia:

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

Potom stav dotazujte pomocí generations.retrieve:

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

Pro produkční zápisové požadavky používejte Idempotency-Key. SDK ho vystavuje jako idempotencyKey.

Nahrání souborů

Použijte files.upload k nahrání referenčních obrázků, videí nebo audia:

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

Použijte files.retrieve pro opětovné načtení nahraných metadat:

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

Když soubor používáte v generování, předejte vrácená veřejná pole přes 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
      }
    ]
  }
});

Každý referenční obrázek pro Image5 nebo Grok Imagine Image 2.0 vyžaduje width, height, size_bytes a image_dimensions_token z původní odpovědi na nahrání svázané s modelem. Pozdější volání files.retrieve může vrátit token jako null; místo odhadování MIME typu, rozměrů nebo velikosti v bajtech nahrajte zdrojový obrázek znovu. Layer Decomposition navíc vynucuje geometrické limity pro jeden obrázek; Grok Image 2 přijímá pro standardní úpravu obrázku jeden až pět podepsaných referenčních obrázků JPEG, PNG nebo WebP.

U referenčního videa Video8 použijte video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes a video_metadata_token z původní odpovědi na nahrání svázané s modelem jako width, height, framesPerSecond, videoBitrateMbps, sizeBytes a videoMetadataToken. durationSeconds a durationToken ponechte jako samostatné podepsané potvrzení délky. Pokud při pozdějším volání files.retrieve některý z tokenů chybí, nahrajte zdrojové video znovu.

Wan 3.0 používá stejné mapování polí SDK ve vzájemně výlučných režimech text, frames a reference. Každou referenci nahrajte s model: "wan-3-0-video"; obrázky vyžadují podepsaná pole obrázku, videa vyžadují podepsanou délku i metadata videa a audio vyžaduje původní mime_type, size_bytes, duration_seconds a duration_token. V params nastavte seedance_scene, variant, resolution, aspect_ratio, duration, audio a volitelný seed. Inteligentní délka má hodnotu -1, rezervuje 30 sekund a nelze ji kombinovat s referenčním videem; zkratky file-to-video a link-to-video zůstávají nedostupné.

Kontrola kreditů

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

Správa webhooků

Když je přístup k webhookům zapnutý pro nasazení a účet, vytvořte koncový bod webhooku:

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 se vrací pouze po volání create nebo rotate. Uložte ho na serveru.

Další pomocné metody pro webhooky:

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

Před důvěrou k obsahu webhooku ověřte podpis doručení:

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

Pomocná metoda SDK používá stejný HMAC-SHA256 kontrakt dokumentovaný v API Webhooks.

Chat

Použijte chat.completions.create pro jeden nestreamovaný tah Chat API:

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

Pokračujte s vráceným 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."
});

Načtěte relace vytvořené přes API:

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

Použijte chat.completions.stream pro čtení Server-Sent Events jako asynchronní iterátor:

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 slouží jen k zobrazení. Potvrzený výsledek je dostupný po message.completed a později ho lze načíst pomocí chat.sessions.retrieve.

Chyby

SDK vyhazuje RivyaAPIError pro odpovědi veřejného API mimo třídu 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 obsahuje stav HTTP, veřejný chybový kód, zprávu, ID požadavku, pokud je dostupné, a bezpečnou podmnožinu hlaviček odpovědi.

Validace

Než budete změnu považovat za dokončenou, spusťte kontroly SDK:

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

pnpm sdk:check obsahuje statickou kontrolu kontraktu a bezsíťovou runtime kontrolu pro parsování chyb, bezpečné chybové hlavičky, idempotency hlavičky, Bearer autentizaci, veřejný výpis modelů, parsování Chat streaming SSE, chybové události Chat streamingu a ověření podpisu webhooku.

Rivya TypeScript SDK