SSE akışlı dahil Chat, modeller, üretim 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 müşteri 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.

SDK uygulanmış istemci davranışını belgeler. İstekler Public API'nin dağıtımda etkin olmasını, geçerli hesap anahtarını ve canlı API durumu işlemi destekleyen modeli gerektirir.

Durum

Package şu anda bu repository içinde özel 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 üretim oluşturma ve alma
Dosyalar API yükleme ve alma
kredi bakiyesi alma
webhook uç nokta yönetimi, test teslimatları, olay listeleme, teslimat listeleme ve secret rotation
webhook imza doğrulama
non-akışlı ve akışlı Chat completions, ayrıca API tarafından oluşturulan sohbet sessions

Chat akışlı bu özel beta içinde sunucu tarafı SSE ayrıştırma üzerinden kullanılabilir. Secret API anahtarlarını sunucunuzda tutun.

Bu Repo İçinde Kurulum

SDK beta aşamasındayken local package kaynak 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 olay'lerine, ekran görüntülerine veya paylaşılan destek kayıtlarına koymayın.

Modelleri Listeleme

models.list herkese açık'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 üretim 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 sorgulamak edin:

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

Üretim write istek'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-lite",
  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 üretim içinde dosya kullanırken dönen herkese açık alanları params.referenceMediaItems üzerinden gönderin:

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

Image5 veya Grok Imagine Image 2.0 için kullanılan her referans görüntüsü, özgün modele bağlı yükleme yanıtındaki width, height, size_bytes ve image_dimensions_token değerlerini gerektirir. Daha sonraki bir files.retrieve çağrısı token'ı null olarak döndürebilir; MIME türünü, boyutları veya bayt boyutunu tahmin etmek yerine kaynak görüntüyü yeniden yükleyin. Katman Decomposition ayrıca tek görüntüye ilişkin geometri limitlerini uygular; Grok Image 2, standart görüntü düzenleme için bir ila beş imzalı JPEG, PNG veya WebP referansını kabul eder.

Bir Video8 referans videosu için özgün modele bağlı yükleme yanıtındaki video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes ve video_metadata_token değerlerini sırasıyla width, height, framesPerSecond, videoBitrateMbps, sizeBytes ve videoMetadataToken olarak kullanın. durationSeconds ile durationToken değerlerini ayrı bir imzalı süre kanıtı olarak saklayın. Daha sonraki bir files.retrieve çağrısında iki token'dan biri eksikse kaynak videoyu yeniden yükleyin.

Wan 3.0, birbirini dışlayan text, frames ve reference sahnelerinde aynı SDK alan eşlemesini kullanır. Her referansı model: "wan-3-0-video" ile yükleyin; görüntüler imzalı görüntü alanlarını, videolar hem imzalı süreyi hem de video metadata bilgilerini, ses ise özgün mime_type, size_bytes, duration_seconds ve duration_token değerlerini gerektirir. params içinde seedance_scene, variant, resolution, aspect_ratio, duration, audio ve isteğe bağlı seed değerini ayarlayın. Akıllı süre -1 değeridir, 30 saniye ayırır ve referans videosuyla kullanılamaz; dosyadan videoya ve bağlantıdan videoya kısayollar kullanılamaz.

Kredileri Kontrol Etme

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

Webhooks Yönetimi

Webhook erişimi dağıtım ve hesap için etkin olduğunda bir webhook uç nokta'i 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 oluşturmak 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 teslimat 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-akışlı Chat API turu için chat.completions.create kullanın:

const completion = await rivya.chat.completions.create(
  {
    model: "claude-sonnet-5-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: "claude-sonnet-5-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: "claude-sonnet-5-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 yanıt'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 durum, herkese açık hata kodu, mesaj, varsa istek id ve güvenli yanıt-başlık 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; hata ayrıştırma, güvenli hata başlıklar, idempotency başlıklar, Bearer auth, herkese açık model listeleme, Chat akışlı SSE ayrıştırma, Chat akışlı hata olaylar ve webhook imza doğrulama için statik sözleşme kontrolü ve no-network çalışma zamanı kontrolü içerir.

Rivya TypeScript SDK