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.

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

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

Τα όρια για τις υπογεγραμμένες εικόνες αναφοράς περιλαμβάνουν:

Κάθε εικόνα αναφοράς Image5, Grok Imagine Image 2.0 ή Wan 3.0 πρέπει να ανεβαίνει με το model προορισμού της. Διατηρήστε τα width, height, size_bytes και image_dimensions_token της αρχικής απόκρισης· το αίτημα generation πρέπει να τα στείλει ως width, height, sizeBytes και imageDimensionsToken. Αυθαίρετα εξωτερικά URL εικόνων δεν ικανοποιούν αυτή την επικύρωση που δεσμεύεται στο μοντέλο.

Η αποσύνθεση επιπέδων επικυρώνει επιπλέον τις διαστάσεις εικόνας που ανιχνεύτηκαν πριν από το ανέβασμα: συνολικά 262.144–36.000.000 pixels και αναλογία διαστάσεων από 1:16 έως 16:1.

Τα όρια ανεβάσματος ανά μοντέλο Video8 και Wan 3.0 περιλαμβάνουν:

Αυτά είναι τα ανώτατα όρια ανεβάσματος που δέχεται το Rivya και μπορεί να είναι χαμηλότερα από τα όρια μιας upstream υπηρεσίας. Ανεβάστε κάθε αναφορά Video8 ή Wan 3.0 με το model προορισμού της. Τα βίντεο αναφοράς απαιτούν τόσο την υπογεγραμμένη απόδειξη διάρκειας όσο και τα υπογεγραμμένα metadata βίντεο από την αρχική απόκριση ανεβάσματος που δεσμεύεται στο μοντέλο. Τα token διάρκειας ήχου του Wan 3.0 δεσμεύονται επίσης στον ανιχνευμένο τύπο MIME και στο μέγεθος ανεβάσματος σε byte.

Οι εικόνες Wan 3.0 πρέπει να έχουν 240–8.000 pixel ανά πλευρά και τα βίντεο 240–4.096 pixel ανά πλευρά· και τα δύο πρέπει να παραμένουν εντός ορίου αναλογίας διαστάσεων 1:8–8:1. Στη λειτουργία αναφοράς, το βίντεο και ο ήχος έχουν ξεχωριστά συνολικά όρια 15 δευτερολέπτων, ενώ ο ήχος δεν μπορεί να είναι ο μοναδικός τύπος αναφοράς.

Το 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-lite" \
  -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-lite");
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-lite",
            "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,
  "width": 1024,
  "height": 1024,
  "image_dimensions_token": "signed_image_metadata_token",
  "video_width": null,
  "video_height": null,
  "frames_per_second": null,
  "video_bitrate_mbps": null,
  "video_file_size_bytes": null,
  "video_metadata_token": null,
  "created_at": "2026-05-11T00:00:00.000Z",
  "expires_at": null
}

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

Για υποστηριζόμενα ανεβάσματα εικόνων, τα width και height ανιχνεύονται από τα bytes του αρχείου. Και τα πέντε μοντέλα Image5, καθώς και τα Grok Imagine Image 2.0 και Wan 3.0, απαιτούν το υπογεγραμμένο image_dimensions_token από την αρχική απόκριση ανεβάσματος που δεσμεύεται στο μοντέλο· αντιγράψτε το στο στοιχείο αναφοράς ως imageDimensionsToken και αντιγράψτε το size_bytes ως sizeBytes. Μια μεταγενέστερη ανάκτηση metadata αρχείου μπορεί να επιστρέψει αυτό το token ως null, οπότε ανεβάστε ξανά την πηγαία εικόνα αν το αρχικό token δεν είναι διαθέσιμο ή έχει λήξει.

Για υποστηριζόμενα ανεβάσματα βίντεο Video8 και Wan 3.0, το Rivya επιθεωρεί τα bytes MP4 ή MOV και επιστρέφει video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes και video_metadata_token. Αντιγράψτε τα στο στοιχείο αναφοράς ως width, height, framesPerSecond, videoBitrateMbps, sizeBytes και videoMetadataToken. Το token δεσμεύεται στον λογαριασμό, στο μοντέλο προορισμού, στο URL, στον τύπο MIME, στις διαστάσεις, στον ρυθμό καρέ, στο bitrate και στο μέγεθος ανεβάσματος. Η διάρκεια επαληθεύεται ξεχωριστά με το durationToken. Μια μεταγενέστερη ανάκτηση metadata αρχείου μπορεί να επιστρέψει το video_metadata_token ως null· ανεβάστε ξανά το πηγαίο βίντεο αντί να επινοήσετε metadata.

Ανάκτηση 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-lite",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png",
        "width": 1024,
        "height": 1024,
        "sizeBytes": 482314,
        "imageDimensionsToken": "image_dimensions_token_from_files_api"
      }
    ]
  },
  "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",
  "width": 1920,
  "height": 1080,
  "framesPerSecond": 30,
  "videoBitrateMbps": 8.5,
  "sizeBytes": 26214400,
  "videoMetadataToken": "video_metadata_token_from_files_api"
}

Τα πλήρη υπογεγραμμένα πεδία βίντεο παραπάνω απαιτούνται για αναφορές βίντεο Video8 και Wan 3.0. Οι αναφορές ήχου Wan 3.0 χρησιμοποιούν mimeType, sizeBytes, durationSeconds και durationToken, ενώ οι αναφορές εικόνας χρησιμοποιούν το συμβόλαιο metadata ανά μοντέλο που περιγράφεται παραπάνω.

Για το Seedream 5.0 Pro Layer Decomposition, στείλτε ακριβώς μία εικόνα και τα υπογεγραμμένα metadata που επιστράφηκαν από το ανέβασμα για το συγκεκριμένο μοντέλο:

{
  "model": "seedream-5-pro-layer-decomposition",
  "prompt": "Separate the product, shadow, typography, and background into clean layers",
  "params": {
    "size": "auto",
    "output_format": "png",
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "campaign.tiff",
        "mimeType": "image/tiff",
        "width": 2048,
        "height": 2048,
        "sizeBytes": 6291456,
        "imageDimensionsToken": "image_dimensions_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.

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

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

• Δημιουργία generation

• Rivya TypeScript SDK

• Αναφορά API μοντέλων

• Σφάλματα και όρια API

• OpenAPI και συμβόλαιο schema