Upload billed-, video- eller audioreferencefiler til Rivya API-genereringsanmodninger med MIME-kontrol, størrelsesgrænser og duration tokens.

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

Felt	Type	Påkrævet	Noter
`file`	binary	ja	Billed-, video- eller audiofilen, der skal uploades.
`kind`	string	ja	En af `image`, `video` eller `audio`.
`model`	string	nej	Offentlig model-ID. Når den er angivet, validerer Rivya, at modellen accepterer denne filtype.
`client_request_id`	string	nej	Dit trace-ID, op til 128 tegn.

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:

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

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

Rivya validerer den registrerede filsignatur, ikke kun filnavnets extension.

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

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
}

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.

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",
  "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 audio:

{
  "url": "https://...",
  "kind": "video",
  "name": "source.mov",
  "mimeType": "video/quicktime",
  "durationSeconds": 12.4,
  "durationToken": "duration_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:

HTTP	Code	Årsag
400	`validation_failed`	Manglende `file`, ikke-understøttet `kind`, ikke-understøttet MIME-type, for stor fil, eller modellen accepterer ikke den valgte type.
401	`api_key_missing` / `api_key_invalid`	Manglende eller ugyldig Bearer API-nøgle.
403	`api_scope_denied`	Nøglen inkluderer ikke `files:create` eller `files:read` for den ønskede handling.
429	`rate_limited`	For mange filuploads i det aktuelle minut.
503	`public_api_disabled`	Public API er deaktiveret i det aktuelle miljø.

Sikkerhedsnoter

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

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

Files API