Rivya TypeScript SDK beta를 사용해 models, generations, files, credits, webhooks, SSE streaming을 포함한 Chat용 Public API v1을 호출하세요.

Rivya는 server-side Public API integrations를 위한 TypeScript SDK beta를 제공합니다.

SDK는 Rivya Public API v1 위의 얇은 client입니다. lower-level contract는 OpenAPI와 Schema Contract로 유지되며, SDK methods는 해당 schema와 계속 정렬되어야 합니다.

Status

현재 package는 이 repository 안에서 private beta로 유지됩니다. package name, metadata, changelog, release process가 명시적으로 승인되기 전까지 npm에 publish되지 않습니다.

SDK는 다음을 지원합니다.

model listing
asynchronous generation create and retrieve
Files API upload and retrieve
credit balance retrieval
webhook endpoint management, test deliveries, event listing, delivery listing, secret rotation
webhook signature verification
non-streaming 및 streaming Chat completions, API-created chat sessions

Chat streaming은 이 private beta에서 server-side SSE parsing을 통해 사용할 수 있습니다. secret API keys는 server에 보관하세요.

이 Repo에서 설치

SDK가 beta인 동안 local package source를 사용하세요.

pnpm --dir packages/rivya-sdk typecheck

Application code는 secret API key를 server에 보관해야 합니다.

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

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

secret API keys를 browser bundles, localStorage, analytics events, screenshots, shared tickets에 넣지 마세요.

Models 나열

models.list는 public이며 API key가 필요하지 않습니다.

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

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

Generation 만들기

비동기 image, video, audio generation에는 generations.create를 사용하세요.

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

그다음 generations.retrieve로 poll하세요.

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

production write requests에는 Idempotency-Key를 사용하세요. SDK는 이것을 idempotencyKey로 노출합니다.

Files 업로드

reference images, videos, audio에는 files.upload를 사용하세요.

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

업로드한 metadata를 다시 읽으려면 files.retrieve를 사용하세요.

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

generation에서 file을 사용할 때는 반환된 public fields를 params.referenceMediaItems로 전달하세요.

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

Credits 확인

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

Webhooks 관리

webhook endpoint 만들기:

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은 create 또는 rotate calls 후에만 반환됩니다. server에 저장하세요.

다른 webhook helpers:

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를 신뢰하기 전에 delivery signatures를 검증하세요.

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에 문서화된 동일한 HMAC-SHA256 contract를 사용합니다.

Chat

non-streaming Chat API turn 하나에는 chat.completions.create를 사용하세요.

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

반환된 session_id로 이어가세요.

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-created sessions 읽기:

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

Server-Sent Events를 async iterator로 소비하려면 chat.completions.stream을 사용하세요.

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는 display 전용입니다. committed result는 message.completed 이후 사용할 수 있으며, 나중에 chat.sessions.retrieve로 읽을 수 있습니다.

Errors

non-2xx Public API responses의 경우 SDK는 RivyaAPIError를 throw합니다.

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 error code, message, 사용 가능한 경우 request id, safe response-header subset이 포함됩니다.

Validation

change를 완료로 보기 전에 SDK checks를 실행하세요.

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

pnpm sdk:check에는 static contract check와 no-network runtime check가 포함되며, error parsing, safe error headers, idempotency headers, Bearer auth, public model listing, Chat streaming SSE parsing, Chat streaming error events, webhook signature verification을 다룹니다.

Rivya TypeScript SDK