MIME checks, size limits और duration tokens के साथ Rivya API generation requests के लिए image, video या audio reference files upload करें।

जिन models को image, video या audio inputs चाहिए, उनके लिए 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। Present होने पर Rivya validate करता है कि model यह file kind accept करता है।
`client_request_id`	string	no	आपका trace ID, 128 characters तक।

जब file किसी specific model के लिए हो, तब model इस्तेमाल करें। इससे file accept होने से पहले model-specific MIME और size validation मिलती है।

Upload Limits

Files API वही upload policy इस्तेमाल करता है जो 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`

कुछ models की limits अलग होती हैं। उदाहरण के लिए, selected reference-image models larger 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

Same Rivya account की 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

Top-level files field को POST /api/v1/generations पर न भेजें।

नई 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 करता है, तो new 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`	Bearer API key missing या invalid है।
403	`api_scope_denied`	Requested action के लिए key में `files:create` या `files:read` शामिल नहीं है।
429	`rate_limited`	Current minute में बहुत अधिक 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 बनाने के लिए इस्तेमाल करें, और public pages में expose न करें।

Files API

विषय-सूची