↓
Rivya AI Docs

Files API: upload reference images, video, and audio

Upload reference media with Rivya's Files API. Check model limits, keep signed metadata, and pass it into generation requests.

Last reviewed on November 11, 2026

Use POST /api/v1/files to upload one reference image, video, or audio file. Use the returned URL and required metadata in a separate generation request.

An upload does not create a generation task or reserve generation credits. Follow your model's input format when you submit the generation, usually through params.referenceMediaItems.

Choose a model with API access that accepts your file kind. Check its API reference before uploading.

Prompt units and complete layer results

Read prompt_length_unit together with max_prompt_length from GET /api/v1/models. utf8_bytes counts the original text bytes, including spaces and line breaks; utf16_code_units counts JavaScript UTF-16 units. A null limit does not mean unlimited or optional text. Gemini TTS uses the byte unit.

A completed layer-decomposition result can include result.layers alongside the complete result.urls list. Keep each layer’s z_index, URL, size, name, description and bounding box when provided; index zero is the base image. The TypeScript SDK exposes these fields. Upload references for the selected model and pass its original signed metadata; declared dimensions or duration alone do not replace verification.

Endpoint

POST https://rivya.ai/api/v1/files
GET https://rivya.ai/api/v1/files/{fileId}

Send a Bearer API key with each request. For an upload, the HTTP client must also supply the multipart boundary and a valid Content-Length:

Authorization: Bearer rvya_sk_...
Content-Type: multipart/form-data; boundary=...
Content-Length: ...

Let curl, FormData, or your multipart library calculate the boundary and body length. Do not manually set Content-Type in the JavaScript and Python examples below. Requests without a valid Content-Length are rejected.

Your key needs files:create to upload and files:read to retrieve metadata. Keys created through Rivya's account settings include both scopes by default. A key must also be valid, active, and unexpired.

Multipart Fields

FieldTypeRequiredNotes
filebinaryyesOne image, video, or audio file.
kindstringyesOne of image, video, or audio.
modelstringnoTarget model ID. Rivya checks whether this model is currently callable and accepts the file kind.
client_request_idstringnoYour trace ID, up to 128 characters.

Use the exact model ID from Model API Reference. Supplying model applies that model's MIME, size, and required metadata checks before the upload is accepted. Models that require signed reference metadata need the file to be uploaded for that same model.

client_request_id is a trace value, not an idempotency key. Repeating an upload may create another file record; this endpoint does not apply Idempotency-Key replay rules.

Upload Limits

Files API uses Rivya's reference-upload policies and accepts one file per request. The tables also show reference counts for a generation; check the model's mode and allowed input combinations.

Rivya checks file bytes as well as size. A filename extension or client-supplied MIME type does not establish the detected format.

The default limits apply when no model-specific policy is selected. Sizes use MiB: 1 MiB is 1,048,576 bytes.

KindDefault maximum file sizeMIME types
image10 MiBimage/jpeg, image/png, image/webp
video50 MiBvideo/mp4, video/quicktime, video/webm
audio10 MiBaudio/mpeg, audio/mp4, audio/wav, audio/x-wav, audio/aac, audio/ogg

A model-specific policy can change these limits. Rivya currently caps a single file at 95 MiB and the declared multipart body at 96 MiB, including its framing and fields. Check the target model's API reference before accepting uploads from your users.

Examples of signed image-reference limits:

ModelImages per generationMaximum per imageImage formats
seedream-5-proup to 1010 MiBJPEG, PNG, WebP
seedream-5-pro-layer-decompositionexactly 130 MiBJPEG or PNG
nano-banana-2-liteup to 1030 MiBJPEG, PNG, WebP
qwen-image-3 / qwen-image-3-proup to 310 MiBJPEG, PNG, WebP, BMP, GIF, TIFF
grok-imagine-image-2-0up to 5 in editing mode10 MiBJPEG, PNG, WebP
wan-3-0-videoup to 10 in reference mode; 1 required and 1 optional in frames mode20 MiBJPEG, non-transparent PNG, WebP, BMP

