Carica file di riferimento immagine, video o audio per richieste di generazione Rivya API, con controlli MIME, limiti di dimensione e duration token.

Usa POST /api/v1/files per caricare media di riferimento per modelli che richiedono input immagine, video o audio.

Files API serve solo per input di riferimento. Non crea task di generazione da sola. Dopo l'upload, passa url e metadati restituiti nei params del modello, di solito tramite params.referenceMediaItems.

Endpoint

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

Header richiesti:

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

La chiave API deve includere lo scope files:create per caricare e files:read per recuperare metadati. Le nuove chiavi Rivya API includono entrambi gli scope per impostazione predefinita.

Campi multipart

Campo	Tipo	Richiesto	Note
`file`	binary	sì	Il file immagine, video o audio da caricare.
`kind`	string	sì	Uno tra `image`, `video` o `audio`.
`model`	string	no	ID pubblico del modello. Quando presente, Rivya valida che il modello accetti questo tipo di file.
`client_request_id`	string	no	Il tuo ID di tracciamento, fino a 128 caratteri.

Usa model quando il file è destinato a un modello specifico. Questo ti dà validazione MIME e dimensione specifica per modello prima che il file venga accettato.

Limiti di upload

Files API usa la stessa policy di upload dei riferimenti Rivya.

Limiti predefiniti:

Kind	Dimensione massima predefinita	Tipi MIME comuni
`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`

Alcuni modelli hanno limiti diversi. Per esempio, alcuni modelli con immagine di riferimento permettono immagini più grandi, e alcuni modelli con riferimento video permettono file fino al limite di upload sicuro del prodotto. Passa sempre model quando conosci il modello target e leggi riferimento API dei modelli prima di accettare upload dagli utenti.

Rivya valida la firma rilevata del file, non solo l'estensione del nome file.

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

Esempio 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);

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

Risposta

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

Per upload video e audio, duration_seconds può essere valorizzato. Quando un modello richiede verifica della durata, copia duration_token nel parametro di generazione correlato come durationToken.

Recuperare i metadati del file

Usa GET /api/v1/files/{fileId} per leggere i metadati di un file appartenente allo stesso account Rivya:

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

La risposta usa la stessa forma PublicApiFile dell'upload. Se il file appartiene a un altro account o non è più disponibile, l'API restituisce not_found.

Usare l'upload nei parametri di generazione

Non inviare un campo files al livello principale a POST /api/v1/generations.

Per nuove integrazioni, passa il risultato dell'upload tramite 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"
}

Per video o audio:

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

Alcuni parametri di modelli più vecchi usano ancora campi URL specifici per modello. Se il riferimento API dei modelli documenta un parametro specifico, segui quella pagina modello invece di inventare un nuovo campo.

Errori

Files API usa lo stesso envelope di errore pubblico del resto di Rivya API:

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

Casi comuni:

HTTP	Code	Causa
400	`validation_failed`	`file` mancante, `kind` non supportato, tipo MIME non supportato, file troppo grande o modello che non accetta il kind selezionato.
401	`api_key_missing` / `api_key_invalid`	Chiave API Bearer mancante o non valida.
403	`api_scope_denied`	La chiave non include `files:create` o `files:read` per l'azione richiesta.
429	`rate_limited`	Troppi upload di file nel minuto corrente.
503	`public_api_disabled`	Public API è disabilitata nell'ambiente corrente.

Note di sicurezza

Non conservare chiavi API complete in browser, client mobili, log, eventi analytics o screenshot.

Tratta gli URL dei file caricati e i valori duration_token come materiale temporaneo di integrazione. Usali solo per costruire la richiesta di generazione successiva e non esporli in pagine pubbliche.

Files API