↓
Rivya AI 文件

Files API

為 Rivya API 生成請求上傳圖片、影片或音訊參考檔案,並處理 MIME 檢查、大小限制和 duration tokens。

最近審閱於 2026年11月11日

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

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

提示詞單位與完整圖層結果

讀取 GET /api/v1/models 時,請將 prompt_length_unit 與 max_prompt_length 一起使用。utf8_bytes 計算原文的 UTF-8 位元組,包含空格與換行;utf16_code_units 計算 JavaScript 的 UTF-16 程式碼單元。上限為 null 不代表文字不限長或可以不填。Gemini TTS 使用位元組單位。

已完成的圖層拆分結果可在完整的 result.urls 之外提供 result.layers。請保留每層回傳的 z_index、URL、尺寸、名稱、說明與邊界框,索引零是底圖。TypeScript SDK 已提供這些欄位。參考檔案須依所選模型上傳,並傳回原始簽章中繼資料;單獨宣告尺寸或時長不能代替核驗。

Endpoint

讓 curl、FormData 或 multipart 程式庫計算 boundary 與內容長度;以下 JavaScript、Python 範例不要手動設定 Content-Type。缺少有效 Content-Length 會被拒絕。Key 另須有效、未撤銷且未到期。

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; boundary=...
Content-Length: ...

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

Multipart 欄位

從模型 API 參考取得精確 ID。指定 model 後會驗證可呼叫狀態、檔案種類、MIME、大小與必要中繼資料。需要模型綁定簽章時,必須為同一目標模型上傳。client_request_id 僅是追蹤值,不提供冪等;重複上傳可能建立新檔案記錄,此端點不依 Idempotency-Key 重播。

欄位類型必填說明
filebinaryyes要上傳的圖片、影片或音訊檔案。
kindstringyesimage、video 或 audio 其中之一。
modelstringno公開模型 ID。提供時,Rivya 會驗證該模型是否接受這種檔案類型。
client_request_idstringno你的 trace ID,最多 128 個字元。

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

上傳限制

Seedance 2 Mini 與 MiniMax H3 的影片、音訊均為每份 2–15 秒;Seedance 2.5 為每份 2–30 秒。OmniHuman 1.5 音訊須大於 0 且小於 60 秒;Volcengine Lip Sync 的影片與音訊都須能偵測到正時長。Wan 3.0 圖片每邊 240–8,000 像素、影片每邊 240–4,096 像素,長寬比均為 1:8–8:1;音訊與影片各有獨立 15 秒總量,音訊不能是唯一媒體。參考影片秒數加輸出秒數不超過 30,且智慧輸出時長不能搭配參考影片。

每次請求僅上傳一個檔案;表中數量上限是生成任務的參考數量,仍須符合所選模式組合。Rivya 同時檢查檔案內容與大小,副檔名或用戶端 MIME 不能證明格式。1 MiB = 1,048,576 位元組;單檔總上限為 95 MiB,宣告的 multipart 內容總上限為 96 MiB,包含邊界與欄位。模型規則可改變預設限制。

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

預設限制:

類型預設最大大小常見 MIME 類型
image10 MiBimage/jpeg, image/png, image/webp
video50 MiBvideo/mp4, video/quicktime, video/webm
audio10 MiBaudio/mpeg, audio/mp4, audio/wav, audio/x-wav, audio/aac, audio/ogg

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

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

模型圖片上限單張上限接受的圖片 MIME 類型
seedream-5-pro1010 MiBJPEG, PNG, WebP
seedream-5-pro-layer-decomposition恰好 1 張30 MiBJPEG / PNG
nano-banana-2-lite1030 MiBJPEG, PNG, WebP
qwen-image-3 / qwen-image-3-pro310 MiBJPEG, PNG, WebP, BMP, GIF, TIFF
grok-imagine-image-2-0510 MiBJPEG, PNG, WebP
wan-3-0-video參考模式 10 張;影格模式 1–2 張20 MiBJPEG、不含透明度的 PNG、WebP、BMP

每張 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。

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

模型圖片輸入影片輸入音訊輸入
kling-3-turbo1 張 × 10 MiB;JPEG 或 PNG不接受不接受
seedance-2-mini最多 9 張 × 30 MiB;JPEG / PNG / WebP / GIF最多 3 個 × 50 MiB;MP4 或 MOV最多 3 個 × 15 MiB;MP3 或 WAV
seedance-2-5最多 30 張 × 30 MiB;JPEG / PNG / WebP最多 10 個 × 95 MiB;MP4 或 MOV最多 10 個 × 15 MiB;MP3 或 WAV
minimax-h3最多 9 張 × 30 MiB;JPEG、PNG 或 WebP最多 3 個 × 50 MiB;MP4 或 MOV最多 3 個 × 15 MiB;MP3 或 WAV
happyhorse-1-1最多 9 張 × 20 MiB;JPEG、PNG 或 WebP不接受不接受
omnihuman-1-51 張 × 10 MiB;JPEG、PNG 或 WebP不接受1 個 × 10 MiB;MP3、M4A、WAV、AAC 或 OGG
volcengine-video-lip-sync不接受1 個 × 95 MiB;MP4 或 MOV1 個 × 10 MiB;MP3、M4A、WAV、AAC 或 OGG
wan-3-0-video影格:1 張必填、1 張選填;參考:最多 10 張 × 20 MiB;JPEG、不含透明度的 PNG、WebP 或 BMP參考:最多 5 個 × 95 MiB;MP4 或 MOV;每個 1–15 秒,合計 15 秒參考:最多 5 個 × 15 MiB;MP3 或 WAV;每個 1–15 秒,合計 15 秒;不可作為唯一輸入

