Files API

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

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:

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 limite seguro de upload 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.

Os limites para referências de imagem assinadas são:

Toda imagem de referência do Image5, do Grok Imagine Image 2.0 ou do Wan 3.0 deve ser enviada com o model de destino. Guarde os valores width, height, size_bytes e image_dimensions_token da resposta original; a solicitação de geração deve enviá-los como width, height, sizeBytes e imageDimensionsToken. URLs arbitrárias de imagens externas não atendem a essa validação vinculada ao modelo.

A decomposição em camadas também valida as dimensões detectadas da imagem antes do upload: de 262.144 a 36.000.000 de pixels no total e proporção entre 1:16 e 16:1.

Os limites de upload específicos dos modelos com referência de vídeo incluem:

Esses são os limites de upload aceitos pela Rivya, que podem ser menores que o limite do provedor de origem. Envie cada referência do Video8 ou do Wan 3.0 com o model de destino. Vídeos de referência exigem tanto a comprovação de duração assinada quanto os metadados de vídeo assinados da resposta original do upload vinculado ao modelo. Os tokens de duração de áudio do Wan 3.0 também vinculam o tipo MIME detectado e o tamanho do upload em bytes.

As imagens do Wan 3.0 devem ter de 240 a 8.000 pixels por lado, e os vídeos, de 240 a 4.096 pixels por lado; ambos devem permanecer dentro da faixa de proporção de 1:8–8:1. No modo de referência, vídeo e áudio têm limites totais separados de 15 segundos, e o áudio não pode ser o único tipo de referência.

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-lite" \
  -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-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);

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

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.

Para uploads de imagem compatíveis, width e height são detectados a partir dos bytes do arquivo. O image_dimensions_token assinado da resposta original do upload vinculado ao modelo é obrigatório para todos os cinco modelos Image5, para o Grok Imagine Image 2.0 e para o Wan 3.0; copie-o para o item de referência como imageDimensionsToken e copie size_bytes como sizeBytes. Uma consulta posterior aos metadados do arquivo pode retornar esse token como null; portanto, faça novo upload da imagem de origem se o token original não estiver disponível ou tiver expirado.

Para uploads de vídeo compatíveis com Video8 e Wan 3.0, a Rivya inspeciona os bytes MP4 ou MOV e retorna video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes e video_metadata_token. Copie-os para o item de referência como width, height, framesPerSecond, videoBitrateMbps, sizeBytes e videoMetadataToken. O token fica vinculado à conta, ao modelo de destino, à URL, ao tipo MIME, às dimensões, à taxa de quadros, à taxa de bits e ao tamanho do upload. A duração é verificada separadamente com durationToken. Uma consulta posterior aos metadados do arquivo pode retornar video_metadata_token como null; faça novo upload do vídeo de origem em vez de inventar metadados.

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-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 vídeo ou áudio:

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

Os campos de vídeo assinados completos acima são obrigatórios para referências de vídeo do Video8 e do Wan 3.0. Referências de áudio do Wan 3.0 usam mimeType, sizeBytes, durationSeconds e durationToken; referências de imagem usam o contrato de metadados específico do modelo descrito acima.

Para o Seedream 5.0 Pro Layer Decomposition, envie exatamente uma imagem e os metadados assinados retornados pelo upload vinculado ao modelo:

{
  "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.tiff",
        "mimeType": "image/tiff",
        "width": 2048,
        "height": 2048,
        "sizeBytes": 6291456,
        "imageDimensionsToken": "image_dimensions_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:

Notas de Segurança

Não armazene chaves completas de API em navegadores, clientes móveis, registros, eventos de análise ou capturas de tela.

Trate as URLs dos arquivos enviados e os valores de duration_token, image_dimensions_token e video_metadata_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.

Páginas Relacionadas

• Criar Geração

• Rivya TypeScript SDK

• Referência da API de Modelos

• Erros e Limites da API

• Contrato de OpenAPI e Schema