Files API

Użyj POST /api/v1/files, aby przesłać media referencyjne dla modeli, które potrzebują wejść obrazu, wideo albo audio.

Files API służy wyłącznie do wejść referencyjnych. Samodzielnie nie tworzy zadań generowania. Po przesłaniu przekaż zwrócone url i metadane do params modelu, zwykle przez params.referenceMediaItems.

Endpoint

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

Wymagane nagłówki:

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

Klucz API musi zawierać zakres files:create, aby przesyłać pliki, oraz files:read, aby pobierać metadane. Nowo utworzone klucze Rivya API domyślnie zawierają oba zakresy.

Pola Multipart

Użyj model, gdy plik jest przeznaczony dla konkretnego modelu. Dzięki temu przed zaakceptowaniem pliku otrzymasz walidację MIME i rozmiaru właściwą dla modelu.

Limity Przesyłania

Files API używa tej samej polityki przesyłania co uploady referencyjne Rivya.

Domyślne limity:

Niektóre modele mają inne limity. Na przykład wybrane modele z obrazem referencyjnym dopuszczają większe obrazy, a wybrane modele z referencją wideo dopuszczają pliki aż do produktowego, bezpiecznego limitu przesyłania. Zawsze przekazuj model, gdy znasz model docelowy, i przeczytaj Referencję modeli API, zanim zaakceptujesz uploady użytkowników.

Limity dla podpisanych obrazów referencyjnych obejmują:

Każdy obraz referencyjny Image5, Grok Imagine Image 2.0 lub Wan 3.0 musi zostać przesłany ze swoim docelowym model. Zachowaj pola width, height, size_bytes i image_dimensions_token z pierwotnej odpowiedzi; żądanie generowania musi wysłać je jako width, height, sizeBytes i imageDimensionsToken. Dowolne zewnętrzne adresy URL obrazów nie spełniają tej walidacji powiązanej z modelem.

Dekompozycja na warstwy dodatkowo sprawdza wykryte wymiary obrazu przed przesłaniem: łącznie 262,144–36,000,000 pikseli oraz proporcje od 1:16 do 16:1.

Limity właściwe dla modeli z referencją wideo obejmują:

Są to maksymalne limity przesyłania akceptowane przez Rivya, które mogą być niższe niż limit usługi nadrzędnej. Każdy materiał referencyjny Video8 lub Wan 3.0 przesyłaj z docelowym model. Referencyjne pliki wideo wymagają zarówno podpisanego potwierdzenia czasu trwania, jak i podpisanych metadanych wideo z pierwotnej odpowiedzi uploadu powiązanego z modelem. Tokeny czasu trwania audio Wan 3.0 są również powiązane z wykrytym typem MIME i rozmiarem uploadu w bajtach.

Każdy bok obrazu Wan 3.0 musi mieć 240–8 000 pikseli, a wideo 240–4 096 pikseli; oba typy muszą zachować proporcje w zakresie 1:8–8:1. W trybie referencyjnym wideo i audio mają osobne łączne limity 15 sekund, a audio nie może być jedynym typem referencji.

Rivya waliduje wykrytą sygnaturę pliku, nie tylko rozszerzenie nazwy pliku.

Przykład 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"

Przykład 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);

Przykład 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"])

Odpowiedź

{
  "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
}

Dla uploadów wideo i audio duration_seconds może być wypełnione. Gdy model wymaga weryfikacji czasu trwania, skopiuj duration_token do powiązanego parametru generowania jako durationToken.

Dla obsługiwanych uploadów obrazów pola width i height są wykrywane na podstawie bajtów pliku. Wszystkie pięć modeli Image5, Grok Imagine Image 2.0 oraz Wan 3.0 wymagają podpisanego image_dimensions_token z pierwotnej odpowiedzi uploadu powiązanego z modelem; skopiuj go do elementu referencyjnego jako imageDimensionsToken, a size_bytes skopiuj jako sizeBytes. Późniejsze pobranie metadanych pliku może zwrócić dla tego tokenu wartość null, dlatego ponownie prześlij obraz źródłowy, jeśli pierwotny token jest niedostępny lub wygasł.

Dla obsługiwanych uploadów wideo Video8 i Wan 3.0 Rivya analizuje bajty MP4 lub MOV i zwraca video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes oraz video_metadata_token. Skopiuj je do elementu referencyjnego odpowiednio jako width, height, framesPerSecond, videoBitrateMbps, sizeBytes i videoMetadataToken. Token jest powiązany z kontem, modelem docelowym, adresem URL, typem MIME, wymiarami, liczbą klatek na sekundę, przepływnością i rozmiarem uploadu. Czas trwania jest weryfikowany niezależnie przez durationToken. Późniejsze pobranie metadanych pliku może zwrócić video_metadata_token jako null; zamiast wymyślać metadane, ponownie prześlij źródłowy plik wideo.

Pobierz Metadane Pliku

Użyj GET /api/v1/files/{fileId}, aby odczytać metadane pliku należącego do tego samego konta Rivya:

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

Odpowiedź używa tego samego kształtu PublicApiFile co upload. Jeśli plik należy do innego konta albo nie jest już dostępny, API zwraca not_found.

Użyj Uploadu w Parametrach Generowania

Nie wysyłaj pola files na najwyższym poziomie do POST /api/v1/generations.

Dla nowych integracji przekaż wynik uploadu przez 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"
}

Dla wideo albo audio:

{
  "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"
}

Kompletny zestaw podpisanych pól wideo pokazany wyżej jest wymagany dla referencji wideo Video8 i Wan 3.0. Referencje dźwiękowe Wan 3.0 używają mimeType, sizeBytes, durationSeconds i durationToken, a referencje obrazowe — właściwego dla modelu kontraktu metadanych obrazu opisanego powyżej.

Dla Seedream 5.0 Pro Layer Decomposition wyślij dokładnie jeden obraz oraz podpisane metadane zwrócone przez upload powiązany z tym modelem:

{
  "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"
      }
    ]
  }
}

Niektóre starsze parametry modelu nadal używają pól URL specyficznych dla modelu. Jeśli Referencja modeli API dokumentuje konkretny parametr, postępuj zgodnie z tą stroną modelu, zamiast wymyślać nowe pole.

Błędy

Files API używa tej samej publicznej koperty błędu co reszta Rivya API:

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

Typowe przypadki:

Uwagi o Bezpieczeństwie

Nie przechowuj pełnych kluczy API w przeglądarkach, klientach mobilnych, logach, zdarzeniach analitycznych ani zrzutach ekranu.

Traktuj URL-e przesłanych plików oraz wartości duration_token, image_dimensions_token i video_metadata_token jako tymczasowy materiał integracyjny. Używaj ich tylko do zbudowania kolejnego żądania generowania i nie ujawniaj ich na publicznych stronach.

Powiązane Strony

• Utwórz generowanie

• Rivya TypeScript SDK

• Referencja modeli API

• Błędy i limity API

• Kontrakt OpenAPI i schemat