파일 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 오디오 재생 시간 토큰도 감지된 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 모델 5종, Grok Imagine Image 2.0 및 Wan 3.0은 모두 원래의 모델 지정 업로드 응답에 포함된 서명된 image_dimensions_token을 요구합니다. 참조 항목의 imageDimensionsToken으로 복사하고, size_bytes도 sizeBytes로 복사하세요. 이후 파일 메타데이터 조회에서는 토큰이 null일 수 있으므로, 원래 토큰을 사용할 수 없거나 토큰이 만료되었다면 원본 이미지를 다시 업로드하세요.

지원되는 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으로 복사하세요. 토큰은 계정, 대상 모델, URL, MIME 형식, 크기, 프레임 속도, 비트레이트 및 업로드 크기에 바인딩됩니다. 재생 시간은 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에서 업로드 사용하기

POST /api/v1/generations에 최상위 files 필드를 보내지 마세요.

새 연동에서는 업로드 결과를 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 키를 브라우저, 모바일 클라이언트, 로그, 분석 이벤트 또는 스크린샷에 저장하지 마세요.

업로드된 파일 URL, duration_token, image_dimensions_token, video_metadata_token 값은 임시 연동 자료로 취급하세요. 후속 생성 요청을 만들 때만 사용하고 공개 페이지에 노출하지 마세요.

관련 페이지

• 생성 작업 만들기

• Rivya TypeScript SDK

• 모델 API 참고 문서

• API 오류와 제한

• OpenAPI와 스키마 계약