Last opp bilde-, video- eller lydreferansefiler for Rivya API-genereringsforespørsler, med MIME-sjekker, størrelsesgrenser og duration tokens.

Bruk POST /api/v1/files for å laste opp referansemedier for modeller som trenger bilde-, video- eller lydinput.

Files API er bare for referanseinput. Det oppretter ikke genereringsoppgaver alene. Etter opplasting sender du den returnerte url og metadata inn i modellens params, vanligvis gjennom params.referenceMediaItems.

Endepunkt

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

Påkrevde headers:

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

API-nøkkelen må inkludere scopet files:create for opplasting og files:read for å hente metadata. Nyopprettede Rivya API-nøkler inkluderer begge scopene som standard.

Multipart-felt

Field	Type	Required	Notater
`file`	binary	yes	Bilde-, video- eller lydfilen som skal lastes opp.
`kind`	string	yes	En av `image`, `video` eller `audio`.
`model`	string	no	Offentlig modell-ID. Når den er med, validerer Rivya at modellen godtar denne filtypen.
`client_request_id`	string	no	Din trace ID, opptil 128 tegn.

Bruk model når filen er ment for en bestemt modell. Dette gir deg modellspesifikk MIME- og størrelsesvalidering før filen godtas.

Opplastingsgrenser

Files API bruker samme opplastingspolicy som Rivya-referanseopplastinger.

Standardgrenser:

Kind	Standard maks størrelse	Vanlige 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`

Noen modeller har andre grenser. For eksempel tillater utvalgte referansebildemodeller større bilder, og utvalgte videoreferansemodeller tillater filer opp til produktets edge-safe opplastingsgrense. Send alltid med model når du kjenner målmodellen, og les modell-API-referanse før du godtar brukeropplastinger.

Rivya validerer den oppdagede filsignaturen, ikke bare filnavnendelsen.

curl-eksempel

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

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

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

Respons

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

For video- og lydopplastinger kan duration_seconds fylles ut. Når en modell krever varighetsverifisering, kopierer du duration_token inn i den relaterte genereringsparameteren som durationToken.

Hent filmetadata

Bruk GET /api/v1/files/{fileId} for å lese metadata for en fil som eies av samme Rivya-konto:

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

Responsen bruker samme PublicApiFile-form som opplasting. Hvis filen tilhører en annen konto eller ikke lenger er tilgjengelig, returnerer API-et not_found.

Bruk opplastingen i genereringsparams

Ikke send et toppnivåfelt kalt files til POST /api/v1/generations.

For nye integrasjoner sender du opplastingsresultatet gjennom 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"
}

For video eller lyd:

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

Noen eldre modellparametere bruker fortsatt modellspesifikke URL-felt. Hvis modell-API-referanse dokumenterer en bestemt parameter, følg den modellsiden i stedet for å finne opp et nytt felt.

Feil

Files API bruker samme offentlige feilkonvolutt som resten av Rivya API:

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

Vanlige tilfeller:

HTTP	Code	Årsak
400	`validation_failed`	Manglende `file`, ikke-støttet `kind`, ikke-støttet MIME-type, for stor fil eller modellen godtar ikke valgt type.
401	`api_key_missing` / `api_key_invalid`	Manglende eller ugyldig Bearer API-nøkkel.
403	`api_scope_denied`	Nøkkelen inkluderer ikke `files:create` eller `files:read` for den forespurte handlingen.
429	`rate_limited`	For mange filopplastinger i det nåværende minuttet.
503	`public_api_disabled`	Public API er deaktivert i det nåværende miljøet.

Sikkerhetsnotater

Ikke lagre fullstendige API-nøkler i nettlesere, mobilklienter, logger, analytics-hendelser eller skjermbilder.

Behandle opplastede fil-URL-er og duration_token-verdier som midlertidig integrasjonsmateriale. Bruk dem bare til å bygge den påfølgende genereringsforespørselen, og ikke eksponer dem på offentlige sider.

Files API