Chat API

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:

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.

1. Sube una imagen con POST /api/v1/files.

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

Páginas relacionadas

• Modelos de la API

• Files API

• Créditos de la API

• Errores y límites de la API

• Contrato de OpenAPI y schema