Files API

Folosește POST /api/v1/files pentru a încărca materiale de referință destinate modelelor care necesită intrări imagine, video sau audio.

Files API este destinat exclusiv intrărilor de referință. Nu creează singur sarcini de generare. După încărcare, transmite valoarea url returnată și metadatele în params ale modelului, de obicei prin params.referenceMediaItems.

Endpoint

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

Antete obligatorii:

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

Cheia API trebuie să includă permisiunea files:create pentru încărcare și files:read pentru recuperarea metadatelor. Cheile Rivya API create recent includ implicit ambele permisiuni.

Câmpuri multipart

Folosește model când fișierul este destinat unui anumit model. Astfel, validarea MIME și a dimensiunii specifice modelului are loc înainte ca fișierul să fie acceptat.

Limite de încărcare

Files API folosește aceeași politică de încărcare ca materialele de referință Rivya.

Limite prestabilite:

Unele modele au limite diferite. De exemplu, anumite modele cu imagini de referință permit imagini mai mari, iar unele modele cu referință video permit fișiere până la limita pe care produsul o poate accepta în siguranță. Trimite întotdeauna model când cunoști modelul țintă și consultă Referința API pentru modele înainte de a accepta încărcări de la utilizatori.

Limitele pentru imaginile de referință semnate includ:

Fiecare imagine de referință Image5, Grok Imagine Image 2.0 sau Wan 3.0 trebuie încărcată împreună cu model țintă. Păstrează valorile width, height, size_bytes și image_dimensions_token din răspunsul original; cererea de generare trebuie să le transmită ca width, height, sizeBytes și imageDimensionsToken. URL-urile externe arbitrare ale imaginilor nu îndeplinesc această validare asociată modelului.

Descompunerea pe straturi validează suplimentar dimensiunile detectate ale imaginii înainte de încărcare: 262,144–36,000,000 de pixeli în total și un raport de aspect cuprins între 1:16 și 16:1.

Limitele de încărcare specifice modelelor Video8 și Wan 3.0 includ:

Acestea sunt plafoanele de încărcare acceptate de Rivya și pot fi mai mici decât limita serviciului furnizor. Încarcă fiecare referință Video8 sau Wan 3.0 împreună cu model țintă. Videoclipurile de referință necesită atât dovada semnată a duratei, cât și metadatele video semnate din răspunsul original al încărcării asociate modelului. Tokenurile de durată pentru audio Wan 3.0 sunt asociate și tipului MIME detectat, precum și dimensiunii în octeți a încărcării.

Imaginile Wan 3.0 trebuie să aibă 240–8.000 de pixeli pe fiecare latură, iar videoclipurile 240–4.096 de pixeli pe fiecare latură; ambele trebuie să se încadreze într-un raport de aspect de 1:8–8:1. În modul de referință, videoclipurile și fișierele audio au limite totale separate de 15 secunde, iar audio nu poate fi singurul tip de referință.

Rivya validează semnătura detectată a fișierului, nu doar extensia numelui acestuia.

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

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-lite",
            "client_request_id": "asset-123",
        },
        timeout=60,
    )

uploaded_file = response.json()
print(uploaded_file["id"], uploaded_file["url"])

Răspuns

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

Pentru încărcările video și audio, duration_seconds poate avea o valoare. Când un model necesită verificarea duratei, copiază duration_token în parametrul de generare corespunzător sub formă durationToken.

Pentru încărcările de imagini acceptate, width și height sunt detectate din octeții fișierului. Toate cele cinci modele Image5, precum și Grok Imagine Image 2.0 și Wan 3.0, necesită valoarea semnată image_dimensions_token din răspunsul original al încărcării asociate modelului; copiaz-o în elementul de referință ca imageDimensionsToken și copiază size_bytes ca sizeBytes. O recuperare ulterioară a metadatelor fișierului poate returna acest token ca null, așadar reîncarcă imaginea sursă dacă tokenul original nu mai este disponibil sau a expirat.

Pentru încărcările video acceptate de Video8 și Wan 3.0, Rivya inspectează octeții MP4 sau MOV și returnează video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes și video_metadata_token. Copiază-le în elementul de referință ca width, height, framesPerSecond, videoBitrateMbps, sizeBytes și videoMetadataToken. Tokenul este asociat contului, modelului țintă, URL-ului, tipului MIME, dimensiunilor, ratei de cadre, bitrate-ului și dimensiunii fișierului încărcat. Durata este verificată separat prin durationToken. O recuperare ulterioară a metadatelor fișierului poate returna video_metadata_token ca null; reîncarcă videoclipul sursă în loc să inventezi metadate.

Recuperează metadatele fișierului

Folosește GET /api/v1/files/{fileId} pentru a citi metadatele unui fișier deținut de același cont Rivya:

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

Răspunsul folosește aceeași structură PublicApiFile ca încărcarea. Dacă fișierul aparține altui cont sau nu mai este disponibil, API-ul returnează not_found.

Folosește încărcarea în parametrii de generare

Nu trimite un câmp de nivel superior files către POST /api/v1/generations.

Pentru integrări noi, transmite rezultatul încărcării prin 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"
}

Pentru video sau 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"
}

Setul complet de câmpuri video semnate de mai sus este obligatoriu pentru referințele video Video8 și Wan 3.0. Referințele audio Wan 3.0 folosesc mimeType, sizeBytes, durationSeconds și durationToken; referințele imagine folosesc contractul de metadate specific modelului descris mai sus.

Pentru Seedream 5.0 Pro Layer Decomposition, trimite exact o imagine și metadatele semnate returnate de încărcarea asociată modelului:

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

Unii parametri mai vechi ai modelelor folosesc încă anumite câmpuri URL specifice modelului. Dacă Referința API pentru modele documentează un anumit parametru, urmează pagina modelului respectiv în loc să inventezi un câmp nou.

Erori

Files API folosește aceeași structură publică de eroare ca restul Rivya API:

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

Cazuri frecvente:

Note de securitate

Nu stoca chei API complete în browsere, clienți mobili, jurnale, evenimente de analiză sau capturi de ecran.

Tratează URL-urile fișierelor încărcate și valorile duration_token, image_dimensions_token și video_metadata_token ca materiale temporare de integrare. Folosește-le numai pentru a construi cererea de generare următoare și nu le expune în pagini publice.

Pagini asociate

• Creează o generare

• Rivya TypeScript SDK

• Referința API pentru modele

• Erori și limite API

• Contract OpenAPI și schemă