Files API

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

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:

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

Grensene for signerte bildereferanser omfatter:

Hvert referansebilde for Image5, Grok Imagine Image 2.0 eller Wan 3.0 må lastes opp med den aktuelle målmodellen i model. Behold width, height, size_bytes og image_dimensions_token fra den opprinnelige responsen. Genereringsforespørselen må sende dem som width, height, sizeBytes og imageDimensionsToken. Vilkårlige eksterne bilde-URL-er oppfyller ikke denne modellbundne valideringen.

Layer Decomposition validerer i tillegg de registrerte bildedimensjonene før opplasting: totalt 262 144–36 000 000 piksler og et sideforhold fra 1:16 til 16:1.

Modellspesifikke opplastingsgrenser for Video8 omfatter:

Dette er Rivyas godtatte opplastingsgrenser, som kan være lavere enn grensene til en oppstrømstjeneste. Last opp hver Video8- eller Wan 3.0-referanse med den aktuelle målmodellen i model. Referansevideoer krever både det signerte varighetsbeviset og de signerte videometadataene fra den opprinnelige modellbundne opplastingsresponsen. Varighetstoken for Wan 3.0-lyd binder også den registrerte MIME-typen og opplastingens byte-størrelse.

Wan 3.0-bilder må være 240–8 000 piksler per side, og videoer må være 240–4 096 piksler per side; begge må holde seg innenfor sideforholdet 1:8–8:1. I referansemodus har video og lyd separate totalgrenser på 15 sekunder, og lyd kan ikke være den eneste referansetypen.

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-lite" \
  -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-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-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-lite",
            "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,
  "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
}

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.

For støttede bildeopplastinger registreres width og height fra selve filbyteinnholdet. Alle de fem Image5-modellene, Grok Imagine Image 2.0 og Wan 3.0 krever den signerte image_dimensions_token fra den opprinnelige modellbundne opplastingsresponsen. Kopier den til referanseoppføringen som imageDimensionsToken, og kopier size_bytes som sizeBytes. Et senere kall for å hente filmetadata kan returnere tokenet som null; last derfor opp kildebildet på nytt hvis det opprinnelige tokenet ikke er tilgjengelig eller har utløpt.

For støttede Video8- og Wan 3.0-videoopplastinger undersøker Rivya MP4- eller MOV-byteinnholdet og returnerer video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes og video_metadata_token. Kopier dem til referanseoppføringen som width, height, framesPerSecond, videoBitrateMbps, sizeBytes og videoMetadataToken. Tokenet er bundet til kontoen, målmodellen, URL-en, MIME-typen, dimensjonene, bildefrekvensen, bithastigheten og opplastingsstørrelsen. Varigheten verifiseres separat med durationToken. Et senere kall for å hente filmetadata kan returnere video_metadata_token som null; last opp kildevideoen på nytt i stedet for å finne på metadata.

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

For video eller lyd:

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

Alle de signerte videofeltene ovenfor er påkrevd for Video8- og Wan 3.0-videoreferanser. Wan 3.0-lydreferanser bruker mimeType, sizeBytes, durationSeconds og durationToken; bildereferanser bruker den modellspesifikke bildemetadatakontrakten som er beskrevet ovenfor.

For Seedream 5.0 Pro Layer Decomposition sender du nøyaktig ett bilde og de signerte metadataene som ble returnert av den modellbundne opplastingen:

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

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:

Sikkerhetsnotater

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

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

Relaterte sider

• Opprett generering

• Rivya TypeScript SDK

• Modell-API-referanse

• API-feil og begrensninger

• OpenAPI- og schema-kontrakt