↓
Documentación de Rivya AI

Crear generación

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

Última revisión el 2026/08/25

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-lite",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "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"
      }
    ]
  }
}

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.

Cada imagen de referencia para Image5 necesita width, height, size_bytes e image_dimensions_token de la respuesta original de Files API vinculada al modelo, enviados como width, height, sizeBytes e imageDimensionsToken. Un token ausente, caducado, vinculado a otros datos o inventado por el cliente falla antes de crear la tarea y reservar créditos. Layer Decomposition también exige exactamente una imagen dentro de sus límites geométricos documentados.

Grok Imagine Image 2.0 está sujeto al mismo contrato de metadatos de imagen firmados. Para texto a imagen, no envíes ningún elemento de referencia; para la edición estándar de imágenes, envía de uno a cinco elementos JPEG, PNG o WebP únicos y firmados. El modo de texto a imagen acepta 1:1, 2:3, 3:2, 16:9 o 9:16; la edición de imágenes también admite auto. Segment Map y Segment Edit no son modos invocables mediante Public API.

Cada video de referencia para Video8 necesita duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes y video_metadata_token de la respuesta original vinculada al modelo. Envíalos como durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes y videoMetadataToken. Ambos tokens firmados se verifican antes de crear la tarea y reservar créditos.

Wan 3.0 usa tres valores de seedance_scene mutuamente excluyentes. text no acepta medios subidos; frames requiere una primera imagen y permite una última imagen opcional; reference acepta un conjunto firmado de imágenes, videos y audio, pero el audio no puede ser el único medio. Todas las URL de referencia deben proceder de subidas originales de Files API vinculadas al modelo. Los accesos directos de archivo a video y de enlace a video siguen sin estar disponibles.

Define variant como standard o prime, resolution como 480P, 720P o 1080P, y aspect_ratio como adaptive, 16:9, 4:3, 1:1, 3:4 o 9:16. duration acepta números enteros de 2 a 30, o -1 para duración inteligente; audio controla el audio creado por el modelo y seed acepta de 0 a 2147483647. El prompt, después de recortar los espacios, debe contener entre 1 y 20.000 caracteres.

Wan 3.0 Standard reserva 8, 16 o 32 créditos por segundo de salida solicitado a 480P, 720P o 1080P. Prime reserva 12,2, 25,2 o 50,4 créditos por segundo. Rivya redondea una sola vez al alza la reserva combinada; la duración inteligente reserva 30 segundos. Un uso real válido que no supere la reserva se liquida y devuelve la diferencia. Si el uso real falta, no es válido o supera la reserva, se conserva la reserva y el caso entra en conciliación, sin un cargo adicional oculto.

En el modo de referencia de Wan 3.0, envía como máximo 10 imágenes, 5 videos y 5 clips de audio. Cada video o audio debe durar entre 1 y 15 segundos, y cada tipo tiene su propio límite total de 15 segundos. duration=-1 no se puede usar con video de referencia; cuando hay video de entrada, los segundos verificados del video de entrada más los segundos de salida solicitados no deben superar 30.

Ejemplo de solicitud Video8 para una tarea de sincronización labial con video y 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"
      }
    ]
  }
}

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.

Páginas relacionadas

Referencia de modelos de la API

Consulta IDs de modelos de Rivya API, disponibilidad, modos admitidos, tablas de parámetros, límites de prompt, reglas de medios de referencia y enlaces de detalle de modelo.

Chat API

Usa Rivya Chat API para turnos sin streaming o con SSE, sesiones creadas por API, adjuntos de imagen file_id y liquidación de créditos basada en tokens.

Tabla de contenido

Endpoint
Body de solicitud
Archivos de referencia en params
Ejemplo curl
Ejemplo JavaScript
Ejemplo Python
Respuesta
Idempotencia
Páginas relacionadas