↓
Rivya AI ドキュメント

Rivya TypeScript SDK ガイド

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

2026/08/26 最終レビュー

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-lite",
  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-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 と Grok Imagine Image 2.0 の参照画像はすべて、元のモデル紐付きアップロード応答に含まれる width、height、size_bytes、image_dimensions_token を必要とします。後の files.retrieve で token が null の場合は、MIME type、寸法、バイトサイズを推測せず、元画像を再アップロードしてください。Layer Decomposition ではさらに、1 枚の画像に対する幾何制限も適用され、Grok Image 2 の標準画像編集では署名済み JPEG、PNG、WebP 参照画像を 1～5 枚使用できます。

Video8 の参照動画では、元のモデル紐付きアップロード応答に含まれる video_width、video_height、frames_per_second、video_bitrate_mbps、video_file_size_bytes、video_metadata_token を、それぞれ width、height、framesPerSecond、videoBitrateMbps、sizeBytes、videoMetadataToken として使います。durationSeconds と durationToken は、独立した署名済みの長さ証明として保持してください。後の files.retrieve でどちらかの token が欠けている場合は、元動画を再アップロードしてください。

Wan 3.0 の相互排他的な text、frames、reference の各シーンでは、同じ SDK フィールドマッピングを使います。各参照ファイルは model: "wan-3-0-video" を指定してアップロードしてください。画像には署名済み画像フィールド、動画には署名済み長さと動画メタデータの両方、音声には元の mime_type、size_bytes、duration_seconds、duration_token が必要です。params 内で seedance_scene、variant、resolution、aspect_ratio、duration、audio、任意の seed を設定します。インテリジェント長さは -1 で、30 秒分を予約し、参照動画とは併用できません。ファイルから動画、リンクから動画へのショートカットは引き続き利用できません。

クレジットを確認する

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 チェックが含まれます。

関連ページ

OpenAPI とスキーマ契約

Rivya API v1 のスキーマソース、互換性ルール、公開フィールド、読み取り専用 OpenAPI JSON 契約を確認します。

API モデル

Rivya API モデルを一覧し、モデル ID、カテゴリ、プロンプト上限、参照メディア、準備状態、Files API 依存関係を理解します。

目次

ステータス
このリポジトリでインストールする
モデル一覧
生成を作成する
ファイルをアップロードする
クレジットを確認する
Webhooks を管理する
Chat
エラー
検証
関連ページ