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 Key 必须包含 files:create scope；重新读取元数据时必须包含 files:read scope。新创建的 Rivya API Key 默认包含这两个 scope。

Multipart 字段

如果这个文件会用于某个确定模型，建议传入 model。这样可以在文件被接受前执行模型专属的 MIME 和大小校验。

上传限制

Files API 复用 Rivya 参考素材上传 policy。

默认限制：

部分模型有不同限制。例如，部分参考图片模型允许更大的图片，部分视频参考模型允许使用产品边界内更高的上传上限。只要你知道目标模型，就应该传入 model，并在接收用户上传前阅读 模型 API Reference。

已签名图片参考素材的限制如下：

每一张 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 之间。

视频参考模型的专项上传限制如下：

以上是 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 示例

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。后续查询文件元数据时，该 token 可能返回 null；如果原 token 不可用或已过期，请重新上传源图片。

对于支持的 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。该 token 会绑定账户、目标模型、URL、MIME、宽高、帧率、码率和上传字节数；时长由独立的 durationToken 验证。后续查询可能返回 null 的 video_metadata_token；此时应重新上传源视频，不能自行构造元数据。

查询文件元数据

使用 GET /api/v1/files/{fileId} 可以读取同一 Rivya 账户名下文件的元数据：

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

响应使用和上传接口相同的 PublicApiFile 结构。如果文件属于其他账户或已不可用，API 会返回 not_found。

在生成参数中使用上传结果

不要给 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": "将产品、阴影、文字与背景拆分成清晰图层",
  "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 Reference 写明了具体参数，请按该模型页面说明使用，不要自行发明新字段。

错误

Files API 使用和其他 Rivya API 一致的公共错误结构：

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

常见情况：

安全说明

不要把完整 API Key 存在浏览器、移动客户端、日志、分析事件或截图中。

上传后的文件 URL、duration_token、image_dimensions_token 和 video_metadata_token 应按临时接入材料处理。只在构造后续生成请求时使用，不要暴露到公开页面。

相关页面

• 创建生成任务

• Rivya TypeScript SDK

• 模型 API Reference

• API 错误码与限制

• OpenAPI 与 Schema 合同