MIME checks, size limits, duration tokens와 함께 Rivya API generation requests용 이미지, 비디오, 오디오 reference files를 업로드하세요.

이미지, 비디오, 오디오 입력이 필요한 모델의 reference media를 업로드하려면 POST /api/v1/files를 사용하세요.

Files API는 reference inputs 전용입니다. 그 자체로 generation tasks를 만들지는 않습니다. 업로드 후 반환된 url과 metadata를 model params에 전달하세요. 보통 params.referenceMediaItems를 사용합니다.

Endpoint

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

Required headers:

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

업로드하려면 API key에 files:create scope가 있어야 하고, metadata를 가져오려면 files:read가 있어야 합니다. 새로 만든 Rivya API keys에는 두 scope가 기본으로 포함됩니다.

Multipart Fields

Field	Type	Required	Notes
`file`	binary	yes	업로드할 이미지, 비디오, 오디오 파일입니다.
`kind`	string	yes	값은 `image`, `video`, `audio` 중 하나입니다.
`model`	string	no	Public model ID입니다. 값이 있으면 Rivya는 해당 model이 이 file kind를 받는지 검증합니다.
`client_request_id`	string	no	최대 128 characters인 trace ID입니다.

파일이 특정 model용이라면 model을 사용하세요. 파일이 수락되기 전에 model-specific MIME 및 size validation을 받을 수 있습니다.

Upload Limits

Files API는 Rivya reference uploads와 같은 upload policy를 사용합니다.

Default limits:

Kind	Default max size	Common MIME types
`image`	10 MB	`image/jpeg`, `image/png`, `image/webp`
`video`	50 MB	`video/mp4`, `video/quicktime`, `video/webm`
`audio`	10 MB	`audio/mpeg`, `audio/mp4`, `audio/wav`, `audio/x-wav`, `audio/aac`, `audio/ogg`

일부 모델에는 다른 제한이 있습니다. 예를 들어 일부 reference-image models는 더 큰 이미지를 허용하고, 일부 video-reference models는 제품의 edge-safe upload ceiling까지 파일을 허용합니다. target model을 알고 있다면 항상 model을 전달하고, 사용자 업로드를 받기 전에 Model API Reference를 읽으세요.

Rivya는 filename extension뿐 아니라 감지된 file signature를 검증합니다.

curl Example

curl https://rivya.ai/api/v1/files \
  -H "Authorization: Bearer rvya_sk_..." \
  -F "file=@./reference.png" \
  -F "kind=image" \
  -F "model=nano-banana-2" \
  -F "client_request_id=asset-123"

JavaScript Example

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

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",
            "client_request_id": "asset-123",
        },
        timeout=60,
    )

uploaded_file = response.json()
print(uploaded_file["id"], uploaded_file["url"])

Response

{
  "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,
  "created_at": "2026-05-11T00:00:00.000Z",
  "expires_at": null
}

비디오와 오디오 업로드의 경우 duration_seconds가 채워질 수 있습니다. model이 duration verification을 요구하면 duration_token을 관련 generation parameter에 durationToken으로 복사하세요.

File Metadata 가져오기

같은 Rivya account가 소유한 file의 metadata를 읽으려면 GET /api/v1/files/{fileId}를 사용하세요.

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

Response는 upload와 같은 PublicApiFile shape를 사용합니다. file이 다른 account에 속하거나 더 이상 사용할 수 없다면 API는 not_found를 반환합니다.

Generation Params에서 Upload 사용하기

POST /api/v1/generations에 top-level files field를 보내지 마세요.

새 integration에서는 upload result를 params.referenceMediaItems로 전달하세요.

{
  "model": "nano-banana-2",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  },
  "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"
}

일부 오래된 model parameters는 여전히 model-specific URL fields를 사용합니다. Model API Reference가 특정 parameter를 문서화한다면 새 field를 만들지 말고 해당 model page를 따르세요.

Errors

Files API는 Rivya API의 나머지 부분과 같은 public error envelope를 사용합니다.

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

Common cases:

HTTP	Code	Cause
400	`validation_failed`	필수 `file` 누락, 지원되지 않는 `kind`, 지원되지 않는 MIME type, 너무 큰 file, 또는 model이 선택한 kind를 받지 않습니다.
401	`api_key_missing` / `api_key_invalid`	Bearer API key가 없거나 유효하지 않습니다.
403	`api_scope_denied`	요청한 action에 필요한 `files:create` 또는 `files:read`가 key에 없습니다.
429	`rate_limited`	현재 minute에 file uploads가 너무 많습니다.
503	`public_api_disabled`	현재 environment에서 Public API가 비활성화되었습니다.

Security Notes

전체 API keys를 browsers, mobile clients, logs, analytics events, screenshots에 저장하지 마세요.

업로드된 file URLs와 duration_token 값은 임시 integration material로 다루세요. 후속 generation request를 만들 때만 사용하고 public pages에 노출하지 마세요.

Files API