Files API ガイド

画像、動画、音声入力を必要とするモデル向けに参照メディアをアップロードするには、POST /api/v1/files を使います。

Files API は参照入力専用です。それ自体では生成タスクを作成しません。アップロード後、返された url とメタデータをモデルの params に渡します。通常は params.referenceMediaItems を使います。

エンドポイント

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

必須ヘッダー:

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

アップロードするには API キーに files:create スコープが必要で、メタデータを取得するには files:read が必要です。新しく作成された Rivya API キーには、デフォルトで両方のスコープが含まれます。

Multipart フィールド

ファイルを特定のモデルで使う予定がある場合は model を使ってください。ファイルが受理される前に、モデル固有の MIME とサイズ検証を受けられます。

アップロード制限

Files API は Rivya の参照アップロードと同じポリシーを使います。

デフォルト制限:

一部のモデルには異なる制限があります。たとえば、一部の参照画像モデルはより大きな画像を許可し、一部の動画参照モデルは製品側で安全に受け付けられる上限までのファイルを許可します。対象モデルがわかっている場合は必ず 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 が受け付けるアップロード上限であり、上流サービスの上限より低い場合があります。Video8 または Wan 3.0 の各参照ファイルは、対象の model を指定してアップロードしてください。参照動画には、元のモデル紐付きアップロード応答から得た署名済みの長さ証明と署名済み動画メタデータの両方が必要です。Wan 3.0 の音声 duration token は、検出された MIME type とアップロードのバイトサイズにも紐付きます。

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 の 5 モデルすべて、Grok Imagine Image 2.0、Wan 3.0 では、元のモデル紐付きアップロード応答で返された署名済み image_dimensions_token が必要です。その値を参照アイテムの imageDimensionsToken に、size_bytes の値を sizeBytes にコピーしてください。後からファイルメタデータを取得すると 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 type、寸法、フレームレート、ビットレート、アップロードサイズに紐付きます。長さは durationToken で別途検証されます。後からファイルメタデータを取得したときに video_metadata_token が null の場合は、メタデータを作り出さず、元動画を再アップロードしてください。

ファイルメタデータを取得する

同じ Rivya アカウントが所有するファイルのメタデータを読み取るには、GET /api/v1/files/{fileId} を使います。

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

応答はアップロード時と同じ PublicApiFile 形式を使います。ファイルが別のアカウントに属している、または利用できなくなっている場合、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 を使い、画像参照には前述のモデル固有画像メタデータ契約を使います。

Seedream 5.0 Pro Layer Decomposition では、モデルに紐付けたアップロードが返す署名済みメタデータとともに、画像を必ず 1 枚だけ送信します。

{
  "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 の他の部分と同じ公開エラーエンベロープを使います。

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

一般的なケース:

セキュリティメモ

完全な API キーをブラウザ、モバイルクライアント、ログ、analytics イベント、スクリーンショットに保存しないでください。

アップロードされたファイル URL、duration_token、image_dimensions_token、video_metadata_token の値は、一時的な統合素材として扱ってください。後続の生成リクエストを組み立てるためにのみ使い、公開ページに露出させないでください。

関連ページ

• 生成を作成する

• Rivya TypeScript SDK

• モデル API リファレンス

• API エラーと制限

• OpenAPI とスキーマ契約