Files API

Використовуйте POST /api/v1/files, щоб завантажувати референс-медіа для моделей, яким потрібні зображення, відео або аудіо на вході.

Files API призначений лише для референс-вхідних даних. Він сам по собі не створює задачі генерації. Після завантаження передайте повернений url і метадані в params моделі, зазвичай через params.referenceMediaItems.

Endpoint

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-ключ має містити scope files:create, а для читання метаданих потрібен files:read. Нові Rivya API-ключі за замовчуванням містять обидва scope.

Multipart-поля

Використовуйте model, коли файл призначений для конкретної моделі. Так ви отримаєте перевірку MIME та розміру з урахуванням моделі ще до прийняття файлу.

Ліміти завантаження

Files API використовує ту саму політику завантаження, що й референс-завантаження Rivya.

Стандартні ліміти:

Деякі моделі мають інші ліміти. Наприклад, окремі моделі для референс-зображень дозволяють більші зображення, а окремі моделі з відеореференсами дозволяють файли до межі, яку продукт може безпечно прийняти. Завжди передавайте model, коли знаєте цільову модель, і прочитайте Model API Reference, перш ніж приймати користувацькі завантаження.

Обмеження для підписаних референс-зображень:

Кожне референс-зображення для Image5, Grok Imagine Image 2.0 або Wan 3.0 потрібно завантажувати із зазначенням цільової model. Збережіть width, height, size_bytes та image_dimensions_token з початкової відповіді: у запиті генерації їх потрібно передати як width, height, sizeBytes та imageDimensionsToken. Довільні зовнішні URL зображень не відповідають цій перевірці з прив'язкою до моделі.

Для декомпозиції на шари додатково перевіряються визначені розміри зображення ще до завантаження: від 262,144 до 36,000,000 пікселів загалом і співвідношення сторін від 1:16 до 16:1.

Обмеження на завантаження для моделей Video8 і Wan 3.0:

Це граничні значення завантаження, які приймає 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, 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; у такому разі повторно завантажте вихідне відео, а не вигадуйте метадані.

Отримання метаданих файлу

Використовуйте GET /api/v1/files/{fileId}, щоб прочитати метадані файлу, який належить тому самому акаунту Rivya:

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 передайте рівно одне зображення та підписані метадані з його завантаження, прив'язаного до моделі:

{
  "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-поля. Якщо Model API Reference документує конкретний параметр, дотримуйтеся цієї сторінки моделі, а не вигадуйте нове поле.

Помилки

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

• Model API Reference

• Помилки та ліміти API

• OpenAPI та контракт схеми