Files API

Nutze POST /api/v1/files, um Referenzmedien für Modelle hochzuladen, die Bild-, Video- oder Audioeingaben brauchen.

Files API ist nur für Referenzeingaben gedacht. Sie erstellt selbst keine Generation-Tasks. Übergib nach dem Upload die zurückgegebene url und Metadaten an die Modell-params, meist über params.referenceMediaItems.

Endpoint

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

Erforderliche Header:

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

Der API Key muss den Scope files:create zum Hochladen und files:read zum Abrufen von Metadaten enthalten. Neu erstellte Rivya API Keys enthalten beide Scopes standardmäßig.

Multipart-Felder

Nutze model, wenn die Datei für ein bestimmtes Modell gedacht ist. Dadurch erhältst du modellspezifische MIME- und Größenvalidierung, bevor die Datei akzeptiert wird.

Upload-Limits

Files API nutzt dieselbe Upload-Policy wie Rivya-Referenzuploads.

Standardlimits:

Einige Modelle haben andere Limits. Zum Beispiel erlauben ausgewählte Referenzbild-Modelle größere Bilder, und ausgewählte Videoreferenz-Modelle erlauben Dateien bis zu der im Produkt sicher unterstützten Upload-Obergrenze. Übergib immer model, wenn du das Zielmodell kennst, und lies die Modell-API-Referenz, bevor du Nutzeruploads akzeptierst.

Für signierte Bildreferenzen gelten folgende Limits:

Jedes Referenzbild für Image5, Grok Imagine Image 2.0 oder Wan 3.0 muss zusammen mit seinem Ziel-model hochgeladen werden. Bewahre width, height, size_bytes und image_dimensions_token aus der ursprünglichen Antwort auf. In der Generierungsanfrage sendest du sie als width, height, sizeBytes und imageDimensionsToken. Beliebige externe Bild-URLs erfüllen diese modellgebundene Prüfung nicht.

Bei der Ebenenzerlegung werden vor dem Upload zusätzlich die erkannten Bildabmessungen geprüft: insgesamt 262.144–36.000.000 Pixel und ein Seitenverhältnis von 1:16 bis 16:1.

Für Modelle mit Videoreferenzen gelten folgende spezifische Upload-Limits:

Dies sind die von Rivya akzeptierten Upload-Obergrenzen; sie können niedriger sein als die Limits eines vorgelagerten Dienstes. Lade jede Video8- oder Wan-3.0-Referenz zusammen mit ihrem Ziel-model hoch. Referenzvideos benötigen sowohl den signierten Dauernachweis als auch die signierten Videometadaten aus der ursprünglichen modellgebundenen Upload-Antwort. Die Audio-Dauer-Token von Wan 3.0 binden außerdem den erkannten MIME-Typ und die Upload-Größe in Byte.

Wan-3.0-Bilder müssen pro Seite 240–8.000 Pixel messen, Videos 240–4.096 Pixel; beide müssen innerhalb eines Seitenverhältnisses von 1:8–8:1 bleiben. Im Referenzmodus gelten für Video und Audio jeweils getrennte Gesamtdauergrenzen von 15 Sekunden, und Audio darf nicht die einzige Referenzart sein.

Rivya validiert die erkannte Dateisignatur, nicht nur die Dateiendung.

curl-Beispiel

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

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

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

Antwort

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

Bei Video- und Audio-Uploads kann duration_seconds befüllt sein. Wenn ein Modell eine Dauerprüfung erfordert, kopiere duration_token als durationToken in den zugehörigen Generation-Parameter.

Bei unterstützten Bild-Uploads werden width und height aus den tatsächlichen Dateibytes ermittelt. Alle fünf Image5-Modelle, Grok Imagine Image 2.0 und Wan 3.0 benötigen den signierten image_dimensions_token aus der ursprünglichen modellgebundenen Upload-Antwort. Kopiere ihn als imageDimensionsToken in den Referenzeintrag und size_bytes als sizeBytes. Ein späterer Abruf der Dateimetadaten kann für diesen Token null zurückgeben. Lade das Quellbild erneut hoch, wenn der ursprüngliche Token fehlt oder abgelaufen ist.

Bei unterstützten Video8- und Wan-3.0-Video-Uploads untersucht Rivya die tatsächlichen MP4- oder MOV-Dateibytes und gibt video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes und video_metadata_token zurück. Kopiere sie als width, height, framesPerSecond, videoBitrateMbps, sizeBytes und videoMetadataToken in den Referenzeintrag. Der Token ist an Konto, Zielmodell, URL, MIME-Typ, Abmessungen, Bildrate, Bitrate und Upload-Größe gebunden. Die Dauer wird separat mit durationToken geprüft. Ein späterer Abruf der Dateimetadaten kann für video_metadata_token den Wert null zurückgeben; lade das Quellvideo erneut hoch, statt Metadaten zu erfinden.

Dateimetadaten abrufen

Nutze GET /api/v1/files/{fileId}, um Metadaten für eine Datei zu lesen, die demselben Rivya-Konto gehört:

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

Die Antwort verwendet dieselbe PublicApiFile-Form wie der Upload. Wenn die Datei zu einem anderen Konto gehört oder nicht mehr verfügbar ist, gibt die API not_found zurück.

Upload in Generation-Params verwenden

Sende kein top-level Feld files an POST /api/v1/generations.

Für neue Integrationen übergib das Upload-Ergebnis über 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"
}

Für Video oder 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"
}

Die vollständigen signierten Videofelder oben sind für Video8- und Wan-3.0-Videoreferenzen erforderlich. Wan-3.0-Audioreferenzen verwenden mimeType, sizeBytes, durationSeconds und durationToken; Bildreferenzen folgen dem oben beschriebenen modellspezifischen Bildmetadaten-Vertrag.

Für Seedream 5.0 Pro Layer Decomposition sendest du genau ein Bild zusammen mit den signierten Metadaten aus dem modellgebundenen Upload:

{
  "model": "seedream-5-pro-layer-decomposition",
  "prompt": "Trenne Produkt, Schatten, Typografie und Hintergrund in saubere Ebenen",
  "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"
      }
    ]
  }
}

Einige ältere Modellparameter verwenden weiterhin modellspezifische URL-Felder. Wenn die Modell-API-Referenz einen bestimmten Parameter dokumentiert, folge dieser Modellseite, statt ein neues Feld zu erfinden.

Fehler

Files API verwendet denselben öffentlichen Fehlerumschlag wie der Rest der Rivya API:

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

Häufige Fälle:

Sicherheitshinweise

Speichere vollständige API Keys nicht in Browsern, Mobile Clients, Logs, Analytics-Events oder Screenshots.

Behandle hochgeladene Datei-URLs sowie duration_token-, image_dimensions_token- und video_metadata_token-Werte als temporäres Integrationsmaterial. Nutze sie nur, um die anschließende Generation-Anfrage zu bauen, und lege sie nicht auf öffentlichen Seiten offen.

Verwandte Seiten

• Generation erstellen

• Rivya TypeScript SDK

• Modell-API-Referenz

• API-Fehler und Limits

• OpenAPI- und Schema-Vertrag