Incarca fisiere imagine, video sau audio de referinta pentru cereri de generare Rivya API, cu verificari MIME, limite de dimensiune si tokeni de durata.

Foloseste POST /api/v1/files pentru a incarca media de referinta pentru modelele care au nevoie de inputuri imagine, video sau audio.

Files API este doar pentru inputuri de referinta. Nu creeaza singur sarcini de generare. Dupa incarcare, trimite url returnat si metadata in params ale modelului, de obicei prin params.referenceMediaItems.

Endpoint

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

Headere necesare:

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

Cheia API trebuie sa includa scope-ul files:create pentru incarcare si files:read pentru recuperarea metadatelor. Cheile Rivya API nou create includ implicit ambele scope-uri.

Campuri multipart

Camp	Tip	Necesar	Note
`file`	binary	da	Fisierul imagine, video sau audio de incarcat.
`kind`	string	da	Una dintre valorile `image`, `video` sau `audio`.
`model`	string	nu	ID public de model. Cand este prezent, Rivya valideaza ca modelul accepta acest tip de fisier.
`client_request_id`	string	nu	ID-ul tau de trasabilitate, pana la 128 de caractere.

Foloseste model cand fisierul este destinat unui model specific. Astfel primesti validare MIME si de dimensiune specifica modelului inainte ca fisierul sa fie acceptat.

Limite de incarcare

Files API foloseste aceeasi politica de incarcare ca incarcarile de referinta Rivya.

Limite implicite:

Tip	Dimensiune maxima implicita	Tipuri MIME comune
`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`

Unele modele au limite diferite. De exemplu, anumite modele cu imagini de referinta permit imagini mai mari, iar anumite modele cu referinta video permit fisiere pana la plafonul de incarcare edge-safe al produsului. Trimite intotdeauna model cand stii modelul tinta si citeste Referinta API pentru modele inainte sa accepti incarcari de la utilizatori.

Rivya valideaza semnatura detectata a fisierului, nu doar extensia numelui de fisier.

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

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

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

Raspuns

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

Pentru incarcari video si audio, duration_seconds poate fi populat. Cand un model cere verificarea duratei, copiaza duration_token in parametrul de generare asociat ca durationToken.

Recupereaza metadatele fisierului

Foloseste GET /api/v1/files/{fileId} pentru a citi metadatele unui fisier detinut de acelasi cont Rivya:

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

Raspunsul foloseste aceeasi forma PublicApiFile ca incarcarea. Daca fisierul apartine altui cont sau nu mai este disponibil, API-ul returneaza not_found.

Foloseste incarcarea in parametrii de generare

Nu trimite un camp top-level files catre POST /api/v1/generations.

Pentru integrari noi, trimite rezultatul incarcarii prin params.referenceMediaItems:

{
  "model": "nano-banana-2",
  "prompt": "Restilizeaza aceasta fotografie de produs pentru o pagina de catalog editorial curata",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  },
  "client_request_id": "order-123-preview"
}

Pentru video sau audio:

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

Unii parametri mai vechi ai modelelor folosesc inca fielduri URL specifice modelului. Daca Referinta API pentru modele documenteaza un parametru specific, urmeaza pagina acelui model in loc sa inventezi un camp nou.

Erori

Files API foloseste acelasi pachet public de eroare ca restul Rivya API:

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

Cazuri comune:

HTTP	Cod	Cauza
400	`validation_failed`	Lipseste `file`, `kind` nu este acceptat, tipul MIME nu este acceptat, fisierul este prea mare sau modelul nu accepta tipul selectat.
401	`api_key_missing` / `api_key_invalid`	Cheie API Bearer lipsa sau invalida.
403	`api_scope_denied`	Cheia nu include `files:create` sau `files:read` pentru actiunea ceruta.
429	`rate_limited`	Prea multe incarcari de fisiere in minutul curent.
503	`public_api_disabled`	Public API este dezactivat in mediul curent.

Note de securitate

Nu stoca chei API complete in browsere, clienti mobili, loguri, evenimente de analytics sau capturi de ecran.

Trateaza URL-urile fisierelor incarcate si valorile duration_token ca material temporar de integrare. Foloseste-le doar pentru a construi cererea de generare urmatoare si nu le expune in pagini publice.

Files API