ใช้ Rivya TypeScript SDK beta เพื่อเรียก Public API v1 สำหรับ models, generations, files, credits, webhooks และ Chat รวมถึง SSE streaming

Rivya มี TypeScript SDK beta สำหรับ server-side Public API integrations

SDK เป็น client บาง ๆ บน Rivya Public API v1 contract ระดับล่างยังคงเป็น OpenAPI และ Schema Contract และ SDK methods ต้องสอดคล้องกับ schema นั้น

สถานะ

ตอนนี้ package นี้ดูแลอยู่ภายใน repository นี้ในฐานะ private beta ยังไม่ publish ไปยัง npm จนกว่า package name, metadata, changelog และ release process จะได้รับการอนุมัติชัดเจน

SDK รองรับ:

รายการโมเดล
asynchronous generation create และ retrieve
Files API upload และ retrieve
ดึงยอดเครดิต
การจัดการ webhook endpoint, test deliveries, event listing, delivery listing และ secret rotation
การตรวจ webhook signature
non-streaming และ streaming Chat completions รวมถึง chat sessions ที่สร้างผ่าน API

Chat streaming พร้อมใช้ใน private beta นี้ผ่าน server-side SSE parsing เก็บ secret API keys ไว้บน server ของคุณเท่านั้น

ติดตั้งใน Repo นี้

ใช้ local package source ระหว่างที่ SDK อยู่ใน beta:

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.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

ใช้ generations.create สำหรับ asynchronous image, video หรือ audio generation:

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

จากนั้น poll ด้วย generations.retrieve:

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

ใช้ Idempotency-Key สำหรับ production write requests SDK เปิดค่าเดียวกันนี้ในชื่อ idempotencyKey

อัปโหลดไฟล์

ใช้ files.upload สำหรับ reference images, videos หรือ audio:

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

เมื่อใช้ไฟล์ใน generation ให้ส่ง 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 });

ตรวจ delivery signatures ก่อนเชื่อถือ webhook payloads:

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 ใช้ HMAC-SHA256 contract ชุดเดียวกับที่บันทึกไว้ใน API Webhooks

การใช้งาน Chat

ใช้ chat.completions.create สำหรับ Chat API turn แบบ non-streaming หนึ่งรอบ:

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."
});

อ่าน sessions ที่สร้างผ่าน API:

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

ใช้ chat.completions.stream เพื่อ consume Server-Sent Events เป็น async iterator:

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 ใช้สำหรับแสดงผลเท่านั้น ผลลัพธ์ที่ commit แล้วจะพร้อมหลัง message.completed และอ่านภายหลังได้ด้วย chat.sessions.retrieve

ข้อผิดพลาด

SDK จะ throw RivyaAPIError สำหรับ Public API responses ที่ไม่ใช่ 2xx:

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

การตรวจสอบ

รัน SDK checks ก่อนถือว่า change เสร็จ:

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 สำหรับนักพัฒนา