Crie um fluxo multimodal com a API da Rivya

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.

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 é:

1. preparar o ID do modelo, prompt e params compatíveis

2. adicionar uma chave de idempotência para retries seguros

3. submeter pelo endpoint de geração

4. salvar o ID público da task

5. 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:

1. uma chave de API

2. um modelo de imagem selecionado

3. ainda sem upload de arquivos

4. uma requisição de geração

5. um caminho de polling de status

6. uma prévia simples do resultado no seu produto

7. 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.