SDK TypeScript του Rivya

Το Rivya παρέχει ένα SDK TypeScript σε δοκιμαστική έκδοση για ενσωματώσεις του δημόσιου API στην πλευρά του διακομιστή.

Το SDK λειτουργεί ως ελαφρύς πελάτης πάνω από το δημόσιο API v1 του Rivya. Η σύμβαση χαμηλότερου επιπέδου παραμένει η σύμβαση OpenAPI και σχήματος, και οι μέθοδοι του SDK πρέπει να παραμένουν ευθυγραμμισμένες με αυτό το σχήμα.

Το SDK τεκμηριώνει την υλοποιημένη συμπεριφορά του πελάτη. Τα αιτήματα εξακολουθούν να απαιτούν ενεργοποιημένο δημόσιο API για την εγκατάσταση, έγκυρο κλειδί λογαριασμού και μοντέλο του οποίου η ενεργή κατάσταση API επιτρέπει τη ζητούμενη ενέργεια.

Κατάσταση

Το πακέτο συντηρείται προς το παρόν μέσα σε αυτό το αποθετήριο ως ιδιωτική δοκιμαστική έκδοση. Δεν δημοσιεύεται στο npm μέχρι να εγκριθούν ρητά το όνομα του πακέτου, τα μεταδεδομένα, το αρχείο αλλαγών και η διαδικασία έκδοσης.

Το SDK υποστηρίζει:

• λίστα μοντέλων

• δημιουργία και ανάκτηση ασύγχρονων εργασιών δημιουργίας

• μεταφόρτωση και ανάκτηση μέσω του API αρχείων

• ανάκτηση υπολοίπου πιστωτικών μονάδων

• διαχείριση τελικού σημείου webhook, δοκιμαστικών παραδόσεων, λίστας συμβάντων, λίστας παραδόσεων και εναλλαγής μυστικού

• επαλήθευση υπογραφής webhook

• πλήρεις και τμηματικά μεταδιδόμενες αποκρίσεις συνομιλίας, καθώς και συνεδρίες συνομιλίας που δημιουργούνται μέσω API

Η τμηματική μετάδοση συνομιλίας είναι διαθέσιμη σε αυτή την ιδιωτική έκδοση beta μέσω ανάλυσης 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, τις διαστάσεις ή το μέγεθος σε byte. Το 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. Ορίστε τα seedance_scene, variant, resolution, aspect_ratio, duration, audio και το προαιρετικό seed μέσα στο params. Η έξυπνη διάρκεια είναι -1, δεσμεύει 30 δευτερόλεπτα και δεν συνδυάζεται με βίντεο αναφοράς· οι συντομεύσεις μετατροπής αρχείου σε βίντεο και συνδέσμου σε βίντεο παραμένουν μη διαθέσιμες.

Έλεγχος πιστωτικών μονάδων

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

Διαχείριση webhooks

Όταν η πρόσβαση στα webhooks είναι ενεργοποιημένη για την εγκατάσταση και τον λογαριασμό, δημιουργήστε ένα τελικό σημείο webhook:

const endpoint = await rivya.webhooks.create({
  name: "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 για webhooks.

Συνομιλία

Χρησιμοποιήστε το chat.completions.create για έναν γύρο του 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 για να καταναλώσετε Server-Sent Events ως ασύγχρονο επαναλήπτη:

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 για αποκρίσεις του δημόσιου 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 της συνομιλίας, συμβάντα σφάλματος στη ροή συνομιλίας και επαλήθευση υπογραφής webhook.

Σχετικές σελίδες

• Σύμβαση OpenAPI και σχήματος

• Γρήγορη εκκίνηση API

• API αρχείων

• API για webhooks

• API συνομιλίας