Envie jobs assíncronos de geração da Rivya API com model, prompt, params, Idempotency-Key e campos de resposta pública.

Use POST /api/v1/generations para enviar um job assíncrono de geração de imagem, vídeo ou áudio.

Para modelos de chat, use Chat API. POST /api/v1/generations não cria sessões de chat nem mensagens de assistente.

Endpoint

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

Headers obrigatórios:

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

Header recomendado:

Idempotency-Key: your-unique-request-key

Corpo da Solicitação

{
  "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 obrigatório do modelo
prompt: texto do prompt, obrigatório em muitos modelos
params: objeto de parâmetros específico do modelo
client_request_id: ID de rastreamento opcional do seu sistema

Leia a Referência da API de Modelos para params específicos por modelo.

Arquivos de Referência em Params

Para modelos que aceitam mídia de referência enviada por upload, primeiro chame a Files API. Depois envie o resultado do upload por params do modelo; não adicione um campo files de nível superior à solicitação de geração.

Use params.referenceMediaItems para novas integrações:

{
  "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 áudio ou vídeo que exigem verificação de duração, inclua o duration_token retornado por /api/v1/files como durationToken na entrada relacionada de referenceMediaItems.

Exemplo com 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"
    }
  }'

Exemplo em 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);

Exemplo em 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"])

Resposta

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

Salve o id e consulte Status de Geração. Se você configurar Webhooks da API, a Rivya também poderá enviar um evento assinado generation.succeeded ou generation.failed quando a tarefa chegar a um estado terminal.

Idempotência

Use Idempotency-Key para novas tentativas. Se a mesma chave e o mesmo corpo da solicitação forem reproduzidos, a Rivya poderá retornar a resposta pública armazenada em vez de criar uma tarefa duplicada.

Se a mesma chave for reutilizada com entrada diferente, a API retornará idempotency_conflict.

Criar Geração