Files API

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ı

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:

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 güvenli biçimde kabul edebildiği yükleme üst sınırı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.

İmzalı görüntü referanslarının limitleri şunlardır:

Image5, Grok Imagine Image 2.0 veya Wan 3.0 için kullanılan her referans görüntüsü hedef model değeriyle yüklenmelidir. Özgün yanıttaki width, height, size_bytes ve image_dimensions_token değerlerini saklayın; oluşturma isteği bunları width, height, sizeBytes ve imageDimensionsToken olarak göndermelidir. Herhangi bir harici görüntü URL'si, modele bağlı bu doğrulamanın yerini tutmaz.

Katman ayrıştırma ayrıca yüklemeden önce algılanan görüntü boyutlarını doğrular: toplam 262,144–36,000,000 piksel ve 1:16 ile 16:1 arasında en-boy oranı.

Video referansı kullanan modellere özgü yükleme limitleri şunlardır:

Bunlar Rivya'nın kabul ettiği yükleme tavanlarıdır ve bir üst hizmetin limitlerinden daha düşük olabilir. Her Video8 veya Wan 3.0 referansını hedef model değeriyle yükleyin. Referans videolar, özgün modele bağlı yükleme yanıtındaki hem imzalı süre kanıtını hem de imzalı video metadata bilgilerini gerektirir. Wan 3.0 ses süre token'ları ayrıca algılanan MIME türüne ve yüklemenin bayt boyutuna bağlıdır.

Wan 3.0 görüntülerinin her kenarı 240–8.000 piksel, videolarının her kenarı ise 240–4.096 piksel olmalıdır; her ikisinin en-boy oranı da 1:8–8:1 aralığında kalmalıdır. Referans modunda video ile ses için ayrı ayrı toplam 15 saniye sınırı vardır ve ses tek referans türü olamaz.

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-lite" \
  -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-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 Ö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-lite",
            "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,
  "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 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.

Desteklenen görüntü yüklemelerinde width ve height, dosya baytlarından algılanır. Beş Image5 modelinin tamamı, Grok Imagine Image 2.0 ve Wan 3.0, özgün modele bağlı yükleme yanıtındaki imzalı image_dimensions_token değerini zorunlu tutar; bu değeri referans öğesine imageDimensionsToken, size_bytes değerini de sizeBytes olarak kopyalayın. Dosya metadata bilgileri daha sonra alındığında bu token null dönebilir; özgün token kullanılamıyorsa veya süresi dolmuşsa kaynak görüntüyü yeniden yükleyin.

Desteklenen Video8 ve Wan 3.0 video yüklemelerinde Rivya, MP4 veya MOV baytlarını inceler ve video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes ile video_metadata_token değerlerini döndürür. Bunları referans öğesine sırasıyla width, height, framesPerSecond, videoBitrateMbps, sizeBytes ve videoMetadataToken olarak kopyalayın. Token; hesap, hedef model, URL, MIME türü, boyutlar, kare hızı, bit hızı ve yükleme boyutuna bağlıdır. Süre ayrıca durationToken ile doğrulanır. Dosya metadata bilgileri daha sonra alındığında video_metadata_token değeri null dönebilir; metadata uydurmak yerine kaynak videoyu yeniden yükleyin.

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

Video veya ses için:

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

Yukarıdaki eksiksiz imzalı video alanları, Video8 ve Wan 3.0 video referansları için zorunludur. Wan 3.0 ses referansları mimeType, sizeBytes, durationSeconds ve durationToken kullanır; görüntü referansları ise yukarıda açıklanan modele özgü görüntü metadata sözleşmesini kullanır.

Seedream 5.0 Pro Layer Decomposition için tam olarak bir görüntü ile modele bağlı yüklemenin döndürdüğü imzalı metadata bilgilerini gönderin:

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

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:

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, duration_token, image_dimensions_token ve video_metadata_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.

İlgili Sayfalar

• Oluşturma İşi Başlatma

• Rivya TypeScript SDK

• Model API Referansı

• API Hataları ve Limitleri

• OpenAPI ve Şema Sözleşmesi