MIME kontrolleri, boyut limitleri ve duration token'larıyla Rivya API oluşturma istekleri için görüntü, video veya ses referans dosyaları yükleyin.

Görüntü, video veya ses girdisi gerektiren modeller için referans medyayı yüklemek üzere POST /api/v1/files kullanın.

Files API yalnızca referans girdiler içindir. Tek başına oluşturma görevi oluşturmaz. Yüklemeden sonra dönen url ve metadata bilgilerini model params içine, genellikle params.referenceMediaItems üzerinden gönderin.

Endpoint

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

Gerekli header'lar:

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

API anahtarı yükleme için files:create, metadata alma için files:read scope'unu içermelidir. Yeni oluşturulan Rivya API anahtarları varsayılan olarak iki scope'u da içerir.

Multipart Alanları

Alan	Tür	Gerekli	Notlar
`file`	binary	evet	Yüklenecek görüntü, video veya ses dosyası.
`kind`	string	evet	`image`, `video` veya `audio` değerlerinden biri.
`model`	string	hayır	Public model ID'si. Varsa Rivya, modelin bu dosya türünü kabul ettiğini doğrular.
`client_request_id`	string	hayır	En fazla 128 karakterlik trace ID'niz.

Dosya belirli bir model için kullanılacaksa model gönderin. Böylece dosya kabul edilmeden önce modele özel MIME ve boyut doğrulaması yapılır.

Yükleme Limitleri

Files API, Rivya referans yüklemeleriyle aynı yükleme politikasını kullanır.

Varsayılan limitler:

Tür	Varsayılan maksimum boyut	Yaygın MIME türleri
`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`

Bazı modellerin limitleri farklıdır. Örneğin seçili referans görüntü modelleri daha büyük görüntülere izin verir, seçili video referans modelleri ise ürünün edge-safe yükleme tavanına kadar dosyalara izin verir. Hedef modeli bildiğinizde her zaman model gönderin ve kullanıcı yüklemelerini kabul etmeden önce Model API Referansı sayfasını okuyun.

Rivya yalnızca dosya adı uzantısını değil, algılanan dosya imzasını doğrular.

curl Örneği

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 Örneği

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 Örneği

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

Yanıt

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

Video ve ses yüklemelerinde duration_seconds dolu olabilir. Bir model süre doğrulaması gerektiriyorsa duration_token değerini ilgili oluşturma parametresine durationToken olarak kopyalayın.

Dosya Metadata Bilgilerini Alma

Aynı Rivya hesabına ait bir dosyanın metadata bilgilerini okumak için GET /api/v1/files/{fileId} kullanın:

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

Yanıt, yükleme ile aynı PublicApiFile şeklini kullanır. Dosya başka bir hesaba aitse veya artık kullanılamıyorsa API not_found döndürür.

Yüklemeyi Oluşturma Params İçinde Kullanma

POST /api/v1/generations isteğine üst düzey files alanı göndermeyin.

Yeni entegrasyonlarda yükleme sonucunu params.referenceMediaItems üzerinden gönderin:

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

Video veya ses için:

{
  "url": "https://...",
  "kind": "video",
  "name": "source.mov",
  "mimeType": "video/quicktime",
  "durationSeconds": 12.4,
  "durationToken": "duration_token_from_files_api"
}

Bazı eski model parametreleri hâlâ modele özel URL alanlarını kullanır. Model API Referansı belirli bir parametreyi belgeliyorsa yeni bir alan uydurmak yerine ilgili model sayfasını izleyin.

Hatalar

Files API, Rivya API'nin geri kalanıyla aynı public hata envelope'unu kullanır:

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

Yaygın durumlar:

HTTP	Code	Neden
400	`validation_failed`	`file` eksik, `kind` desteklenmiyor, MIME türü desteklenmiyor, dosya çok büyük veya model seçilen türü kabul etmiyor.
401	`api_key_missing` / `api_key_invalid`	Bearer API anahtarı eksik veya geçersiz.
403	`api_scope_denied`	Anahtar, istenen işlem için `files:create` veya `files:read` içermiyor.
429	`rate_limited`	Geçerli dakika içinde çok fazla dosya yüklemesi var.
503	`public_api_disabled`	Public API geçerli ortamda devre dışı.

Güvenlik Notları

Tam API anahtarlarını tarayıcılarda, mobil istemcilerde, günlüklerde, analiz olaylarında veya ekran görüntülerinde saklamayın.

Yüklenen dosya URL'lerini ve duration_token değerlerini geçici entegrasyon materyali olarak ele alın. Bunları yalnızca devamındaki oluşturma isteğini kurmak için kullanın ve public sayfalarda göstermeyin.

Files API