Use a Rivya Chat API para turnos sem streaming ou com SSE, sessões criadas pela API, anexos de imagem por file_id e liquidação de créditos baseada em tokens.

Use POST /api/v1/chat/completions para uma resposta completa de chat sem streaming, ou POST /api/v1/chat/completions/stream para Server-Sent Events.

A Chat API é baseada em sessões. Omita session_id para iniciar uma nova sessão de chat da API. Envie um session_id retornado para continuar a mesma sessão criada pela API.

Escopo Atual

A Chat API v1 oferece suporte a:

respostas de assistente sem streaming
streaming SSE com text/event-stream
sessões de chat criadas pela API
reserva de créditos da conta e liquidação final baseada em tokens
busca web opcional, reasoning effort e thought mode quando o modelo selecionado oferecer suporte
anexos de imagem por valores file_id da Files API

A Chat API v1 não oferece suporte a:

histórico bruto de messages fornecido pelo usuário
continuação de sessões de chat exclusivas do Studio
URLs arbitrárias de anexos externos
eventos de webhook de Chat

Escopos Necessários

Use uma chave de API com:

chat:create
chat:read

Novas chaves criadas em Configurações incluem os dois escopos por padrão. Chaves antigas talvez precisem ser recriadas antes de chamar a Chat API.

Criar uma Conclusão de Chat

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-001"
  }'

Resposta:

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "session_id": "session_id",
  "model": "gpt-5-2-chat",
  "created_at": "2026-05-11T00:00:00.000Z",
  "message": {
    "id": "assistant_message_id",
    "role": "assistant",
    "content": "..."
  },
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 320,
    "total_tokens": 1520
  },
  "credits": {
    "reserved": 3,
    "final": 2
  }
}

Fazer Streaming de uma Conclusão de Chat

Use POST /api/v1/chat/completions/stream quando seu servidor quiser receber deltas do assistente conforme eles chegam:

curl -N https://rivya.ai/api/v1/chat/completions/stream \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: chat-stream-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

Respostas com streaming usam Content-Type: text/event-stream; charset=utf-8.

Eventos:

Event	Meaning
`session.created`	A chave de API, o modelo, a sessão, os anexos, o limite de taxa e as checagens de reserva de créditos passaram.
`message.delta`	Um delta exibível da mensagem do assistente. Esta ainda não é uma mensagem confirmada.
`message.completed`	A mensagem do assistente foi confirmada na sessão criada pela API.
`usage.completed`	O uso de tokens e os créditos finais foram liquidados.
`heartbeat`	Evento keepalive durante pausas longas.
`error`	Envelope de erro da API pública para uma falha depois que o streaming começou.
`done`	O stream terminou com sucesso.

Exemplo de stream:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"gpt-5-2-chat"}

event: message.delta
data: {"request_id":"req_...","session_id":"session_id","delta":"Draft ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Draft ...","created_at":"2026-05-11T00:00:00.000Z"}}

event: usage.completed
data: {"request_id":"req_...","session_id":"session_id","usage":{"input_tokens":1200,"output_tokens":320,"total_tokens":1520},"credits":{"reserved":3,"final":2}}

event: done
data: {"request_id":"req_...","ok":true}

Se um erro acontecer depois do primeiro evento SSE, o stream envia event: error e depois fecha:

event: error
data: {"error":{"code":"internal_error","message":"The request could not be completed.","requestId":"req_..."}}

Se o cliente desconectar antes da conclusão, a Rivya interrompe o stream de geração em andamento quando possível. Deltas parciais não são salvos como mensagem final do assistente. Se o servidor já tiver confirmado message.completed, o resultado final poderá ser lido depois com GET /api/v1/chat/sessions/{sessionId}.

Continuar uma Sessão

Use o session_id retornado:

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-002" \
  -d '{
    "model": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

A sessão deve pertencer à mesma conta Rivya e ter sido criada pela Public API. Sessões de chat exclusivas do Studio não são retornadas nem continuadas pela Chat API.

Anexos de Imagem

Anexos de chat usam registros da Files API, não URLs externas.

Faça upload de uma imagem com POST /api/v1/files.
Use o id retornado como attachments[].file_id.

{
  "model": "gpt-5-2-chat",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

O arquivo deve pertencer à mesma conta, ter kind: "image" e estar disponível. Modelos que não oferecem suporte a anexos de imagem retornam chat_attachment_not_supported.

Controles Opcionais

{
  "model": "gpt-5-2-chat",
  "message": "Compare three launch options.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

O suporte a controles varia por modelo. Leia /api/v1/models e confira chat_capabilities antes de expor controles na sua interface.

Listar Sessões

Use GET /api/v1/chat/sessions com uma chave que inclua chat:read.

curl https://rivya.ai/api/v1/chat/sessions \
  -H "Authorization: Bearer rvya_sk_..."

Isso retorna apenas sessões criadas pela API:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-chat",
      "tool_slug": null,
      "title": "Write a concise launch plan...",
      "controls": {
        "enable_web_search": false,
        "reasoning_effort": null,
        "thought_mode": null
      },
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:00:00.000Z",
      "last_message_at": "2026-05-11T00:00:00.000Z"
    }
  ]
}

Obter uma Sessão

Use GET /api/v1/chat/sessions/{sessionId} para ler uma sessão criada pela API e suas mensagens confirmadas.

curl https://rivya.ai/api/v1/chat/sessions/session_id \
  -H "Authorization: Bearer rvya_sk_..."

A resposta inclui mensagens confirmadas do usuário e do assistente. Ela não expõe campos internos de provedores.

Idempotência

Use Idempotency-Key para toda solicitação de produção POST /api/v1/chat/completions e POST /api/v1/chat/completions/stream.

Se uma nova tentativa usar a mesma chave e o mesmo corpo, a Rivya poderá retornar a resposta armazenada sem criar outra mensagem nem consumir créditos novamente. Se a mesma chave for reutilizada com entrada diferente, a API retornará idempotency_conflict.

Para novas tentativas de streaming, a Rivya não reproduz deltas históricos de tokens. Um replay concluído retorna uma sequência SSE mínima com session.created, message.completed, usage.completed e done.

Erros Comuns

Code	Meaning
`chat_model_not_supported`	O modelo selecionado não está disponível para a Chat API.
`chat_session_conflict`	A sessão não pode ser usada para esta solicitação.
`chat_attachment_not_supported`	O anexo está ausente, não pertence à conta, não é uma imagem ou não é suportado pelo modelo.
`insufficient_credits`	A conta não tem créditos suficientes para o turno.
`idempotency_conflict`	A chave de idempotência foi reutilizada com entrada diferente.

Chat API