Files API

Použijte POST /api/v1/files k nahrání referenčních médií pro modely, které potřebují vstupy v podobě obrázku, videa nebo audia.

Files API slouží pouze pro referenční vstupy. Samo o sobě nevytváří úlohy generování. Po nahrání předejte vrácené url a metadata do modelových params, obvykle přes params.referenceMediaItems.

Koncový bod

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

Požadované hlavičky:

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

API klíč musí pro nahrání obsahovat oprávnění files:create a pro načtení metadat files:read. Nově vytvořené klíče Rivya API obsahují obě oprávnění ve výchozím nastavení.

Multipart pole

Použijte model, když je soubor určený pro konkrétní model. Získáte tím modelově specifickou validaci MIME a velikosti ještě před přijetím souboru.

Limity nahrávání

Files API používá stejnou zásadu nahrávání jako referenční nahrávání v Rivya.

Výchozí limity:

Některé modely mají jiné limity. Například vybrané modely pro referenční obrázky povolují větší obrázky a vybrané modely s video referencemi povolují soubory až do limitu, který produkt dokáže bezpečně přijmout. Když znáte cílový model, vždy předejte model a před přijímáním uživatelských nahrávek si přečtěte referenci modelového API.

Limity pro podepsané referenční obrázky zahrnují:

Každý referenční obrázek pro Image5, Grok Imagine Image 2.0 nebo Wan 3.0 musí být nahrán se svým cílovým model. Uchovejte width, height, size_bytes a image_dimensions_token z původní odpovědi; požadavek na generování je musí odeslat jako width, height, sizeBytes a imageDimensionsToken. Libovolné externí URL obrázků tuto validaci svázanou s modelem nesplňují.

Rozklad do vrstev navíc před nahráním ověřuje zjištěné rozměry obrázku: celkem 262,144–36,000,000 pixelů a poměr stran od 1:16 do 16:1.

Limity nahrávání specifické pro modely Video8 a Wan 3.0 zahrnují:

Jedná se o limity nahrávání přijímané službou Rivya, které mohou být nižší než limity poskytovatele modelu. Každou referenci Video8 nebo Wan 3.0 nahrajte s jejím cílovým model. Referenční videa vyžadují jak podepsané potvrzení délky, tak podepsaná metadata videa z původní odpovědi na nahrání svázané s modelem. Tokeny délky audia Wan 3.0 jsou navíc svázány se zjištěným MIME typem a velikostí nahraného souboru v bajtech.

Obrázky Wan 3.0 musí mít každý rozměr v rozsahu 240–8 000 pixelů a videa v rozsahu 240–4 096 pixelů; obě média musí dodržet poměr stran 1:8–8:1. V referenčním režimu mají video a audio samostatné souhrnné limity 15 sekund a audio nesmí být jediným druhem reference.

Rivya ověřuje detekovaný podpis souboru, ne pouze příponu názvu souboru.

Příklad 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"

Příklad JavaScriptu

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

Příklad Pythonu

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

Odpověď

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

U nahraného videa a audia může být vyplněno duration_seconds. Když model vyžaduje ověření délky, zkopírujte duration_token do souvisejícího parametru generování jako durationToken.

U podporovaných nahraných obrázků se width a height zjišťují z bajtů souboru. Všech pět modelů Image5, Grok Imagine Image 2.0 i Wan 3.0 vyžaduje podepsaný image_dimensions_token z původní odpovědi na nahrání svázané s modelem; zkopírujte ho do položky reference jako imageDimensionsToken a size_bytes jako sizeBytes. Pozdější načtení metadat souboru může tento token vrátit jako null, takže pokud původní token není dostupný nebo vypršel, nahrajte zdrojový obrázek znovu.

U podporovaných nahraných videí pro Video8 a Wan 3.0 Rivya kontroluje bajty MP4 nebo MOV a vrací video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes a video_metadata_token. Zkopírujte je do položky reference jako width, height, framesPerSecond, videoBitrateMbps, sizeBytes a videoMetadataToken. Token je svázaný s účtem, cílovým modelem, URL, MIME typem, rozměry, snímkovou frekvencí, datovým tokem a velikostí nahraného souboru. Délka se ověřuje samostatně pomocí durationToken. Pozdější načtení metadat souboru může vrátit video_metadata_token jako null; místo vymýšlení metadat nahrajte zdrojové video znovu.

Načtení metadat souboru

Použijte GET /api/v1/files/{fileId} pro načtení metadat souboru, který patří ke stejnému účtu Rivya:

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

Odpověď používá stejný tvar PublicApiFile jako nahrání. Pokud soubor patří jinému účtu nebo už není dostupný, API vrátí not_found.

Použití nahraného souboru v parametrech generování

Pole files neposílejte na nejvyšší úrovni do POST /api/v1/generations.

U nových integrací předejte výsledek nahrání přes 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"
}

Pro video nebo 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"
}

Výše uvedená úplná podepsaná pole videa jsou pro video reference Video8 a Wan 3.0 povinná. Audio reference Wan 3.0 používají mimeType, sizeBytes, durationSeconds a durationToken; obrazové reference používají modelově specifický kontrakt metadat obrázku popsaný výše.

Pro Seedream 5.0 Pro Layer Decomposition odešlete přesně jeden obrázek a podepsaná metadata vrácená jeho nahráním svázaným s modelem:

{
  "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ěkteré starší modelové parametry stále používají modelově specifická URL pole. Pokud reference modelového API dokumentuje konkrétní parametr, postupujte podle stránky daného modelu místo vymýšlení nového pole.

Chyby

Files API používá stejnou veřejnou obálku chyby jako zbytek Rivya API:

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

Běžné případy:

Bezpečnostní poznámky

Neukládejte celé API klíče do prohlížečů, mobilních klientů, logů, analytických událostí ani screenshotů.

URL nahraných souborů a hodnoty duration_token, image_dimensions_token a video_metadata_token považujte za dočasný integrační materiál. Používejte je pouze pro sestavení navazujícího požadavku na generování a nezveřejňujte je na veřejných stránkách.

Související stránky

• Vytvoření generování

• Rivya TypeScript SDK

• Reference modelového API

• Chyby a limity API

• OpenAPI a smlouva schématu