For these image references, upload with the target model and keep the original response's mime_type, width, height, size_bytes, and image_dimensions_token. Send them as mimeType, width, height, sizeBytes, and imageDimensionsToken in the generation reference item. The URL alone is not enough for these models.

Layer decomposition also requires 262,144–36,000,000 detected pixels in the image, with an aspect ratio from 1:16 to 16:1.

Examples of video-model reference limits:

ModelImages per generationVideos per generationAudio files per generation
kling-3-turbo1 × 10 MiB; JPEG or PNGnot acceptednot accepted
seedance-2-miniup to 9 × 30 MiB; JPEG, PNG, WebP, or GIFup to 3 × 50 MiB; MP4 or MOVup to 3 × 15 MiB; MP3 or WAV
seedance-2-5up to 30 × 30 MiB; JPEG, PNG, or WebPup to 10 × 95 MiB; MP4 or MOVup to 10 × 15 MiB; MP3 or WAV
minimax-h3up to 9 × 30 MiB; JPEG, PNG, or WebPup to 3 × 50 MiB; MP4 or MOVup to 3 × 15 MiB; MP3 or WAV
happyhorse-1-1up to 9 × 20 MiB; JPEG, PNG, or WebPnot acceptednot accepted
omnihuman-1-51 × 10 MiB; JPEG, PNG, or WebPnot accepted1 × 10 MiB; MP3, M4A, WAV, AAC, or OGG
volcengine-video-lip-syncnot accepted1 × 95 MiB; MP4 or MOV1 × 10 MiB; MP3, M4A, WAV, AAC, or OGG
wan-3-0-videoframes: 1 required and 1 optional; reference: up to 10 × 20 MiB; JPEG, non-transparent PNG, WebP, or BMPreference: up to 5 × 95 MiB; MP4 or MOV; 1–15 seconds each and 15 seconds totalreference: up to 5 × 15 MiB; MP3 or WAV; 1–15 seconds each and 15 seconds total; audio needs an image or video reference too

These are Rivya's limits, which can be lower than the supplier's. Upload each reference for its target model. Video references for these models need both duration_token and video_metadata_token; Wan 3.0 audio duration tokens also bind the detected MIME type and file size.

Upload duration checks also depend on the model. Seedance 2 Mini and MiniMax H3 accept reference video and audio clips from 2 to 15 seconds each; Seedance 2.5 accepts 2 to 30 seconds each. OmniHuman 1.5 audio must be longer than 0 and shorter than 60 seconds. Volcengine Lip Sync requires a detected positive duration for each video and audio input.

Wan 3.0 images must be 240–8,000 pixels per side, and videos 240–4,096 pixels per side. Both require an aspect ratio from 1:8 to 8:1. In reference mode, video and audio each have a separate 15-second total, and audio cannot be the only input kind. Reference-video seconds plus requested output seconds must not exceed 30; intelligent output duration cannot be combined with a reference video.

curl Example

Replace the key and local filename with your own values before running an 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-lite" \
  -F "client_request_id=asset-123"

JavaScript Example

Run this in a server-side JavaScript module with fetch, FormData, and Blob available. Set RIVYA_API_KEY in the server environment; the client calculates multipart headers for this body.

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();
if (!response.ok) {
  throw new Error(JSON.stringify(uploadedFile.error));
}
console.log(uploadedFile.id, uploadedFile.url);

Python Example

Set RIVYA_API_KEY in the server environment and install requests. The client builds the multipart boundary and length. timeout=60 is a client setting, not a guarantee that an upload completes within 60 seconds.

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()
if not response.ok:
    raise RuntimeError(uploaded_file.get("error"))
print(uploaded_file["id"], uploaded_file["url"])

Response

This is an illustrative response for a model-bound image upload. The byte size, timestamp, and tokens are example values; use the values from your own successful upload 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,
  "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
}

For video and audio, a detected duration may appear as duration_seconds. Where your model requires a verified duration, send the matching duration_token as durationToken. Keep the original mime_type and size_bytes too.

