Files API मार्गदर्शिका

जिन मॉडल को इमेज, वीडियो या ऑडियो इनपुट चाहिए, उनके लिए संदर्भ मीडिया अपलोड करने के लिए POST /api/v1/files इस्तेमाल करें।

Files API केवल संदर्भ इनपुट के लिए है। यह अपने आप जनरेशन कार्य नहीं बनाता। अपलोड के बाद मिले url और मेटाडेटा को मॉडल params में भेजें, आम तौर पर params.referenceMediaItems के माध्यम से।

एंडपॉइंट

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

ज़रूरी हेडर:

Authorization: Bearer rvya_sk_...
Content-Type: multipart/form-data

अपलोड करने के लिए API कुंजी में files:create अनुमति और मेटाडेटा प्राप्त करने के लिए files:read होना चाहिए। नई Rivya API कुंजियों में डिफ़ॉल्ट रूप से दोनों अनुमतियां शामिल होती हैं।

मल्टीपार्ट फ़ील्ड

जब फ़ाइल किसी खास मॉडल के लिए हो, तब model इस्तेमाल करें। इससे फ़ाइल स्वीकार होने से पहले मॉडल-विशिष्ट MIME और आकार की पुष्टि हो जाती है।

अपलोड सीमाएँ

Files API वही अपलोड नीति इस्तेमाल करता है जो Rivya के संदर्भ अपलोड पर लागू होती है।

सामान्य सीमाएं:

कुछ मॉडल की सीमाएं अलग होती हैं। उदाहरण के लिए, कुछ संदर्भ-चित्र मॉडल बड़े चित्र स्वीकार करते हैं और कुछ वीडियो-संदर्भ मॉडल उतनी बड़ी फ़ाइल स्वीकार करते हैं, जितनी उत्पाद सुरक्षित रूप से संभाल सकता है। लक्षित मॉडल पता हो, तो हमेशा model भेजें और उपयोगकर्ता के अपलोड स्वीकार करने से पहले मॉडल API संदर्भ पढ़ें।

हस्ताक्षरित चित्र-संदर्भ की सीमाओं में ये शामिल हैं:

हर Image5, Grok Imagine Image 2.0 या Wan 3.0 संदर्भ चित्र को उसके लक्षित model के साथ अपलोड करना जरूरी है। मूल जवाब के width, height, size_bytes और image_dimensions_token सुरक्षित रखें; जनरेशन अनुरोध में उन्हें width, height, sizeBytes और imageDimensionsToken के रूप में भेजना जरूरी है। मनमाने बाहरी चित्र URL मॉडल से बंधे इस सत्यापन को पूरा नहीं करते।

Layer Decomposition में अपलोड से पहले पहचाने गए चित्र आयाम भी सत्यापित होते हैं: कुल 262,144–36,000,000 पिक्सेल और 1:16 से 16:1 तक का पक्षानुपात।

Video8 की मॉडल-विशिष्ट अपलोड सीमाओं में ये शामिल हैं:

ये Rivya की स्वीकार्य अधिकतम अपलोड सीमाएं हैं और आधारभूत सेवा की सीमा से कम हो सकती हैं। हर Video8 या Wan 3.0 संदर्भ को उसके लक्षित model के साथ अपलोड करें। संदर्भ वीडियो के लिए मूल, मॉडल से बंधे अपलोड जवाब का हस्ताक्षरित अवधि प्रमाण और हस्ताक्षरित वीडियो मेटाडेटा, दोनों जरूरी हैं। Wan 3.0 के ध्वनि अवधि टोकन पहचाने गए MIME प्रकार और अपलोड के बाइट आकार से भी बंधे होते हैं।

Wan 3.0 चित्रों की हर भुजा 240–8,000 पिक्सेल और वीडियो की हर भुजा 240–4,096 पिक्सेल होनी चाहिए; दोनों का पक्षानुपात 1:8–8:1 की सीमा में रहना चाहिए। संदर्भ विधि में वीडियो और ध्वनि के लिए अलग-अलग कुल 15 सेकंड की सीमा है, और केवल ध्वनि को संदर्भ के रूप में नहीं भेजा जा सकता।

Rivya केवल फ़ाइल नाम का विस्तार नहीं, बल्कि पहचाना गया फ़ाइल हस्ताक्षर सत्यापित करता है।

curl उदाहरण

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 उदाहरण

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();
console.log(uploadedFile.id, uploadedFile.url);

Python उदाहरण

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()
print(uploaded_file["id"], uploaded_file["url"])

जवाब

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

