Faça upload de arquivos de referência de imagem, vídeo ou áudio para solicitações de geração da Rivya API, com checagens MIME, limites de tamanho e tokens de duração.

Use POST /api/v1/files para enviar mídia de referência para modelos que precisam de entradas de imagem, vídeo ou áudio.

A Files API é apenas para entradas de referência. Ela não cria tarefas de geração por si só. Depois do upload, envie a url retornada e os metadados nos params do modelo, normalmente por params.referenceMediaItems.

Endpoint

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

Headers obrigatórios:

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

A chave de API deve incluir o escopo files:create para upload e files:read para recuperar metadados. Chaves da Rivya API recém-criadas incluem os dois escopos por padrão.

Campos Multipart

Field	Type	Required	Notes
`file`	binary	yes	O arquivo de imagem, vídeo ou áudio a enviar.
`kind`	string	yes	Um de `image`, `video` ou `audio`.
`model`	string	no	ID público do modelo. Quando presente, a Rivya valida se o modelo aceita esse tipo de arquivo.
`client_request_id`	string	no	Seu ID de rastreamento, com até 128 caracteres.

Use model quando o arquivo for destinado a um modelo específico. Isso fornece validação MIME e de tamanho específica do modelo antes que o arquivo seja aceito.

Limites de Upload

A Files API usa a mesma política de upload das referências da Rivya.

Limites padrão:

Kind	Default max size	Common MIME types
`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`

Alguns modelos têm limites diferentes. Por exemplo, certos modelos com imagem de referência permitem imagens maiores, e certos modelos com referência de vídeo permitem arquivos até o teto de upload edge-safe do produto. Sempre envie model quando souber o modelo de destino, e leia a Referência da API de Modelos antes de aceitar uploads de usuários.

A Rivya valida a assinatura detectada do arquivo, não apenas a extensão do nome.

Exemplo com 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"

Exemplo em 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);

Exemplo em 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"])

Resposta

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

Para uploads de vídeo e áudio, duration_seconds pode ser preenchido. Quando um modelo exige verificação de duração, copie duration_token para o parâmetro de geração relacionado como durationToken.

Recuperar Metadados do Arquivo

Use GET /api/v1/files/{fileId} para ler metadados de um arquivo pertencente à mesma conta Rivya:

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

A resposta usa o mesmo formato PublicApiFile do upload. Se o arquivo pertencer a outra conta ou não estiver mais disponível, a API retornará not_found.

Usar o Upload nos Params de Geração

Não envie um campo files de nível superior para POST /api/v1/generations.

Para novas integrações, envie o resultado do upload por 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 vídeo ou áudio:

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

Alguns parâmetros de modelos mais antigos ainda usam campos de URL específicos do modelo. Se a Referência da API de Modelos documentar um parâmetro específico, siga a página desse modelo em vez de inventar um novo campo.

Erros

A Files API usa o mesmo envelope público de erro que o restante da Rivya API:

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

Casos comuns:

HTTP	Code	Cause
400	`validation_failed`	`file` ausente, `kind` sem suporte, tipo MIME sem suporte, arquivo grande demais ou modelo não aceita o tipo selecionado.
401	`api_key_missing` / `api_key_invalid`	Chave de API Bearer ausente ou inválida.
403	`api_scope_denied`	A chave não inclui `files:create` ou `files:read` para a ação solicitada.
429	`rate_limited`	Uploads de arquivo demais no minuto atual.
503	`public_api_disabled`	A Public API está desativada no ambiente atual.

Notas de Segurança

Não armazene chaves completas de API em navegadores, clientes mobile, logs, eventos de analytics ou capturas de tela.

Trate URLs de arquivos enviados e valores de duration_token como material temporário de integração. Use-os apenas para montar a solicitação de geração seguinte e não os exponha em páginas públicas.

Files API