อัปโหลดไฟล์อ้างอิงแบบรูปภาพ วิดีโอ หรือเสียงสำหรับคำขอสร้างงานผ่าน Rivya API พร้อมการตรวจ MIME, size limits และ duration tokens

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

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

Endpoint ของ API

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 key ต้องมี scope files:create เพื่ออัปโหลด และ files:read เพื่อดึง metadata key ของ Rivya API ที่สร้างใหม่จะมี scopes ทั้งสองนี้ตามค่าเริ่มต้น

ฟิลด์ Multipart

ฟิลด์	ประเภท	จำเป็น	หมายเหตุ
`file`	binary	yes	ไฟล์รูปภาพ วิดีโอ หรือเสียงที่จะอัปโหลด
`kind`	string	yes	หนึ่งใน `image`, `video` หรือ `audio`
`model`	string	no	public model ID เมื่อส่งมา Rivya จะตรวจว่าโมเดลรับ file kind นี้หรือไม่
`client_request_id`	string	no	trace ID ของคุณ สูงสุด 128 ตัวอักษร

ใช้ model เมื่อไฟล์นี้ตั้งใจใช้กับโมเดลเฉพาะ วิธีนี้ช่วยให้คุณได้การตรวจ MIME และขนาดตามโมเดลก่อนที่ไฟล์จะถูกยอมรับ

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

Files API ใช้นโยบายอัปโหลดเดียวกับการอัปโหลด reference ของ Rivya

ค่า default limits:

ชนิด	ขนาดสูงสุดเริ่มต้น	MIME type ที่พบบ่อย
รูปภาพ (`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`

บางโมเดลมีขีดจำกัดต่างกัน ตัวอย่างเช่น โมเดล reference-image บางตัวรองรับรูปภาพขนาดใหญ่กว่า และโมเดล video-reference บางตัวรองรับไฟล์ได้ถึงเพดานอัปโหลดที่ปลอดภัยของผลิตภัณฑ์ ส่ง model เสมอเมื่อคุณรู้โมเดลเป้าหมาย และอ่าน Model API Reference ก่อนรับ upload จากผู้ใช้

Rivya ตรวจ signature ของไฟล์ที่ตรวจพบ ไม่ได้ดูแค่นามสกุลไฟล์

ตัวอย่าง 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
}

สำหรับ video และ audio uploads อาจมีค่า duration_seconds เมื่อโมเดลต้องตรวจ duration ให้คัดลอก duration_token ไปยัง generation parameter ที่เกี่ยวข้องในชื่อ durationToken

ดึง Metadata ของไฟล์

ใช้ GET /api/v1/files/{fileId} เพื่ออ่าน metadata ของไฟล์ที่เป็นของบัญชี Rivya เดียวกัน:

curl https://rivya.ai/api/v1/files/file_... \
  -H "Authorization: Bearer rvya_sk_..."

การตอบกลับใช้ shape PublicApiFile เดียวกับ upload หากไฟล์เป็นของบัญชีอื่นหรือใช้งานไม่ได้แล้ว API จะคืน not_found

ใช้ Upload ใน Generation Params

อย่าส่ง field files ระดับบนสุดไปยัง POST /api/v1/generations

สำหรับการเชื่อมต่อใหม่ ให้ส่งผลลัพธ์ upload ผ่าน 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"
}

สำหรับ video หรือ audio:

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

model parameters รุ่นเก่าบางตัวยังใช้ URL fields เฉพาะโมเดล หาก Model API Reference ระบุ parameter เฉพาะไว้ ให้ทำตามหน้าโมเดลนั้นแทนการคิด field ใหม่เอง

ข้อผิดพลาด

Files API ใช้ public error envelope เดียวกับส่วนอื่นของ Rivya API:

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

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

HTTP	Code	สาเหตุ
400	`validation_failed`	ขาด `file`, `kind` ไม่รองรับ, MIME type ไม่รองรับ, file ใหญ่เกินไป หรือโมเดลไม่รับ kind ที่เลือก
401	`api_key_missing` / `api_key_invalid`	ขาด Bearer API key หรือ key ไม่ถูกต้อง
403	`api_scope_denied`	key ไม่มี `files:create` หรือ `files:read` สำหรับ action ที่เรียก
429	`rate_limited`	file uploads ในหนึ่งนาทีปัจจุบันมากเกินไป
503	`public_api_disabled`	Public API ถูกปิดในสภาพแวดล้อมปัจจุบัน

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

อย่าเก็บ API keys เต็มไว้ใน browsers, mobile clients, logs, analytics events หรือ screenshots

ให้ถือ uploaded file URLs และค่า duration_token เป็นวัสดุสำหรับการเชื่อมต่อชั่วคราว ใช้เฉพาะเพื่อสร้าง generation request ถัดไป และอย่าเปิดเผยใน public pages

Files API ของ Rivya