API Files

Utilisez POST /api/v1/files pour importer des médias de référence destinés aux modèles qui ont besoin d'entrées image, vidéo ou audio.

L'API Files sert uniquement aux entrées de référence. Elle ne crée pas de tâches de génération à elle seule. Après l'import, transmettez l'url renvoyée et les métadonnées dans les params du modèle, généralement via params.referenceMediaItems.

Endpoint

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

En-têtes requis :

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

La clé API doit inclure le scope files:create pour importer et files:read pour récupérer les métadonnées. Les clés API Rivya nouvellement créées incluent les deux scopes par défaut.

Champs multipart

Utilisez model quand le fichier est destiné à un modèle précis. Cela vous donne une validation MIME et de taille propre au modèle avant l'acceptation du fichier.

Limites d'import

L'API Files utilise la même politique d'import que les imports de référence Rivya.

Limites par défaut :

Certains modèles ont des limites différentes. Par exemple, certains modèles avec image de référence acceptent des images plus grandes, et certains modèles avec référence vidéo acceptent des fichiers jusqu'au plafond d'import sûr côté edge du produit. Transmettez toujours model lorsque vous connaissez le modèle cible, et lisez la référence API des modèles avant d'accepter les imports utilisateur.

Rivya valide la signature détectée du fichier, pas seulement l'extension du nom de fichier.

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

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

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

Réponse

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

Pour les imports vidéo et audio, duration_seconds peut être renseigné. Quand un modèle exige une vérification de durée, copiez duration_token dans le paramètre de génération associé sous la forme durationToken.

Récupérer les métadonnées d'un fichier

Utilisez GET /api/v1/files/{fileId} pour lire les métadonnées d'un fichier appartenant au même compte Rivya :

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

La réponse utilise la même forme PublicApiFile que l'import. Si le fichier appartient à un autre compte ou n'est plus disponible, l'API renvoie not_found.

Utiliser l'import dans les params de génération

N'envoyez pas de champ files au niveau racine vers POST /api/v1/generations.

Pour les nouvelles intégrations, transmettez le résultat de l'import via params.referenceMediaItems :

{
  "model": "nano-banana-2",
  "prompt": "Recompose cette photo produit pour une page catalogue éditoriale nette",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  },
  "client_request_id": "order-123-preview"
}

Pour une vidéo ou un audio :

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

Certains anciens paramètres de modèles utilisent encore des champs d'URL propres au modèle. Si la référence API des modèles documente un paramètre spécifique, suivez cette page de modèle au lieu d'inventer un nouveau champ.

Erreurs

L'API Files utilise la même enveloppe d'erreur publique que le reste de l'API Rivya :

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

Cas courants :

Notes de sécurité

Ne stockez pas de clés API complètes dans les navigateurs, clients mobiles, logs, événements analytics ou captures d'écran.

Traitez les URL de fichiers importés et les valeurs duration_token comme du matériel temporaire d'intégration. Utilisez-les seulement pour construire la requête de génération suivante, et ne les exposez pas dans des pages publiques.

Pages associées

• Créer une génération
• SDK TypeScript Rivya
• Référence API des modèles
• Erreurs et limites API
• Contrat OpenAPI et schéma