Files API

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

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

Titik akhir

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

Pengepala yang diperlukan:

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

Kunci API mesti menyertakan skop files:create untuk memuat naik dan files:read untuk mendapatkan metadata. Kunci Rivya API yang baru dicipta menyertakan kedua-dua skop secara lalai.

Medan multipart

Gunakan model apabila fail ditujukan kepada model tertentu. Ini membolehkan MIME dan saiz disahkan mengikut model sebelum fail diterima.

Had muat naik

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

Had lalai:

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

Had rujukan imej bertandatangan termasuk:

Setiap imej rujukan Image5, Grok Imagine Image 2.0, atau Wan 3.0 mesti dimuat naik dengan model sasarannya. Simpan width, height, size_bytes, dan image_dimensions_token daripada respons asal; permintaan penjanaan mesti menghantarnya sebagai width, height, sizeBytes, dan imageDimensionsToken. URL imej luaran sebarangan tidak memenuhi pengesahan terikat model ini.

Penguraian lapisan turut mengesahkan dimensi imej yang dikesan sebelum muat naik: jumlah 262,144–36,000,000 piksel dan nisbah bidang dari 1:16 hingga 16:1.

Had muat naik khusus model Video8 termasuk:

Ini ialah had muat naik yang diterima Rivya, yang mungkin lebih rendah daripada had perkhidmatan huluan. Muat naik setiap rujukan Video8 atau Wan 3.0 dengan model sasarannya. Video rujukan memerlukan bukti tempoh bertandatangan dan metadata video bertandatangan daripada respons muat naik asal yang terikat pada model. Token tempoh audio Wan 3.0 turut terikat pada jenis MIME yang dikesan dan saiz bait muat naik.

Setiap sisi imej Wan 3.0 mesti berukuran 240–8,000 piksel dan setiap sisi video mesti berukuran 240–4,096 piksel; kedua-duanya mesti kekal dalam sempadan nisbah bidang 1:8–8:1. Dalam mod rujukan, video dan audio mempunyai had jumlah 15 saat yang berasingan, dan audio tidak boleh menjadi satu-satunya jenis rujukan.

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

Bagi muat naik imej yang disokong, width dan height dikesan daripada bait fail. Kelima-lima model Image5, Grok Imagine Image 2.0, dan Wan 3.0 memerlukan image_dimensions_token bertandatangan daripada respons muat naik asal yang terikat pada model; salinnya ke dalam item rujukan sebagai imageDimensionsToken, dan salin size_bytes sebagai sizeBytes. Pengambilan metadata fail kemudian mungkin mengembalikan token itu sebagai null, jadi muat naik semula imej sumber jika token asal tidak tersedia atau telah tamat tempoh.

Bagi muat naik video Video8 dan Wan 3.0 yang disokong, Rivya memeriksa bait MP4 atau MOV dan mengembalikan video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, dan video_metadata_token. Salinnya ke dalam item rujukan sebagai width, height, framesPerSecond, videoBitrateMbps, sizeBytes, dan videoMetadataToken. Token itu terikat pada akaun, model sasaran, URL, jenis MIME, dimensi, kadar bingkai, kadar bit, dan saiz muat naik. Tempoh disahkan secara berasingan melalui durationToken. Pengambilan metadata fail kemudian mungkin mengembalikan video_metadata_token sebagai null; muat naik semula video sumber dan jangan mereka-reka metadata.

Dapatkan metadata fail

Gunakan GET /api/v1/files/{fileId} untuk membaca metadata fail yang dimiliki oleh 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 itu milik akaun lain atau tidak lagi tersedia, API mengembalikan not_found.

Gunakan muat naik dalam parameter penjanaan

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

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

Medan video bertandatangan yang lengkap di atas diperlukan untuk rujukan video Video8 dan Wan 3.0. Rujukan audio Wan 3.0 menggunakan mimeType, sizeBytes, durationSeconds, dan durationToken; rujukan imej menggunakan kontrak metadata imej khusus model yang diterangkan di atas.

Bagi Seedream 5.0 Pro Layer Decomposition, hantar tepat satu imej dan metadata bertandatangan yang dikembalikan oleh muat naik terikat modelnya:

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

Sesetengah parameter model lama masih menggunakan medan URL khusus model. Jika Rujukan API Model mendokumenkan parameter tertentu, ikuti halaman model itu dan jangan mereka-reka medan baharu.

Ralat

Files API menggunakan sampul ralat awam yang sama seperti bahagian Rivya API yang lain:

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

Kes lazim:

Catatan keselamatan

Jangan simpan kunci API penuh dalam pelayar, klien mudah alih, log, peristiwa analitik, atau tangkapan skrin.

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

Halaman berkaitan

• Cipta Penjanaan

• Rivya TypeScript SDK

• Rujukan API Model

• Ralat dan Had API

• Kontrak OpenAPI dan Skema