Files API
通过 Rivya API 上传图片、视频或音频参考文件,并使用 MIME 校验、大小限制和 duration token。
最近审阅于 2026年11月11日
使用 POST /api/v1/files 上传模型生成所需的图片、视频或音频参考素材。
Files API 只用于参考输入,本身不会创建生成任务。上传完成后,把返回的 url 和元数据放入模型 params,通常使用 params.referenceMediaItems。
提示词单位与完整图层结果
读取 GET /api/v1/models 时,请将 prompt_length_unit 与 max_prompt_length 一起使用。utf8_bytes 计算原文的 UTF-8 字节,包含空格和换行;utf16_code_units 计算 JavaScript 的 UTF-16 代码单元。上限为 null 不代表文字不限长或可以不填。Gemini TTS 使用字节单位。
已完成的图层拆分结果可在完整的 result.urls 之外提供 result.layers。请保留每层返回的 z_index、URL、尺寸、名称、说明和边界框,索引零是底图。TypeScript SDK 已提供这些字段。参考文件必须按所选模型上传,并传回原始签名元数据;单独声明尺寸或时长不能代替核验。
Endpoint
让 curl、FormData 或 multipart 库计算 boundary 和正文长度;以下 JavaScript、Python 示例不要手动设置 Content-Type。缺少有效 Content-Length 会被拒绝。Key 还须有效、未撤销且未过期。
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; boundary=...
Content-Length: ...上传时 API Key 必须包含 files:create scope;重新读取元数据时必须包含 files:read scope。新创建的 Rivya API Key 默认包含这两个 scope。
Multipart 字段
从模型 API 参考取得精确 ID。指定 model 后会校验可调用状态、文件类别、MIME、大小及所需元数据。需要模型绑定签名时,必须为同一目标模型上传。client_request_id 只是追踪值,不提供幂等;重复上传可能新建文件记录,此端点不按 Idempotency-Key 重放。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | binary | 是 | 要上传的图片、视频或音频文件。 |
kind | string | 是 | image、video 或 audio。 |
model | string | 否 | 公共模型 ID。传入后,Rivya 会校验该模型是否接受这种文件类型。 |
client_request_id | string | 否 | 你的追踪 ID,最多 128 个字符。 |
如果这个文件会用于某个确定模型,建议传入 model。这样可以在文件被接受前执行模型专属的 MIME 和大小校验。
上传限制
Seedance 2 Mini 与 MiniMax H3 的视频、音频均为每份 2–15 秒;Seedance 2.5 为每份 2–30 秒。OmniHuman 1.5 音频须大于 0 且小于 60 秒;Volcengine Lip Sync 的视频和音频都须能检测到正时长。Wan 3.0 图片每边 240–8,000 像素、视频每边 240–4,096 像素,宽高比均为 1:8–8:1;音频和视频各有独立 15 秒总量,音频不能是唯一媒体。参考视频秒数加输出秒数不超过 30,且智能输出时长不能配参考视频。
每次请求只上传一个文件;表中数量上限是生成任务的参考数量,仍须满足所选模式的组合要求。Rivya 同时检查文件内容和大小,扩展名或客户端 MIME 不能证明格式。1 MiB = 1,048,576 字节;单文件总上限为 95 MiB,声明的 multipart 正文总上限为 96 MiB,包含边界与字段。模型规则可以改变默认限制。
Files API 复用 Rivya 参考素材上传 policy。
默认限制:
| 类型 | 默认最大大小 | 常见 MIME |
|---|---|---|
image | 10 MiB | image/jpeg, image/png, image/webp |
video | 50 MiB | video/mp4, video/quicktime, video/webm |
audio | 10 MiB | audio/mpeg, audio/mp4, audio/wav, audio/x-wav, audio/aac, audio/ogg |
部分模型有不同限制。例如,部分参考图片模型允许更大的图片,部分视频参考模型允许使用产品边界内更高的上传上限。只要你知道目标模型,就应该传入 model,并在接收用户上传前阅读 模型 API Reference。
已签名图片参考素材的限制如下:
| 模型 | 最多图片数 | 单图限制 | 接受的图片 MIME |
|---|---|---|---|
seedream-5-pro | 10 | 10 MiB | JPEG、PNG、WebP |
seedream-5-pro-layer-decomposition | 必须恰好 1 张 | 30 MiB | JPEG / PNG |
nano-banana-2-lite | 10 | 30 MiB | JPEG、PNG、WebP |
qwen-image-3 / qwen-image-3-pro | 3 | 10 MiB | JPEG、PNG、WebP、BMP、GIF、TIFF |
grok-imagine-image-2-0 | 5 | 10 MiB | JPEG、PNG、WebP |
wan-3-0-video | 参考场景最多 10 张;首尾帧场景 1–2 张 | 20 MiB | JPEG、无透明通道的 PNG、WebP、BMP |
每一张 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 之间。
视频参考模型的专项上传限制如下:
| 模型 | 图片输入 | 视频输入 | 音频输入 |
|---|---|---|---|
kling-3-turbo | 1 张,每张 10 MiB;JPEG 或 PNG | 不接受 | 不接受 |
seedance-2-mini | 最多 9 张,每张 30 MiB;JPEG / PNG / WebP / GIF | 最多 3 个,每个 50 MiB;MP4 或 MOV | 最多 3 个,每个 15 MiB;MP3 或 WAV |
seedance-2-5 | 最多 30 张,每张 30 MiB;JPEG / PNG / WebP | 最多 10 个,每个 95 MiB;MP4 或 MOV | 最多 10 个,每个 15 MiB;MP3 或 WAV |
minimax-h3 | 最多 9 张,每张 30 MiB;JPEG、PNG 或 WebP | 最多 3 个,每个 50 MiB;MP4 或 MOV | 最多 3 个,每个 15 MiB;MP3 或 WAV |
happyhorse-1-1 | 最多 9 张,每张 20 MiB;JPEG、PNG 或 WebP | 不接受 | 不接受 |
omnihuman-1-5 | 1 张,10 MiB;JPEG、PNG 或 WebP | 不接受 | 1 个,10 MiB;MP3、M4A、WAV、AAC 或 OGG |
volcengine-video-lip-sync | 不接受 | 1 个,95 MiB;MP4 或 MOV | 1 个,10 MiB;MP3、M4A、WAV、AAC 或 OGG |
wan-3-0-video | 首尾帧场景:必需 1 张首帧,可选 1 张尾帧;参考场景:最多 10 张,每张 20 MiB;JPEG、无透明通道的 PNG、WebP 或 BMP | 参考场景:最多 5 个,每个 95 MiB;MP4 或 MOV;每个 1–15 秒,合计不超过 15 秒 | 参考场景:最多 5 个,每个 15 MiB;MP3 或 WAV;每个 1–15 秒,合计不超过 15 秒;不能单独作为输入 |
以上是 Rivya 接受的上传上限,可能低于上游服务的理论上限。每个 Video8 或 Wan 3.0 参考素材都必须带目标 model 上传。参考视频必须同时携带原始模型绑定上传响应返回的时长签名和视频元数据签名。Wan 3.0 音频的时长 token 还会绑定识别出的 MIME 和上传字节数。
Wan 3.0 图片的宽高均须为 240–8,000 像素,视频宽高均须为 240–4,096 像素;两者都必须保持在 1:8–8:1 的宽高比边界内。参考场景中的视频和音频各自有 15 秒合计时长上限,且音频不能成为唯一的参考类型。
Rivya 会校验文件签名识别出的 MIME,不只依赖文件扩展名。
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 示例
以下 JavaScript 示例在服务端运行,需设置 RIVYA_API_KEY。检查 HTTP 成功后才把响应当作上传结果;不要把密钥交给浏览器。
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();
if (!response.ok) {
throw new Error(JSON.stringify(uploadedFile.error));
}
console.log(uploadedFile.id, uploadedFile.url);Python 示例
Python 示例需要 requests 及服务端 RIVYA_API_KEY。超时限制的是 HTTP 等待,不证明上传失败或未存储文件。
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()
if not response.ok:
raise RuntimeError(uploaded_file.get("error"))
print(uploaded_file["id"], uploaded_file["url"])响应
已签名图片须将原始上传响应映射到生成参考项:mime_type → mimeType, width → width, height → height, size_bytes → sizeBytes, image_dimensions_token → imageDimensionsToken,与原 URL 和目标模型一起保留。视频的 sizeBytes 应直接使用 video_file_size_bytes;不要用码率乘时长估算,视频采样码率不等于整个容器大小。示例中的时间、大小与 token 只是示例,不是真实签名。
{
"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 由文件内容识别。保留原 URL、目标模型和完整上传响应;后续 GET 不会重建 image_dimensions_token,该字段一律为 null。原 token 缺失或过期时重新上传。
需要签名视频元数据时,Rivya 检查 MP4 或 MOV 的文件内容,并映射:video_width → width, video_height → height, frames_per_second → framesPerSecond, video_bitrate_mbps → videoBitrateMbps, video_file_size_bytes → sizeBytes, video_metadata_token → videoMetadataToken。签名绑定账户、目标模型、URL、MIME、尺寸、帧率、码率和文件大小;durationToken 单独验证时长。后续 GET 的 video_metadata_token 一律为 null,不能自行构造元数据来替代原上传响应。
签名元数据与文件有效期
时长、图片尺寸和视频元数据 token 从签发起一小时过期。必需 token 缺失或过期时,为目标模型重新上传原文件,并原样复制上传元数据。
上传 URL 只是临时生成输入;保留自己的原文件,必要时重新上传。文件记录的 expires_at 为 null 也不保证远端 URL 始终可用。
查询文件元数据
此端点读取所属账户的文件记录;同账户另一把有效 Key 具有 files:read 也可读取。响应仍是 PublicApiFile;记录不存在、不属该账户或状态不再为 available 时返回 not_found。读取记录不检查远端 URL 是否能下载。
GET 不恢复图片或视频签名元数据,以下字段始终为 null:width, height, image_dimensions_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, video_metadata_token。重新签发的音频时长 token 不含 MIME 与文件大小,不能替代某些模型所需绑定信息。生成时保留完整原始上传响应;必要签名信息缺失或过期须重新上传原文件。
curl https://rivya.ai/api/v1/files/file_... \
-H "Authorization: Bearer rvya_sk_..."在生成参数中使用上传结果
不要给 POST /api/v1/generations 发送顶层 files 字段。
新集成优先把上传结果放入 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 图层拆分必须传入恰好一张图片,并携带绑定模型上传后返回的签名元数据:
{
"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.png",
"mimeType": "image/png",
"width": 2048,
"height": 2048,
"sizeBytes": 6291456,
"imageDimensionsToken": "image_dimensions_token_from_files_api"
}
]
}
}部分旧参数仍使用模型专属 URL 字段。如果 模型 API Reference 写明了具体参数,请按该模型页面说明使用,不要自行发明新字段。
错误
读取 code 并保留返回的 requestId。上传超时或响应无法读取时,不能确认文件是否已存储;重试可能新建记录,不证明此前失败。
Files API 使用和其他 Rivya API 一致的公共错误结构:
{
"error": {
"code": "validation_failed",
"message": "The request is invalid. Check the endpoint's required fields and parameters.",
"requestId": "req_..."
}
}常见情况:
| HTTP | Code | 原因 |
|---|---|---|
| 400 | validation_failed | 缺文件、错误 multipart 头或长度、不支持的种类或格式、过大文件、无效必需元数据,或模型不接受该上传。 |
| 401 | api_key_missing / api_key_invalid / api_key_revoked / api_key_expired | 缺失、无效、已撤销或过期的 Key,或账户不允许使用公开 API。 |
| 403 | api_scope_denied | 缺少上传所需 files:create 或读取所需 files:read。 |
| 404 | not_found | 没有所属账户可用文件记录,或模型未知/不是异步生成模型。 |
| 429 | rate_limited | 达到 Key 上传频率限制,或上传并发槽已满。 |
| 500 | internal_error | 无法确认请求结果,或所需元数据签名不可用。 |
| 503 | public_api_disabled | 当前部署关闭公开 API。 |
安全说明
保留自己的原始媒体。元数据端点检查账户归属,但不能依赖该检查限制返回 URL 的下载;不要把上传 URL 或签名 token 放到公开页面。
不要把完整 API Key 存在浏览器、移动客户端、日志、分析事件或截图中。
上传后的文件 URL、duration_token、image_dimensions_token 和 video_metadata_token 应按临时接入材料处理。只在构造后续生成请求时使用,不要暴露到公开页面。
