Files API

استخدم 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

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

حدود الرفع

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

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

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

تشمل حدود مراجع الصور الموقعة ما يلي:

يجب رفع كل صورة مرجعية لنماذج Image5 أو لنموذجي Grok Imagine Image 2.0 وWan 3.0 باستخدام model المستهدف. احتفظ بقيم width وheight وsize_bytes وimage_dimensions_token من الاستجابة الأصلية؛ ويجب أن يرسلها طلب التوليد بأسماء width وheight وsizeBytes وimageDimensionsToken. لا تفي عناوين URL الخارجية العشوائية للصور بمتطلبات هذا التحقق المرتبط بالنموذج.

يتحقق تفكيك الطبقات أيضا من أبعاد الصورة المكتشفة قبل الرفع: يجب أن يتراوح إجمالي عدد البكسلات بين 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؛ أعد رفع الفيديو المصدر بدلا من اختلاق البيانات الوصفية.

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

استخدم 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-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"
}

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

{
  "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 خاصة بالنموذج. إذا وثق مرجع Model API معاملا محددا، فاتبع صفحة ذلك النموذج بدلا من اختراع حقل جديد.

الأخطاء

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

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

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

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

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

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

صفحات ذات صلة

• إنشاء توليد

• Rivya TypeScript SDK

• مرجع Model API

• أخطاء API وحدودها

• OpenAPI وعقد Schema