Files API

Brug POST /api/v1/files til at uploade referencemedier til modeller, der kræver billed-, video- eller audioinput.

Files API er kun til referenceinput. Den opretter ikke selv genereringsopgaver. Efter upload sender du den returnerede url og metadata ind i modellens params, normalt via params.referenceMediaItems.

Endpoint

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

Påkrævede headers:

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

API-nøglen skal inkludere scopet files:create for at uploade og files:read for at hente metadata. Nyoprettede Rivya API-nøgler inkluderer som standard begge scopes.

Multipart-felter

Brug model, når filen er tiltænkt en bestemt model. Det giver dig modelspecifik MIME- og størrelsesvalidering, før filen accepteres.

Uploadgrænser

Files API bruger den samme uploadpolitik som Rivya-referenceuploads.

Standardgrænser:

Nogle modeller har andre grænser. For eksempel tillader udvalgte referencebilledmodeller større billeder, og udvalgte videoreferencemodeller tillader filer op til produktets sikre uploadgrænse. Send altid model, når du kender målmodellen, og læs Model API Reference, før du accepterer brugeruploads.

Grænserne for signerede billedreferencer omfatter:

Hvert referencebillede til Image5, Grok Imagine Image 2.0 eller Wan 3.0 skal uploades med sin målmodel i model. Bevar width, height, size_bytes og image_dimensions_token fra det oprindelige svar; genereringsanmodningen skal sende dem som width, height, sizeBytes og imageDimensionsToken. Vilkårlige eksterne billed-URL'er opfylder ikke denne modelbundne validering.

Layer Decomposition validerer desuden de registrerede billeddimensioner før upload: i alt 262,144–36,000,000 pixels og et billedformat fra 1:16 til 16:1.

Modelspecifikke uploadgrænser for Video8 omfatter:

Dette er Rivyas accepterede uploadgrænser, som kan være lavere end en ekstern tjenestes grænse. Upload hver Video8- eller Wan 3.0-reference med sin målmodel i model. Referencevideoer kræver både det signerede varighedsbevis og de signerede videometadata fra det oprindelige modelbundne uploadsvar. Varighedstokens for Wan 3.0-lyd binder også den registrerede MIME-type og uploadstørrelsen i bytes.

Wan 3.0-billeder skal være 240–8.000 pixels pr. side, og videoer skal være 240–4.096 pixels pr. side; begge skal holde sig inden for billedformatet 1:8–8:1. I referencetilstand har video og lyd separate samlede grænser på 15 sekunder, og lyd må ikke være den eneste referencetype.

Rivya validerer den registrerede filsignatur, ikke kun filnavnets filendelse.

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

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,
  "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 audiouploads kan duration_seconds være udfyldt. Når en model kræver varighedsverifikation, skal du kopiere duration_token ind i den relaterede genereringsparameter som durationToken.

For understøttede billeduploads registreres width og height fra filens bytes. Alle fem Image5-modeller, Grok Imagine Image 2.0 og Wan 3.0 kræver det signerede image_dimensions_token fra det oprindelige modelbundne uploadsvar; kopiér det til referenceelementet som imageDimensionsToken, og kopiér size_bytes som sizeBytes. En senere hentning af filmetadata kan returnere dette token som null, så upload kildebilledet igen, hvis det oprindelige token er utilgængeligt eller udløbet.

For understøttede Video8- og Wan 3.0-videouploads undersøger Rivya MP4- eller MOV-filens bytes og returnerer video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes og video_metadata_token. Kopiér dem til referenceelementet som width, height, framesPerSecond, videoBitrateMbps, sizeBytes og videoMetadataToken. Tokenet er bundet til kontoen, målmodellen, URL'en, MIME-typen, dimensionerne, billedfrekvensen, bitraten og uploadstørrelsen. Varigheden verificeres separat med durationToken. En senere hentning af filmetadata kan returnere video_metadata_token som null; upload kildevideoen igen i stedet for at opfinde metadata.

Hent filmetadata

Brug GET /api/v1/files/{fileId} til at læse metadata for en fil, der ejes af den samme Rivya-konto:

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

Svaret bruger samme PublicApiFile-format som upload. Hvis filen tilhører en anden konto eller ikke længere er tilgængelig, returnerer API'en not_found.

Brug uploaden i genereringsparams

Send ikke et top-level files-felt til POST /api/v1/generations.

For nye integrationer skal uploadresultatet sendes via 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 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"
}

De komplette signerede videofelter ovenfor er påkrævet for Video8- og Wan 3.0-videoreferencer. Wan 3.0-lydreferencer bruger mimeType, sizeBytes, durationSeconds og durationToken; billedreferencer bruger den modelspecifikke kontrakt for billedmetadata, som er beskrevet ovenfor.

For Seedream 5.0 Pro Layer Decomposition skal du sende præcis ét billede og de signerede metadata fra det modelbundne upload:

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

Nogle ældre modelparametre bruger stadig modelspecifikke URL-felter. Hvis Model API Reference dokumenterer en bestemt parameter, skal du følge den modelside i stedet for at opfinde et nyt felt.

Fejl

Files API bruger den samme offentlige fejlkonvolut som resten af Rivya API:

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

Almindelige tilfælde:

Sikkerhedsnoter

Gem ikke fulde API-nøgler i browsere, mobilklienter, logs, analytics-events eller screenshots.

Behandl uploadede fil-URL'er samt værdierne i duration_token, image_dimensions_token og video_metadata_token som midlertidigt integrationsmateriale. Brug dem kun til at bygge den opfølgende genereringsanmodning, og eksponér dem ikke på offentlige sider.

Relaterede sider

• Opret generation

• Rivya TypeScript SDK

• Model API Reference

• API-fejl og grænser

• OpenAPI- og schema-kontrakt