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 استعمال کریں۔

فائلز API صرف reference inputs کے لیے ہے۔ یہ خود generation tasks create نہیں کرتی۔ Upload کے بعد returned url اور metadata کو model params میں pass کریں، عموماً params.referenceMediaItems کے ذریعے۔

اینڈ پوائنٹ

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

درکار headers:

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

Upload کے لیے API key میں files:create scope اور metadata retrieve کرنے کے لیے files:read ہونا چاہیے۔ نئی بنائی گئی Rivya API keys میں default طور پر دونوں scopes شامل ہوتے ہیں۔

Multipart fields

فیلڈ	قسم	درکار	نوٹس
`file`	binary	ہاں	Upload کی جانے والی image، video، یا audio file۔
`kind`	string	ہاں	`image`، `video`، یا `audio` میں سے ایک۔
`model`	string	نہیں	Public model ID۔ موجود ہو تو Rivya validate کرتا ہے کہ model اس file kind کو accept کرتا ہے۔
`client_request_id`	string	نہیں	آپ کا trace ID، 128 characters تک۔

جب file کسی specific model کے لیے intended ہو تو model استعمال کریں۔ اس سے file accept ہونے سے پہلے model-specific MIME اور size validation ملتی ہے۔

Upload limits

فائلز API وہی upload policy استعمال کرتی ہے جو Rivya reference uploads استعمال کرتے ہیں۔

Default limits یہ ہیں:

Kind	Default زیادہ سے زیادہ size	عام 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 مثال

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 مثال

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 مثال

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 require کرے تو duration_token کو related generation parameter میں durationToken کے طور پر copy کریں۔

File metadata retrieve کریں

اسی 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 جیسی same PublicApiFile shape استعمال کرتا ہے۔ اگر file کسی دوسرے account کی ہو یا اب available نہ ہو تو API not_found return کرتی ہے۔

Upload کو generation params میں استعمال کریں

POST /api/v1/generations کو top-level files field نہ بھیجیں۔

نئی integrations کے لیے upload result کو params.referenceMediaItems کے ذریعے pass کریں:

{
  "model": "nano-banana-2",
  "prompt": "اس product photo کو clean editorial catalog page کے لیے restyle کریں",
  "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

فائلز API باقی Rivya API جیسا same public error envelope استعمال کرتی ہے:

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

عام cases:

HTTP	Code	وجہ
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 میں بہت زیادہ 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 سمجھیں۔ انہیں صرف follow-up generation request build کرنے کے لیے استعمال کریں، اور public pages میں expose نہ کریں۔

فائلز API

فہرست