Przesyłaj referencyjne pliki obrazów, wideo albo audio dla żądań generowania Rivya API, z kontrolą MIME, limitami rozmiaru i tokenami czasu trwania.

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

Pole	Typ	Wymagane	Uwagi
`file`	binary	yes	Plik obrazu, wideo albo audio do przesłania.
`kind`	string	yes	Jedno z `image`, `video` albo `audio`.
`model`	string	no	Publiczny ID modelu. Gdy jest obecny, Rivya sprawdza, czy model akceptuje ten rodzaj pliku.
`client_request_id`	string	no	Twój ID śledzenia, maksymalnie 128 znaków.

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:

Rodzaj	Domyślny maks. rozmiar	Typowe typy MIME
`image`	10 MB	`image/jpeg`, `image/png`, `image/webp`
`video`	50 MB	`video/mp4`, `video/quicktime`, `video/webm`
`audio`	10 MB	`audio/mpeg`, `audio/mp4`, `audio/wav`, `audio/x-wav`, `audio/aac`, `audio/ogg`

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.

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

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

Dla wideo albo audio:

{
  "url": "https://...",
  "kind": "video",
  "name": "source.mov",
  "mimeType": "video/quicktime",
  "durationSeconds": 12.4,
  "durationToken": "duration_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:

HTTP	Kod	Przyczyna
400	`validation_failed`	Brak `file`, nieobsługiwany `kind`, nieobsługiwany typ MIME, zbyt duży plik albo model nie akceptuje wybranego rodzaju.
401	`api_key_missing` / `api_key_invalid`	Brakujący albo nieprawidłowy klucz Bearer API.
403	`api_scope_denied`	Klucz nie zawiera `files:create` albo `files:read` dla żądanej akcji.
429	`rate_limited`	Zbyt wiele uploadów plików w bieżącej minucie.
503	`public_api_disabled`	Public API jest wyłączone w bieżącym środowisku.

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 i wartości duration_token jako tymczasowy materiał integracyjny. Używaj ich tylko do zbudowania kolejnego żądania generowania i nie ujawniaj ich na publicznych stronach.

Files API