वीडियो और ध्वनि अपलोड के लिए duration_seconds भरा हो सकता है। जब कोई मॉडल अवधि सत्यापन मांगता है, तो संबंधित जनरेशन मापदंड में duration_token को durationToken के रूप में कॉपी करें।

समर्थित चित्र अपलोड में width और height फ़ाइल के बाइट से पहचाने जाते हैं। सभी पांच Image5 मॉडल, Grok Imagine Image 2.0 और Wan 3.0 को मूल, मॉडल से बंधे अपलोड जवाब का हस्ताक्षरित image_dimensions_token चाहिए; उसे संदर्भ प्रविष्टि में imageDimensionsToken और size_bytes को sizeBytes के रूप में कॉपी करें। बाद में फ़ाइल मेटाडेटा लेने पर यह टोकन null हो सकता है, इसलिए मूल टोकन उपलब्ध न हो या उसकी अवधि समाप्त हो गई हो, तो स्रोत चित्र फिर अपलोड करें।

समर्थित Video8 और Wan 3.0 वीडियो अपलोड में Rivya MP4 या MOV बाइट जांचकर video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes और video_metadata_token लौटाता है। इन्हें संदर्भ प्रविष्टि में width, height, framesPerSecond, videoBitrateMbps, sizeBytes और videoMetadataToken के रूप में कॉपी करें। टोकन खाते, लक्षित मॉडल, URL, MIME प्रकार, आयाम, फ़्रेम दर, बिटरेट और अपलोड आकार से बंधा होता है। अवधि का सत्यापन अलग durationToken से होता है। बाद में फ़ाइल मेटाडेटा लेने पर video_metadata_token null हो सकता है; मेटाडेटा गढ़ने के बजाय स्रोत वीडियो फिर अपलोड करें।

फ़ाइल मेटाडेटा प्राप्त करें

उसी Rivya खाते की फ़ाइल का मेटाडेटा पढ़ने के लिए GET /api/v1/files/{fileId} इस्तेमाल करें:

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

जवाब अपलोड जैसा ही PublicApiFile रूप इस्तेमाल करता है। अगर फ़ाइल किसी दूसरे खाते की है या अब उपलब्ध नहीं है, तो API not_found लौटाता है।

जनरेशन पैरामीटर में अपलोड का उपयोग करें

ऊपरी स्तर का files फ़ील्ड POST /api/v1/generations पर न भेजें।

नए एकीकरण के लिए अपलोड का नतीजा params.referenceMediaItems के माध्यम से भेजें:

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

Video या audio के लिए:

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

ऊपर दिए गए सभी हस्ताक्षरित वीडियो फ़ील्ड Video8 और Wan 3.0 वीडियो संदर्भों के लिए जरूरी हैं। Wan 3.0 ध्वनि संदर्भों में mimeType, sizeBytes, durationSeconds और durationToken इस्तेमाल होते हैं; चित्र संदर्भ ऊपर बताए गए मॉडल-विशिष्ट चित्र मेटाडेटा अनुबंध का पालन करते हैं।

Seedream 5.0 Pro Layer Decomposition के लिए ठीक एक चित्र और उसके मॉडल से बंधे अपलोड से मिला हस्ताक्षरित मेटाडेटा भेजें:

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

कुछ पुराने मॉडल मापदंड अब भी मॉडल-विशिष्ट URL फ़ील्ड इस्तेमाल करते हैं। अगर मॉडल API संदर्भ में कोई खास मापदंड दर्ज है, तो नया फ़ील्ड गढ़ने के बजाय उस मॉडल पेज का पालन करें।

त्रुटियाँ

Files API बाकी Rivya API जैसा ही सार्वजनिक त्रुटि आवरण इस्तेमाल करता है:

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

आम मामले:

सुरक्षा नोट

पूरी API कुंजियां ब्राउज़र, मोबाइल क्लाइंट, लॉग, विश्लेषिकी घटनाओं या स्क्रीनशॉट में न सहेजें।

अपलोड की गई फ़ाइल के URL तथा duration_token, image_dimensions_token और video_metadata_token मानों को अस्थायी एकीकरण सामग्री मानें। इन्हें केवल आगे का जनरेशन अनुरोध बनाने के लिए इस्तेमाल करें और सार्वजनिक पेजों पर उजागर न करें।

संबंधित पेज

• जनरेशन बनाएं

• Rivya TypeScript SDK

• मॉडल API संदर्भ

• API त्रुटियाँ और सीमाएँ

• OpenAPI और स्कीमा अनुबंध