↓
Documentación de Rivya AI

Chat API

Envía turnos de texto con Chat API de Rivya. Consulta campos, eventos SSE, reglas de sesión y liquidación de créditos.

Última revisión el 11 de noviembre de 2026

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.

Esta página documenta el contrato implementado de la API pública v1. La ejecución depende de que la API pública esté habilitada en el despliegue, la cuenta tenga una clave válida y el modelo figure como disponible para API en la lista actual. Que esté documentado no implica que pueda usarse en todos los entornos.

Solicitudes de texto a Gemini 4 Carbon

Esta opción de Rivya para Gemini 4 Carbon solo admite texto, sin adjuntos, búsqueda web, herramientas ni ajustes de razonamiento. La respuesta completa se entrega tras validar el estado final. La reserva cubre todo el contexto publicado del modelo para entrada y salida, sin usar una longitud predeterminada de respuesta como límite de facturación.

La cotización promocional actual caduca a las 00:00 UTC del 30 de noviembre de 2026. Las nuevas solicitudes se detienen en ese momento hasta confirmar otra cotización. Las existentes conservan la cotización de su creación y se ajustan con consumo confirmado. No continúes ni reenvíes automáticamente una solicitud incierta.

Alcance actual

Chat API v1 ofrece respuestas sin streaming, SSE con text/event-stream, sesiones de API, reserva de créditos, registro de tokens y liquidación de créditos. La búsqueda web, el esfuerzo de razonamiento, el modo de pensamiento y las imágenes vía Files dependen del modelo.

Los modelos Claude disponibles actualmente aceptan solo texto y modo de pensamiento, sin adjuntos, búsqueda web ni selección de esfuerzo de razonamiento. Los modelos no disponibles o Coming Soon no se pueden llamar. Comprueba la disponibilidad y chat_capabilities en la lista de modelos; la lista del proveedor no describe las funciones expuestas por Rivya.

No admite historial bruto messages, continuar sesiones exclusivas de Studio, URL externas arbitrarias como adjuntos ni eventos de webhook de Chat.

Scopes requeridos

Usa chat:create para enviar un turno y chat:read para listar o leer sesiones de API:

chat:create
chat:read

Las claves nuevas de la configuración incluyen ambos. Si faltan en una clave antigua, crea una sustituta. La clave debe estar activa y vigente, y la cuenta debe tener acceso a la API.

Crear un chat completion

Los dos endpoints aceptan los mismos campos:

CampoObligatorioDescripción
modelSíID de modelo de chat disponible, hasta 160 caracteres. Conserva el modelo de la sesión al continuar.
messageSíDe 1 a 8.000 caracteres tras quitar espacios de los extremos. Rivya carga la conversación guardada; no envíes messages.
session_idNoSesión de API de esta cuenta, hasta 160 caracteres. Omítelo para crear una nueva.
tool_slugNoIdentificador de preajuste de chat, hasta 160 caracteres. Consulta Controles opcionales.
enable_web_searchNoBooleano, activo solo si el modelo lo admite y el valor es true.
reasoning_effortNodefault, minimal, low, medium, high o xhigh. Solo tienen efecto los valores de chat_capabilities.reasoning_efforts; otras opciones válidas usan el predeterminado.
thought_modeNodefault, on u off. on/off solo tienen efecto con chat_capabilities.thoughts verdadero; default no especifica el ajuste.
attachmentsNoHasta seis objetos con file_id, también sujetos al límite del modelo. Consulta Adjuntos de imagen.
client_request_idNoIdentificador de auditoría de hasta 128 caracteres. No sustituye a Idempotency-Key.

Sustituye la clave de ejemplo, usa una clave de idempotencia distinta por cada turno nuevo y ten saldo suficiente:

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": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-001"
  }'

Respuesta ilustrativa: los ID, fechas, tokens y créditos son ejemplos, no una cotización para el prompt:

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

La reserva se hace antes de solicitar la respuesta y depende del modelo, los mensajes guardados, el mensaje actual, las instrucciones predefinidas y los adjuntos admitidos. usage registra tokens, no el coste final en créditos.

Comprueba credits.settlement_status. Con un consumo comunicado válido y no superior a la reserva, Rivya liquida y devuelve la diferencia. Si falta, es inválido o supera la reserva, devuelve RECONCILIATION_REQUIRED y credits.final sigue siendo la reserva. Una respuesta guardada con uso registrado puede seguir sin liquidación resuelta. Consulta Créditos de API.

Hacer streaming de un chat completion

Usa POST /api/v1/chat/completions/stream para leer el texto a medida que llega:

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": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

La respuesta usa Content-Type: text/event-stream; charset=utf-8.

EventoSignificado
session.createdSe validaron clave, modelo, sesión, adjuntos, límite de solicitudes y reserva.
message.deltaFragmento para mostrar, todavía sin mensaje guardado.
message.completedMensaje del asistente guardado en la sesión de API.
usage.completedTokens y créditos, incluido settlement_status; no garantiza liquidación completa.
heartbeatMantiene la conexión durante las pausas.
errorError tras el inicio; comprueba el código, sin suponer que no se guardó el turno.
doneEl flujo terminó correctamente; comprueba la liquidación por separado.

Ejemplo de turno liquidado con los mismos valores anteriores:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"claude-sonnet-5-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,"settlement_status":"SETTLED"}}

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

