Muat naik fail rujukan imej, video, atau audio untuk permintaan generation Rivya API, dengan semakan MIME, had saiz, dan token durasi.

Gunakan POST /api/v1/files untuk memuat naik media rujukan bagi model yang memerlukan input imej, video, atau audio.

Files API hanya untuk input rujukan. Ia tidak mencipta tugasan generation dengan sendirinya. Selepas muat naik, hantar url dan metadata yang dikembalikan ke dalam params model, biasanya melalui params.referenceMediaItems.

Endpoint

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

Header diperlukan:

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

API key mesti menyertakan scope files:create untuk muat naik dan files:read untuk mendapatkan metadata. Rivya API key yang baru dicipta menyertakan kedua-dua scope secara lalai.

Medan Multipart

Field	Type	Required	Nota
`file`	binary	yes	Fail imej, video, atau audio untuk dimuat naik.
`kind`	string	yes	Salah satu daripada `image`, `video`, atau `audio`.
`model`	string	no	Public model ID. Apabila ada, Rivya mengesahkan bahawa model menerima jenis fail ini.
`client_request_id`	string	no	Trace ID anda, sehingga 128 aksara.

Gunakan model apabila fail ditujukan untuk model tertentu. Ini memberi anda pengesahan MIME dan saiz khusus model sebelum fail diterima.

Had Muat Naik

Files API menggunakan dasar muat naik yang sama seperti muat naik rujukan Rivya.

Had lalai:

Kind	Saiz maksimum lalai	Jenis MIME lazim
`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`

Sesetengah model mempunyai had berbeza. Contohnya, model rujukan imej tertentu membenarkan imej lebih besar, dan model rujukan video tertentu membenarkan fail sehingga had muat naik produk yang selamat di edge. Sentiasa hantar model apabila anda tahu model sasaran, dan baca Rujukan API Model sebelum menerima muat naik pengguna.

Rivya mengesahkan signature fail yang dikesan, bukan hanya sambungan nama fail.

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 muat naik video dan audio, duration_seconds mungkin diisi. Apabila model memerlukan pengesahan durasi, salin duration_token ke dalam parameter generation berkaitan sebagai durationToken.

Dapatkan Metadata Fail

Gunakan GET /api/v1/files/{fileId} untuk membaca metadata bagi fail yang dimiliki akaun Rivya yang sama:

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

Respons menggunakan bentuk PublicApiFile yang sama seperti muat naik. Jika fail milik akaun lain atau tidak lagi tersedia, API mengembalikan not_found.

Gunakan Muat Naik Dalam Params Generation

Jangan hantar medan files peringkat atas ke POST /api/v1/generations.

Untuk integrasi baharu, hantar hasil muat naik 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"
}

Sesetengah parameter model lama masih menggunakan medan URL khusus model. Jika Rujukan API Model mendokumenkan parameter tertentu, ikut halaman model itu dan jangan mencipta medan baharu.

Ralat

Files API menggunakan envelope ralat awam yang sama seperti seluruh Rivya API:

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

Kes lazim:

HTTP	Code	Sebab
400	`validation_failed`	`file` tiada, `kind` tidak disokong, jenis MIME tidak disokong, fail terlalu besar, atau model tidak menerima kind yang dipilih.
401	`api_key_missing` / `api_key_invalid`	Bearer API key tiada atau tidak sah.
403	`api_scope_denied`	Key tidak menyertakan `files:create` atau `files:read` untuk tindakan yang diminta.
429	`rate_limited`	Terlalu banyak muat naik fail dalam minit semasa.
503	`public_api_disabled`	Public API dilumpuhkan dalam environment semasa.

Nota Keselamatan

Jangan simpan API key penuh dalam pelayar, client mudah alih, log, event analytics, atau tangkapan skrin.

Anggap URL fail yang dimuat naik dan nilai duration_token sebagai bahan integrasi sementara. Gunakannya hanya untuk membina permintaan generation susulan, dan jangan dedahkannya pada halaman awam.

Files API