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
| Field | Type | Required | Notes |
|---|---|---|---|
file | binary | yes | One image, video, or audio file. |
kind | string | yes | One of image, video, or audio. |
model | string | no | Target model ID. Rivya checks whether this model is currently callable and accepts the file kind. |
client_request_id | string | no | Your 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.
| Kind | Default maximum file size | MIME types |
|---|---|---|
image | 10 MiB | image/jpeg, image/png, image/webp |
video | 50 MiB | video/mp4, video/quicktime, video/webm |
audio | 10 MiB | audio/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:
| Model | Images per generation | Maximum per image | Image formats |
|---|---|---|---|
seedream-5-pro | up to 10 | 10 MiB | JPEG, PNG, WebP |
seedream-5-pro-layer-decomposition | exactly 1 | 30 MiB | JPEG or PNG |
nano-banana-2-lite | up to 10 | 30 MiB | JPEG, PNG, WebP |
qwen-image-3 / qwen-image-3-pro | up to 3 | 10 MiB | JPEG, PNG, WebP, BMP, GIF, TIFF |
grok-imagine-image-2-0 | up to 5 in editing mode | 10 MiB | JPEG, PNG, WebP |
wan-3-0-video | up to 10 in reference mode; 1 required and 1 optional in frames mode | 20 MiB | JPEG, 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:
| Model | Images per generation | Videos per generation | Audio files per generation |
|---|---|---|---|
kling-3-turbo | 1 × 10 MiB; JPEG or PNG | not accepted | not accepted |
seedance-2-mini | up to 9 × 30 MiB; JPEG, PNG, WebP, or GIF | up to 3 × 50 MiB; MP4 or MOV | up to 3 × 15 MiB; MP3 or WAV |
seedance-2-5 | up to 30 × 30 MiB; JPEG, PNG, or WebP | up to 10 × 95 MiB; MP4 or MOV | up to 10 × 15 MiB; MP3 or WAV |
minimax-h3 | up to 9 × 30 MiB; JPEG, PNG, or WebP | up to 3 × 50 MiB; MP4 or MOV | up to 3 × 15 MiB; MP3 or WAV |
happyhorse-1-1 | up to 9 × 20 MiB; JPEG, PNG, or WebP | not accepted | not accepted |
omnihuman-1-5 | 1 × 10 MiB; JPEG, PNG, or WebP | not accepted | 1 × 10 MiB; MP3, M4A, WAV, AAC, or OGG |
volcengine-video-lip-sync | not accepted | 1 × 95 MiB; MP4 or MOV | 1 × 10 MiB; MP3, M4A, WAV, AAC, or OGG |
wan-3-0-video | frames: 1 required and 1 optional; reference: up to 10 × 20 MiB; JPEG, non-transparent PNG, WebP, or BMP | reference: up to 5 × 95 MiB; MP4 or MOV; 1–15 seconds each and 15 seconds total | reference: 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:
| HTTP | Code | Cause |
|---|---|---|
| 400 | validation_failed | Missing file, invalid multipart headers or length, unsupported kind or format, oversized file, invalid required metadata, or a model that cannot accept this upload. |
| 401 | api_key_missing / api_key_invalid / api_key_revoked / api_key_expired | Missing, invalid, inactive, or expired Bearer key, or an account that cannot use the Public API. |
| 403 | api_scope_denied | The key lacks files:create for upload or files:read for retrieval. |
| 404 | not_found | No owned available file record, or the supplied model is unknown or is not an asynchronous generation model. |
| 429 | rate_limited | The key's upload rate limit was reached, or all upload slots are in use. |
| 500 | internal_error | Rivya could not confirm the result of the request, or required metadata signing is unavailable. |
| 503 | public_api_disabled | Public 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.
