Загружайте справочные изображения, видео или аудиофайлы для запросов генерации через Rivya API с проверками MIME, лимитами размера и токенами длительности.

Используйте 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-формы

Поле	Тип	Обязательно	Примечания
`file`	двоичный	да	Изображение, видео или аудиофайл для загрузки.
`kind`	строка	да	Одно из значений: `image`, `video` или `audio`.
`model`	строка	нет	Публичный ID модели. Если он передан, Rivya проверяет, принимает ли модель такой тип файла.
`client_request_id`	строка	нет	Ваш ID трассировки, до 128 символов.

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

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

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

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

Тип	Максимальный размер по умолчанию	Распространенные MIME-типы
`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`

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

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

Для загрузок видео и аудио может заполняться duration_seconds. Когда модель требует проверки длительности, скопируйте duration_token в связанный параметр генерации как durationToken.

Получение метаданных файла

Используйте 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",
  "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"
}

Некоторые старые параметры моделей все еще используют специализированные URL-поля. Если справочник Model API документирует конкретный параметр, следуйте странице этой модели вместо того, чтобы придумывать новое поле.

Ошибки

Files API использует ту же публичную оболочку ошибки, что и остальной Rivya API:

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

Частые случаи:

HTTP	Код	Причина
400	`validation_failed`	Отсутствует `file`, не поддерживается `kind`, не поддерживается MIME-тип, файл слишком большой или модель не принимает выбранный тип файла.
401	`api_key_missing` / `api_key_invalid`	Отсутствует или недействителен API-ключ Bearer.
403	`api_scope_denied`	Ключ не включает `files:create` или `files:read` для запрошенного действия.
429	`rate_limited`	Слишком много загрузок файлов за текущую минуту.
503	`public_api_disabled`	Public API отключен в текущем окружении.

Примечания по безопасности

Не храните полные API-ключи в браузерах, мобильных клиентах, логах, аналитических событиях или скриншотах.

Считайте URL загруженных файлов и значения duration_token временным материалом интеграции. Используйте их только для построения последующего запроса генерации и не раскрывайте на публичных страницах.

Files API