ফাইল API নির্দেশিকা

ছবি, ভিডিও বা অডিও ইনপুট দরকার এমন মডেলের রেফারেন্স মাধ্যম আপলোড করতে POST /api/v1/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 ও আকার যাচাই হবে।

আপলোডের সীমা

ফাইল 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 কী ব্রাউজার, মোবাইল ক্লায়েন্ট, লগ, বিশ্লেষণমূলক ঘটনা বা পর্দার ছবিতে সংরক্ষণ করবেন না।

আপলোড করা ফাইলের URL এবং duration_token, image_dimensions_token ও video_metadata_token-এর মানকে সাময়িক সমন্বয়-উপকরণ হিসেবে বিবেচনা করুন। এগুলো শুধু পরবর্তী তৈরির অনুরোধ গঠনে ব্যবহার করুন; প্রকাশ্য পাতায় দেখাবেন না।

সম্পর্কিত পৃষ্ঠা

• তৈরির কাজ শুরু করুন

• Rivya TypeScript SDK

• মডেল API রেফারেন্স

• API ত্রুটি ও সীমা

• OpenAPI ও স্কিমা চুক্তি