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:readLas 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:
| Campo | Obligatorio | Descripción |
|---|---|---|
model | Sí | ID de modelo de chat disponible, hasta 160 caracteres. Conserva el modelo de la sesión al continuar. |
message | Sí | De 1 a 8.000 caracteres tras quitar espacios de los extremos. Rivya carga la conversación guardada; no envíes messages. |
session_id | No | Sesión de API de esta cuenta, hasta 160 caracteres. Omítelo para crear una nueva. |
tool_slug | No | Identificador de preajuste de chat, hasta 160 caracteres. Consulta Controles opcionales. |
enable_web_search | No | Booleano, activo solo si el modelo lo admite y el valor es true. |
reasoning_effort | No | default, minimal, low, medium, high o xhigh. Solo tienen efecto los valores de chat_capabilities.reasoning_efforts; otras opciones válidas usan el predeterminado. |
thought_mode | No | default, on u off. on/off solo tienen efecto con chat_capabilities.thoughts verdadero; default no especifica el ajuste. |
attachments | No | Hasta seis objetos con file_id, también sujetos al límite del modelo. Consulta Adjuntos de imagen. |
client_request_id | No | Identificador 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.
| Evento | Significado |
|---|---|
session.created | Se validaron clave, modelo, sesión, adjuntos, límite de solicitudes y reserva. |
message.delta | Fragmento para mostrar, todavía sin mensaje guardado. |
message.completed | Mensaje del asistente guardado en la sesión de API. |
usage.completed | Tokens y créditos, incluido settlement_status; no garantiza liquidación completa. |
heartbeat | Mantiene la conexión durante las pausas. |
error | Error tras el inicio; comprueba el código, sin suponer que no se guardó el turno. |
done | El 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.
Sube la imagen a
POST /api/v1/filesconfiles:create.Usa el
iddevuelto enattachments[].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ódigo | Significado |
|---|---|
chat_model_not_supported | Modelo ausente, no es de chat o no está disponible. |
chat_session_conflict | Modelo o preajuste en conflicto con la sesión, o identificador desconocido. |
chat_attachment_not_supported | Sin compatibilidad o archivo ausente, no disponible, ajeno, no es imagen o tiene formato inválido. |
insufficient_credits | Saldo disponible insuficiente para reservar el turno. |
idempotency_conflict | Datos distintos, solicitud pendiente o ninguna respuesta guardada disponible. |
not_found | Sesión ausente, ajena o no creada por API. |
validation_failed | Campos fuera del schema o ID de adjuntos repetidos. |
internal_error | Resultado incierto; busca la respuesta guardada antes de crear otro turno. |
