Files API

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

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:

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

Limieten voor ondertekende referentieafbeeldingen:

Elke Image5-, Grok Imagine Image 2.0- of Wan 3.0-referentieafbeelding moet worden geüpload met het bijbehorende doelmodel in model. Bewaar uit de oorspronkelijke response width, height, size_bytes en image_dimensions_token; stuur deze in de generatierequest respectievelijk mee als width, height, sizeBytes en imageDimensionsToken. Willekeurige externe afbeeldings-URL's voldoen niet aan deze modelgebonden validatie.

Bij Layer Decomposition worden vóór de upload ook de gedetecteerde afbeeldingsafmetingen gevalideerd: in totaal 262,144–36,000,000 pixels en een beeldverhouding van 1:16 tot en met 16:1.

Voor modellen met videoreferenties gelden onder meer deze modelspecifieke uploadlimieten:

Dit zijn de uploadlimieten die Rivya accepteert; ze kunnen lager zijn dan de limiet van een achterliggende dienst. Upload elke Video8- of Wan 3.0-referentie met het bijbehorende doelmodel in model. Referentievideo's vereisen zowel het ondertekende bewijs van de duur als de ondertekende videometadata uit de oorspronkelijke modelgebonden uploadresponse. De audioduurtokens van Wan 3.0 zijn ook gebonden aan het gedetecteerde MIME-type en de uploadgrootte in bytes.

Wan 3.0-afbeeldingen moeten per zijde 240–8.000 pixels meten en video's per zijde 240–4.096 pixels; beide moeten binnen een beeldverhouding van 1:8–8:1 blijven. In de referentiemodus gelden voor video en audio afzonderlijke totaallimieten van 15 seconden en mag audio niet het enige referentietype zijn.

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

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

Bij ondersteunde afbeeldingsuploads worden width en height uit de bestandsbytes gedetecteerd. Alle vijf Image5-modellen, Grok Imagine Image 2.0 en Wan 3.0 vereisen de ondertekende image_dimensions_token uit de oorspronkelijke modelgebonden uploadresponse. Kopieer deze naar het referentie-item als imageDimensionsToken en kopieer size_bytes als sizeBytes. Als je de bestandsmetadata later opnieuw ophaalt, kan het token null zijn. Upload de bronafbeelding daarom opnieuw wanneer het oorspronkelijke token niet beschikbaar of verlopen is.

Bij ondersteunde Video8- en Wan 3.0-videouploads inspecteert Rivya de MP4- of MOV-bytes en retourneert video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes en video_metadata_token. Kopieer deze naar het referentie-item als width, height, framesPerSecond, videoBitrateMbps, sizeBytes en videoMetadataToken. Het token is gebonden aan het account, het doelmodel, de URL, het MIME-type, de afmetingen, de framerate, de bitrate en de uploadgrootte. De duur wordt afzonderlijk geverifieerd met durationToken. Als je de bestandsmetadata later opnieuw ophaalt, kan video_metadata_token null zijn; upload de bronvideo opnieuw in plaats van metadata te verzinnen.

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

Voor video of 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"
}

De volledige ondertekende videovelden hierboven zijn vereist voor Video8- en Wan 3.0-videoreferenties. Wan 3.0-audioreferenties gebruiken mimeType, sizeBytes, durationSeconds en durationToken; afbeeldingsreferenties gebruiken het modelspecifieke contract voor afbeeldingsmetadata dat hierboven is beschreven.

Stuur voor Seedream 5.0 Pro Layer Decomposition exact één afbeelding mee, samen met de ondertekende metadata uit de modelgebonden upload:

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

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:

Beveiligingsnotities

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

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

Gerelateerde pagina's

• Generatie aanmaken

• Rivya TypeScript-SDK

• Model API-referentie

• API-fouten en limieten

• OpenAPI- en schemacontract