Rivya TypeScript SDK
Use o beta do Rivya TypeScript SDK para chamar a Public API v1 em modelos, gerações, arquivos, créditos, webhooks e Chat, incluindo streaming SSE.
Última revisão em 5 de novembro de 2026
A Rivya fornece um beta do TypeScript SDK para integrações da Public API no lado do servidor.
O SDK é um cliente fino sobre a Rivya Public API v1. O contrato de nível mais baixo continua sendo Contrato de OpenAPI e Schema, e os métodos do SDK devem permanecer alinhados com esse schema.
O SDK documenta o comportamento implementado do cliente. As requisições ainda exigem API Pública habilitada no deployment, uma chave válida da conta e um modelo cujo status ao vivo para API permita a operação solicitada.
Status
O pacote @rivya/sdk é uma beta privada e ainda não foi publicado no npm. Os exemplos exigem acesso ao código privado do SDK e uma compilação que resolva @rivya/sdk.
O cliente oferece listagem de modelos, criação e consulta de gerações assíncronas, upload e consulta de arquivos, saldo de créditos, gerenciamento de endpoints de webhook, testes, listas de eventos e entregas, rotação de segredos, verificação de assinatura e Chat com ou sem streaming, incluindo sessões criadas pela API. O streaming usa análise SSE no servidor. Mantenha as chaves secretas no servidor.
Instalar Neste Repo
Estes comandos se aplicam a um checkout do Rivya com as dependências instaladas. Verificam o código do SDK; não baixam a beta do npm nem compilam o pacote exportado:
pnpm --dir packages/rivya-sdk typecheckO ambiente do servidor precisa de fetch, Headers, FormData, Blob e AbortController. A verificação de webhooks também exige globalThis.crypto.subtle. Mantenha a importação e a chave secreta no servidor:
import { RivyaClient } from "@rivya/sdk";
const rivya = new RivyaClient({
apiKey: process.env.RIVYA_API_KEY
});Não inclua chaves secretas em bundles do navegador, localStorage, eventos de análise, capturas de tela ou chamados compartilhados.
Além de apiKey, RivyaClient aceita baseURL, timeoutMs, fetch e defaultHeaders. Os padrões são https://rivya.ai e 60.000 ms de timeout. As opções por requisição incluem idempotencyKey, headers e signal; o SDK não repete requisições nem consulta o status automaticamente.
Listar Modelos
models.list é público e não exige chave de API:
const models = await rivya.models.list();
for (const model of models.data) {
console.log(model.id, model.api_status, model.supported_api_inputs);
}A lista inclui registros de descoberta que não podem ser chamados agora. Confira api_status, supported_api_inputs, file_kinds e chat_capabilities antes de exibir modelos ou controles. Modelos coming_soon, temporarily_unavailable ou studio_only não podem ser chamados pela Public API. O SDK não libera recursos exclusivos do provedor.
Criar uma Geração
Use generations.create com um modelo assíncrono disponível de imagem, vídeo ou áudio. Modelos de chat usam os métodos separados de Chat:
const generation = await rivya.generations.create(
{
model: "z-image",
prompt: "A clean editorial product image on a soft studio background",
client_request_id: "order-123-preview"
},
{
idempotencyKey: "order-123-preview"
}
);
console.log(generation.id, generation.status);generations.retrieve lê uma tarefa da conta da chave e pode atualizar seu status. Exige generations:read. O SDK não faz polling automático; consulte novamente enquanto o status for queued ou processing:
const current = await rivya.generations.retrieve(generation.id);
console.log(current.status, current.result?.primary_url);succeeded e failed são estados finais da tarefa, sem comprovar a liquidação dos créditos. Mesmo com sucesso, primary_url pode ser null; confira result.urls e settlement_status. Uma requisição HTTP malsucedida não significa que a tarefa falhou. Consulte Status da geração e Créditos da API.
idempotencyKey define o cabeçalho Idempotency-Key. Use uma nova chave para cada nova tarefa ou turno nos POSTs de geração e Chat. Ao verificar um resultado incerto, preserve a chave de API, a chave de idempotência e o corpo originais. Uma resposta salva pode ser reproduzida; um registro pendente ou um corpo diferente pode retornar idempotency_conflict. client_request_id é uma identificação de rastreamento, sem proteção contra duplicatas.
Fazer Upload de Arquivos
Use files.upload com files:create para um tipo de referência aceito pelo modelo. Quando ele exigir metadados assinados, vincule o upload ao ID do modelo da geração:
import { readFile } from "node:fs/promises";
const file = new Blob([await readFile("./reference.png")], {
type: "image/png"
});
const uploaded = await rivya.files.upload({
file,
filename: "reference.png",
kind: "image",
model: "nano-banana-2-lite",
client_request_id: "asset-123"
});
console.log(uploaded.id, uploaded.url);files.retrieve exige files:read, lê um arquivo disponível da conta e pode reemitir um token de duração, mas não repete todos os metadados do upload:
const sameFile = await rivya.files.retrieve(uploaded.id);
console.log(sameFile.mime_type, sameFile.duration_token);Guarde a resposta original. No GET atual, width, height, image_dimensions_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes e video_metadata_token são sempre null. Um token de duração de áudio emitido pelo GET não vincula MIME nem tamanho em bytes; não substitui o token original nos modelos que exigem esses dados.
Para gerações com referenceMediaItems, mapeie a resposta original para params.referenceMediaItems. O exemplo usa o mesmo upload de nano-banana-2-lite; não altere URL, modelo, MIME, dimensões ou tamanho dos campos assinados:
await rivya.generations.create({
model: "nano-banana-2-lite",
prompt: "Restyle this product photo for a clean editorial catalog page",
params: {
referenceMediaItems: [
{
url: uploaded.url,
kind: uploaded.kind,
name: uploaded.file_name,
mimeType: uploaded.mime_type,
durationSeconds: uploaded.duration_seconds ?? undefined,
durationToken: uploaded.duration_token ?? undefined,
width: uploaded.video_width ?? uploaded.width ?? undefined,
height: uploaded.video_height ?? uploaded.height ?? undefined,
sizeBytes: uploaded.video_file_size_bytes ?? uploaded.size_bytes,
imageDimensionsToken: uploaded.image_dimensions_token ?? undefined,
framesPerSecond: uploaded.frames_per_second ?? undefined,
videoBitrateMbps: uploaded.video_bitrate_mbps ?? undefined,
videoMetadataToken: uploaded.video_metadata_token ?? undefined
}
]
}
});Referências de seedream-5-pro, seedream-5-pro-layer-decomposition, nano-banana-2-lite, qwen-image-3, qwen-image-3-pro e grok-imagine-image-2-0 exigem mime_type, width, height, size_bytes e image_dimensions_token do upload original vinculado ao modelo. Mapeie para mimeType, width, height, sizeBytes e imageDimensionsToken. Se o token expirou ou a resposta se perdeu, envie a imagem novamente com o mesmo modelo; não estime os metadados.
Layer Decomposition aceita uma imagem e aplica limites geométricos. A edição com Grok Imagine Image 2.0 aceita de uma a cinco referências JPEG, PNG ou WebP assinadas. Confira os modos e limites atuais nas referências dos modelos.
Vídeos de referência de seedance-2-mini, seedance-2-5, minimax-h3, gemini-omni-video, gemini-omni-flash-1-1 e volcengine-video-lip-sync exigem video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes e video_metadata_token do upload original. Passe como width, height, framesPerSecond, videoBitrateMbps, sizeBytes e videoMetadataToken. Preserve durationSeconds e durationToken como prova separada de duração. Reenvie se faltar uma prova ou ela expirar; o GET não restaura video_metadata_token. Confira Modelos da API antes de escolher entradas de vídeo.
No Wan 3.0, envie cada referência com model: "wan-3-0-video". As cenas text, frames e reference são mutuamente exclusivas. Imagens exigem os campos assinados acima; vídeos exigem provas de duração e metadados de vídeo; áudios exigem os valores correspondentes a mimeType, sizeBytes, durationSeconds e durationToken do POST original. O token deve vincular MIME e tamanho; o token reemitido pelo GET não serve como substituto.
Defina seedance_scene, variant, resolution, aspect_ratio, duration, audio e o seed opcional em params. duration: -1 seleciona duração inteligente, reserva 30 segundos de saída e não pode ser combinado com vídeo de referência. Com vídeo de referência, a duração cobrada soma a saída aos segundos verificados do vídeo de entrada. Não há atalhos de arquivo para vídeo ou link para vídeo.
URLs de upload são temporárias. Guarde os arquivos de origem e reenvie quando a URL ou um token obrigatório deixar de funcionar. Um registro Files não garante armazenamento permanente.
Verificar Créditos
credits.retrieve exige credits:read e retorna o saldo da mesma carteira usada pelo Studio. Não fornece uma cotação nem confirma um reembolso específico:
const credits = await rivya.credits.retrieve();
console.log(credits.current_credits);Gerenciar Webhooks
Com webhooks habilitados no ambiente e uma chave da conta com webhooks:manage, crie um endpoint com uma URL pública permitida:
const endpoint = await rivya.webhooks.create({
name: "Production webhook",
url: "https://example.com/rivya/webhook",
event_types: ["generation.succeeded", "generation.failed"]
});
const signingSecret = endpoint.signing_secret;
console.log(endpoint.id);Guarde signing_secret com segurança no servidor ao criar o endpoint ou girar o segredo. Respostas comuns de listagem e consulta não o incluem.
Use webhooks.test somente com o endpoint ativo: ele tenta uma entrega real à URL cadastrada. Guarde o novo signing_secret de webhooks.rotateSecret; a rotação não oferece período de tolerância ao segredo anterior:
await rivya.webhooks.list();
await rivya.webhooks.retrieve(endpoint.id);
await rivya.webhooks.test(endpoint.id);
await rivya.webhooks.update(endpoint.id, { status: "disabled" });
const rotatedEndpoint = await rivya.webhooks.rotateSecret(endpoint.id);
const rotatedSigningSecret = rotatedEndpoint.signing_secret;
await rivya.webhooks.deliveries.list(endpoint.id, { limit: 20 });
await rivya.webhookEvents.list({ limit: 20 });Verifique a assinatura antes de confiar no corpo. Aqui, rawBody é a string original, sem alterações, e request é a requisição recebida. Só analise o corpo depois da verificação:
import { verifyRivyaWebhookSignature } from "@rivya/sdk";
const ok = await verifyRivyaWebhookSignature({
rawBody,
timestamp: request.headers.get("rivya-webhook-timestamp") || "",
signatureHeader: request.headers.get("rivya-webhook-signature") || "",
signingSecret: process.env.RIVYA_WEBHOOK_SIGNING_SECRET || ""
});
if (!ok) {
throw new Error("Invalid Rivya webhook signature");
}O helper verifica HMAC-SHA256 sobre o timestamp e o corpo original. Por padrão, rejeita timestamps a mais de 300 segundos do relógio local. Exige Web Crypto e pode lançar uma exceção se essa API faltar. Veja o formato em API Webhooks.
Chat
Use chat.completions.create com chat:create e um modelo de chat disponível para um turno sem streaming. Os modelos Claude atualmente disponíveis aceitam texto e modo de pensamento, mas não anexos de imagem, busca na web ou seleção de esforço de raciocínio. Confira chat_capabilities:
const completion = await rivya.chat.completions.create(
{
model: "claude-sonnet-5-chat",
message: "Write a concise launch plan for a new product image campaign",
client_request_id: "chat-001"
},
{
idempotencyKey: "chat-001"
}
);
console.log(completion.session_id, completion.message.content);Continue com o session_id retornado, o mesmo modelo e uma nova chave para o próximo turno:
await rivya.chat.completions.create(
{
model: "claude-sonnet-5-chat",
session_id: completion.session_id,
message: "Now turn that into a 5-step execution checklist."
},
{
idempotencyKey: "chat-002"
}
);Leia sessões com chat:read. Os métodos retornam apenas sessões da conta criadas pela API, não chats exclusivos do Studio. O histórico no navegador da mesma conta também pode conter sessões da API:
await rivya.chat.sessions.list({ limit: 20 });
await rivya.chat.sessions.retrieve(completion.session_id);Use chat.completions.stream para consumir SSE como iterador assíncrono. Trate erros tanto na chamada inicial quanto durante a iteração:
const stream = await rivya.chat.completions.stream(
{
model: "claude-sonnet-5-chat",
message: "Write a concise launch plan for a new product image campaign",
client_request_id: "chat-stream-001"
},
{
idempotencyKey: "chat-stream-001"
}
);
for await (const event of stream) {
if (event.event === "message.delta") {
process.stdout.write(event.data.delta);
}
if (event.event === "message.completed") {
console.log(event.data.message.id);
}
}message.delta serve para exibição, sem confirmar a gravação. message.completed confirma uma mensagem salva do assistente. Após desconexão ou erro, confira a sessão com chat.sessions.retrieve. Nem uma desconexão nem o simples EOF do iterador provam que nada foi salvo.
usage.completed inclui credits.settlement_status. done marca o fim bem-sucedido do fluxo, sem garantir liquidação. Nesta beta, o iterador não exige done e ignora silenciosamente frames SSE que não consegue analisar. Confira mensagens concluídas e liquidação; resposta parcial ou interrompida não garante reembolso. Veja Chat API.
Erros
O SDK lança RivyaAPIError para respostas HTTP não 2xx que consegue ler. A mesma classe cobre chave local ausente, eventos de erro de Chat analisados e verificações do fluxo:
import { RivyaAPIError } from "@rivya/sdk";
try {
await rivya.generations.retrieve("task_missing");
} catch (error) {
if (error instanceof RivyaAPIError) {
console.log(error.status, error.code, error.requestId);
} else {
throw error;
}
}Ela contém mensagem, status, código e ID de requisição opcionais e um subconjunto permitido de cabeçalhos. Em respostas não 2xx, status é o status HTTP. Um evento de erro do Chat usa status SDK 500, mesmo com streaming iniciado em HTTP 200. Corpo de stream ausente e nomes de evento inesperados também podem causar erros do SDK.
Falhas de rede, cancelamento e leitura do corpo podem propagar outros tipos de erro. Uma resposta bem-sucedida é analisada como JSON quando possível; caso contrário, retorna texto, sem validação pelo tipo TypeScript. Frames SSE reconhecidos também não são validados contra o schema. O tipo do erro não revela se a gravação ocorreu: confira a tarefa ou sessão original antes de repetir.
Validação
Para mantenedores com um checkout do Rivya, execute após alterar o cliente:
pnpm sdk:check
pnpm --dir packages/rivya-sdk typecheck
pnpm content:api-docspnpm sdk:check combina comparação estática de SDK/OpenAPI/documentação com verificações simuladas, sem rede, de erros, cabeçalhos seguros, idempotência, Bearer auth, modelos públicos, análise SSE de Chat, eventos de erro e assinaturas de webhook. Não chama provedores nem comprova disponibilidade de modelos, liquidação de reembolsos ou entrega completa de SSE.