For the signed image references described above, width and height are detected from the file bytes. Copy image_dimensions_token as imageDimensionsToken, mime_type as mimeType, and size_bytes as sizeBytes, along with the returned dimensions. Keep these fields together with their original URL and target model.

For video references that require signed metadata, Rivya inspects the MP4 or MOV bytes and returns video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, and video_metadata_token. Send these as width, height, framesPerSecond, videoBitrateMbps, sizeBytes, and videoMetadataToken. The signature binds the account, target model, URL, MIME type, dimensions, frame rate, bitrate, and file size. durationToken verifies duration separately.

Use the returned video_file_size_bytes for the upload's total size. Do not derive sizeBytes from bitrate and duration; the reported bitrate describes video samples, which can differ from the whole container's contents.

Signed metadata and file lifetime

Duration, image-dimensions, and video-metadata tokens expire one hour after issue. Upload the original file again for its target model if the required token is missing or expired. Copy metadata from the upload response without changing it.

Upload URLs are temporary generation inputs. Keep your original files and re-upload them when needed. A null expires_at in Rivya's file record does not guarantee that the remote URL will remain available.

Retrieve File Metadata

Use GET /api/v1/files/{fileId} to retrieve a file record owned by your Rivya account. Another valid key for that account can read it if the key has files:read:

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

The response uses the same PublicApiFile shape as upload. A missing record, another account's file, or a record whose status is no longer available returns not_found. This request reads the stored record; it does not check whether the remote URL still downloads.

GET does not restore signed image or video metadata. Reissued audio duration tokens also omit MIME type and file size, which some models require. Keep the complete upload response for generation; re-upload the original file if required signed metadata is missing or expired.

Use The Upload In Generation Params

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

For a model that accepts params.referenceMediaItems, pass the matching fields from its upload response. This image example preserves the model-bound URL and metadata:

{
  "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"
}

For a video reference, use a reference item with the required duration and video metadata. Replace all placeholder values with the corresponding values from your upload:

{
  "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"
}

The complete signed video fields above are required for the listed models' video references. Wan 3.0 audio references use mimeType, sizeBytes, durationSeconds, and durationToken. Image references use the signed image fields described above. Required fields depend on the model and media kind.

For Seedream 5.0 Pro Layer Decomposition, send exactly one image with the signed metadata returned by its model-bound upload:

{
  "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.png",
        "mimeType": "image/png",
        "width": 2048,
        "height": 2048,
        "sizeBytes": 6291456,
        "imageDimensionsToken": "image_dimensions_token_from_files_api"
      }
    ]
  }
}

Some models use a specific URL parameter instead. Follow the exact field names on Model API Reference.

Errors

Files API uses Rivya's public error envelope. This example shows a validation error; read code and retain requestId when it is supplied:

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid. Check the endpoint's required fields and parameters.",
    "requestId": "req_..."
  }
}

Common cases:

HTTPCodeCause
400validation_failedMissing file, invalid multipart headers or length, unsupported kind or format, oversized file, invalid required metadata, or a model that cannot accept this upload.
401api_key_missing / api_key_invalid / api_key_revoked / api_key_expiredMissing, invalid, inactive, or expired Bearer key, or an account that cannot use the Public API.
403api_scope_deniedThe key lacks files:create for upload or files:read for retrieval.
404not_foundNo owned available file record, or the supplied model is unknown or is not an asynchronous generation model.
429rate_limitedThe key's upload rate limit was reached, or all upload slots are in use.
500internal_errorRivya could not confirm the result of the request, or required metadata signing is unavailable.
503public_api_disabledPublic API is disabled in the current environment.

If an upload times out or its response cannot be read, you may not know whether a file was stored. Keep any request ID you received. Retrying can create another file record; it does not prove the earlier upload failed.

Security Notes

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

Keep uploaded URLs and duration_token, image_dimensions_token, and video_metadata_token values out of public pages. Use them for the follow-up request and keep the original media in your own storage. The metadata endpoint checks account ownership; do not rely on that check to restrict downloads from the returned URL.