Upload afbeeldings-, video- of audioreferentiebestanden voor Rivya API-generatierequests, met MIME-checks, groottelimieten en duration tokens.

Gebruik POST /api/v1/files om referentiemedia te uploaden voor modellen die beeld-, video- of audio-input nodig hebben.

Files API is alleen bedoeld voor referentie-inputs. De API maakt zelf geen generatietaken aan. Geef na upload de teruggegeven url en metadata door in model params, meestal via params.referenceMediaItems.

Endpoint

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

Vereiste headers:

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

De API-sleutel moet de scope files:create bevatten om te uploaden en files:read om metadata op te halen. Nieuw aangemaakte Rivya API-sleutels bevatten beide scopes standaard.

Multipartvelden

Veld	Type	Vereist	Notities
`file`	binary	ja	Het afbeeldings-, video- of audiobestand dat je uploadt.
`kind`	string	ja	Een van `image`, `video` of `audio`.
`model`	string	nee	Publieke model-ID. Wanneer aanwezig valideert Rivya of het model dit bestandstype accepteert.
`client_request_id`	string	nee	Je trace-ID, tot 128 tekens.

Gebruik model wanneer het bestand bedoeld is voor een specifiek model. Zo krijg je modelspecifieke MIME- en groottevalidatie voordat het bestand wordt geaccepteerd.

Uploadlimieten

Files API gebruikt hetzelfde uploadbeleid als Rivya-referentie-uploads.

Standaardlimieten:

Kind	Standaard max. grootte	Veelvoorkomende MIME-types
`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`

Sommige modellen hebben andere limieten. Zo staan bepaalde referentiebeeldmodellen grotere afbeeldingen toe, en bepaalde videoreferentiemodellen bestanden tot aan de edge-safe uploadlimiet van het product. Geef altijd model mee wanneer je het doelmodel kent, en lees Model API-referentie voordat je uploads van gebruikers accepteert.

Rivya valideert de gedetecteerde bestandssignatuur, niet alleen de bestandsextensie.

curl-voorbeeld

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-voorbeeld

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-voorbeeld

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"])

Response

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

Voor video- en audio-uploads kan duration_seconds worden gevuld. Wanneer een model duration-verificatie vereist, kopieer je duration_token naar de bijbehorende generatieparameter als durationToken.

Bestandsmetadata ophalen

Gebruik GET /api/v1/files/{fileId} om metadata te lezen voor een bestand dat eigendom is van hetzelfde Rivya-account:

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

De response gebruikt dezelfde PublicApiFile-shape als upload. Als het bestand bij een ander account hoort of niet meer beschikbaar is, retourneert de API not_found.

De upload gebruiken in generatieparams

Stuur geen top-level files-veld naar POST /api/v1/generations.

Geef bij nieuwe integraties het uploadresultaat door via 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"
}

Voor video of audio:

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

Sommige oudere modelparameters gebruiken nog modelspecifieke URL-velden. Als de Model API-referentie een specifieke parameter documenteert, volg dan die modelpagina in plaats van een nieuw veld te verzinnen.

Fouten

Files API gebruikt dezelfde publieke error envelope als de rest van Rivya API:

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

Veelvoorkomende gevallen:

HTTP	Code	Oorzaak
400	`validation_failed`	Ontbrekende `file`, niet-ondersteunde `kind`, niet-ondersteund MIME-type, bestand te groot of model accepteert het geselecteerde type niet.
401	`api_key_missing` / `api_key_invalid`	Ontbrekende of ongeldige Bearer API-sleutel.
403	`api_scope_denied`	De sleutel bevat geen `files:create` of `files:read` voor de gevraagde actie.
429	`rate_limited`	Te veel bestandsuploads in de huidige minuut.
503	`public_api_disabled`	Public API is uitgeschakeld in de huidige omgeving.

Beveiligingsnotities

Sla volledige API-sleutels niet op in browsers, mobiele clients, logs, analytics-events of screenshots.

Behandel geüploade bestands-URL's en duration_token-waarden als tijdelijk integratiemateriaal. Gebruik ze alleen om de opvolgende generatierequest te bouwen en stel ze niet bloot op publieke pagina's.

Files API