Upload image, video, or audio reference files for Rivya API generation requests, with MIME checks, size limits, and duration tokens.

Use POST /api/v1/files to upload reference media for models that need image, video, or audio inputs.

Files API is for reference inputs only. It does not create generation tasks by itself. After upload, pass the returned url and metadata into model params, usually through 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

The API key must include the files:create scope to upload and files:read to retrieve metadata. Newly created Rivya API keys include both scopes by default.

Multipart Fields

Field	Type	Required	Notes
`file`	binary	yes	The image, video, or audio file to upload.
`kind`	string	yes	One of `image`, `video`, or `audio`.
`model`	string	no	Public model ID. When present, Rivya validates that the model accepts this file kind.
`client_request_id`	string	no	Your trace ID, up to 128 characters.

Use model when the file is intended for a specific model. This gives you model-specific MIME and size validation before the file is accepted.

Upload Limits

Files API uses the same upload policy as Rivya reference uploads.

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`

Some models have different limits. For example, selected reference-image models allow larger images, and selected video-reference models allow files up to the product's edge-safe upload ceiling. Always pass model when you know the target model, and read Model API Reference before accepting user uploads.

Rivya validates the detected file signature, not only the filename extension.

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
}

For video and audio uploads, duration_seconds may be populated. When a model requires duration verification, copy duration_token into the related generation parameter as durationToken.

Retrieve File Metadata

Use GET /api/v1/files/{fileId} to read metadata for a file owned by the same Rivya account:

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

The response uses the same PublicApiFile shape as upload. If the file belongs to another account or is no longer available, the API returns not_found.

Use The Upload In Generation Params

Do not send a top-level files field to POST /api/v1/generations.

For new integrations, pass the upload result through 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"
}

For video or audio:

{
  "url": "https://...",
  "kind": "video",
  "name": "source.mov",
  "mimeType": "video/quicktime",
  "durationSeconds": 12.4,
  "durationToken": "duration_token_from_files_api"
}

Some older model parameters still use model-specific URL fields. If the Model API Reference documents a specific parameter, follow that model page instead of inventing a new field.

Errors

Files API uses the same public error envelope as the rest of Rivya API:

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

Common cases:

HTTP	Code	Cause
400	`validation_failed`	Missing `file`, unsupported `kind`, unsupported MIME type, file too large, or model does not accept the selected kind.
401	`api_key_missing` / `api_key_invalid`	Missing or invalid Bearer API key.
403	`api_scope_denied`	The key does not include `files:create` or `files:read` for the requested action.
429	`rate_limited`	Too many file uploads in the current minute.
503	`public_api_disabled`	Public API is disabled in the current environment.

Security Notes

Do not store full API keys in browsers, mobile clients, logs, analytics events, or screenshots.

Treat uploaded file URLs and duration_token values as temporary integration material. Use them only to build the follow-up generation request, and do not expose them in public pages.

Files API

Table of Contents