MIME checks, size limits এবং duration tokens সহ Rivya API generation requests-এর জন্য image, video বা audio reference files upload করুন।

image, video বা audio inputs দরকার এমন models-এর reference media upload করতে POST /api/v1/files ব্যবহার করুন।

Files API শুধু reference inputs-এর জন্য। এটি নিজে generation tasks create করে না। upload-এর পরে returned url এবং metadata model params-এ pass করুন, সাধারণত 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

upload করতে API key-তে files:create scope থাকতে হবে এবং metadata retrieve করতে files:read থাকতে হবে। newly created Rivya API keys defaultভাবে দুইটি scopes অন্তর্ভুক্ত করে।

Multipart Fields

Field	Type	Required	Notes
`file`	binary	yes	upload করার image, video বা audio file।
`kind`	string	yes	`image`, `video` বা `audio`-এর একটি।
`model`	string	no	Public model ID। থাকলে Rivya validate করে যে model এই file kind accept করে।
`client_request_id`	string	no	আপনার trace ID, সর্বোচ্চ 128 characters।

file নির্দিষ্ট model-এর জন্য হলে model ব্যবহার করুন। এতে file accepted হওয়ার আগে model-specific MIME এবং size validation পাবেন।

Upload Limits

Files API Rivya reference uploads-এর একই upload policy ব্যবহার করে।

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`

কিছু models-এর limits আলাদা। উদাহরণস্বরূপ, selected reference-image models বড় images allow করে, এবং selected video-reference models product-এর edge-safe upload ceiling পর্যন্ত files allow করে। target model জানলে সবসময় model pass করুন, এবং user uploads accept করার আগে Model API Reference পড়ুন।

Rivya শুধু filename extension নয়, detected file signature validate করে।

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
}

video এবং audio uploads-এর জন্য duration_seconds populated হতে পারে। model duration verification চাইলে related generation parameter-এ duration_token-কে durationToken হিসেবে copy করুন।

Retrieve File Metadata

একই Rivya account-এর owned file-এর metadata read করতে GET /api/v1/files/{fileId} ব্যবহার করুন:

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

response upload-এর মতো একই PublicApiFile shape ব্যবহার করে। file অন্য account-এর হলে বা আর available না থাকলে API not_found return করে।

Use The Upload In Generation Params

POST /api/v1/generations-এ top-level files field পাঠাবেন না।

new integrations-এর জন্য upload result params.referenceMediaItems দিয়ে pass করুন:

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

video বা audio-এর জন্য:

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

কিছু older model parameters এখনও model-specific URL fields ব্যবহার করে। Model API Reference কোনো specific parameter document করলে নতুন field invent না করে সেই model page follow করুন।

Errors

Files API Rivya API-এর বাকি অংশের মতো একই public error envelope ব্যবহার করে:

{
  "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, অথবা model selected kind accept করে না।
401	`api_key_missing` / `api_key_invalid`	missing বা invalid Bearer API key।
403	`api_scope_denied`	requested action-এর জন্য key-তে `files:create` বা `files:read` নেই।
429	`rate_limited`	current minute-এ too many file uploads।
503	`public_api_disabled`	current environment-এ Public API disabled।

Security Notes

full API keys browsers, mobile clients, logs, analytics events বা screenshots-এ store করবেন না।

uploaded file URLs এবং duration_token values-কে temporary integration material হিসেবে treat করুন। এগুলো শুধু follow-up generation request build করতে ব্যবহার করুন, public pages-এ expose করবেন না।

Files API

Table of Contents