Files API ของ Rivya

ใช้ POST /api/v1/files เพื่ออัปโหลดสื่ออ้างอิงสำหรับโมเดลที่ต้องรับรูปภาพ วิดีโอ หรือเสียง

Files API ใช้สำหรับอินพุตอ้างอิงเท่านั้น ไม่ได้สร้างงานด้วยตัวเอง หลังอัปโหลดแล้ว ให้ส่ง url และข้อมูลประกอบที่ได้กลับมาเข้าไปใน params ของโมเดล โดยปกติจะผ่าน params.referenceMediaItems

ปลายทางของ API

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 และขนาดตามโมเดลก่อนที่ไฟล์จะถูกยอมรับ

ขีดจำกัดการอัปโหลด

Files 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 และ Wan 3.0 ได้แก่:

ตัวเลขเหล่านี้เป็นเพดานอัปโหลดที่ 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"
}

สำหรับ 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 ของแต่ละโมเดล ระบุพารามิเตอร์เฉพาะไว้ ให้ทำตามหน้าโมเดลนั้นแทนการคิดฟิลด์ใหม่เอง

ข้อผิดพลาด

Files API ใช้รูปแบบข้อผิดพลาดสาธารณะเดียวกับส่วนอื่นของ Rivya API:

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

กรณีที่พบบ่อย:

หมายเหตุด้านความปลอดภัย

อย่าเก็บคีย์ API แบบเต็มไว้ในเบราว์เซอร์ ไคลเอนต์มือถือ บันทึกระบบ เหตุการณ์วิเคราะห์ หรือภาพหน้าจอ

ให้ถือ URL ของไฟล์ที่อัปโหลดและค่า duration_token, image_dimensions_token และ video_metadata_token เป็นข้อมูลสำหรับการเชื่อมต่อชั่วคราว ใช้เฉพาะเพื่อสร้างคำขอถัดไป และอย่าเปิดเผยบนหน้าสาธารณะ

หน้าที่เกี่ยวข้อง

• การสร้างงานผ่าน API

• Rivya TypeScript SDK

• เอกสารอ้างอิง API ของแต่ละโมเดล

• ข้อผิดพลาดและขีดจำกัด API

• สัญญา OpenAPI และสคีมา