Files API

Χρησιμοποιήστε POST /api/v1/files για να ανεβάσετε μέσα αναφοράς για μοντέλα που χρειάζονται εισόδους εικόνας, βίντεο ή ήχου.

Το Files API προορίζεται μόνο για εισόδους αναφοράς. Δεν δημιουργεί από μόνο του εργασίες generation. Μετά το ανέβασμα, περάστε το επιστρεφόμενο url και τα metadata στα params του μοντέλου, συνήθως μέσω params.referenceMediaItems.

Endpoint

POST https://rivya.ai/api/v1/files
GET https://rivya.ai/api/v1/files/{fileId}

Απαιτούμενα headers:

Authorization: Bearer rvya_sk_...
Content-Type: multipart/form-data

Το κλειδί API πρέπει να περιλαμβάνει το scope files:create για ανέβασμα και files:read για ανάκτηση metadata. Τα νέα κλειδιά Rivya API περιλαμβάνουν και τα δύο scopes από προεπιλογή.

Multipart πεδία

Χρησιμοποιήστε model όταν το αρχείο προορίζεται για συγκεκριμένο μοντέλο. Αυτό σας δίνει model-specific έλεγχο MIME και μεγέθους πριν γίνει δεκτό το αρχείο.

Όρια ανεβάσματος

Το Files API χρησιμοποιεί την ίδια πολιτική ανεβάσματος με τα ανεβάσματα αναφοράς του Rivya.

Προεπιλεγμένα όρια:

Ορισμένα μοντέλα έχουν διαφορετικά όρια. Για παράδειγμα, επιλεγμένα μοντέλα εικόνας αναφοράς επιτρέπουν μεγαλύτερες εικόνες, ενώ επιλεγμένα μοντέλα αναφοράς βίντεο επιτρέπουν αρχεία έως το edge-safe όριο ανεβάσματος του προϊόντος. Περνάτε πάντα model όταν γνωρίζετε το μοντέλο-στόχο και διαβάστε την Αναφορά API μοντέλων πριν δεχτείτε ανεβάσματα χρηστών.

Το Rivya επαληθεύει την ανιχνευμένη υπογραφή αρχείου, όχι μόνο την επέκταση ονόματος αρχείου.

Παράδειγμα curl

curl https://rivya.ai/api/v1/files \
  -H "Authorization: Bearer rvya_sk_..." \
  -F "file=@./reference.png" \
  -F "kind=image" \
  -F "model=nano-banana-2" \
  -F "client_request_id=asset-123"

Παράδειγμα JavaScript

import { readFile } from "node:fs/promises";

const form = new FormData();
const file = new Blob([await readFile("./reference.png")], {
  type: "image/png"
});

form.set("file", file, "reference.png");
form.set("kind", "image");
form.set("model", "nano-banana-2");
form.set("client_request_id", "asset-123");

const response = await fetch("https://rivya.ai/api/v1/files", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RIVYA_API_KEY}`
  },
  body: form
});

const uploadedFile = await response.json();
console.log(uploadedFile.id, uploadedFile.url);

Παράδειγμα Python

import os
import requests

with open("./reference.png", "rb") as file_handle:
    response = requests.post(
        "https://rivya.ai/api/v1/files",
        headers={
            "Authorization": f"Bearer {os.environ['RIVYA_API_KEY']}",
        },
        files={"file": ("reference.png", file_handle, "image/png")},
        data={
            "kind": "image",
            "model": "nano-banana-2",
            "client_request_id": "asset-123",
        },
        timeout=60,
    )

uploaded_file = response.json()
print(uploaded_file["id"], uploaded_file["url"])

Απάντηση

{
  "id": "file_...",
  "object": "file",
  "kind": "image",
  "file_name": "reference.png",
  "mime_type": "image/png",
  "size_bytes": 482314,
  "url": "https://...",
  "duration_seconds": null,
  "duration_token": null,
  "created_at": "2026-05-11T00:00:00.000Z",
  "expires_at": null
}

Για ανεβάσματα βίντεο και ήχου, το duration_seconds μπορεί να συμπληρωθεί. Όταν ένα μοντέλο απαιτεί επαλήθευση διάρκειας, αντιγράψτε το duration_token στη σχετική παράμετρο generation ως durationToken.

Ανάκτηση metadata αρχείου

Χρησιμοποιήστε GET /api/v1/files/{fileId} για να διαβάσετε metadata για αρχείο που ανήκει στον ίδιο λογαριασμό Rivya:

curl https://rivya.ai/api/v1/files/file_... \
  -H "Authorization: Bearer rvya_sk_..."

Η απάντηση χρησιμοποιεί την ίδια μορφή PublicApiFile με το ανέβασμα. Αν το αρχείο ανήκει σε άλλον λογαριασμό ή δεν είναι πλέον διαθέσιμο, το API επιστρέφει not_found.

Χρήση του ανεβάσματος σε generation params

Μην στέλνετε top-level πεδίο files στο POST /api/v1/generations.

Για νέες ενσωματώσεις, περάστε το αποτέλεσμα ανεβάσματος μέσω params.referenceMediaItems:

{
  "model": "nano-banana-2",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  },
  "client_request_id": "order-123-preview"
}

Για βίντεο ή ήχο:

{
  "url": "https://...",
  "kind": "video",
  "name": "source.mov",
  "mimeType": "video/quicktime",
  "durationSeconds": 12.4,
  "durationToken": "duration_token_from_files_api"
}

Ορισμένες παλαιότερες παράμετροι μοντέλων εξακολουθούν να χρησιμοποιούν model-specific πεδία URL. Αν η Αναφορά API μοντέλων τεκμηριώνει συγκεκριμένη παράμετρο, ακολουθήστε τη σελίδα αυτού του μοντέλου αντί να επινοήσετε νέο πεδίο.

Σφάλματα

Το Files API χρησιμοποιεί τον ίδιο δημόσιο φάκελο σφάλματος με το υπόλοιπο Rivya API:

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid.",
    "requestId": "req_..."
  }
}

Συνηθισμένες περιπτώσεις:

Σημειώσεις ασφάλειας

Μην αποθηκεύετε πλήρη κλειδιά API σε browsers, mobile clients, logs, analytics events ή screenshots.

Αντιμετωπίστε τα URLs ανεβασμένων αρχείων και τις τιμές duration_token ως προσωρινό υλικό ενσωμάτωσης. Χρησιμοποιήστε τα μόνο για να χτίσετε το επόμενο αίτημα generation και μην τα εκθέτετε σε δημόσιες σελίδες.

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

• Δημιουργία generation
• Rivya TypeScript SDK
• Αναφορά API μοντέλων
• Σφάλματα και όρια API
• OpenAPI και συμβόλαιο schema