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 que le produit peut accepter en toute sécurité. 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.

Les limites applicables aux références d'image signées sont les suivantes :

Chaque image de référence Image5, Grok Imagine Image 2.0 ou Wan 3.0 doit être importée avec son model cible. Conservez les valeurs width, height, size_bytes et image_dimensions_token de la réponse d'origine ; la requête de génération doit les transmettre sous les noms width, height, sizeBytes et imageDimensionsToken. Une URL d'image externe arbitraire ne satisfait pas cette validation liée au modèle.

La décomposition en calques valide en plus les dimensions détectées avant l'import : 262 144–36 000 000 pixels au total et un rapport d'aspect de 1:16 à 16:1.

Les limites d'import propres aux modèles utilisant des références vidéo sont les suivantes :

Il s'agit des plafonds d'import acceptés par Rivya ; ils peuvent être inférieurs à la limite d'un service en amont. Importez chaque référence Video8 ou Wan 3.0 avec son model cible. Les vidéos de référence exigent à la fois la preuve de durée signée et les métadonnées vidéo signées de la réponse d'import d'origine liée au modèle. Les tokens de durée audio de Wan 3.0 lient aussi le type MIME détecté et la taille importée en octets.

Les images Wan 3.0 doivent mesurer 240–8 000 pixels par côté, et les vidéos 240–4 096 pixels par côté ; les deux doivent respecter un rapport d'aspect compris entre 1:8 et 8:1. En mode référence, la vidéo et l'audio ont chacun une limite cumulée distincte de 15 secondes, et l'audio ne peut pas être le seul type de référence.

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

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

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.

Pour les imports d'image pris en charge, width et height sont détectés à partir des octets du fichier. Les cinq modèles Image5, Grok Imagine Image 2.0 et Wan 3.0 exigent le token image_dimensions_token signé de la réponse d'import d'origine liée au modèle ; copiez-le dans l'élément de référence sous le nom imageDimensionsToken, et copiez size_bytes sous le nom sizeBytes. Une récupération ultérieure des métadonnées du fichier peut renvoyer null pour ce token : réimportez alors l'image source si le token d'origine n'est plus disponible ou a expiré.

Pour les imports vidéo Video8 et Wan 3.0 pris en charge, Rivya analyse les octets MP4 ou MOV et renvoie video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes et video_metadata_token. Copiez-les dans l'élément de référence sous les noms width, height, framesPerSecond, videoBitrateMbps, sizeBytes et videoMetadataToken. Le token est lié au compte, au modèle cible, à l'URL, au type MIME, aux dimensions, à la fréquence d'images, au débit et à la taille importée. La durée est vérifiée séparément avec durationToken. Une récupération ultérieure des métadonnées du fichier peut renvoyer null pour video_metadata_token ; réimportez la vidéo source au lieu d'inventer des métadonnées.

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-lite",
  "prompt": "Recompose cette photo produit pour une page catalogue éditoriale nette",
  "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"
}

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",
  "width": 1920,
  "height": 1080,
  "framesPerSecond": 30,
  "videoBitrateMbps": 8.5,
  "sizeBytes": 26214400,
  "videoMetadataToken": "video_metadata_token_from_files_api"
}

Tous les champs vidéo signés ci-dessus sont requis pour les références vidéo Video8 et Wan 3.0. Les références audio Wan 3.0 utilisent mimeType, sizeBytes, durationSeconds et durationToken ; les références image utilisent le contrat de métadonnées propre au modèle décrit plus haut.

Pour Seedream 5.0 Pro Layer Decomposition, transmettez exactement une image avec les métadonnées signées renvoyées par son import lié au modèle :

{
  "model": "seedream-5-pro-layer-decomposition",
  "prompt": "Séparer le produit, l'ombre, la typographie et l'arrière-plan en calques distincts et propres",
  "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"
      }
    ]
  }
}

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 ainsi que les valeurs duration_token, image_dimensions_token et video_metadata_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