ارفع ملفات مرجعية من الصور أو الفيديو أو الصوت لطلبات التوليد عبر Rivya API، مع فحوصات MIME، وحدود الحجم، وduration tokens.

استخدم POST /api/v1/files لرفع وسائط مرجعية للنماذج التي تحتاج إلى مدخلات صور أو فيديو أو صوت.

Files API مخصص للمدخلات المرجعية فقط. لا ينشئ مهام توليد بمفرده. بعد الرفع، مرر url والبيانات الوصفية العائدة إلى params الخاصة بالنموذج، عادة عبر params.referenceMediaItems.

Endpoint

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

يجب أن يتضمن مفتاح API نطاق files:create للرفع وfiles:read لجلب البيانات الوصفية. تتضمن مفاتيح Rivya API الجديدة كلا النطاقين افتراضيا.

حقول Multipart

Field	Type	Required	Notes
`file`	binary	yes	ملف الصورة أو الفيديو أو الصوت المراد رفعه.
`kind`	string	yes	واحد من `image` أو `video` أو `audio`.
`model`	string	no	معرف نموذج عام. عند وجوده، تتحقق Rivya من أن النموذج يقبل نوع الملف هذا.
`client_request_id`	string	no	معرف التتبع الخاص بك، حتى 128 حرفا.

استخدم model عندما يكون الملف موجها إلى نموذج محدد. يمنحك ذلك تحققا خاصا بالنموذج من MIME والحجم قبل قبول الملف.

حدود الرفع

تستخدم Files API سياسة الرفع نفسها الخاصة بمراجع Rivya.

الحدود الافتراضية:

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`

بعض النماذج لها حدود مختلفة. على سبيل المثال، تسمح نماذج صور مرجعية محددة بصور أكبر، وتسمح نماذج فيديو مرجعية محددة بملفات حتى سقف الرفع الآمن للمنتج. مرر دائما model عندما تعرف النموذج المستهدف، واقرأ مرجع Model API قبل قبول رفع المستخدمين.

تتحقق 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" \
  -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"])

الاستجابة

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

بالنسبة إلى رفع الفيديو والصوت، قد تمتلئ قيمة duration_seconds. عندما يتطلب نموذج التحقق من المدة، انسخ duration_token إلى معامل التوليد المرتبط باسم durationToken.

جلب بيانات الملف الوصفية

استخدم GET /api/v1/files/{fileId} لقراءة البيانات الوصفية لملف يملكه حساب Rivya نفسه:

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

للفيديو أو الصوت:

{
  "url": "https://...",
  "kind": "video",
  "name": "source.mov",
  "mimeType": "video/quicktime",
  "durationSeconds": 12.4,
  "durationToken": "duration_token_from_files_api"
}

لا تزال بعض معاملات النماذج الأقدم تستخدم حقول URL خاصة بالنموذج. إذا وثق مرجع Model API معاملا محددا، فاتبع صفحة ذلك النموذج بدلا من اختراع حقل جديد.

الأخطاء

تستخدم Files API غلاف الخطأ العام نفسه كبقية Rivya API:

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

الحالات الشائعة:

HTTP	Code	Cause
400	`validation_failed`	حقل `file` مفقود، أو `kind` غير مدعوم، أو نوع MIME غير مدعوم، أو الملف كبير جدا، أو النموذج لا يقبل النوع المحدد.
401	`api_key_missing` / `api_key_invalid`	مفتاح Bearer API مفقود أو غير صالح.
403	`api_scope_denied`	لا يتضمن المفتاح `files:create` أو `files:read` للإجراء المطلوب.
429	`rate_limited`	عدد كبير جدا من عمليات رفع الملفات في الدقيقة الحالية.
503	`public_api_disabled`	Public API معطل في البيئة الحالية.

ملاحظات الأمان

لا تخزن مفاتيح API الكاملة في المتصفحات، أو عملاء الهاتف، أو السجلات، أو أحداث analytics، أو لقطات الشاشة.

تعامل مع عناوين URL للملفات المرفوعة وقيم duration_token كمواد تكامل مؤقتة. استخدمها فقط لبناء طلب التوليد اللاحق، ولا تعرضها في صفحات عامة.

Files API