Usa la beta del Rivya TypeScript SDK per chiamare Public API v1 per modelli, generazioni, file, crediti, webhooks e Chat, incluso streaming SSE.

Rivya fornisce una beta del TypeScript SDK per integrazioni Public API lato server.

L'SDK è un client sottile sopra Rivya Public API v1. Il contratto di livello inferiore resta OpenAPI e contratto dello schema, e i metodi SDK devono restare allineati a quello schema.

Stato

Il package è attualmente mantenuto dentro questo repository come beta privata. Non viene pubblicato su npm finché nome del package, metadata, changelog e processo di release non sono approvati esplicitamente.

L'SDK supporta:

elenco modelli
creazione e recupero di generazioni asincrone
upload e recupero Files API
recupero saldo crediti
gestione endpoint webhook, delivery di test, elenco eventi, elenco delivery e rotazione secret
verifica firma webhook
completions Chat non streaming e streaming, più sessioni chat create via API

Lo streaming Chat è disponibile in questa beta privata tramite parsing SSE lato server. Mantieni le chiavi API segrete sul tuo server.

Installazione in questo repo

Usa il sorgente del package locale mentre l'SDK è in beta:

pnpm --dir packages/rivya-sdk typecheck

Il codice applicativo dovrebbe mantenere la chiave API segreta sul server:

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

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

Non inserire chiavi API segrete in bundle browser, localStorage, eventi analytics, screenshot o ticket condivisi.

Elencare i modelli

models.list è pubblico e non richiede una chiave API:

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

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

Creare una generazione

Usa generations.create per generazione asincrona di immagini, video o audio:

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

Poi fai polling con generations.retrieve:

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

Usa Idempotency-Key per richieste di scrittura in produzione. L'SDK lo espone come idempotencyKey.

Caricare file

Usa files.upload per immagini, video o audio di riferimento:

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

Usa files.retrieve per leggere di nuovo i metadati caricati:

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

Quando usi un file in una generazione, passa i campi pubblici restituiti tramite 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
      }
    ]
  }
});

Ogni immagine di riferimento Image5 o Grok Imagine Image 2.0 richiede width, height, size_bytes e image_dimensions_token della risposta originale all'upload associato al modello. Una chiamata successiva a files.retrieve può restituire il token come null: carica nuovamente l'immagine sorgente anziché presumere il tipo MIME, le dimensioni o il numero di byte. Layer Decomposition applica inoltre i propri limiti geometrici per una singola immagine; Grok Image 2 accetta da una a cinque immagini di riferimento JPEG, PNG o WebP firmate per l'editing standard.

Per un video di riferimento Video8, usa video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes e video_metadata_token della risposta originale all'upload associato al modello come width, height, framesPerSecond, videoBitrateMbps, sizeBytes e videoMetadataToken. Mantieni durationSeconds e durationToken come prova firmata della durata separata. Se uno dei due token manca in una successiva chiamata a files.retrieve, carica nuovamente il video sorgente.

Wan 3.0 usa la stessa mappatura dei campi SDK nelle scene mutuamente esclusive text, frames e reference. Carica ogni riferimento con model: "wan-3-0-video"; le immagini richiedono i campi immagine firmati, i video richiedono sia la durata sia i metadati video firmati e l'audio richiede i valori originali mime_type, size_bytes, duration_seconds e duration_token. Imposta seedance_scene, variant, resolution, aspect_ratio, duration, audio e il seed opzionale dentro params. La durata intelligente è -1, prenota 30 secondi e non può essere abbinata a un video di riferimento; le scorciatoie da file a video e da link a video restano non disponibili.

Controllare i crediti

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

Gestire Webhooks

Crea un endpoint webhook:

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

Il signing_secret viene restituito solo dopo chiamate di creazione o rotazione. Conservalo sul tuo server.

Altri helper webhook:

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

Verifica le firme delle delivery prima di fidarti dei payload webhook:

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

L'helper SDK usa lo stesso contratto HMAC-SHA256 documentato in API Webhooks.

Chat

Usa chat.completions.create per un turno Chat API non streaming:

const completion = await rivya.chat.completions.create(
  {
    model: "gpt-5-2-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);

Continua con il session_id restituito:

await rivya.chat.completions.create({
  model: "gpt-5-2-chat",
  session_id: completion.session_id,
  message: "Now turn that into a 5-step execution checklist."
});

Leggi le sessioni create via API:

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

Usa chat.completions.stream per consumare Server-Sent Events come async iterator:

const stream = await rivya.chat.completions.stream(
  {
    model: "gpt-5-2-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 serve solo per visualizzazione. Il risultato confermato è disponibile dopo message.completed e può essere letto più tardi con chat.sessions.retrieve.

Errori

L'SDK lancia RivyaAPIError per risposte Public API non 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 stato HTTP, codice di errore pubblico, messaggio, request id quando disponibile e un sottoinsieme sicuro degli header di risposta.

Validazione

Esegui i controlli SDK prima di considerare completa una modifica:

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

pnpm sdk:check include un controllo statico del contratto e un controllo runtime senza rete per parsing errori, header di errore sicuri, header di idempotenza, auth Bearer, elenco modelli pubblico, parsing SSE dello streaming Chat, eventi di errore streaming Chat e verifica firma webhook.

Rivya TypeScript SDK