Usa Rivya Chat API para turnos sin streaming o con SSE, sesiones creadas por API, adjuntos de imagen file_id y liquidación de créditos basada en tokens.

Usa POST /api/v1/chat/completions para obtener una respuesta de chat completa sin streaming, o POST /api/v1/chat/completions/stream para Server-Sent Events.

Chat API se basa en sesiones. Omite session_id para iniciar una nueva sesión de chat por API. Pasa un session_id devuelto para continuar esa misma sesión creada por API.

Alcance actual

Chat API v1 admite:

respuestas del assistant sin streaming
streaming SSE con text/event-stream
sesiones de chat creadas por API
reserva de créditos de cuenta y liquidación final basada en tokens
búsqueda web, reasoning effort y thought mode opcionales cuando el modelo seleccionado los admite
adjuntos de imagen mediante valores file_id de Files API

Chat API v1 no admite:

historial raw de messages proporcionado por el usuario
continuar sesiones de chat exclusivas de Studio
URL externas arbitrarias para adjuntos
eventos de webhook de Chat

Scopes requeridos

Usa una clave API con:

chat:create
chat:read

Las claves nuevas creadas en Settings incluyen ambos scopes por defecto. Las claves más antiguas quizá deban recrearse antes de llamar a Chat API.

Crear un chat completion

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"
  }'

Respuesta:

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

Hacer streaming de un chat completion

Usa POST /api/v1/chat/completions/stream cuando tu servidor quiera recibir deltas del assistant a medida que llegan:

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"
  }'

Las respuestas streaming usan Content-Type: text/event-stream; charset=utf-8.

Eventos:

Event	Significado
`session.created`	Las comprobaciones de clave API, modelo, sesión, adjuntos, rate limit y reserva de créditos pasaron.
`message.delta`	Un delta de visualización para el mensaje del assistant. Todavía no es un mensaje confirmado.
`message.completed`	El mensaje del assistant se confirmó en la sesión creada por API.
`usage.completed`	El uso de tokens y los créditos finales quedaron liquidados.
`heartbeat`	Evento keepalive durante pausas largas.
`error`	Envoltorio público de error de API para un fallo después de iniciado el streaming.
`done`	El stream terminó correctamente.

Ejemplo 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}

Si ocurre un error después del primer evento SSE, el stream envía event: error y luego se cierra:

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

Si el cliente se desconecta antes de completar, Rivya detiene el stream de generación en curso cuando es posible. Los deltas parciales no se guardan como mensaje final del assistant. Si el servidor ya confirmó message.completed, el resultado final se puede leer más tarde con GET /api/v1/chat/sessions/{sessionId}.

Continuar una sesión

Usa el session_id devuelto:

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."
  }'

La sesión debe pertenecer a la misma cuenta de Rivya y debe haber sido creada por Public API. Chat API no devuelve ni continúa sesiones de chat exclusivas de Studio.

Adjuntos de imagen

Los adjuntos de Chat usan registros de Files API, no URL externas.

Sube una imagen con POST /api/v1/files.
Usa el id devuelto como attachments[].file_id.

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

El archivo debe pertenecer a la misma cuenta, tener kind: "image" y estar disponible. Los modelos que no admiten adjuntos de imagen devuelven chat_attachment_not_supported.

Controles opcionales

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

El soporte de controles varía según el modelo. Lee /api/v1/models y revisa chat_capabilities antes de exponer controles en tu UI.

Listar sesiones

Usa GET /api/v1/chat/sessions con una clave que incluya chat:read.

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

Esto devuelve solo sesiones creadas por 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"
    }
  ]
}

Obtener una sesión

Usa GET /api/v1/chat/sessions/{sessionId} para leer una sesión creada por API y sus mensajes confirmados.

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

La respuesta incluye mensajes confirmados de user y assistant. No expone campos internos del proveedor.

Idempotencia

Usa Idempotency-Key en cada solicitud de producción POST /api/v1/chat/completions y POST /api/v1/chat/completions/stream.

Si un reintento usa la misma clave y el mismo body, Rivya puede devolver la respuesta guardada sin crear otro mensaje ni consumir créditos de nuevo. Si la misma clave se reutiliza con una entrada distinta, la API devuelve idempotency_conflict.

Para reintentos de streaming, Rivya no reproduce deltas históricos de tokens. Una repetición completada devuelve una secuencia SSE mínima con session.created, message.completed, usage.completed y done.

Errores comunes

Code	Significado
`chat_model_not_supported`	El modelo seleccionado no está disponible para Chat API.
`chat_session_conflict`	La sesión no se puede usar para esta solicitud.
`chat_attachment_not_supported`	El adjunto falta, no pertenece a la cuenta, no es una imagen o el modelo no lo admite.
`insufficient_credits`	La cuenta no tiene créditos suficientes para el turno.
`idempotency_conflict`	La clave de idempotencia se reutilizó con una entrada diferente.

Chat API