Usa la beta del SDK TypeScript de Rivya para llamar a Public API v1 para modelos, generaciones, archivos, créditos, webhooks y Chat, incluido streaming SSE.

Rivya ofrece una beta del SDK TypeScript para integraciones de Public API del lado del servidor.

El SDK es un cliente ligero sobre Rivya Public API v1. El contrato de nivel inferior sigue siendo Contrato OpenAPI y de esquema, y los métodos del SDK deben mantenerse alineados con ese esquema.

Estado

El paquete se mantiene actualmente dentro de este repositorio como beta privada. No se pública en npm hasta que el nombre del paquete, los metadatos, el changelog y el proceso de lanzamiento estén aprobados explícitamente.

El SDK admite:

listado de modelos
creación y consulta de generaciones asíncronas
carga y consulta con Files API
consulta del saldo de créditos
gestión de endpoints de webhook, entregas de prueba, listado de eventos, listado de entregas y rotación de secretos
verificación de firmas de webhook
completions de Chat con y sin streaming, además de sesiones de chat creadas por API

El streaming de Chat está disponible en esta beta privada mediante parsing SSE del lado del servidor. Mantén las claves secretas de API en tu servidor.

Instalación en este repositorio

Usa el código fuente del paquete local mientras el SDK esté en beta:

pnpm --dir packages/rivya-sdk typecheck

El código de la aplicación debe mantener la clave secreta de API en el servidor:

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

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

No coloques claves secretas de API en bundles del navegador, localStorage, eventos de analítica, capturas de pantalla ni tickets compartidos.

Listar modelos

models.list es público y no requiere una clave de API:

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

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

Crear una generación

Usa generations.create para generar imágenes, video o audio de forma asíncrona:

const generation = await rivya.generations.create(
  {
    model: "z-image",
    prompt: "Una imagen editorial limpia de producto sobre un fondo suave de estudio",
    client_request_id: "order-123-preview"
  },
  {
    idempotencyKey: "order-123-preview"
  }
);

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

Después, consulta el estado con generations.retrieve:

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

Usa Idempotency-Key para solicitudes de escritura en producción. El SDK lo expone como idempotencyKey.

Subir archivos

Usa files.upload para imágenes, videos o audios de referencia:

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

Usa files.retrieve para volver a leer los metadatos del archivo subido:

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

Cuando uses un archivo en una generación, pasa los campos públicos devueltos mediante params.referenceMediaItems:

await rivya.generations.create({
  model: "nano-banana-2",
  prompt: "Rediseña esta foto de producto para una página limpia de catálogo editorial",
  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
      }
    ]
  }
});

Consultar créditos

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

Gestionar webhooks

Crea un endpoint de 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);

signing_secret solo se devuelve después de llamadas de creación o rotación. Guárdalo en tu servidor.

Otros helpers de 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 las firmas de entrega antes de confiar en los payloads de 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");
}

El helper del SDK usa el mismo contrato HMAC-SHA256 documentado en API Webhooks.

Chat

Usa chat.completions.create para un turno de Chat API sin streaming:

const completion = await rivya.chat.completions.create(
  {
    model: "gpt-5-2-chat",
    message: "Escribe un plan de lanzamiento conciso para una nueva campaña de imágenes de producto",
    client_request_id: "chat-001"
  },
  {
    idempotencyKey: "chat-001"
  }
);

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

Continúa con el session_id devuelto:

await rivya.chat.completions.create({
  model: "gpt-5-2-chat",
  session_id: completion.session_id,
  message: "Ahora conviértelo en una checklist de ejecución de 5 pasos."
});

Lee sesiones creadas por API:

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

Usa chat.completions.stream para consumir Server-Sent Events como iterador asíncrono:

const stream = await rivya.chat.completions.stream(
  {
    model: "gpt-5-2-chat",
    message: "Escribe un plan de lanzamiento conciso para una nueva campaña de imágenes de producto",
    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 solo sirve para mostrar incrementos. El resultado confirmado está disponible después de message.completed y se puede leer más tarde con chat.sessions.retrieve.

Errores

El SDK lanza RivyaAPIError para respuestas de Public API que no sean 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 incluye el estado HTTP, el código de error público, el mensaje, el request id cuando está disponible y un subconjunto seguro de headers de respuesta.

Validación

Ejecuta las comprobaciones del SDK antes de considerar completado un cambio:

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

pnpm sdk:check incluye una comprobación estática del contrato y una comprobación runtime sin red para parsing de errores, headers de error seguros, headers de idempotencia, autenticación Bearer, listado público de modelos, parsing SSE de streaming de Chat, eventos de error de streaming de Chat y verificación de firmas de webhook.

SDK TypeScript de Rivya