Uma boa integração com a API da Rivya não é apenas uma requisição para um modelo.

A maioria dos fluxos reais de produto tem uma pequena cadeia: escolher o modelo certo, preparar o input, enviar arquivos de referência quando necessário, submeter um job, acompanhar status, lidar com créditos e avisar o produto quando o resultado estiver pronto.

Este artigo mostra o formato de planejamento. Use Rivya API Quickstart para o caminho executável mais curto e use as docs da API para os campos exatos de requisição.

Comece pelo momento do produto

Antes de escolher endpoints, descreva o momento do produto em uma frase.

Exemplos:

Criar um rascunho de imagem de produto quando um vendedor envia um briefing de listagem.
Gerar um conceito curto de vídeo depois que um gerente de campanha aprova uma direção still.
Enviar um turno de chat dentro de uma ferramenta interna de pesquisa e transmitir a resposta de volta ao usuário.
Enviar uma imagem de referência, submeter uma requisição de modelo compatível e avisar o usuário quando o resultado estiver pronto.

Essa frase impede que a integração vire uma coleção solta de chamadas de API.

Mapeie o fluxo antes de escrever código

Use esta tabela antes de abrir o schema da requisição.

Etapa do fluxo	Pergunta de produto	Área da API
Acesso da conta	Qual conta Rivya é dona do uso?	Autenticação da API
Escolha de modelo	Qual ID público de modelo combina com este trabalho?	Modelos da API
Input de referência	O modelo precisa de mídia enviada?	Files API
Geração	Isto é um job assíncrono de imagem, vídeo ou áudio?	Criar geração
Chat	Isto é um turno de modelo de chat em vez de um job de geração?	Chat API
Status	Como o produto saberá que o resultado está pronto?	Status de geração
Evento de conclusão	Outro sistema deve receber um callback assinado?	API Webhooks
Créditos	Como a equipe entenderá o custo?	Créditos da API

O fluxo deve ser claro o bastante para que cada área da API tenha uma razão para existir.

Etapa 1: crie uma chave para a integração

Crie uma chave de API para o app, ambiente ou fluxo específico que vai usá-la.

Evite usar uma chave para tudo. Nomear chaves por finalidade facilita a revisão posterior:

production-image-workflow
staging-video-tests
internal-chat-assistant
webhook-smoke-test

Leia Autenticação da API antes de armazenar a chave. O segredo completo é exibido uma vez, então sua equipe deve salvá-lo imediatamente no secret store server-side correto.

Etapa 2: escolha modelos pela lista pública da API

Não faça hard-code de um modelo só porque ele funcionou em um teste manual.

Use Modelos da API e Referência da API de modelos para confirmar:

o ID público do modelo
se ele está disponível pela API
modo de input compatível
expectativas de prompt e parâmetros
se Files API é necessária
comportamento de crédito e notas de prontidão

É aqui que muitas integrações ficam mais limpas. Um modelo perfeito para um teste manual no Studio pode não ser o melhor primeiro modelo para um fluxo automatizado de produto.

Etapa 3: decida se Files API faz parte da primeira versão

Se o modelo consegue rodar a partir de input de texto, mantenha a primeira versão text-only.

Adicione Files API apenas quando o fluxo realmente precisar de mídia de referência.

Quando precisar, defina:

quais tipos de arquivo o produto aceita
quem é dono da etapa de limpeza de arquivos
o que acontece quando o upload falha
como os dados de arquivo retornados são passados para parâmetros do modelo
se o mesmo arquivo deve ser reutilizado ou enviado novamente

Isso evita que uma experiência frágil de arquivos fique escondida atrás de um botão de geração que parece limpo.

Etapa 4: submeta um job de geração

Para geração de imagem, vídeo e áudio, o padrão normal é:

preparar o ID do modelo, prompt e params compatíveis
adicionar uma chave de idempotência para retries seguros
submeter pelo endpoint de geração
salvar o ID público da task
fazer polling de status até a task alcançar um estado terminal

Use Criar geração para o formato da requisição e Status de geração para lidar com o resultado.

