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. Новые API-ключи Rivya по умолчанию включают обе области доступа.

Поля multipart-формы

Используйте model, когда файл предназначен для конкретной модели. Так вы получите проверку MIME и размера с учетом модели до того, как файл будет принят.

Лимиты загрузки

Files API использует ту же политику загрузки, что и справочные материалы Rivya.

Лимиты по умолчанию:

У некоторых моделей другие лимиты. Например, отдельные модели со справочными изображениями разрешают более крупные картинки, а отдельные модели с видеореференсами допускают файлы до верхней границы загрузки продукта. Всегда передавайте model, когда знаете целевую модель, и читайте справочник Model API, прежде чем принимать пользовательские загрузки.

Ограничения для подписанных справочных изображений:

Каждое справочное изображение 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.

Ограничения загрузки для моделей с видеореференсами:

Это предельные размеры загрузки, принимаемые 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.

Использование загрузки в параметрах генерации

Не отправляйте поле верхнего уровня 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 документирует конкретный параметр, следуйте странице этой модели вместо того, чтобы придумывать новое поле.

Ошибки

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

• Ошибки и лимиты API

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