Files API

Dùng POST /api/v1/files để tải lên nội dung đa phương tiện tham chiếu cho các mô hình cần đầu vào hình ảnh, video hoặc âm thanh.

Files API chỉ dành cho đầu vào tham chiếu. API này không tự tạo tác vụ sinh nội dung. Sau khi tải lên, hãy truyền url và siêu dữ liệu được trả về vào params của mô hình, thường là qua params.referenceMediaItems.

Điểm cuối

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

Các header bắt buộc:

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

Khóa API phải có phạm vi files:create để tải lên và files:read để truy xuất siêu dữ liệu. Các khóa Rivya API mới tạo mặc định có cả hai phạm vi này.

Trường multipart

Hãy dùng model khi tệp dành cho một mô hình cụ thể. Nhờ đó, MIME và kích thước sẽ được kiểm tra theo đúng 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ư chức năng tải tệp tham chiếu của Rivya.

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

Một số mô hình có giới hạn khác. Chẳng hạn, một số mô hình dùng ảnh tham chiếu cho phép ảnh lớn hơn, còn một số mô hình dùng video tham chiếu cho phép tệp đạt đến ngưỡng tải lên an toàn tối đa của sản phẩm. Luôn truyền model khi bạn biết mô hình đích và đọc Tài liệu tham chiếu API mô hình trước khi chấp nhận tệp do người dùng tải lên.

Giới hạn cho ảnh tham chiếu có chữ ký gồm:

Mọi ảnh tham chiếu cho Image5, Grok Imagine Image 2.0 hoặc Wan 3.0 đều phải được tải lên cùng model đích. Hãy giữ lại width, height, size_bytes và image_dimensions_token từ phản hồi ban đầu; yêu cầu tạo nội dung phải gửi các giá trị đó dưới dạng width, height, sizeBytes và imageDimensionsToken. URL ảnh bên ngoài tùy ý không đáp ứng được bước xác thực gắn với mô hình này.

Với phân tách lớp, hệ thống còn xác thực kích thước ảnh đã phát hiện trước khi tải lên: tổng số pixel trong khoảng 262,144–36,000,000 và tỷ lệ khung hình từ 1:16 đến 16:1.

Giới hạn tải lên riêng cho các mô hình Video8 và Wan 3.0 gồm:

Đây là các ngưỡng tải lên mà Rivya chấp nhận và có thể thấp hơn giới hạn của dịch vụ thượng nguồn. Hãy tải từng tệp tham chiếu Video8 hoặc Wan 3.0 lên cùng model đích. Video tham chiếu cần cả bằng chứng thời lượng có chữ ký lẫn siêu dữ liệu video có chữ ký từ phản hồi tải lên ban đầu được gắn với mô hình. Token thời lượng âm thanh của Wan 3.0 còn được ràng buộc với kiểu MIME đã phát hiện và kích thước byte của tệp tải lên.

Ảnh Wan 3.0 phải có kích thước 240–8.000 pixel ở mỗi chiều, còn video phải có kích thước 240–4.096 pixel ở mỗi chiều; cả hai phải nằm trong giới hạn tỷ lệ khung hình 1:8–8:1. Trong chế độ tham chiếu, video và âm thanh có các giới hạn tổng thời lượng riêng là 15 giây, đồng thời âm thanh không thể là loại tham chiếu duy nhất.

Rivya xác thực chữ ký thực tế phát hiện trong tệp, không chỉ phần mở rộng của 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-lite" \
  -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-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);

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

Với tệp video và âm thanh được tải lên, duration_seconds có thể có giá trị. Khi một 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ố tạo nội dung liên quan dưới dạng durationToken.

Với tệp ảnh được hỗ trợ, width và height được phát hiện từ chính dữ liệu tệp. Cả năm mô hình Image5, Grok Imagine Image 2.0 và Wan 3.0 đều yêu cầu image_dimensions_token có chữ ký từ phản hồi tải lên ban đầu có gắn mô hình; hãy sao chép token đó vào mục tham chiếu dưới dạng imageDimensionsToken, đồng thời sao chép size_bytes dưới dạng sizeBytes. Lần truy xuất siêu dữ liệu tệp sau đó có thể trả về token này là null, vì vậy hãy tải lại ảnh nguồn nếu token ban đầu không còn hoặc đã hết hạn.

Với các lượt tải video được Video8 và Wan 3.0 hỗ trợ, Rivya kiểm tra dữ liệu MP4 hoặc MOV rồi trả về video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes và video_metadata_token. Hãy sao chép chúng vào mục tham chiếu dưới dạng width, height, framesPerSecond, videoBitrateMbps, sizeBytes và videoMetadataToken. Token được ràng buộc với tài khoản, mô hình đích, URL, kiểu MIME, kích thước, tốc độ khung hình, bitrate và kích thước tệp tải lên. Thời lượng được xác minh riêng bằng durationToken. Lần truy xuất siêu dữ liệu tệp sau đó có thể trả về video_metadata_token là null; hãy tải lại video nguồn thay vì tự tạo siêu dữ liệu.

Truy xuất siêu dữ liệu tệp

Dùng GET /api/v1/files/{fileId} để đọc siêu dữ liệu của một 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ư khi tải lên. 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 params tạo nội dung

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, hãy truyền kết quả tải lên qua 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"
}

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",
  "width": 1920,
  "height": 1080,
  "framesPerSecond": 30,
  "videoBitrateMbps": 8.5,
  "sizeBytes": 26214400,
  "videoMetadataToken": "video_metadata_token_from_files_api"
}

Các trường video có chữ ký đầy đủ ở trên là bắt buộc đối với video tham chiếu Video8 và Wan 3.0. Tệp âm thanh tham chiếu Wan 3.0 dùng mimeType, sizeBytes, durationSeconds và durationToken; tệp ảnh tham chiếu dùng hợp đồng siêu dữ liệu hình ảnh riêng cho từng mô hình được mô tả ở trên.

Với Seedream 5.0 Pro Layer Decomposition, hãy gửi đúng một ảnh cùng siêu dữ liệu có chữ ký được trả về từ lượt tải lên gắn với mô hình:

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

Một số tham số mô hình cũ vẫn dùng trường URL riêng cho từng mô hình. Nếu Tài liệ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ạo trường mới.

Lỗi

Files API dùng cùng cấu trúc lỗi công khai 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:

Ghi chú bảo mật

Không lưu toàn bộ khóa API trong trình duyệt, ứng dụng di động, nhật ký, sự kiện phân tích hoặc ảnh chụp màn hình.

Hãy coi URL tệp đã tải lên cùng các giá trị duration_token, image_dimensions_token và video_metadata_token là dữ liệu tích hợp tạm thời. Chỉ dùng chúng để tạo yêu cầu sinh nội dung tiếp theo và không để lộ trên các trang công khai.

Trang liên quan

• Tạo nội dung

• Rivya TypeScript SDK

• Tài liệu tham chiếu API mô hình

• Lỗi và giới hạn API

• Hợp đồng OpenAPI và schema