Використовуйте закриту бета-версію Rivya TypeScript SDK для викликів моделей, генерацій, файлів, кредитів, вебхуків і Chat через Public API v1, зокрема через SSE.

Rivya надає закриту бета-версію TypeScript SDK для серверних інтеграцій із Public API.

SDK є тонким клієнтом над Rivya Public API v1. Нижчорівневим контрактом лишається OpenAPI і контракт схеми, а методи SDK мають залишатися узгодженими з цією схемою.

SDK описує реалізовану поведінку клієнта. Для запитів і далі потрібні ввімкнений Public API, чинний ключ акаунта й модель, актуальний API-статус якої дозволяє потрібну операцію.

Статус

Пакет наразі підтримується всередині цього репозиторію як приватна бета. Його не публікують у npm, доки назву пакета, метадані, журнал змін і процес релізу не буде явно затверджено.

SDK підтримує:

перегляд списку моделей
створення та отримання асинхронних генерацій
завантаження й отримання через Files API
отримання балансу кредитів
керування кінцевими точками webhook, тестові доставки, список подій, список доставок і ротацію секрету
перевірку webhook-підпису
відповіді Chat без потокового передавання і з ним, а також сесії чату, створені через API

Потокове передавання Chat доступне в цій приватній бета-версії через серверний парсер SSE. Тримайте секретні API-ключі на своєму сервері.

Встановлення в цьому репозиторії

Поки SDK перебуває в бета-версії, використовуйте локальне джерело пакета:

pnpm --dir packages/rivya-sdk typecheck

Код застосунку має зберігати секретний API-ключ на сервері:

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

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

Не розміщуйте секретні ключі API у браузерних збірках, localStorage, аналітичних подіях, знімках екрана або спільних зверненнях підтримки.

Перегляд моделей

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: "Чисте редакційне зображення товару на м'якому студійному тлі",
    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: "Зміни стиль цього фото товару для чистої редакційної сторінки каталогу",
  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 може повернути для токена null; у такому разі повторно завантажте вихідне зображення замість того, щоб вгадувати MIME-тип, розміри або розмір у байтах. Layer Decomposition додатково застосовує обмеження геометрії для одного зображення; Grok Image 2 приймає від одного до п'яти підписаних референс-зображень JPEG, PNG або WebP для стандартного редагування зображення.

Для референс-відео 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 бракує будь-якого токена, повторно завантажте вихідне відео.

Wan 3.0 використовує однакове зіставлення полів SDK у взаємовиключних режимах text, frames і reference. Завантажуйте кожен референс із 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 секунд і не поєднується з референс-відео; спрощені режими file-to-video і link-to-video залишаються недоступними.

Перевірка кредитів

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

Керування Webhooks

Коли доступ до вебхуків увімкнено для розгортання й акаунта, створіть кінцеву точку вебхука:

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:

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:

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 використовує той самий контракт HMAC-SHA256, що описаний у вебхуках API.

Chat

Використовуйте chat.completions.create для одного ходу Chat API без потокового передавання:

const completion = await rivya.chat.completions.create(
  {
    model: "claude-sonnet-5-chat",
    message: "Склади стислий план запуску нової кампанії із зображеннями товару",
    client_request_id: "chat-001"
  },
  {
    idempotencyKey: "chat-001"
  }
);

console.log(completion.session_id, completion.message.content);

Продовжуйте з поверненим session_id:

await rivya.chat.completions.create({
  model: "claude-sonnet-5-chat",
  session_id: completion.session_id,
  message: "Тепер перетвори його на список із п'яти кроків."
});

Читайте сесії, створені через API:

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

Використовуйте chat.completions.stream, щоб читати події SSE як асинхронний ітератор:

const stream = await rivya.chat.completions.stream(
  {
    model: "claude-sonnet-5-chat",
    message: "Склади стислий план запуску нової кампанії із зображеннями товару",
    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 викидає RivyaAPIError для відповідей Public API поза діапазоном 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, публічний код і текст помилки, ідентифікатор запиту за наявності та безпечну підмножину заголовків відповіді.

Валідація

Запустіть перевірки SDK, перш ніж вважати зміну завершеною:

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

pnpm sdk:check містить статичну та автономну перевірку контракту: розбір помилок, безпечні заголовки, ідемпотентність, автентифікацію Bearer, публічний список моделей, потоки SSE для Chat, помилки потокового передавання та перевірку підписів вебхуків.

Rivya TypeScript SDK