فائلز API

جن ماڈلز کو تصویر، ویڈیو یا آواز کا ان پٹ درکار ہو ان کے لیے حوالہ جاتی میڈیا اپ لوڈ کرنے کو POST /api/v1/files استعمال کریں۔

Files API صرف حوالہ جاتی ان پٹ کے لیے ہے۔ یہ خود تخلیقی کام نہیں بناتی۔ اپ لوڈ کے بعد حاصل شدہ URL اور معلومات کو ماڈل کے params میں بھیجیں۔

اینڈ پوائنٹ

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 اور جسامت کی جانچ ہو جاتی ہے۔

اپ لوڈ کی حدود

فائلز 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 واپس کرتی ہے۔

اپ لوڈ کو نتیجہ سازی کے پیرامیٹرز میں استعمال کریں

POST /api/v1/generations کو بالائی سطح کا files خانہ نہ بھیجیں۔

نئے انضمامات کے لیے اپ لوڈ کا نتیجہ 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 حوالہ کسی مخصوص پیرامیٹر کی وضاحت کرتا ہے تو نیا خانہ گھڑنے کے بجائے اسی ماڈل صفحے کی پیروی کریں۔

خرابیاں

فائلز API باقی Rivya API جیسا ہی عوامی خرابی کا سانچہ استعمال کرتی ہے:

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

عام صورتیں:

حفاظتی نکات

مکمل API کلیدیں براؤزرز، موبائل کلائنٹس، نوشتوں، تجزیاتی واقعات یا تصویری عکسوں میں محفوظ نہ کریں۔

اپ لوڈ شدہ فائل URLs اور duration_token، image_dimensions_token اور video_metadata_token کی اقدار کو عارضی انضمامی مواد سمجھیں۔ انہیں صرف اگلی نتیجہ سازی درخواست بنانے کے لیے استعمال کریں اور عوامی صفحات پر ظاہر نہ کریں۔

متعلقہ صفحات

• نتیجہ بنانے کی درخواست

• Rivya TypeScript SDK

• ماڈل API حوالہ

• API کی خرابیاں اور حدود

• OpenAPI اور اسکیما کا معاہدہ