Files API

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

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:

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.

I limiti per i riferimenti immagine firmati includono:

Ogni immagine di riferimento Image5, Grok Imagine Image 2.0 o Wan 3.0 deve essere caricata specificando il relativo model. Conserva width, height, size_bytes e image_dimensions_token della risposta originale; la richiesta di generazione deve inviarli come width, height, sizeBytes e imageDimensionsToken. Gli URL di immagini esterne arbitrari non soddisfano questa validazione associata al modello.

La scomposizione in livelli convalida inoltre le dimensioni rilevate dell'immagine prima dell'upload: da 262,144 a 36,000,000 pixel totali e proporzioni comprese tra 1:16 e 16:1.

I limiti di upload specifici dei modelli con riferimento video includono:

Questi sono i limiti di upload accettati da Rivya e possono essere inferiori a quelli di un servizio a monte. Carica ogni riferimento Video8 o Wan 3.0 specificando il relativo model. I video di riferimento richiedono sia la prova firmata della durata sia i metadati video firmati della risposta originale all'upload associato al modello. I token di durata audio di Wan 3.0 vincolano anche il tipo MIME rilevato e la dimensione dell'upload in byte.

Le immagini di Wan 3.0 devono misurare 240–8.000 pixel per lato e i video 240–4.096 pixel per lato; entrambi devono rispettare un intervallo di proporzioni pari a 1:8–8:1. In modalità riferimento, video e audio hanno limiti complessivi separati di 15 secondi e l'audio non può essere l'unico tipo di riferimento.

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-lite" \
  -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-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);

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

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.

Per gli upload di immagini supportati, width e height vengono rilevati dai byte del file. Tutti e cinque i modelli Image5, Grok Imagine Image 2.0 e Wan 3.0 richiedono il valore firmato image_dimensions_token della risposta originale all'upload associato al modello: copialo nell'elemento di riferimento come imageDimensionsToken e copia size_bytes come sizeBytes. Un successivo recupero dei metadati del file può restituire questo token come null; se il token originale non è disponibile o è scaduto, carica di nuovo l'immagine sorgente.

Per gli upload video Video8 e Wan 3.0 supportati, Rivya ispeziona i byte MP4 o MOV e restituisce video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes e video_metadata_token. Copiali nell'elemento di riferimento come width, height, framesPerSecond, videoBitrateMbps, sizeBytes e videoMetadataToken. Il token è associato all'account, al modello di destinazione, all'URL, al tipo MIME, alle dimensioni, alla frequenza dei fotogrammi, al bitrate e alla dimensione dell'upload. La durata viene verificata separatamente tramite durationToken. Un successivo recupero dei metadati del file può restituire video_metadata_token come null: carica di nuovo il video sorgente invece di inventare i metadati.

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

Per video o 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"
}

I campi video firmati completi riportati sopra sono obbligatori per i riferimenti video Video8 e Wan 3.0. I riferimenti audio di Wan 3.0 usano mimeType, sizeBytes, durationSeconds e durationToken; quelli immagine usano il contratto di metadati specifico del modello descritto sopra.

Per Seedream 5.0 Pro Layer Decomposition, invia esattamente un'immagine e i metadati firmati restituiti dal relativo upload associato al modello:

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

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:

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, image_dimensions_token e video_metadata_token come materiale temporaneo di integrazione. Usali solo per costruire la richiesta di generazione successiva e non esporli in pagine pubbliche.

Pagine correlate

• Creare una generazione

• Rivya TypeScript SDK

• Riferimento API dei modelli

• Errori e limiti API

• OpenAPI e contratto dello schema