Soumettez des tâches de génération asynchrones à l'API Rivya avec model, prompt, params, Idempotency-Key et champs de réponse publics.

Utilisez POST /api/v1/generations pour soumettre une tâche de génération asynchrone d'image, de vidéo ou d'audio.

Pour les modèles de chat, utilisez API Chat. POST /api/v1/generations ne crée pas de sessions de chat ni de messages assistant.

Endpoint

POST https://rivya.ai/api/v1/generations

En-têtes requis :

Authorization: Bearer rvya_sk_...
Content-Type: application/json

En-tête recommandé :

Idempotency-Key: your-unique-request-key

Corps de requête

{
  "model": "z-image",
  "prompt": "Image produit éditoriale nette sur fond studio doux",
  "params": {
    "aspect_ratio": "1:1"
  },
  "client_request_id": "order-123-preview"
}

Champs :

model : ID public du modèle requis
prompt : texte du prompt, requis par de nombreux modèles
params : objet de paramètres propre au modèle
client_request_id : ID de trace optionnel provenant de votre système

Lisez la référence API des modèles pour les params propres à chaque modèle.

Fichiers de référence dans params

Pour les modèles qui acceptent des médias de référence importés, appelez d'abord API Files. Transmettez ensuite le résultat de l'import via les params du modèle ; n'ajoutez pas de champ files au niveau racine de la requête de génération.

Utilisez params.referenceMediaItems pour les nouvelles intégrations :

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

Pour les entrées audio ou vidéo qui exigent une vérification de durée, incluez le duration_token renvoyé par /api/v1/files sous forme de durationToken dans l'entrée referenceMediaItems associée.

Chaque image de référence Image5 exige les valeurs width, height, size_bytes et image_dimensions_token de la réponse d'origine de l'API Files liée au modèle, transmises sous les noms width, height, sizeBytes et imageDimensionsToken. Un token manquant, expiré, associé à d'autres données ou inventé par le client entraîne un rejet avant la création de la tâche et la réservation des crédits. Layer Decomposition exige en plus exactement une image respectant les limites géométriques documentées.

Grok Imagine Image 2.0 utilise le même contrat de métadonnées d'image signées. N'envoyez aucun élément de référence pour la génération texte-vers-image ; pour l'édition d'image standard, envoyez 1 à 5 éléments JPEG, PNG ou WebP uniques et signés. La génération texte-vers-image accepte 1:1, 2:3, 3:2, 16:9 ou 9:16 ; l'édition d'image accepte aussi auto. Segment Map et Segment Edit ne sont pas des modes appelables via l'API publique.

Chaque vidéo de référence Video8 exige les valeurs duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes et video_metadata_token de la réponse d'origine liée au modèle. Transmettez-les sous les noms durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes et videoMetadataToken. Les deux tokens signés sont vérifiés avant la création de la tâche et la réservation des crédits.

Wan 3.0 utilise trois valeurs seedance_scene mutuellement exclusives. text n'accepte aucun média importé ; frames exige une première image et autorise une dernière image facultative ; reference accepte un ensemble signé d'images, de vidéos et d'audio, mais l'audio ne peut pas être le seul média. Toutes les URL de référence doivent provenir d'imports Files API d'origine liés au modèle. Les raccourcis fichier-vers-vidéo et lien-vers-vidéo restent indisponibles.

Définissez variant sur standard ou prime, resolution sur 480P, 720P ou 1080P, et aspect_ratio sur adaptive, 16:9, 4:3, 1:1, 3:4 ou 9:16. duration accepte les nombres entiers de 2 à 30, ou -1 pour la durée intelligente ; audio contrôle l'audio créé par le modèle et seed accepte les valeurs de 0 à 2147483647. Le prompt, une fois les espaces de début et de fin supprimés, doit contenir entre 1 et 20 000 caractères.

Wan 3.0 Standard réserve 8, 16 ou 32 crédits par seconde de sortie demandée en 480P, 720P ou 1080P. Prime réserve 12,2, 25,2 ou 50,4 crédits par seconde. Rivya arrondit une seule fois la réservation cumulée à l'entier supérieur ; la durée intelligente réserve 30 secondes. Une utilisation réelle valide qui ne dépasse pas la réservation est réglée et la différence est remboursée. Si l'utilisation réelle est absente, invalide ou supérieure, la réservation est conservée et passe en rapprochement, sans débit supplémentaire masqué.

En mode référence Wan 3.0, envoyez au maximum 10 images, 5 vidéos et 5 clips audio. Chaque vidéo ou clip audio doit durer de 1 à 15 secondes, et chaque type possède sa propre limite cumulée de 15 secondes. duration=-1 ne peut pas être utilisé avec une vidéo de référence ; avec une entrée vidéo, la durée vérifiée de la vidéo d'entrée plus la durée de sortie demandée ne doit pas dépasser 30 secondes.

Exemple de requête Video8 pour une tâche de synchronisation labiale avec vidéo et audio :

{
  "model": "volcengine-video-lip-sync",
  "prompt": "",
  "params": {
    "mode": "lite",
    "separate_vocal": "false",
    "open_scenedet": "false",
    "referenceMediaItems": [
      {
        "url": "https://.../source.mov",
        "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"
      },
      {
        "url": "https://.../dialogue.wav",
        "kind": "audio",
        "name": "dialogue.wav",
        "mimeType": "audio/wav",
        "durationSeconds": 12.4,
        "durationToken": "audio_duration_token_from_files_api"
      }
    ]
  }
}

Exemple curl

curl https://rivya.ai/api/v1/generations \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-preview-001" \
  -d '{
    "model": "z-image",
    "prompt": "Image produit éditoriale nette sur fond studio doux",
    "params": {
      "aspect_ratio": "1:1"
    }
  }'

Exemple JavaScript

const response = await fetch("https://rivya.ai/api/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RIVYA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "product-preview-001"
  },
  body: JSON.stringify({
    model: "z-image",
    prompt: "Image produit éditoriale nette sur fond studio doux",
    params: { aspect_ratio: "1:1" }
  })
});

const generation = await response.json();
console.log(generation.id, generation.status);

Exemple Python

import os
import requests

response = requests.post(
    "https://rivya.ai/api/v1/generations",
    headers={
        "Authorization": f"Bearer {os.environ['RIVYA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "product-preview-001",
    },
    json={
        "model": "z-image",
        "prompt": "Image produit éditoriale nette sur fond studio doux",
        "params": {"aspect_ratio": "1:1"},
    },
    timeout=30,
)

generation = response.json()
print(generation["id"], generation["status"])

Réponse

{
  "id": "task_public_id",
  "status": "queued",
  "model": "z-image",
  "reserved_credits": 1,
  "final_credits": 0,
  "created_at": "2026-05-10T00:00:00.000Z",
  "updated_at": "2026-05-10T00:00:00.000Z",
  "result": null,
  "error": null
}

Enregistrez l'id et interrogez le statut de génération. Si vous configurez les webhooks API, Rivya peut aussi envoyer un événement signé generation.succeeded ou generation.failed lorsque la tâche atteint un état terminal.

Idempotence

Utilisez Idempotency-Key pour les nouvelles tentatives. Si la même clé et le même corps de requête sont rejoués, Rivya peut renvoyer la réponse publique stockée au lieu de créer une tâche en double.

Si la même clé est réutilisée avec une entrée différente, l'API renvoie idempotency_conflict.

Créer une génération