Tiedosto-API

Käytä POST /api/v1/files -endpointtia referenssimedian lataamiseen malleille, jotka tarvitsevat kuva-, video- tai audiosyötteitä.

Files API on tarkoitettu vain referenssisyötteille. Se ei luo generointitehtäviä yksinään. Latauksen jälkeen anna palautettu url ja metadata mallin params-kenttiin, yleensä params.referenceMediaItems-rakenteen kautta.

Rajapintareitti

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

Vaaditut headerit:

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

API-avaimessa täytyy olla files:create-käyttöoikeus lataamista varten ja files:read metatietojen hakemista varten. Uudet Rivya API -avaimet sisältävät molemmat oikeudet oletuksena.

Multipart-kentät

Käytä model-kenttää, kun tiedosto on tarkoitettu tietylle mallille. Näin saat mallikohtaisen MIME- ja kokotarkistuksen ennen tiedoston hyväksymistä.

Latausrajat

Files API käyttää samaa latauskäytäntöä kuin Rivyan referenssilataukset.

Oletusrajat:

Joillakin malleilla on eri rajat. Esimerkiksi tietyt referenssikuvamallit sallivat suuremmat kuvat, ja tietyt videoreferenssimallit sallivat tiedostoja tuotteen turvalliseen latausrajaan asti. Anna aina model, kun tiedät kohdemallin, ja lue mallien API-viite ennen käyttäjälatausten hyväksymistä.

Allekirjoitettujen kuvareferenssien rajat ovat:

Jokainen Image5-, Grok Imagine Image 2.0- tai Wan 3.0 -referenssikuva on ladattava kohdemallin tunnuksella model. Säilytä alkuperäisen vastauksen width, height, size_bytes ja image_dimensions_token; generointipyynnön on lähetettävä ne nimillä width, height, sizeBytes ja imageDimensionsToken. Mielivaltaiset ulkoiset kuva-URL-osoitteet eivät täytä tätä malliin sidottua validointia.

Layer Decomposition validoi lisäksi tiedostosta havaitut kuvan mitat ennen latausta: yhteensä 262 144–36 000 000 pikseliä ja kuvasuhde väliltä 1:16 aina suhteeseen 16:1.

Video8-mallien mallikohtaiset latausrajat ovat:

Nämä ovat Rivyan hyväksymät latauskatot, jotka voivat olla ulkoisen palvelun rajaa matalammat. Lataa jokainen Video8- tai Wan 3.0 -referenssi kohdearvolla model. Referenssivideot tarvitsevat sekä allekirjoitetun kestotodisteen että alkuperäisen malliin sidotun latausvastauksen allekirjoitetut videometatiedot. Wan 3.0 -audion kestotoken sitoo myös havaitun MIME-tyypin ja latauksen tavukoon.

Wan 3.0 -kuvien sivujen on oltava 240–8 000 pikseliä ja videoiden sivujen 240–4 096 pikseliä; molempien kuvasuhteen on pysyttävä välillä 1:8–8:1. Referenssitilassa videolla ja audiolla on erilliset 15 sekunnin kokonaisrajat, eikä audio voi olla ainoa referenssityyppi.

Rivya tarkistaa havaitun tiedostosignatuurin, ei pelkästään tiedostonimen päätettä.

curl-esimerkki

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

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

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

Vastaus

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

Video- ja audiolatauksissa duration_seconds voi täyttyä. Kun malli vaatii keston tarkistusta, kopioi duration_token liittyvään generointiparametriin nimellä durationToken.

Tuetuissa kuvalatauksissa width ja height havaitaan tiedoston tavuista. Kaikki viisi Image5-mallia, Grok Imagine Image 2.0 ja Wan 3.0 vaativat alkuperäisen malliin sidotun latausvastauksen allekirjoitetun image_dimensions_token-arvon; kopioi se referenssikohteeseen nimellä imageDimensionsToken ja kopioi size_bytes nimellä sizeBytes. Myöhempi tiedostometadatan haku voi palauttaa tokenin arvona null, joten lataa lähdekuva uudelleen, jos alkuperäinen token ei ole saatavilla tai se on vanhentunut.

Tuetuissa Video8- ja Wan 3.0 -videolatauksissa Rivya tarkistaa MP4- tai MOV-tiedoston tavut ja palauttaa kentät video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes ja video_metadata_token. Kopioi ne referenssikohteeseen nimillä width, height, framesPerSecond, videoBitrateMbps, sizeBytes ja videoMetadataToken. Token sidotaan tiliin, kohdemalliin, URL-osoitteeseen, MIME-tyyppiin, mittoihin, kuvataajuuteen, bittinopeuteen ja latauskokoon. Kesto tarkistetaan erikseen durationToken-arvolla. Myöhempi tiedostometadatan haku voi palauttaa video_metadata_token-arvon null; lataa lähdevideo uudelleen sen sijaan, että keksisit metatiedot itse.

Hae tiedoston metadata

Käytä GET /api/v1/files/{fileId} -endpointtia samalle Rivya-tilille kuuluvan tiedoston metadatan lukemiseen:

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

Vastaus käyttää samaa PublicApiFile-muotoa kuin lataus. Jos tiedosto kuuluu toiselle tilille tai ei ole enää saatavilla, API palauttaa virheen not_found.

Käytä latausta generointiparametreissa

Älä lähetä ylätason files-kenttää endpointille POST /api/v1/generations.

Uusissa integraatioissa anna lataustulos params.referenceMediaItems-rakenteen kautta:

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

Videolle tai audiolle:

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

Edellä olevat täydelliset allekirjoitetut videokentät ovat pakollisia Video8- ja Wan 3.0 -videoreferensseille. Wan 3.0 -audioreferenssit käyttävät kenttiä mimeType, sizeBytes, durationSeconds ja durationToken; kuvareferenssit käyttävät edellä kuvattua mallikohtaista kuvametadatasopimusta.

Lähetä Seedream 5.0 Pro Layer Decomposition -mallille täsmälleen yksi kuva sekä sen malliin sidotun latauksen palauttamat allekirjoitetut metatiedot:

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

Jotkin vanhemmat malliparametrit käyttävät edelleen mallikohtaisia URL-kenttiä. Jos mallien API-viite dokumentoi tietyn parametrin, noudata kyseistä mallisivua uuden kentän keksimisen sijaan.

Virheet

Files API käyttää samaa julkista virhekuorta kuin muu Rivya API:

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

Yleiset tapaukset:

Turvallisuushuomiot

Älä tallenna kokonaisia API-avaimia selaimiin, mobiiliasiakkaisiin, lokeihin, analytiikkatapahtumiin tai kuvakaappauksiin.

Käsittele ladattujen tiedostojen URL-osoitteita sekä duration_token-, image_dimensions_token- ja video_metadata_token-arvoja väliaikaisena integraatiomateriaalina. Käytä niitä vain jatkogenerointipyynnön rakentamiseen äläkä paljasta niitä julkisilla sivuilla.

Liittyvät sivut

• Luo generointi

• Rivyan TypeScript SDK

• Mallien API-viite

• API-virheet ja rajoitukset

• OpenAPI- ja schema-sopimus