O produto deve tratar queued, processing, succeeded e failed como estados visíveis ao usuário. Não faça usuários lerem detalhes de sistema nem adivinharem por que um job está lento.

Etapa 5: use Chat API para modelos de chat

Modelos de chat devem usar Chat API, não o endpoint de geração.

Isso importa porque trabalho de chat tem comportamento diferente:

turnos de chat podem pertencer a sessões criadas pela API
streaming não-SSE e SSE têm experiências de usuário diferentes
anexos de imagem usam IDs de arquivo da Files API
acerto de créditos acompanha o turno de chat, não uma task assíncrona normal de mídia

Se seu produto precisa de uma resposta de assistente dentro da própria interface, Chat API pode ser o caminho certo. Se o usuário ainda está explorando ideias, Rivya Chat ou Studio pode ser melhor.

Etapa 6: comece com polling, depois adicione webhooks

Para uma primeira versão, polling é mais fácil de raciocinar.

Adicione API Webhooks quando:

o produto tem muitos jobs assíncronos
clientes em espera não devem fazer polling diretamente
sistemas downstream precisam de eventos de conclusão assinados
tratamento de retry e duplicidade já foi desenhado

Receivers de webhook devem ser simples e rígidos: verificar a assinatura, aceitar eventos duplicate-safe, atualizar um registro de produto e registrar apenas o que é seguro registrar.

Etapa 7: torne créditos visíveis no produto

A API da Rivya usa os mesmos créditos de conta que o Studio.

Sua integração deve decidir quanto disso mostrar. No mínimo, a equipe deve saber:

qual conta é dona da chave de API
qual fluxo pode consumir créditos
o que acontece quando os créditos estão baixos demais
como estados de geração com falha são explicados
para onde enviar alguém com dúvidas de crédito e cobrança

Use Créditos da API, Créditos e cobrança na Rivya e Como pensar sobre créditos, packs e planos da Rivya para o modelo de carteira visível ao usuário.

Uma primeira versão pequena

Uma boa primeira versão é intencionalmente limitada.

Por exemplo:

uma chave de API
um modelo de imagem selecionado
ainda sem upload de arquivos
uma requisição de geração
um caminho de polling de status
uma prévia simples do resultado no seu produto
uma mensagem clara de erro de crédito

Essa versão prova a conexão antes de adicionar mais partes móveis.

Uma versão mais completa

Depois que a primeira versão funciona, um fluxo mais completo pode adicionar:

Files API para imagens ou vídeos de referência
controles de parâmetros específicos por modelo
idempotência ligada ao registro do seu produto
webhooks assinados para conclusão
Chat API para turnos de assistente
um stream de eventos server-side quando chat precisa de output ao vivo
views administrativas ou de suporte para jobs com falha

Cada adição deve responder a uma necessidade real de produto. Se ela só deixa a demo maior, deixe de fora.

Erros comuns de integração

Evite estes padrões:

começar com todos os recursos da API ao mesmo tempo
esconder uso de créditos do dono da conta
usar suposições exclusivas do Studio em um fluxo de API
tratar uploads de arquivo como detalhe posterior
repetir requisições de geração sem idempotência
usar Chat API para jobs que deveriam ser geração assíncrona
usar endpoints de geração para turnos de chat
registrar chaves completas de API, segredos de webhook ou detalhes temporários de arquivo

O fluxo de API mais seguro é explícito sobre propriedade, estado e tratamento de falhas.

Para onde ir depois

Comece por Developers para o hub público da API.
Use Rivya API Quickstart para executar a primeira requisição.
Use Modelos da API antes de selecionar IDs de modelo.
Use Files API apenas quando o modelo realmente precisar de mídia de referência.
Use Chat API para turnos de chat e respostas de chat em streaming.
Use API Webhooks quando polling já não for suficiente.
Se o fluxo ainda precisa de exploração humana, leia Quando usar a API da Rivya em vez do Studio antes de automatizá-lo.

Crie um fluxo multimodal com a API da Rivya