Files API

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

Files API hanya digunakan untuk input referensi. API ini tidak membuat tugas generasi secara langsung. Setelah file diunggah, teruskan 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 memiliki scope files:create untuk mengunggah dan files:read untuk mengambil metadata. API key Rivya yang baru dibuat menyertakan kedua scope tersebut secara default.

Field Multipart

Gunakan model saat file ditujukan untuk model tertentu. Dengan begitu, validasi MIME dan ukuran khusus model dilakukan sebelum file diterima.

Batas Unggahan

Files API menggunakan kebijakan unggahan yang sama dengan unggahan referensi Rivya.

Batas default:

Beberapa model memiliki batas berbeda. Misalnya, model referensi gambar tertentu menerima gambar yang lebih besar, sedangkan model referensi video tertentu menerima file hingga batas maksimum yang dapat diterima produk dengan aman. Selalu sertakan model jika Anda mengetahui model tujuan, dan baca Referensi API Model sebelum menerima unggahan pengguna.

Batas referensi gambar bertanda tangan mencakup:

Setiap gambar referensi Image5, Grok Imagine Image 2.0, atau Wan 3.0 harus diunggah dengan model tujuannya. Simpan width, height, size_bytes, dan image_dimensions_token dari respons asli; permintaan generasi harus mengirimkannya sebagai width, height, sizeBytes, dan imageDimensionsToken. URL gambar eksternal apa pun tidak memenuhi validasi yang terikat ke model ini.

Layer decomposition juga memvalidasi dimensi gambar yang terdeteksi sebelum unggahan: total 262,144–36,000,000 piksel dan rasio aspek dari 1:16 hingga 16:1.

Batas unggahan khusus model Video8 dan Wan 3.0 mencakup:

Batas tersebut adalah batas unggahan yang diterima Rivya dan mungkin lebih rendah daripada batas layanan penyedia model. Unggah setiap referensi Video8 atau Wan 3.0 dengan model tujuannya. Video referensi memerlukan bukti durasi bertanda tangan dan metadata video bertanda tangan dari respons unggahan asli yang terikat ke model. Token durasi audio Wan 3.0 juga terikat ke jenis MIME yang terdeteksi dan ukuran byte unggahan.

Gambar Wan 3.0 harus berukuran 240–8.000 piksel pada setiap sisi, sedangkan video harus berukuran 240–4.096 piksel pada setiap sisi; keduanya harus berada dalam batas rasio aspek 1:8–8:1. Dalam mode referensi, video dan audio memiliki batas total terpisah sebesar 15 detik, dan audio tidak dapat menjadi satu-satunya jenis referensi.

Rivya memvalidasi tanda tangan berkas 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-lite" \
  -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-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);

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

Untuk unggahan video dan audio, duration_seconds dapat terisi. Jika model memerlukan verifikasi durasi, salin duration_token ke parameter generasi terkait sebagai durationToken.

Untuk unggahan gambar yang didukung, width dan height dideteksi dari byte file. Kelima model Image5, Grok Imagine Image 2.0, dan Wan 3.0 memerlukan image_dimensions_token bertanda tangan dari respons unggahan asli yang terikat ke model; salin nilainya ke item referensi sebagai imageDimensionsToken, dan salin size_bytes sebagai sizeBytes. Permintaan metadata file berikutnya dapat mengembalikan token tersebut sebagai null, jadi unggah ulang gambar sumber jika token asli tidak tersedia atau sudah kedaluwarsa.

Untuk unggahan video Video8 dan Wan 3.0 yang didukung, Rivya memeriksa byte MP4 atau MOV dan mengembalikan video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, dan video_metadata_token. Salin sebagai width, height, framesPerSecond, videoBitrateMbps, sizeBytes, dan videoMetadataToken pada item referensi. Token tersebut terikat ke akun, model tujuan, URL, jenis MIME, dimensi, frame rate, bitrate, dan ukuran unggahan. Durasi diverifikasi secara terpisah dengan durationToken. Permintaan metadata file berikutnya dapat mengembalikan video_metadata_token sebagai null; unggah ulang video sumber dan jangan membuat metadata sendiri.

Mengambil Metadata File

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

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

Respons menggunakan struktur PublicApiFile yang sama seperti unggahan. Jika file dimiliki akun lain atau sudah tidak tersedia, API mengembalikan not_found.

Menggunakan Unggahan dalam Params Generasi

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

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

Untuk video atau audio:

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

Seluruh field video bertanda tangan di atas wajib disertakan untuk referensi video Video8 dan Wan 3.0. Referensi audio Wan 3.0 menggunakan mimeType, sizeBytes, durationSeconds, dan durationToken; referensi gambar mengikuti kontrak metadata gambar khusus model yang dijelaskan di atas.

Untuk Seedream 5.0 Pro Layer Decomposition, kirim tepat satu gambar beserta metadata bertanda tangan yang dikembalikan oleh unggahan yang terikat ke model:

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

Beberapa parameter model lama masih menggunakan field URL khusus model. Jika Referensi API Model mendokumentasikan parameter tertentu, ikuti halaman model tersebut dan jangan membuat field baru.

Error

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

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

Kasus umum:

Catatan Keamanan

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

Perlakukan URL file yang diunggah serta nilai duration_token, image_dimensions_token, dan video_metadata_token sebagai materi integrasi sementara. Gunakan hanya untuk menyusun permintaan generasi lanjutan, dan jangan mengeksposnya di halaman publik.

Halaman Terkait

• Membuat Generasi

• Rivya TypeScript SDK

• Referensi API Model

• Error dan Batas API

• Kontrak OpenAPI dan Schema