Envía trabajos asíncronos de generación de Rivya API con model, prompt, params, Idempotency-Key y campos de respuesta públicos.

Usa POST /api/v1/generations para enviar un trabajo asíncrono de generación de imagen, video o audio.

Para modelos de chat, usa Chat API. POST /api/v1/generations no crea sesiones de chat ni mensajes del assistant.

Endpoint

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

Headers requeridos:

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

Header recomendado:

Idempotency-Key: your-unique-request-key

Body de solicitud

{
  "model": "z-image",
  "prompt": "A clean editorial product image on a soft studio background",
  "params": {
    "aspect_ratio": "1:1"
  },
  "client_request_id": "order-123-preview"
}

Campos:

model: ID público del modelo, requerido
prompt: texto del prompt, requerido por muchos modelos
params: objeto de parámetros específico del modelo
client_request_id: ID de trazabilidad opcional de tu sistema

Lee la referencia de modelos de la API para ver params específicos de cada modelo.

Archivos de referencia en params

Para modelos que aceptan medios de referencia subidos, llama primero a Files API. Luego pasa el resultado de subida mediante params del modelo; no añadas un campo files de nivel superior a la solicitud de generación.

Usa params.referenceMediaItems para integraciones nuevas:

{
  "model": "nano-banana-2",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  }
}

Para entradas de audio o video que requieran verificación de duración, incluye el duration_token devuelto por /api/v1/files como durationToken en la entrada relacionada de referenceMediaItems.

Ejemplo 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": "A clean editorial product image on a soft studio background",
    "params": {
      "aspect_ratio": "1:1"
    }
  }'

Ejemplo 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: "A clean editorial product image on a soft studio background",
    params: { aspect_ratio: "1:1" }
  })
});

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

Ejemplo 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": "A clean editorial product image on a soft studio background",
        "params": {"aspect_ratio": "1:1"},
    },
    timeout=30,
)

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

Respuesta

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

Guarda el id y consulta estado de generación. Si configuras API Webhooks, Rivya también puede enviar un evento firmado generation.succeeded o generation.failed cuando la tarea alcance un estado terminal.

Idempotencia

Usa Idempotency-Key para reintentos. Si se repiten la misma clave y el mismo cuerpo de solicitud, Rivya puede devolver la respuesta pública guardada en lugar de crear una tarea duplicada.

Si la misma clave se reutiliza con una entrada diferente, la API devuelve idempotency_conflict.

Crear generación