SSE streaming dahil Chat, modeller, generation işleri, dosyalar, krediler ve webhook'lar için Public API v1 çağrılarında Rivya TypeScript SDK beta'yı kullanın.

Rivya, sunucu tarafı Public API entegrasyonları için TypeScript SDK beta sağlar.

SDK, Rivya Public API v1 üzerinde ince bir client katmanıdır. Daha düşük seviyeli sözleşme OpenAPI ve Şema Sözleşmesi olarak kalır ve SDK method'ları bu şemayla uyumlu kalmalıdır.

Durum

Package şu anda bu repository içinde private beta olarak tutuluyor. Package adı, metadata, changelog ve release süreci açıkça onaylanmadan npm'e yayınlanmaz.

SDK şunları destekler:

model listeleme
asenkron generation oluşturma ve alma
Files API yükleme ve alma
kredi bakiyesi alma
webhook endpoint yönetimi, test teslimatları, event listeleme, delivery listeleme ve secret rotation
webhook imza doğrulama
non-streaming ve streaming Chat completions, ayrıca API tarafından oluşturulan chat sessions

Chat streaming bu private beta içinde sunucu tarafı SSE parsing üzerinden kullanılabilir. Secret API anahtarlarını sunucunuzda tutun.

Bu Repo İçinde Kurulum

SDK beta aşamasındayken local package source kullanın:

pnpm --dir packages/rivya-sdk typecheck

Application kodu secret API anahtarını sunucuda tutmalıdır:

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

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

Secret API anahtarlarını browser bundle'larına, localStorage'a, analytics event'lerine, ekran görüntülerine veya paylaşılan destek kayıtlarına koymayın.

Modelleri Listeleme

models.list public'tir ve API anahtarı gerektirmez:

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

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

Oluşturma İşi Başlatma

Asenkron görüntü, video veya ses generation için generations.create kullanın:

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

Sonra generations.retrieve ile poll edin:

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

Production write request'leri için Idempotency-Key kullanın. SDK bunu idempotencyKey olarak sunar.

Dosya Yükleme

Referans görüntüleri, videoları veya sesi yüklemek için files.upload kullanın:

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

Yüklenen metadata bilgisini tekrar okumak için files.retrieve kullanın:

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

Bir generation içinde dosya kullanırken dönen public alanları params.referenceMediaItems üzerinden gönderin:

await rivya.generations.create({
  model: "nano-banana-2",
  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
      }
    ]
  }
});

Kredileri Kontrol Etme

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

Webhooks Yönetimi

Webhook endpoint oluşturun:

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 yalnızca create veya rotate çağrılarından sonra döner. Bunu sunucunuzda saklayın.

Diğer webhook helper'ları:

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

Webhook payload'larına güvenmeden önce delivery imzalarını doğrulayın:

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

SDK helper'ı API Webhooks içinde belgelenen aynı HMAC-SHA256 sözleşmesini kullanır.

Chat

Tek bir non-streaming Chat API turu için chat.completions.create kullanın:

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

Dönen session_id ile devam edin:

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

API tarafından oluşturulan session'ları okuyun:

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

Server-Sent Events'i async iterator olarak tüketmek için chat.completions.stream kullanın:

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 yalnızca gösterim içindir. Committed sonuç message.completed sonrasında kullanılabilir ve daha sonra chat.sessions.retrieve ile okunabilir.

Hatalar

SDK, 2xx olmayan Public API response'ları için RivyaAPIError fırlatır:

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, HTTP status, public hata kodu, message, varsa request id ve güvenli response-header alt kümesini içerir.

Doğrulama

Bir değişikliği tamamlanmış saymadan önce SDK kontrollerini çalıştırın:

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

pnpm sdk:check; error parsing, safe error headers, idempotency headers, Bearer auth, public model listing, Chat streaming SSE parsing, Chat streaming error events ve webhook signature verification için statik sözleşme kontrolü ve no-network runtime kontrolü içerir.

Rivya TypeScript SDK