這些是 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 範例

以下 JavaScript 範例在伺服器執行,須設定 RIVYA_API_KEY。檢查 HTTP 成功後才將回應視為上傳結果;不要將金鑰交給瀏覽器。

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();
if (!response.ok) {
  throw new Error(JSON.stringify(uploadedFile.error));
}
console.log(uploadedFile.id, uploadedFile.url);

Python 範例

Python 範例需要 requests 與伺服器端 RIVYA_API_KEY。逾時限制的是 HTTP 等待,不證明上傳失敗或未儲存檔案。

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()
if not response.ok:
    raise RuntimeError(uploaded_file.get("error"))
print(uploaded_file["id"], uploaded_file["url"])

回應

已簽章圖片須將原始上傳回應對應至生成參考項:mime_type → mimeType, width → width, height → height, size_bytes → sizeBytes, image_dimensions_token → imageDimensionsToken,與原 URL 及目標模型一起保存。影片的 sizeBytes 應直接使用 video_file_size_bytes;不要以位元率乘時長估算,影片取樣位元率不等於整個容器大小。範例中的時間、大小與 token 僅為範例,不是真實簽章。

{
  "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 由檔案內容識別。保留原 URL、目標模型與完整上傳回應;後續 GET 不會重建 image_dimensions_token,該欄位一律為 null。原 token 缺失或到期時重新上傳。

需要簽章影片中繼資料時,Rivya 檢查 MP4 或 MOV 檔案內容,並對應:video_width → width, video_height → height, frames_per_second → framesPerSecond, video_bitrate_mbps → videoBitrateMbps, video_file_size_bytes → sizeBytes, video_metadata_token → videoMetadataToken。簽章綁定帳戶、目標模型、URL、MIME、尺寸、幀率、位元率與檔案大小;durationToken 另行驗證時長。後續 GET 的 video_metadata_token 一律為 null,不能自行建構中繼資料取代原上傳回應。

簽章中繼資料與檔案效期

時長、圖片尺寸與影片中繼資料 token 自簽發起一小時到期。必要 token 缺失或到期時,為目標模型重新上傳原檔案,並原樣複製上傳中繼資料。

上傳 URL 僅是暫時的生成輸入;保留自己的原檔案,必要時重新上傳。檔案記錄的 expires_at 為 null 也不保證遠端 URL 一直可用。

取回檔案 Metadata

此端點讀取所屬帳戶的檔案記錄;同帳戶另一把有效 Key 具備 files:read 也可讀取。回應仍為 PublicApiFile;記錄不存在、不屬於該帳戶或狀態不再為 available 時回傳 not_found。讀取記錄不檢查遠端 URL 是否可下載。

GET 不還原圖片或影片簽章中繼資料,以下欄位一律為 null:width, height, image_dimensions_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, video_metadata_token。重新簽發的音訊時長 token 不含 MIME 與檔案大小,不能替代部分模型所需的綁定資訊。生成時保留完整原始上傳回應;必要簽章資訊缺失或到期須重新上傳原檔案。

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

在生成 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.png",
        "mimeType": "image/png",
        "width": 2048,
        "height": 2048,
        "sizeBytes": 6291456,
        "imageDimensionsToken": "image_dimensions_token_from_files_api"
      }
    ]
  }
}

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

錯誤

讀取 code 並保留回傳的 requestId。上傳逾時或回應無法讀取時,無法確認檔案是否已儲存;重試可能建立新記錄,不證明先前失敗。

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

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid. Check the endpoint's required fields and parameters.",
    "requestId": "req_..."
  }
}

常見情況:

HTTPCode原因
400validation_failed缺少檔案、錯誤 multipart 標頭或長度、不支援的種類或格式、檔案過大、必要中繼資料無效,或模型不接受該上傳。
401api_key_missing / api_key_invalid / api_key_revoked / api_key_expiredKey 缺失、無效、已撤銷或到期,或帳戶不允許使用公開 API。
403api_scope_denied缺少上傳所需 files:create 或讀取所需 files:read。
404not_found沒有所屬帳戶可用檔案記錄,或模型未知/不是非同步生成模型。
429rate_limited達到 Key 上傳頻率限制,或上傳並行名額已滿。
500internal_error無法確認請求結果,或必要中繼資料簽章不可用。
503public_api_disabled目前部署停用公開 API。

安全性注意事項

保留自己的原始媒體。中繼資料端點檢查帳戶歸屬,但不能依賴該檢查限制回傳 URL 的下載;不要將上傳 URL 或簽章 token 放到公開頁面。

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

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

相關頁面