Sube archivos de referencia de imagen, video o audio para solicitudes de generación de Rivya API, con comprobaciones MIME, límites de tamaño y tokens de duración.

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

Campo	Tipo	Requerido	Notas
`file`	binary	sí	El archivo de imagen, video o audio que se va a subir.
`kind`	string	sí	Uno de `image`, `video` o `audio`.
`model`	string	no	ID público del modelo. Cuando está presente, Rivya válida que el modelo acepte este tipo de archivo.
`client_request_id`	string	no	Tu ID de trazabilidad, de hasta 128 caracteres.

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:

Tipo	Tamaño máximo por defecto	Tipos MIME comunes
`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`

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.

Rivya válida 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" \
  -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");
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",
            "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,
  "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.

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

Para video o audio:

{
  "url": "https://...",
  "kind": "video",
  "name": "source.mov",
  "mimeType": "video/quicktime",
  "durationSeconds": 12.4,
  "durationToken": "duration_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:

HTTP	Código	Causa
400	`validation_failed`	Falta `file`, `kind` no es compatible, el tipo MIME no es compatible, el archivo es demasiado grande o el modelo no acepta el tipo seleccionado.
401	`api_key_missing` / `api_key_invalid`	Falta la clave API Bearer o no es válida.
403	`api_scope_denied`	La clave no incluye `files:create` o `files:read` para la acción solicitada.
429	`rate_limited`	Demasiadas subidas de archivos en el minuto actual.
503	`public_api_disabled`	Public API está desactivada en el entorno actual.

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 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.

Files API