Utilisez la bêta du SDK TypeScript Rivya pour appeler Public API v1 sur les modèles, générations, fichiers, crédits, webhooks et Chat, y compris le streaming SSE.

Rivya fournit une bêta du SDK TypeScript pour les intégrations Public API côté serveur.

Le SDK est un client léger au-dessus de Rivya Public API v1. Le contrat de niveau inférieur reste le contrat OpenAPI et schéma, et les méthodes du SDK doivent rester alignées avec ce schéma.

Statut

Le package est actuellement maintenu dans ce dépôt en beta privée. Il n'est pas publié sur npm tant que le nom du package, les métadonnées, le changelog et le processus de release ne sont pas explicitement approuvés.

Le SDK prend en charge :

la liste des modèles
la création et la récupération de générations asynchrones
l'import et la récupération via l'API Files
la récupération du solde de crédits
la gestion des endpoints webhook, les livraisons de test, la liste des événements, la liste des livraisons et la rotation des secrets
la vérification des signatures webhook
les completions Chat non-streaming et streaming, ainsi que les sessions de chat créées par l'API

Le streaming Chat est disponible dans cette bêta privée via l'analyse SSE côté serveur. Gardez les clés API secrètes sur votre serveur.

Installer dans ce dépôt

Utilisez la source du package local tant que le SDK est en bêta :

pnpm --dir packages/rivya-sdk typecheck

Le code applicatif doit garder la clé API secrète sur le serveur :

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

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

Ne placez pas de clés API secrètes dans les bundles navigateur, localStorage, événements analytics, captures d'écran ou tickets partagés.

Lister les modèles

models.list est public et ne nécessite pas de clé API :

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

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

Créer une génération

Utilisez generations.create pour la génération asynchrone d'image, de vidéo ou d'audio :

const generation = await rivya.generations.create(
  {
    model: "z-image",
    prompt: "Image produit éditoriale nette sur fond studio doux",
    client_request_id: "order-123-preview"
  },
  {
    idempotencyKey: "order-123-preview"
  }
);

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

Interrogez ensuite avec generations.retrieve :

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

Utilisez Idempotency-Key pour les requêtes d'écriture en production. Le SDK l'expose sous la forme idempotencyKey.

Importer des fichiers

Utilisez files.upload pour les images, vidéos ou audios de référence :

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",
  client_request_id: "asset-123"
});

console.log(uploaded.id, uploaded.url);

Utilisez files.retrieve pour relire les métadonnées importées :

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

Lorsque vous utilisez un fichier dans une génération, transmettez les champs publics renvoyés via params.referenceMediaItems :

await rivya.generations.create({
  model: "nano-banana-2",
  prompt: "Recompose cette photo produit pour une page catalogue éditoriale nette",
  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
      }
    ]
  }
});

Vérifier les crédits

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

Gérer les webhooks

Créez un endpoint webhook :

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

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

Le signing_secret est renvoyé uniquement après les appels de création ou de rotation. Stockez-le sur votre serveur.

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

Vérifiez les signatures de livraison avant de faire confiance aux payloads 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("Signature webhook Rivya invalide");
}

Le helper du SDK utilise le même contrat HMAC-SHA256 que celui documenté dans Webhooks API.

Chat

Utilisez chat.completions.create pour un tour Chat API non-streaming :

const completion = await rivya.chat.completions.create(
  {
    model: "gpt-5-2-chat",
    message: "Rédige un plan de lancement concis pour une nouvelle campagne visuelle produit",
    client_request_id: "chat-001"
  },
  {
    idempotencyKey: "chat-001"
  }
);

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

Continuez avec le session_id renvoyé :

await rivya.chat.completions.create({
  model: "gpt-5-2-chat",
  session_id: completion.session_id,
  message: "Transforme maintenant cela en checklist opérationnelle en 5 étapes."
});

Lisez les sessions créées par l'API :

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

Utilisez chat.completions.stream pour consommer les Server-Sent Events comme un itérateur asynchrone :

const stream = await rivya.chat.completions.stream(
  {
    model: "gpt-5-2-chat",
    message: "Rédige un plan de lancement concis pour une nouvelle campagne visuelle produit",
    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 sert uniquement à l'affichage. Le résultat validé est disponible après message.completed et peut être relu plus tard avec chat.sessions.retrieve.

Erreurs

Le SDK lance RivyaAPIError pour les réponses 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 inclut le statut HTTP, le code d'erreur public, le message, l'id de requête lorsqu'il est disponible et un sous-ensemble sûr d'en-têtes de réponse.

Validation

Exécutez les contrôles du SDK avant de considérer un changement comme terminé :

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

pnpm sdk:check inclut un contrôle statique du contrat et un contrôle runtime sans réseau pour le parsing des erreurs, les en-têtes d'erreur sûrs, les en-têtes d'idempotence, l'authentification Bearer, la liste publique des modèles, le parsing SSE du streaming Chat, les événements d'erreur du streaming Chat et la vérification des signatures webhook.

SDK TypeScript Rivya