使用 Rivya TypeScript SDK beta 呼叫 Public API v1，涵蓋 models、generations、files、credits、webhooks，以及包含 SSE 串流的 Chat。

Rivya 提供 TypeScript SDK beta，供伺服器端 Public API 整合使用。

SDK 是 Rivya Public API v1 上的一層薄 client。較底層合約仍以 OpenAPI 與 Schema 合約為準，SDK methods 必須與該 schema 保持一致。

狀態

這個 package 目前以 private beta 形式維護在此 repository 內。除非 package name、metadata、changelog 和 release process 明確核准，否則不會發佈到 npm。

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 保留在你的伺服器上。

在此 Repo 中安裝

SDK 處於 beta 時，請使用本機 package source：

pnpm --dir packages/rivya-sdk typecheck

Application code 應該將 secret API key 保留在伺服器端：

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

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

不要將 secret API keys 放入 browser bundles、localStorage、analytics events、截圖或共享 tickets。

列出模型

models.list 是公開的，不需要 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);
}

建立生成任務

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

production write requests 請使用 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 再次讀取已上傳 metadata：

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 只會在 create 或 rotate calls 後回傳。請將它儲存在你的伺服器上。

其他 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 payloads 前，請先驗證 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 合約。

Chat

使用 chat.completions.create 送出一個非串流 Chat API 回合：

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

使用 chat.completions.stream 以 async iterator 消費 Server-Sent Events：

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 讀取。

錯誤

對於非 2xx Public API responses，SDK 會拋出 RivyaAPIError：

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、公開 error code、message、可用時的 request id，以及安全的 response-header subset。

驗證

將變更視為完成前，請先執行 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

狀態