Gunakan Rivya TypeScript SDK beta untuk memanggil Public API v1 bagi model, penjanaan, fail, kredit, webhook, dan sembang termasuk penstriman SSE.

Rivya menyediakan TypeScript SDK beta untuk integrasi Public API pada bahagian pelayan.

SDK ini ialah klien ringkas di atas Rivya Public API v1. Kontrak peringkat bawah kekal sebagai Kontrak OpenAPI dan Skema, dan kaedah SDK mesti terus sejajar dengan skema tersebut.

SDK ini mendokumenkan tingkah laku klien yang telah dilaksanakan. Permintaan tetap memerlukan API Awam diaktifkan untuk persekitaran pelaksanaan, kunci akaun yang sah dan model yang status API aktifnya membenarkan operasi berkenaan.

Status

Pakej ini kini diselenggara dalam repositori ini sebagai beta persendirian. Ia tidak diterbitkan ke npm sehingga nama pakej, metadata, log perubahan, dan proses keluaran diluluskan secara jelas.

SDK menyokong:

penyenaraian model
penciptaan dan pengambilan penjanaan tak segerak
muat naik dan pengambilan melalui API Fail
pengambilan baki kredit
pengurusan titik akhir webhook, penghantaran ujian, penyenaraian peristiwa, penyenaraian penghantaran, dan putaran rahsia
pengesahan tandatangan webhook
pelengkapan sembang tanpa penstriman dan dengan penstriman, serta sesi sembang yang dicipta melalui API

Penstriman sembang tersedia dalam beta persendirian ini melalui penghuraian SSE pada bahagian pelayan. Simpan kunci API rahsia pada pelayan anda.

Pasang dalam repositori ini

Gunakan sumber pakej setempat semasa SDK masih dalam beta:

pnpm --dir packages/rivya-sdk typecheck

Kod aplikasi perlu menyimpan kunci API rahsia pada pelayan:

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

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

Jangan letakkan kunci API rahsia dalam berkas pelayar, localStorage, peristiwa analitik, tangkapan skrin, atau tiket yang dikongsi.

Senaraikan model

models.list bersifat awam dan tidak memerlukan kunci API:

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

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

Cipta penjanaan

Gunakan generations.create untuk penjanaan imej, video, atau audio tak segerak:

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

Kemudian buat semakan berkala dengan generations.retrieve:

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

Gunakan Idempotency-Key untuk permintaan tulis produksi. SDK mendedahkannya sebagai idempotencyKey.

Muat naik fail

Gunakan files.upload untuk imej, video, atau audio rujukan:

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

Gunakan files.retrieve untuk membaca semula metadata yang dimuat naik:

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

Apabila menggunakan fail dalam penjanaan, masukkan medan awam yang dikembalikan melalui 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
      }
    ]
  }
});

Setiap imej rujukan Image5 dan Grok Imagine Image 2.0 memerlukan width, height, size_bytes, dan image_dimensions_token daripada respons muat naik asalnya yang terikat pada model. Panggilan files.retrieve kemudian mungkin mengembalikan token sebagai null; muat naik semula imej sumber dan jangan meneka jenis MIME, dimensi, atau saiz bait. Layer Decomposition turut menguatkuasakan had geometri satu imej; Grok Image 2 menerima 1–5 rujukan JPEG, PNG atau WebP bertandatangan untuk penyuntingan imej standard.

Untuk video rujukan Video8, gunakan video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, dan video_metadata_token daripada respons muat naik asal yang terikat pada model sebagai width, height, framesPerSecond, videoBitrateMbps, sizeBytes, dan videoMetadataToken. Kekalkan durationSeconds dan durationToken sebagai bukti tempoh bertandatangan yang berasingan. Jika salah satu token tiada dalam files.retrieve kemudian, muat naik semula video sumber.

Wan 3.0 menggunakan pemetaan medan SDK yang sama merentas scene text, frames, dan reference yang saling eksklusif. Muat naik setiap rujukan dengan model: "wan-3-0-video"; imej memerlukan medan imej bertandatangan, video memerlukan tempoh dan metadata video bertandatangan, manakala audio memerlukan mime_type, size_bytes, duration_seconds, dan duration_token asal. Tetapkan seedance_scene, variant, resolution, aspect_ratio, duration, audio, dan seed pilihan di dalam params. Tempoh pintar ialah -1, menempah 30 saat, dan tidak boleh digabungkan dengan video rujukan; pintasan fail kepada video dan pautan kepada video kekal tidak tersedia.

Semak kredit

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

Urus webhook

Apabila akses webhook diaktifkan untuk persekitaran pelaksanaan dan akaun, cipta titik akhir webhook:

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 hanya dikembalikan selepas panggilan cipta atau putar. Simpannya pada pelayan anda.

Pembantu webhook lain:

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

Sahkan tandatangan penghantaran sebelum mempercayai muatan webhook:

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

Pembantu SDK menggunakan kontrak HMAC-SHA256 yang sama seperti yang didokumenkan dalam API Webhooks.

Sembang

Gunakan chat.completions.create untuk satu giliran Chat API tanpa penstriman:

const completion = await rivya.chat.completions.create(
  {
    model: "claude-sonnet-5-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);

Teruskan dengan session_id yang dikembalikan:

await rivya.chat.completions.create({
  model: "claude-sonnet-5-chat",
  session_id: completion.session_id,
  message: "Now turn that into a 5-step execution checklist."
});

Baca sesi yang dicipta melalui API:

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

Gunakan chat.completions.stream untuk menggunakan Server-Sent Events sebagai pengulang tak segerak:

const stream = await rivya.chat.completions.stream(
  {
    model: "claude-sonnet-5-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 hanya untuk paparan. Hasil yang dimuktamadkan tersedia selepas message.completed, dan boleh dibaca kemudian dengan chat.sessions.retrieve.

Ralat

SDK melontarkan RivyaAPIError untuk respons Public API bukan 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 merangkumi status HTTP, kod ralat awam, mesej, ID permintaan apabila tersedia, dan subset pengepala respons yang selamat.

Pengesahan

Jalankan semakan SDK sebelum menganggap perubahan selesai:

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

pnpm sdk:check merangkumi semakan kontrak statik dan semakan masa jalan tanpa rangkaian untuk penghuraian ralat, pengepala ralat selamat, pengepala idempotensi, pengesahan Bearer, penyenaraian model awam, penghuraian SSE penstriman sembang, peristiwa ralat penstriman sembang, dan pengesahan tandatangan webhook.

Rivya TypeScript SDK