Rivya TypeScript SDK beta を使って、モデル、生成、ファイル、クレジット、webhooks、SSE ストリーミングを含む Chat 向けに Public API v1 を呼び出します。

Rivya は、サーバー側 Public API 統合向けに TypeScript SDK beta を提供しています。

SDK は Rivya Public API v1 の薄いクライアントです。低レベルの契約は引き続き OpenAPI とスキーマ契約であり、SDK のメソッドはそのスキーマと整合している必要があります。

ステータス

この package は現在、このリポジトリ内で private beta として管理されています。パッケージ名、metadata、changelog、リリースプロセスが明示的に承認されるまで、npm には公開されません。

SDK は次に対応しています。

モデル一覧
非同期生成の作成と取得
Files API のアップロードと取得
クレジット残高の取得
webhook endpoint 管理、テスト delivery、イベント一覧、delivery 一覧、secret ローテーション
webhook 署名検証
非ストリーミングおよびストリーミングの Chat completions、API 作成チャットセッション

Chat streaming は、この private beta ではサーバー側 SSE 解析を通じて利用できます。secret API キーはサーバーに保管してください。

このリポジトリでインストールする

SDK が beta の間は、ローカル package source を使います。

pnpm --dir packages/rivya-sdk typecheck

アプリケーションコードでは、secret API キーをサーバーに保管してください。

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

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

secret API キーをブラウザ bundle、localStorage、analytics イベント、スクリーンショット、共有チケットに置かないでください。

モデル一覧

models.list は公開されており、API キーを必要としません。

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

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

生成を作成する

非同期の画像、動画、音声生成には 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 でポーリングします。

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

本番の書き込みリクエストでは Idempotency-Key を使ってください。SDK ではこれを idempotencyKey として公開しています。

ファイルをアップロードする

参照画像、動画、音声には 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);

アップロード済みメタデータを再度読み取るには files.retrieve を使います。

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

生成でファイルを使う場合は、返された公開フィールドを 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
      }
    ]
  }
});

クレジットを確認する

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 は作成またはローテーション呼び出しの直後にのみ返されます。サーバーに保存してください。

その他の webhook helper:

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 署名を検証してください。

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 契約を使います。

Chat

非ストリーミングの Chat API ターン 1 件には 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 作成セッションを読み取ります。

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 は表示専用です。確定済みの結果は message.completed の後に利用でき、後から chat.sessions.retrieve で読み取れます。

エラー

SDK は、2xx ではない Public API 応答に対して 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、公開エラーコード、message、利用可能な場合の request id、安全な response-header サブセットが含まれます。

検証

変更を完了扱いにする前に、SDK チェックを実行してください。

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

pnpm sdk:check には、静的契約チェックと、エラー解析、安全なエラー header、冪等性 header、Bearer auth、公開モデル一覧、Chat streaming SSE parsing、Chat streaming error events、webhook 署名検証を対象とするネットワーク不要の runtime チェックが含まれます。

Rivya TypeScript SDK ガイド