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",
  "prompt": "Recompose cette photo produit pour une page catalogue éditoriale nette",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  }
}

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.

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