Files API

Használd a POST /api/v1/files endpointot referencia média feltöltéséhez olyan modellekhez, amelyek kép-, videó- vagy hangbemenetet igényelnek.

A Files API kizárólag referencia bemenetekhez való. Önmagában nem hoz létre generálási feladatokat. Feltöltés után add át a visszakapott url értéket és metaadatokat a modell params mezőibe, általában a params.referenceMediaItems alatt.

Endpoint

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

Szükséges headerek:

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

Az API-kulcsnak tartalmaznia kell a files:create scope-ot feltöltéshez, és a files:read scope-ot metaadatok lekéréséhez. Az újonnan létrehozott Rivya API-kulcsok alapértelmezés szerint mindkét scope-ot tartalmazzák.

Multipart mezők

Használd a model mezőt, amikor a fájlt egy konkrét modellhez szánod. Így modell-specifikus MIME- és méretellenőrzést kapsz, mielőtt a rendszer elfogadja a fájlt.

Feltöltési limitek

A Files API ugyanazt a feltöltési szabályzatot használja, mint a Rivya referenciafeltöltései.

Alapértelmezett limitek:

Egyes modellek eltérő limitekkel rendelkeznek. Például bizonyos referencia-képes modellek nagyobb képeket engednek, bizonyos videóreferencia-modellek pedig a termék által biztonságosan fogadható feltöltési határig engednek fájlokat. Mindig add át a model mezőt, ha ismered a célmodellt, és olvasd el a Modell API referenciát, mielőtt felhasználói feltöltéseket fogadnál.

Az aláírt referenciaképekre vonatkozó limitek:

Minden Image5, Grok Imagine Image 2.0 vagy Wan 3.0 referenciaképet a célmodellhez tartozó model mezővel kell feltölteni. Őrizd meg az eredeti válasz width, height, size_bytes és image_dimensions_token értékét; a generálási kérésben ezeket width, height, sizeBytes és imageDimensionsToken néven kell elküldeni. Tetszőleges külső kép-URL nem felel meg ennek a modellhez kötött ellenőrzésnek.

A rétegekre bontás a feltöltés előtt a felismert képméreteket is ellenőrzi: az összes pixelszám 262,144 és 36,000,000 közé, a képarány pedig 1:16 és 16:1 közé kell essen.

A Video8 és Wan 3.0 modellekre vonatkozó feltöltési limitek:

Ezek a Rivya által elfogadott feltöltési plafonok, amelyek alacsonyabbak lehetnek egy upstream szolgáltatás korlátainál. Minden Video8 vagy Wan 3.0 referenciát a célmodellhez tartozó model mezővel tölts fel. A referenciavideókhoz az eredeti, modellhez kötött feltöltési válasz aláírt időtartam-igazolása és aláírt videómetaadatai egyaránt szükségesek. A Wan 3.0 hang-időtartamtokenjei az észlelt MIME-típushoz és a feltöltés bájtméretéhez is kötődnek.

A Wan 3.0 képeinek oldalanként 240–8 000, videóinak oldalanként 240–4 096 pixel között kell lenniük; mindkét médiatípus képaránya az 1:8–8:1 tartományban marad. Referencia módban a videó és a hang külön-külön 15 másodperces összesített korláttal rendelkezik, és a hang nem lehet az egyetlen referenciatípus.

A Rivya az észlelt fájlszignatúrát ellenőrzi, nem csak a fájlnév kiterjesztését.

curl példa

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"

JavaScript példa

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

Python példa

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

Válasz

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

Videó- és hangfeltöltéseknél a duration_seconds kitöltődhet. Ha egy modell időtartam-ellenőrzést igényel, másold a duration_token értéket a kapcsolódó generálási paraméterbe durationToken néven.

A támogatott képfeltöltéseknél a width és a height értékét a rendszer a fájl bájtjaiból állapítja meg. Mind az öt Image5 modell, a Grok Imagine Image 2.0 és a Wan 3.0 is megköveteli az eredeti, modellhez kötött feltöltési válasz aláírt image_dimensions_token értékét; ezt imageDimensionsToken néven, a size_bytes értékét pedig sizeBytes néven másold a referenciaelembe. Egy későbbi fájlmetaadat-lekérés ezt a tokent null értékkel adhatja vissza, ezért töltsd fel újra a forrásképet, ha az eredeti token már nem érhető el vagy lejárt.

A támogatott Video8 és Wan 3.0 videófeltöltéseknél a Rivya megvizsgálja az MP4 vagy MOV fájl bájtjait, és visszaadja a video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes és video_metadata_token értékeket. Másold ezeket a referenciaelembe width, height, framesPerSecond, videoBitrateMbps, sizeBytes és videoMetadataToken néven. A token a fiókhoz, a célmodellhez, az URL-hez, a MIME-típushoz, a méretekhez, a képkockasebességhez, a bitrátához és a feltöltési mérethez kötődik. Az időtartamot a rendszer külön, a durationToken segítségével ellenőrzi. Egy későbbi fájlmetaadat-lekérés a video_metadata_token értékét null értékkel adhatja vissza; ilyenkor töltsd fel újra a forrásvideót ahelyett, hogy metaadatokat találnál ki.

Fájlmetaadatok lekérése

Használd a GET /api/v1/files/{fileId} endpointot ugyanahhoz a Rivya-fiókhoz tartozó fájl metaadatainak olvasásához:

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

A válasz ugyanazt a PublicApiFile formát használja, mint a feltöltés. Ha a fájl másik fiókhoz tartozik, vagy már nem érhető el, az API not_found választ ad.

A feltöltés használata generálási params mezőben

Ne küldj felső szintű files mezőt a POST /api/v1/generations kéréshez.

Új integrációknál a feltöltés eredményét a params.referenceMediaItems mezőn keresztül add át:

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

Videóhoz vagy hanghoz:

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

A fenti teljes aláírt videómező-készlet kötelező a Video8 és Wan 3.0 videóreferenciáihoz. A Wan 3.0 hangreferenciái a mimeType, sizeBytes, durationSeconds és durationToken mezőt használják; a képreferenciák pedig a fent leírt, modell-specifikus képmetaadat-szerződést követik.

A Seedream 5.0 Pro Layer Decomposition modellhez pontosan egy képet és a modellhez kötött feltöltésből kapott aláírt metaadatokat küldd:

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

Néhány régebbi modellparaméter továbbra is modell-specifikus URL mezőket használ. Ha a Modell API referencia konkrét paramétert dokumentál, kövesd azt a modelloldalt, ne találj ki új mezőt.

Hibák

A Files API ugyanazt a nyilvános hibaborítékot használja, mint a Rivya API többi része:

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

Gyakori esetek:

Biztonsági megjegyzések

Ne tárolj teljes API-kulcsokat böngészőkben, mobilkliensekben, logokban, analitikai eseményekben vagy képernyőképeken.

A feltöltött fájl URL-eket, valamint a duration_token, image_dimensions_token és video_metadata_token értékeket ideiglenes integrációs anyagként kezeld. Csak a következő generálási kérés felépítéséhez használd őket, és ne tedd ki nyilvános oldalakra.

Kapcsolódó oldalak

• Generálás létrehozása

• Rivya TypeScript SDK

• Modell API referencia

• API hibák és limitek

• OpenAPI és séma szerződés