Käytä Rivyan TypeScript SDK:n beetaversiota julkisen API v1:n mallien, generointien, tiedostojen, krediittien, webhookien ja Chatin kutsumiseen, myös SSE-suoratoistoon.

Rivya tarjoaa TypeScript SDK:n beetaversion palvelinpuolen julkisiin API-integraatioihin.

SDK on kevyt asiakas Rivyan julkiselle API v1:lle. Alemman tason sopimus on edelleen OpenAPI- ja skeemasopimus, ja SDK-menetelmien täytyy pysyä sen mukaisina.

SDK dokumentoi toteutetun asiakkaan toiminnan. Pyynnöt edellyttävät silti, että julkinen API on otettu käyttöön kyseisessä ympäristössä, käytössä on kelvollinen tiliavain ja mallin ajantasainen API-tila sallii pyydetyn toiminnon.

Tila

Pakettia ylläpidetään tällä hetkellä tässä repossa yksityisenä betana. Sitä ei julkaista npm:ään ennen kuin paketin nimi, metadata, muutosloki ja julkaisuprosessi on nimenomaisesti hyväksytty.

SDK tukee:

mallien listausta
asynkronisen generoinnin luontia ja hakemista
Files API -latausta ja hakemista
krediittisaldon hakemista
webhook-endpointtien hallintaa, testitoimituksia, tapahtumien listausta, toimitusten listausta ja salaisuuden kierrätystä
webhook-allekirjoituksen vahvistusta
ei-streamaavia ja streamaavia Chat completions -kutsuja sekä API:n luomia chat-istuntoja

Chat-streamaus on saatavilla tässä yksityisessä betassa palvelinpuolen SSE-jäsennyksen kautta. Pidä salaiset API-avaimet palvelimellasi.

Asenna tässä repossa

Käytä paikallista pakettilähdettä, kun SDK on betassa:

pnpm --dir packages/rivya-sdk typecheck

Sovelluskoodin tulee pitää salainen API-avain palvelimella:

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

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

Älä sijoita salaisia API-avaimia selainpaketteihin, localStorageen, analytiikkatapahtumiin, kuvakaappauksiin tai jaettuihin tiketteihin.

Listaa mallit

models.list on julkinen eikä vaadi API-avainta:

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

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

Luo generointi

Käytä generations.create-metodia asynkroniseen kuva-, video- tai audiogenerointiin:

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

Pollaa sitten generations.retrieve-metodilla:

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

Käytä Idempotency-Key-headeria tuotannon kirjoituspyynnöissä. SDK altistaa sen nimellä idempotencyKey.

Lataa tiedostoja

Käytä files.upload-metodia referenssikuville, videoille tai audiolle:

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

Käytä files.retrieve-metodia ladatun metadatan lukemiseen uudelleen:

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

Kun käytät tiedostoa generoinnissa, anna palautetut julkiset kentät params.referenceMediaItems-rakenteen kautta:

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

Jokainen Image5- tai Grok Imagine Image 2.0 -referenssikuva vaatii alkuperäisen malliin sidotun latausvastauksen width-, height-, size_bytes- ja image_dimensions_token-arvot. Myöhempi files.retrieve-kutsu voi palauttaa tokenin arvona null; lataa lähdekuva uudelleen sen sijaan, että arvaisit MIME-tyypin, mitat tai tavukoon. Layer Decomposition noudattaa lisäksi yhden kuvan geometriarajojaan; Grok Image 2 hyväksyy tavalliseen kuvankäsittelyyn 1–5 allekirjoitettua JPEG-, PNG- tai WebP-referenssiä.

Käytä Video8-referenssivideolle alkuperäisen malliin sidotun latausvastauksen video_width-, video_height-, frames_per_second-, video_bitrate_mbps-, video_file_size_bytes- ja video_metadata_token-arvoja nimillä width, height, framesPerSecond, videoBitrateMbps, sizeBytes ja videoMetadataToken. Säilytä durationSeconds ja durationToken erillisenä allekirjoitettuna kestotodisteena. Jos jompikumpi token puuttuu myöhemmästä files.retrieve-vastauksesta, lataa lähdevideo uudelleen.

Wan 3.0 käyttää samaa SDK-kenttien vastaavuutta toisensa poissulkevissa text-, frames- ja reference-tiloissa. Lataa jokainen referenssi arvolla model: "wan-3-0-video"; kuvat vaativat allekirjoitetut kuvakentät, videot sekä allekirjoitetun keston että videometatiedot ja audio alkuperäiset mime_type-, size_bytes-, duration_seconds- ja duration_token-arvot. Aseta params-objektiin seedance_scene, variant, resolution, aspect_ratio, duration, audio ja valinnainen seed. Älykäs kesto on -1, varaa 30 sekuntia eikä sitä voi yhdistää referenssivideoon; tiedostosta videoksi- ja linkistä videoksi -pikareitit eivät ole käytettävissä.

Tarkista krediitit

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

Hallitse webhookeja

Kun webhook-käyttöoikeus on otettu käyttöön kyseisessä ympäristössä ja tilillä, luo webhook-päätepiste:

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 palautetaan vain luonti- tai kierrätyskutsuissa. Tallenna se palvelimellesi.

Muut webhook-apurit:

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

Vahvista toimitusten allekirjoitukset ennen webhook-payloadien luottamista:

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-apuri käyttää samaa HMAC-SHA256-sopimusta, joka on dokumentoitu sivulla API-webhookit.

Chat

Käytä chat.completions.create-metodia yhteen ei-streamaavaan Chat API -vuoroon:

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

Jatka palautetulla session_id-arvolla:

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

Lue API:n luomia istuntoja:

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

Käytä chat.completions.stream-metodia Server-Sent Events -tapahtumien kuluttamiseen asynkronisena iteraattorina:

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 on vain näyttämistä varten. Tallennettu tulos on saatavilla message.completed-tapahtuman jälkeen ja voidaan lukea myöhemmin chat.sessions.retrieve-metodilla.

Virheet

SDK heittää RivyaAPIError-virheen julkisen API:n vastauksille, joiden tila ei ole 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 sisältää HTTP-statuksen, julkisen virhekoodin, viestin, pyynnön tunnuksen silloin kun se on saatavilla sekä turvallisen osajoukon vastausheadereista.

Validointi

Suorita SDK-tarkistukset ennen kuin pidät muutosta valmiina:

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

pnpm sdk:check sisältää staattisen sopimustarkistuksen ja verkkoa käyttämättömän ajonaikaisen tarkistuksen virheiden jäsennykselle, turvallisille virheheadereille, idempotency-headereille, Bearer-todennukselle, julkiselle mallilistaukselle, Chat-streamauksen SSE-jäsennykselle, Chat-streamauksen virhetapahtumille ja webhook-allekirjoituksen vahvistukselle.

Rivya TypeScript SDK