Unggah file referensi gambar, video, atau audio untuk permintaan generasi Rivya API, dengan pemeriksaan MIME, batas ukuran, dan duration token.

Gunakan POST /api/v1/files untuk mengunggah media referensi bagi model yang membutuhkan input gambar, video, atau audio.

Files API hanya untuk input referensi. API ini tidak membuat tugas generasi dengan sendirinya. Setelah upload, kirim url dan metadata yang dikembalikan ke params model, biasanya melalui params.referenceMediaItems.

Endpoint

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

Header wajib:

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

API key harus menyertakan scope files:create untuk upload dan files:read untuk mengambil metadata. API key Rivya yang baru dibuat menyertakan kedua scope secara default.

Field Multipart

Field	Type	Wajib	Catatan
`file`	binary	ya	File gambar, video, atau audio yang akan diunggah.
`kind`	string	ya	Salah satu dari `image`, `video`, atau `audio`.
`model`	string	tidak	ID model publik. Jika ada, Rivya memvalidasi bahwa model menerima jenis file ini.
`client_request_id`	string	tidak	ID pelacakan Anda, hingga 128 karakter.

Gunakan model saat file ditujukan untuk model tertentu. Ini memberi Anda validasi MIME dan ukuran spesifik model sebelum file diterima.

Batas Upload

Files API memakai policy upload yang sama dengan upload referensi Rivya.

Batas default:

Kind	Ukuran maksimum default	Jenis MIME umum
`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`

Sebagian model memiliki batas berbeda. Misalnya, model referensi gambar tertentu mengizinkan gambar lebih besar, dan model referensi video tertentu mengizinkan file hingga batas upload edge-safe produk. Selalu kirim model saat Anda mengetahui model target, dan baca Referensi API Model sebelum menerima upload pengguna.

Rivya memvalidasi signature file yang terdeteksi, bukan hanya ekstensi nama file.

Contoh curl

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"

Contoh JavaScript

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);

Contoh Python

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

Respons

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

Untuk upload video dan audio, duration_seconds dapat terisi. Saat model membutuhkan verifikasi durasi, salin duration_token ke parameter generasi terkait sebagai durationToken.

Mengambil Metadata File

Gunakan GET /api/v1/files/{fileId} untuk membaca metadata file milik akun Rivya yang sama:

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

Respons memakai shape PublicApiFile yang sama seperti upload. Jika file milik akun lain atau tidak lagi tersedia, API mengembalikan not_found.

Memakai Upload Dalam Params Generasi

Jangan kirim field files tingkat atas ke POST /api/v1/generations.

Untuk integrasi baru, kirim hasil upload melalui 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"
}

Untuk video atau audio:

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

Sebagian parameter model lama masih memakai field URL yang spesifik model. Jika Referensi API Model mendokumentasikan parameter tertentu, ikuti halaman model tersebut alih-alih membuat field baru.

Error

Files API memakai error envelope publik yang sama dengan bagian Rivya API lainnya:

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

Kasus umum:

HTTP	Code	Penyebab
400	`validation_failed`	`file` hilang, `kind` tidak didukung, jenis MIME tidak didukung, file terlalu besar, atau model tidak menerima kind yang dipilih.
401	`api_key_missing` / `api_key_invalid`	Bearer API key hilang atau tidak valid.
403	`api_scope_denied`	Key tidak menyertakan `files:create` atau `files:read` untuk tindakan yang diminta.
429	`rate_limited`	Terlalu banyak upload file dalam menit saat ini.
503	`public_api_disabled`	Public API dinonaktifkan di environment saat ini.

Catatan Keamanan

Jangan menyimpan API key lengkap di browser, klien mobile, log, event analytics, atau screenshot.

Perlakukan URL file yang diunggah dan nilai duration_token sebagai material integrasi sementara. Gunakan hanya untuk membuat permintaan generasi lanjutan, dan jangan mengeksposnya di halaman publik.

Files API