Lade Bild-, Video- oder Audio-Referenzdateien für Rivya API-Generierungsanfragen hoch, mit MIME-Prüfungen, Größenlimits und Duration Tokens.

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

Field	Type	Required	Hinweise
`file`	binary	yes	Die Bild-, Video- oder Audiodatei zum Hochladen.
`kind`	string	yes	Einer von `image`, `video` oder `audio`.
`model`	string	no	Öffentliche Modell-ID. Wenn vorhanden, prüft Rivya, ob das Modell diese Dateiart akzeptiert.
`client_request_id`	string	no	Deine Trace-ID, bis zu 128 Zeichen.

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:

Kind	Default max size	Häufige MIME-Typen
`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`

Einige Modelle haben andere Limits. Zum Beispiel erlauben ausgewählte Referenzbild-Modelle größere Bilder, und ausgewählte Videoreferenz-Modelle erlauben Dateien bis zur edge-sicheren Upload-Obergrenze des Produkts. Übergib immer model, wenn du das Zielmodell kennst, und lies die Modell-API-Referenz, bevor du Nutzeruploads akzeptierst.

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" \
  -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");
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",
            "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,
  "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 Duration-Prüfung erfordert, kopiere duration_token als durationToken in den zugehörigen Generation-Parameter.

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

Für Video oder Audio:

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

HTTP	Code	Ursache
400	`validation_failed`	Fehlendes `file`, nicht unterstütztes `kind`, nicht unterstützter MIME-Typ, zu große Datei oder Modell akzeptiert die gewählte Dateiart nicht.
401	`api_key_missing` / `api_key_invalid`	Fehlender oder ungültiger Bearer API Key.
403	`api_scope_denied`	Der Key enthält für die angefragte Aktion nicht `files:create` oder `files:read`.
429	`rate_limited`	Zu viele Datei-Uploads in der aktuellen Minute.
503	`public_api_disabled`	Public API ist in der aktuellen Umgebung deaktiviert.

Sicherheitshinweise

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

Behandle hochgeladene Datei-URLs und duration_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.

Files API