Rivya TypeScript SDK

Rivya oferă o versiune beta a TypeScript SDK pentru integrări Public API realizate pe server.

SDK-ul este un client minimalist construit peste Rivya Public API v1. Contractul de nivel inferior rămâne Contract OpenAPI și schemă, iar metodele SDK trebuie să rămână aliniate cu schemă respectivă.

SDK-ul documentează comportamentul implementat al clientului. Cererile necesită în continuare Public API activ pentru implementare, o cheie validă a contului și un model a cărui stare API actuală permite operația cerută.

Stare

Pachetul este întreținut în prezent în acest depozit ca versiune beta privată. Nu este publicat pe npm până când numele pachetului, metadatele, jurnalul modificărilor și procesul de lansare nu sunt aprobate explicit.

SDK-ul permite:

• listarea modelelor

• crearea și recuperarea generărilor asincrone

• încărcarea și recuperarea fișierelor prin Files API

• recuperarea soldului de credite

• gestionarea endpointurilor webhook, a livrărilor de test, a listelor de evenimente și livrări, precum și rotația secretului

• verificarea semnăturilor webhook

• răspunsuri Chat fără streaming și cu streaming, plus sesiuni de chat create prin API

Streamingul Chat este disponibil în această versiune beta privată prin analizarea SSE pe server. Păstrează cheile API secrete pe server.

Instalare în acest depozit

Folosește sursa locală a pachetului cât timp SDK-ul se află în versiune beta:

pnpm --dir packages/rivya-sdk typecheck

Codul aplicației trebuie să păstreze cheia API secretă pe server:

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

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

Nu include cheile API secrete în pachete pentru browser, localStorage, evenimente de analiză, capturi de ecran sau tichete partajate.

Listează modelele

models.list este public și nu necesită o cheie API:

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

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

Creează o generare

Folosește generations.create pentru generarea asincronă de imagini, videoclipuri sau materiale audio:

const generation = await rivya.generations.create(
  {
    model: "z-image",
    prompt: "O imagine editorială curată a produsului, pe un fundal discret de studio",
    client_request_id: "order-123-preview"
  },
  {
    idempotencyKey: "order-123-preview"
  }
);

console.log(generation.id, generation.status);

Apoi verifică periodic starea prin generations.retrieve:

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

Folosește Idempotency-Key pentru cererile de scriere în producție. SDK-ul expune această valoare ca idempotencyKey.

Încarcă fișiere

Folosește files.upload pentru imagini, videoclipuri sau fișiere audio de referință:

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

Folosește files.retrieve pentru a citi din nou metadatele încărcate:

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

Când folosești un fișier într-o generare, transmite câmpurile publice returnate prin params.referenceMediaItems:

await rivya.generations.create({
  model: "nano-banana-2-lite",
  prompt: "Reinterpretează această fotografie de produs pentru o pagină editorială curată de catalog",
  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
      }
    ]
  }
});

Fiecare imagine de referință Image5 sau Grok Imagine Image 2.0 necesită valorile width, height, size_bytes și image_dimensions_token din răspunsul original al încărcării asociate modelului. Un apel ulterior files.retrieve poate returna tokenul ca null; reîncarcă imaginea sursă în loc să estimezi tipul MIME, dimensiunile sau dimensiunea în octeți. Layer Decomposition aplică suplimentar limitele geometrice pentru o singură imagine; Grok Image 2 acceptă între una și cinci imagini de referință JPEG, PNG sau WebP semnate pentru editarea standard.

Pentru un videoclip de referință Video8, folosește valorile video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes și video_metadata_token din răspunsul original al încărcării asociate modelului drept width, height, framesPerSecond, videoBitrateMbps, sizeBytes și videoMetadataToken. Păstrează durationSeconds și durationToken ca dovadă semnată separată a duratei. Dacă oricare dintre tokeni lipsește la un apel ulterior files.retrieve, reîncarcă videoclipul sursă.

Wan 3.0 folosește aceeași mapare a câmpurilor SDK în modurile text, frames și reference, care se exclud reciproc. Încarcă fiecare referință cu model: "wan-3-0-video"; imaginile necesită câmpurile de imagine semnate, videoclipurile necesită atât durata, cât și metadatele video semnate, iar audio necesită valorile originale mime_type, size_bytes, duration_seconds și duration_token. Setează seedance_scene, variant, resolution, aspect_ratio, duration, audio și valoarea opțională seed în params. Durata inteligentă este -1, rezervă 30 de secunde și nu poate fi combinată cu un videoclip de referință; scurtăturile file-to-video și link-to-video rămân indisponibile.

Verifică soldul de credite

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

Gestionează webhookurile

Când accesul la webhook-uri este activ pentru implementare și cont, creează un endpoint webhook:

const endpoint = await rivya.webhooks.create({
  name: "Webhook de producție",
  url: "https://example.com/rivya/webhook",
  event_types: ["generation.succeeded", "generation.failed"]
});

console.log(endpoint.id, endpoint.signing_secret);

signing_secret este returnat numai după apelurile de creare sau rotație. Stochează-l pe serverul tău.

Alte funcții ajutătoare pentru webhookuri:

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

Verifică semnăturile livrărilor înainte de a considera de încredere conținutul webhookurilor:

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("Semnătură webhook Rivya nevalidă");
}

Funcția ajutătoare din SDK folosește același contract HMAC-SHA256 documentat în API Webhooks.

Chat

Folosește chat.completions.create pentru o interacțiune Chat API fără streaming:

const completion = await rivya.chat.completions.create(
  {
    model: "claude-sonnet-5-chat",
    message: "Scrie un plan concis pentru lansarea unei noi campanii cu imagini de produs",
    client_request_id: "chat-001"
  },
  {
    idempotencyKey: "chat-001"
  }
);

console.log(completion.session_id, completion.message.content);

Continuă cu valoarea session_id returnată:

await rivya.chat.completions.create({
  model: "claude-sonnet-5-chat",
  session_id: completion.session_id,
  message: "Transformă acum planul într-o listă de verificare cu 5 pași."
});

Citește sesiunile create prin API:

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

Folosește chat.completions.stream pentru a consuma fluxuri Server-Sent Events sub formă unui iterator asincron:

const stream = await rivya.chat.completions.stream(
  {
    model: "claude-sonnet-5-chat",
    message: "Scrie un plan concis pentru lansarea unei noi campanii cu imagini de produs",
    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 este destinat numai afișării. Rezultatul confirmat devine disponibil după message.completed și poate fi citit ulterior cu chat.sessions.retrieve.

Erori

SDK-ul lansează o excepție RivyaAPIError pentru răspunsurile Public API din afară intervalului 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 include codul de stare HTTP, codul public de eroare, mesajul, ID-ul cererii când este disponibil și un subset sigur al antetelor de răspuns.

Validare

Rulează verificările SDK înainte de a considera o modificare finalizată:

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

pnpm sdk:check include o verificare statică a contractului și o verificare de execuție fără rețea pentru analizarea erorilor, antetele sigure de eroare, antetele de idempotență, autentificarea Bearer, listarea publică a modelelor, analizarea SSE pentru streaming Chat, evenimentele de eroare din streaming Chat și verificarea semnăturilor webhook.

Pagini asociate

• Contract OpenAPI și schemă

• Pornire rapidă API

• Files API

• API Webhooks

• Chat API