Files API

使用 POST /api/v1/files 上傳模型需要的圖片、影片或音訊輸入參考媒體。

Files API 僅用於參考輸入。它本身不會建立生成任務。上傳後，請將回傳的 url 和 metadata 放入模型 params，通常是透過 params.referenceMediaItems。

Endpoint

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

必要 headers：

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

API key 必須包含 files:create scope 才能上傳，並包含 files:read 才能取回 metadata。新建立的 Rivya API keys 預設包含這兩個 scopes。

Multipart 欄位

如果檔案是要用於特定模型，請使用 model。這可讓你在檔案被接受前，先取得模型專屬的 MIME 和大小驗證。

上傳限制

Files API 使用與 Rivya 參考上傳相同的上傳政策。

預設限制：

有些模型有不同限制。例如，特定 reference-image 模型允許較大的圖片，特定 video-reference 模型允許檔案達到產品邊界內安全的上傳上限。當你知道目標模型時，請一律傳入 model，並在接受使用者上傳前閱讀 模型 API 參考。

已簽名圖片參考的限制如下：

每張 Image5、Grok Imagine Image 2.0 或 Wan 3.0 參考圖片都必須搭配其目標 model 上傳。請保留原始回應中的 width、height、size_bytes 和 image_dimensions_token；生成請求必須分別以 width、height、sizeBytes 和 imageDimensionsToken 傳送這些資料。任意外部圖片 URL 無法通過這項模型綁定驗證。

Layer Decomposition 還會在上傳前驗證偵測到的圖片尺寸：總像素必須介於 262,144–36,000,000，長寬比則須介於 1:16–16:1。

影片參考模型專屬上傳限制包括：

這些是 Rivya 接受的上傳上限，可能低於上游服務的限制。請使用目標 model 上傳每個 Video8 或 Wan 3.0 參考檔案。參考影片需要同時帶有原始模型綁定上傳回應中的已簽名播放時間證明與已簽名影片 metadata。Wan 3.0 的音訊播放時間 token 也會綁定偵測到的 MIME 類型與上傳檔案位元組大小。

Wan 3.0 圖片的每一邊必須介於 240–8,000 像素，影片的每一邊則必須介於 240–4,096 像素；兩者的長寬比都必須落在 1:8–8:1 範圍內。在參考模式下，影片與音訊各有獨立的 15 秒合計上限，且音訊不能是唯一的參考類型。

Rivya 會驗證偵測到的檔案簽章，而不只看檔名副檔名。

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"

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);

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"])

回應

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

對於影片和音訊上傳，duration_seconds 可能會有值。當模型需要驗證播放時間時，請將 duration_token 複製到相關生成參數中的 durationToken。

對於支援的圖片上傳，系統會從檔案位元組偵測 width 和 height。五個 Image5 模型、Grok Imagine Image 2.0 與 Wan 3.0 都要求原始模型綁定上傳回應中的已簽名 image_dimensions_token；請將它以 imageDimensionsToken 複製到參考項目中，並將 size_bytes 複製為 sizeBytes。稍後取回檔案 metadata 時，這個 token 可能會是 null；若原始 token 不可用或已過期，請重新上傳來源圖片。

對於支援的 Video8 與 Wan 3.0 影片上傳，Rivya 會檢查 MP4 或 MOV 的檔案位元組，並回傳 video_width、video_height、frames_per_second、video_bitrate_mbps、video_file_size_bytes 和 video_metadata_token。請將它們分別以 width、height、framesPerSecond、videoBitrateMbps、sizeBytes 和 videoMetadataToken 複製到參考項目中。此 token 綁定帳號、目標模型、URL、MIME 類型、尺寸、影格率、位元率與上傳大小；播放時間則由 durationToken 獨立驗證。稍後取回檔案 metadata 時，video_metadata_token 可能會是 null；請重新上傳來源影片，不要自行編造 metadata。

取回檔案 Metadata

使用 GET /api/v1/files/{fileId} 讀取同一 Rivya 帳號擁有的檔案 metadata：

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

回應會使用與上傳相同的 PublicApiFile shape。如果檔案屬於另一個帳號或已不再可用，API 會回傳 not_found。

在生成 Params 中使用上傳結果

不要將頂層 files 欄位傳送到 POST /api/v1/generations。

對於新的整合，請透過 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"
}

對於影片或音訊：

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

上述完整的已簽名影片欄位是 Video8 與 Wan 3.0 影片參考的必要條件。Wan 3.0 音訊參考使用 mimeType、sizeBytes、durationSeconds 和 durationToken；圖片參考則使用上文所述的模型專屬圖片 metadata 合約。

對於 Seedream 5.0 Pro Layer Decomposition，請傳送恰好一張圖片，以及模型綁定上傳所回傳的已簽名 metadata：

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

有些較舊的模型參數仍使用模型專屬 URL 欄位。如果 模型 API 參考 記錄了特定參數，請依照該模型頁面，而不是自行發明新欄位。

錯誤

Files API 使用與 Rivya API 其他部分相同的公開錯誤 envelope：

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

常見情況：

安全性注意事項

不要在瀏覽器、行動裝置端、日誌、analytics events 或截圖中儲存完整 API keys。

請將上傳的檔案 URL、duration_token、image_dimensions_token 和 video_metadata_token 值視為暫時的整合材料。只用它們建立後續生成請求，不要暴露在公開頁面中。

相關頁面

• 建立生成任務

• Rivya TypeScript SDK

• 模型 API 參考

• API 錯誤與限制

• OpenAPI 與 Schema 合約