Tải lên tệp tham chiếu hình ảnh, video hoặc âm thanh cho yêu cầu generation của Rivya API, với kiểm tra MIME, giới hạn kích thước và duration tokens.

Dùng POST /api/v1/files để tải media tham chiếu lên cho các mô hình cần input hình ảnh, video hoặc âm thanh.

Files API chỉ dành cho input tham chiếu. Bản thân nó không tạo tác vụ generation. Sau khi tải lên, hãy truyền url và metadata được trả về vào params của mô hình, thường thông qua params.referenceMediaItems.

Endpoint

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

Headers bắt buộc:

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

API key phải bao gồm scope files:create để tải lên và files:read để lấy metadata. Rivya API keys mới tạo mặc định bao gồm cả hai scope.

Trường multipart

Trường	Kiểu	Bắt buộc	Ghi chú
`file`	binary	có	Tệp hình ảnh, video hoặc âm thanh cần tải lên.
`kind`	string	có	Một trong `image`, `video` hoặc `audio`.
`model`	string	không	Public model ID. Khi có trường này, Rivya xác thực rằng mô hình chấp nhận loại tệp này.
`client_request_id`	string	không	Trace ID của bạn, tối đa 128 ký tự.

Dùng model khi tệp được dùng cho một mô hình cụ thể. Điều này giúp bạn có kiểm tra MIME và kích thước theo mô hình trước khi tệp được chấp nhận.

Giới hạn tải lên

Files API dùng cùng chính sách tải lên như Rivya reference uploads.

Giới hạn mặc định:

Loại	Kích thước tối đa mặc định	MIME phổ biến
`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`

Một số mô hình có giới hạn khác. Ví dụ, một số mô hình reference-image cho phép ảnh lớn hơn, và một số mô hình video-reference cho phép tệp tới mức trần tải lên an toàn ở rìa sản phẩm. Luôn truyền model khi bạn biết mô hình đích, và đọc Tham chiếu API mô hình trước khi chấp nhận tệp tải lên từ người dùng.

Rivya xác thực chữ ký tệp được phát hiện, không chỉ phần mở rộng tên tệp.

Ví dụ 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"

Ví dụ 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);

Ví dụ 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"])

Phản hồi

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

Với tải lên video và âm thanh, duration_seconds có thể được điền. Khi mô hình yêu cầu xác minh thời lượng, hãy sao chép duration_token vào tham số generation liên quan dưới dạng durationToken.

Lấy metadata tệp

Dùng GET /api/v1/files/{fileId} để đọc metadata cho tệp thuộc cùng tài khoản Rivya:

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

Phản hồi dùng cùng cấu trúc PublicApiFile như upload. Nếu tệp thuộc tài khoản khác hoặc không còn khả dụng, API trả về not_found.

Dùng tệp tải lên trong generation params

Không gửi trường files cấp cao nhất tới POST /api/v1/generations.

Với tích hợp mới, truyền kết quả upload qua 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"
}

Với video hoặc âm thanh:

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

Một số tham số mô hình cũ vẫn dùng trường URL riêng theo mô hình. Nếu Tham chiếu API mô hình ghi rõ một tham số cụ thể, hãy làm theo trang mô hình đó thay vì tự đặt trường mới.

Lỗi

Files API dùng cùng public error envelope như phần còn lại của Rivya API:

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

Các trường hợp thường gặp:

HTTP	Code	Nguyên nhân
400	`validation_failed`	Thiếu `file`, `kind` không được hỗ trợ, MIME type không được hỗ trợ, tệp quá lớn hoặc mô hình không chấp nhận kind đã chọn.
401	`api_key_missing` / `api_key_invalid`	Thiếu hoặc Bearer API key không hợp lệ.
403	`api_scope_denied`	Key không bao gồm `files:create` hoặc `files:read` cho hành động được yêu cầu.
429	`rate_limited`	Quá nhiều lượt tải tệp lên trong phút hiện tại.
503	`public_api_disabled`	Public API bị tắt trong môi trường hiện tại.

Ghi chú bảo mật

Không lưu API keys đầy đủ trong trình duyệt, client di động, log, sự kiện analytics hoặc ảnh chụp màn hình.

Hãy coi URL tệp đã tải lên và giá trị duration_token là vật liệu tích hợp tạm thời. Chỉ dùng chúng để xây dựng yêu cầu generation tiếp theo, và đừng để lộ chúng trên trang công khai.

Files API