Ladda upp bild-, video- eller ljudreferensfiler för Rivya API-genereringsbegäranden, med MIME-kontroller, storleksgränser och längd tokens.

Använd POST /api/v1/files för att ladda upp referensmedia för modeller som behöver bild-, video- eller ljudinput.

Files API är endast för referensindata. Det skapar inte genereringsuppgifter på egen hand. Efter uppladdning skickar du vidare den returnerade url och metadata till modellens params, oftast via params.referenceMediaItems.

Endpoint

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

Nödvändiga headers:

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

API-nyckeln måste innehålla scope files:create för uppladdning och files:read för att hämta metadata. Nyskapade Rivya API-nycklar innehåller båda scopes som standard.

Multipartfält

Fält	Typ	Krävs	Anteckningar
`file`	binary	ja	Bild-, video- eller ljudfilen som ska laddas upp.
`kind`	string	ja	En av `image`, `video` eller `audio`.
`model`	string	nej	Offentligt modell-ID. När det finns validerar Rivya att modellen accepterar den här filtypen.
`client_request_id`	string	nej	Ditt trace-ID, upp till 128 tecken.

Använd model när filen är avsedd för en specifik modell. Då får du modellspecifik MIME- och storleksvalidering innan filen accepteras.

Uppladdningsgränser

Files API använder samma uppladdningspolicy som Rivyas referensuppladdningar.

Standardgränser:

Typ	Standard maxstorlek	Vanliga MIME-typer
`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`

Vissa modeller har andra gränser. Exempelvis tillåter vissa referensbildmodeller större bilder, och vissa videoreferensmodeller tillåter filer upp till produktens edge-safe uppladdningstak. Skicka alltid model när du vet målmodellen, och läs modellreferensen för API innan du accepterar användaruppladdningar.

Rivya validerar den detekterade filsignaturen, inte bara filnamnsändelsen.

curl-exempel

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"

JavaScript-exempel

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

Python-exempel

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

Svar

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

För video- och ljuduppladdningar kan duration_seconds fyllas i. När en modell kräver durationsverifiering kopierar du duration_token till den relaterade genereringsparametern som durationToken.

Hämta filmetadata

Använd GET /api/v1/files/{fileId} för att läsa metadata för en fil som ägs av samma Rivya-konto:

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

Svaret använder samma PublicApiFile-form som uppladdning. Om filen tillhör ett annat konto eller inte längre är tillgänglig returnerar API:et not_found.

Använd uppladdningen i genereringsparams

Skicka inte ett toppnivåfält files till POST /api/v1/generations.

För nya integrationer skickar du uppladdningsresultatet via params.referenceMediaItems:

{
  "model": "nano-banana-2",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  },
  "client_request_id": "order-123-preview"
}

För video eller ljud:

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

Vissa äldre modellparametrar använder fortfarande modellspecifika URL-fält. Om modellreferensen för API dokumenterar en specifik parameter, följ den modellsidan i stället för att hitta på ett nytt fält.

Fel

Files API använder samma offentliga felkuvert som resten av Rivya API:

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

Vanliga fall:

HTTP	Code	Orsak
400	`validation_failed`	`file` saknas, `kind` stöds inte, MIME-typen stöds inte, filen är för stor eller modellen accepterar inte den valda typen.
401	`api_key_missing` / `api_key_invalid`	Bearer API-nyckel saknas eller är ogiltig.
403	`api_scope_denied`	Nyckeln innehåller inte `files:create` eller `files:read` för den begärda åtgärden.
429	`rate_limited`	För många filuppladdningar under den aktuella minuten.
503	`public_api_disabled`	Public API är inaktiverat i den aktuella miljön.

Säkerhetsnoteringar

Lagra inte fullständiga API-nycklar i webbläsare, mobilklienter, loggar, analys-events eller skärmbilder.

Behandla uppladdade fil-URL:er och duration_token-värden som tillfälligt integrationsmaterial. Använd dem endast för att bygga den efterföljande genereringsbegäran och exponera dem inte på offentliga sidor.

Files API