Fil-API

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.

API-rutt

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 ha behörigheten files:create för uppladdning och files:read för att hämta metadata. Nya Rivya API-nycklar innehåller båda behörigheterna som standard.

Multipartfält

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:

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

Gränser för signerade bildreferenser omfattar:

Varje referensbild för Image5, Grok Imagine Image 2.0 eller Wan 3.0 måste laddas upp med sin målmodell i model. Behåll originalsvarets width, height, size_bytes och image_dimensions_token; genereringsbegäran måste skicka dem som width, height, sizeBytes och imageDimensionsToken. Godtyckliga externa bild-URL:er uppfyller inte den här modellbundna valideringen.

Lageruppdelning validerar dessutom de detekterade bildmåtten före uppladdning: totalt 262,144–36,000,000 pixlar och ett bildförhållande från 1:16 till 16:1.

Modellspecifika uppladdningsgränser för Video8 omfattar:

Det här är Rivyas godkända uppladdningstak, som kan vara lägre än en uppströmstjänsts gräns. Ladda upp varje Video8- eller Wan 3.0-referens med sin målmodell i model. Referensvideor kräver både det signerade varaktighetsbeviset och den signerade videometadatan från det ursprungliga modellbundna uppladdningssvaret. Varaktighetstoken för Wan 3.0-ljud binder även den detekterade MIME-typen och uppladdningens byte-storlek.

Wan 3.0-bilder måste vara 240–8 000 pixlar per sida och videor 240–4 096 pixlar per sida; båda måste hålla sig inom bildförhållandet 1:8–8:1. I referensläge har video och ljud separata sammanlagda gränser på 15 sekunder, och ljud får inte vara den enda referenstypen.

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

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.

För bildformat som stöds detekteras width och height från filens byteinnehåll. Samtliga fem Image5-modeller, Grok Imagine Image 2.0 och Wan 3.0 kräver det signerade image_dimensions_token från det ursprungliga modellbundna uppladdningssvaret; kopiera det till referensposten som imageDimensionsToken och kopiera size_bytes som sizeBytes. En senare hämtning av filmetadata kan returnera token som null, så ladda upp källbilden igen om originaltoken saknas eller har gått ut.

För Video8- och Wan 3.0-videouppladdningar som stöds granskar Rivya MP4- eller MOV-innehållet och returnerar video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes och video_metadata_token. Kopiera dem till referensposten som width, height, framesPerSecond, videoBitrateMbps, sizeBytes och videoMetadataToken. Token är bunden till kontot, målmodellen, URL:en, MIME-typen, måtten, bildfrekvensen, bithastigheten och uppladdningsstorleken. Varaktigheten verifieras separat med durationToken. En senare hämtning av filmetadata kan returnera video_metadata_token som null; ladda upp källvideon igen i stället för att hitta på metadata.

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

För video eller ljud:

{
  "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 fullständiga signerade videofälten ovan krävs för Video8- och Wan 3.0-videoreferenser. Wan 3.0-ljudreferenser använder mimeType, sizeBytes, durationSeconds och durationToken; bildreferenser använder det modellspecifika bildmetadatakontrakt som beskrivs ovan.

För Seedream 5.0 Pro Layer Decomposition ska du skicka exakt en bild och den signerade metadatan som returnerades av dess modellbundna uppladdning:

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

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:

Säkerhetsnoteringar

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

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

Relaterade sidor

• Skapa generation

• Rivya TypeScript SDK

• Modellreferens för API

• API-fel och gränser

• OpenAPI och schemakontrakt