Nahrávejte obrazové, video nebo audio referenční soubory pro požadavky na generování v Rivya API, včetně kontrol MIME, limitů velikosti a tokenů délky.

Použijte POST /api/v1/files k nahrání referenčních médií pro modely, které potřebují obrazové, video nebo audio vstupy.

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é headery:

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

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

Multipart pole

Pole	Typ	Povinné	Poznámky
`file`	binary	ano	Obrazový, video nebo audio soubor k nahrání.
`kind`	string	ano	Jedna z hodnot `image`, `video` nebo `audio`.
`model`	string	ne	Veřejné ID modelu. Pokud je uvedeno, Rivya ověří, že model přijímá tento druh souboru.
`client_request_id`	string	ne	Vaše trace ID, maximálně 128 znaků.

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í uploady Rivya.

Výchozí limity:

Druh	Výchozí maximální velikost	Běžné MIME typy
`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`

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 produktového bezpečného upload stropu. Když znáte cílový model, vždy předejte model a před přijímáním uživatelských uploadů si přečtěte referenci modelového API.

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" \
  -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");
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",
            "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,
  "created_at": "2026-05-11T00:00:00.000Z",
  "expires_at": null
}

U video a audio uploadů 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.

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 upload. Pokud soubor patří jinému účtu nebo už není dostupný, API vrátí not_found.

Použití uploadu v parametrech generování

Neposílejte top-level pole files do POST /api/v1/generations.

U nových integrací předejte výsledek uploadu přes params.referenceMediaItems:

{
  "model": "nano-banana-2",
  "prompt": "Uprav styl této produktové fotografie pro čistou editorialní stránku katalogu",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  },
  "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"
}

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:

HTTP	Kód	Příčina
400	`validation_failed`	Chybí `file`, nepodporovaný `kind`, nepodporovaný MIME typ, příliš velký soubor nebo model nepřijímá vybraný druh.
401	`api_key_missing` / `api_key_invalid`	Chybí Bearer API klíč nebo je neplatný.
403	`api_scope_denied`	Klíč neobsahuje `files:create` nebo `files:read` pro požadovanou akci.
429	`rate_limited`	V aktuální minutě proběhlo příliš mnoho uploadů souborů.
503	`public_api_disabled`	Public API je v aktuálním prostředí vypnuté.

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 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.

Files API