Envie tarefas assíncronas de geração da Rivya API com modelo, prompt, parâmetros, Idempotency-Key e campos de resposta pública.

Use POST /api/v1/generations para enviar uma tarefa assíncrona 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-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 á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.

Toda imagem de referência do Image5 exige os valores width, height, size_bytes e image_dimensions_token da resposta original da Files API vinculada ao modelo, enviados como width, height, sizeBytes e imageDimensionsToken. Um token ausente, expirado, incompatível ou inventado pelo cliente faz a solicitação falhar antes da criação da tarefa e da reserva de créditos. O Layer Decomposition também exige exatamente uma imagem dentro dos limites geométricos documentados.

O Grok Imagine Image 2.0 usa o mesmo contrato de metadados de imagem assinados. Não envie itens de referência para a geração de texto para imagem; na edição padrão de imagem, envie de 1 a 5 itens JPEG, PNG ou WebP únicos e assinados. A geração de texto para imagem aceita 1:1, 2:3, 3:2, 16:9 ou 9:16; a edição de imagem também aceita auto. Segment Map e Segment Edit não são modos disponíveis para chamada pela Public API.

Todo vídeo de referência do Video8 exige os valores duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes e video_metadata_token da resposta original vinculada ao modelo. Envie-os como durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes e videoMetadataToken. Os dois tokens assinados são verificados antes da criação da tarefa e da reserva de créditos.

O Wan 3.0 usa três valores de seedance_scene mutuamente exclusivos. text não aceita mídia enviada; frames exige uma primeira imagem e permite uma última imagem opcional; reference aceita um conjunto assinado de imagens, vídeos e áudio, mas o áudio não pode ser a única mídia. Todas as URLs de referência devem vir de uploads originais da Files API vinculados ao modelo. Os atalhos de arquivo para vídeo e de link para vídeo continuam indisponíveis.

Defina variant como standard ou prime, resolution como 480P, 720P ou 1080P, e aspect_ratio como adaptive, 16:9, 4:3, 1:1, 3:4 ou 9:16. duration aceita números inteiros de 2 a 30, ou -1 para duração inteligente; audio controla o áudio criado pelo modelo, e seed aceita de 0 a 2147483647. O prompt, após remover espaços no início e no fim, deve conter de 1 a 20.000 caracteres.

O Wan 3.0 Standard reserva 8, 16 ou 32 créditos por segundo de saída solicitado em 480P, 720P ou 1080P. O Prime reserva 12,2, 25,2 ou 50,4 créditos por segundo. A Rivya arredonda a reserva combinada para cima uma única vez; a duração inteligente reserva 30 segundos. Uma utilização real válida igual ou inferior à reserva conclui a liquidação e devolve a diferença. Uma utilização real ausente, inválida ou superior mantém a reserva e entra em reconciliação, sem cobrança adicional oculta.

No modo de referência do Wan 3.0, envie no máximo 10 imagens, 5 vídeos e 5 clipes de áudio. Cada vídeo ou áudio deve durar de 1 a 15 segundos, e cada tipo tem seu próprio limite total de 15 segundos. duration=-1 não pode ser usado com vídeo de referência; com entrada de vídeo, os segundos verificados do vídeo de entrada mais os segundos de saída solicitados não podem ultrapassar 30.

Exemplo de solicitação Video8 para uma tarefa de sincronização labial com vídeo e áudio:

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

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