Files API

Usa POST /api/v1/files para subir medios de referencia para modelos que necesitan entradas de imagen, video o audio.

Files API es solo para entradas de referencia. No crea tareas de generación por sí misma. Después de subir el archivo, pasa la url devuelta y los metadatos a los params del modelo, normalmente mediante params.referenceMediaItems.

Endpoint

POST https://rivya.ai/api/v1/files
GET https://rivya.ai/api/v1/files/{fileId}

Headers requeridos:

Authorization: Bearer rvya_sk_...
Content-Type: multipart/form-data

La clave API debe incluir el scope files:create para subir archivos y files:read para recuperar metadatos. Las claves nuevas de Rivya API incluyen ambos scopes por defecto.

Campos multipart

Usa model cuando el archivo esté destinado a un modelo específico. Esto te da validación MIME y de tamaño específica del modelo antes de que se acepte el archivo.

Límites de subida

Files API usa la misma política de subida que las referencias de Rivya.

Límites por defecto:

Algunos modelos tienen límites diferentes. Por ejemplo, ciertos modelos con imagen de referencia admiten imágenes más grandes, y ciertos modelos con video de referencia admiten archivos hasta el techo de subida seguro del producto. Pasa siempre model cuando conozcas el modelo objetivo y lee la referencia de modelos de la API antes de aceptar subidas de usuarios.

Los límites de las referencias de imagen firmadas incluyen:

Cada imagen de referencia de Image5, Grok Imagine Image 2.0 o Wan 3.0 debe subirse indicando su model objetivo. Conserva width, height, size_bytes e image_dimensions_token de la respuesta original; en la solicitud de generación debes enviarlos como width, height, sizeBytes e imageDimensionsToken. Una URL externa arbitraria no satisface esta validación vinculada al modelo.

La descomposición en capas también valida las dimensiones detectadas antes de subir la imagen: entre 262.144 y 36.000.000 píxeles en total y una relación de aspecto de 1:16 a 16:1.

Los límites de subida específicos de los modelos con referencia de video son:

Estos son los límites de subida admitidos por Rivya, que pueden ser inferiores a los del servicio proveedor. Sube cada referencia de Video8 o Wan 3.0 indicando su model objetivo. Los videos de referencia requieren tanto la prueba de duración firmada como los metadatos de video firmados de la respuesta original de subida vinculada al modelo. Los tokens de duración de audio de Wan 3.0 también vinculan el tipo MIME detectado y el tamaño de la subida en bytes.

Las imágenes de Wan 3.0 deben medir entre 240 y 8.000 píxeles por lado, y los videos entre 240 y 4.096 píxeles por lado; ambos deben respetar una relación de aspecto de 1:8–8:1. En el modo de referencia, el video y el audio tienen límites totales independientes de 15 segundos, y el audio no puede ser el único tipo de referencia.

Rivya valida la firma detectada del archivo, no solo la extensión del nombre de archivo.

Ejemplo 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"

Ejemplo 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);

Ejemplo 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"])

Respuesta

{
  "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
}

En subidas de video y audio, duration_seconds puede venir poblado. Cuando un modelo requiere verificación de duración, copia duration_token al parámetro de generación relacionado como durationToken.

En las subidas de imagen compatibles, width y height se detectan a partir de los bytes reales del archivo. Los cinco modelos Image5, Grok Imagine Image 2.0 y Wan 3.0 exigen el image_dimensions_token firmado de la respuesta original vinculada al modelo; cópialo al elemento de referencia como imageDimensionsToken y copia size_bytes como sizeBytes. Una consulta posterior de metadatos puede devolver el token como null; si el token original falta o ha caducado, vuelve a subir la imagen.

En las subidas de video compatibles con Video8 y Wan 3.0, Rivya inspecciona los bytes MP4 o MOV y devuelve video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes y video_metadata_token. Cópialos al elemento de referencia como width, height, framesPerSecond, videoBitrateMbps, sizeBytes y videoMetadataToken. El token queda vinculado a la cuenta, el modelo objetivo, la URL, el tipo MIME, las dimensiones, la frecuencia de fotogramas, el bitrate y el tamaño de la subida. La duración se verifica por separado mediante durationToken. Una consulta posterior de metadatos puede devolver video_metadata_token como null; vuelve a subir el video fuente en lugar de inventar metadatos.

Recuperar metadatos de archivo

Usa GET /api/v1/files/{fileId} para leer metadatos de un archivo que pertenece a la misma cuenta de Rivya:

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

La respuesta usa la misma forma PublicApiFile que la subida. Si el archivo pertenece a otra cuenta o ya no está disponible, la API devuelve not_found.

Usar la subida en params de generación

No envíes un campo files de nivel superior a POST /api/v1/generations.

Para integraciones nuevas, pasa el resultado de la subida mediante 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"
}

Para video o 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"
}

Los campos de video firmados completos del ejemplo anterior son obligatorios para las referencias de video de Video8 y Wan 3.0. Las referencias de audio de Wan 3.0 usan mimeType, sizeBytes, durationSeconds y durationToken; las referencias de imagen usan el contrato de metadatos específico del modelo descrito anteriormente.

Para Seedream 5.0 Pro Layer Decomposition, envía exactamente una imagen y los metadatos firmados devueltos por la subida vinculada al modelo:

{
  "model": "seedream-5-pro-layer-decomposition",
  "prompt": "Separa el producto, la sombra, la tipografía y el fondo en capas limpias",
  "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"
      }
    ]
  }
}

Algunos parámetros de modelos más antiguos todavía usan campos URL específicos del modelo. Si la referencia de modelos de la API documenta un parámetro específico, sigue esa página del modelo en lugar de inventar un campo nuevo.

Errores

Files API usa el mismo envoltorio público de error que el resto de Rivya API:

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

Casos comunes:

Notas de seguridad

No guardes claves API completas en navegadores, clientes móviles, logs, eventos de analytics ni capturas de pantalla.

Trata las URL de archivos subidos y los valores duration_token, image_dimensions_token y video_metadata_token como material temporal de integración. Úsalos solo para construir la solicitud de generación siguiente y no los expongas en páginas públicas.

Páginas relacionadas

• Crear generación

• Rivya TypeScript SDK

• Referencia de modelos de la API

• Errores y límites de la API

• Contrato de OpenAPI y schema