Antes del streaming, los rechazos devuelven error JSON con estado HTTP. Tras iniciarse, el HTTP es 200; si aún se puede enviar el error, llega event: error y el flujo se cierra sin done:

event: error
data: {"error":{"code":"internal_error","message":"Rivya could not confirm the result of this request.","requestId":"req_..."}}

Al desconectarse, Rivya intenta detener el flujo del proveedor. Confirma lo guardado con message.completed o la sesión, no con los fragmentos. Un flujo cortado no revela si se guardó el turno ni cómo se liquidaron los créditos. Si recibiste session_id, consulta GET /api/v1/chat/sessions/{sessionId} antes de otro turno. Una respuesta guardada sigue disponible aunque no llegaran los eventos finales.

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": "claude-sonnet-5-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

La sesión debe pertenecer a la misma cuenta y haberse creado por Public API. Chat API no lista, lee ni continúa sesiones exclusivas de Studio. El historial del navegador de la misma cuenta también puede incluir sesiones de API.

Conserva el modelo. Si hay un preajuste guardado, omite tool_slug para reutilizarlo o envía el mismo identificador; otro se rechaza. Envía los controles deseados en cada turno: los valores omitidos usan los predeterminados, sin heredar la solicitud anterior.

Adjuntos de imagen

Los adjuntos usan registros Files, no URL externas. Los modelos Claude disponibles no aceptan adjuntos. El formato siguiente solo se puede usar si un modelo disponible declara chat_capabilities.image_attachments: true.

  1. Sube la imagen a POST /api/v1/files con files:create.

  2. Usa el id devuelto en attachments[].file_id.

{
  "model": "<image-capable-chat-model-id>",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

El archivo debe pertenecer a la cuenta, estar disponible, tener kind: "image" y ser JPEG, PNG o WebP. Los ID deben ser distintos. El schema permite hasta seis, pero el límite del modelo puede ser menor. Sustituye el modelo de ejemplo por uno disponible que admita imágenes; claude-sonnet-5-chat no sirve. La falta de compatibilidad o un archivo ausente, no disponible, ajeno o de formato incorrecto devuelven chat_attachment_not_supported. Tras comprobar capacidad y cantidad, los ID repetidos devuelven validation_failed.

Controles opcionales

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

Comprueba chat_capabilities en /api/v1/models antes de ofrecer controles. Un valor válido en el schema no habilita funciones incompatibles: la búsqueda queda desactivada, el razonamiento vuelve al predeterminado y el pensamiento se omite. thought_mode controla el ajuste del modelo; no hay un campo separado de pensamientos en la respuesta.

tool_slug selecciona instrucciones predefinidas, actualmente ai-calculator y ai-solver. No ejecuta una calculadora independiente, no verifica respuestas automáticamente ni permite funciones arbitrarias. La elección al crear la sesión se guarda. En una sesión sin preajuste guardado, el parámetro solo se aplica al turno actual, sin convertirse en su preajuste permanente.

Listar sesiones

Usa GET /api/v1/chat/sessions con chat:read:

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

Devuelve solo sesiones de API de esta cuenta, por actividad más reciente. limit se interpreta como entero: los positivos se limitan a 100; en otro caso, el predeterminado es 20. No hay cursor de paginación.

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "claude-sonnet-5-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

Lee una sesión de API y sus mensajes guardados:

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

Devuelve mensajes confirmados de usuario y asistente en orden cronológico, excluyendo turnos pendientes o fallidos. Incluyen id, role, content y created_at; no devuelven tokens, liquidación de créditos, adjuntos ni campos internos del proveedor.

Idempotencia

Envía Idempotency-Key en cada nuevo turno POST de completions o streaming. Tras un error de red, conserva la clave de API, la clave de idempotencia y el cuerpo originales al comprobar la solicitud.

Una respuesta guardada coincidente se reproduce sin crear ni cobrar otro turno. También se reproducen errores guardados. Un cuerpo distinto, una solicitud pendiente o un registro sin respuesta devuelven idempotency_conflict; no indican que debas reenviar con otra clave.

Las reproducciones de streaming correcto envían session.created, message.completed, usage.completed y done, sin los fragmentos antiguos. Los fallos guardados devuelven error JSON con el estado HTTP original, sin repetir un flujo de error.

Si la respuesta queda incompleta, comprueba la sesión original antes de reenviar. Sin session_id, busca conversaciones recientes en la lista y usa la clave y el cuerpo originales para recuperar una respuesta guardada, si existe. client_request_id es solo auditoría. Una clave nueva puede crear otro turno con cargo.

Errores comunes

CódigoSignificado
chat_model_not_supportedModelo ausente, no es de chat o no está disponible.
chat_session_conflictModelo o preajuste en conflicto con la sesión, o identificador desconocido.
chat_attachment_not_supportedSin compatibilidad o archivo ausente, no disponible, ajeno, no es imagen o tiene formato inválido.
insufficient_creditsSaldo disponible insuficiente para reservar el turno.
idempotency_conflictDatos distintos, solicitud pendiente o ninguna respuesta guardada disponible.
not_foundSesión ausente, ajena o no creada por API.
validation_failedCampos fuera del schema o ID de adjuntos repetidos.
internal_errorResultado incierto; busca la respuesta guardada antes de crear otro turno.

Páginas relacionadas