API Reference

Procesamiento de respuestas

URL: https://api.saptiva.com/v1/chat/completions

POST /

Headers

Nombre	Valor
Content-Type	application/json
Authorization	Bearer <API_KEY>

Nuestra API requiere autenticación utilizando un Token Bearer. Genera tu token dentro de nuestro lab y comienza a hacer peticiones. Incluye el token en el header de la solicitud de la siguiente manera:

Authorization: Bearer <TOKEN AUTHORIZATION>

---

Parámetros Obligatorios

Body

Parametro	Tipo	Descripción	Ejemplo
model	string	Nombre del modelo LLM a usar.	Saptiva Cortex
messages	array	Lista (o array) de objetos que representan un historial de conversación entre un sistema y un usuario.	[ { "role": "system", "content": "Eres un agente servicial" }, { "role": "user", "content": "¿Cuál es la capital de Francia?" } ]

---

Parámetros Opcionales

Body

Parámetro	Tipo	Descripción	Valores por Defecto
max_tokens	number	Número de tokens.	600
temperature	double	Grado de aleatoriedad en la generación del texto. (valor entre 0.0 y 1.0)	0.7
top_p	double	Limite de diversidad del conjunto de palabras consideradas. (valor entre 0.0 y 1.0)	0.9
stream	bool	Indica si la respuesta del modelo debe ser enviada por partes (streaming) o completa de una vez.	false
tools	List[ToolItem]	Define una lista de tools a usar. Para más información, consulta Tools.	null
prompt	string	Texto que se busca transformar en un embedding	null

---

Solicitudes (Modelos Texto-Texto)

A continuación, se presenta el formato que debe tener el BODY, junto con el ejemplo de la respuesta esperada.

Modelos:

Saptiva Turbo
Saptiva Legacy

Body

{
  "model": "Saptiva Turbo",
  "messages": [
    {
      "role": "system",
      "content": "Eres un agente servicial"
    },
    {
      "role": "user",
      "content": "¿Cuál es la capital de México?"
    }
  ],
  "max_tokens": 256,
  "temperature": 0.7,
  "top_p": 0.95
}

Respuesta

---

Solicitudes (Modelo de Razonamiento)

A continuación, se presenta el formato que debe tener el BODY, junto con el ejemplo de la respuesta esperada.

Modelo:

Saptiva Cortex
Saptiva Ops

Body

{
    "model": "Saptiva Cortex",
    "messages": [
        {
            "role": "user", 
            "content": "Cuánto es 10/2?"
        }
    ]
}

Respuesta

---

Solicitudes (Modelo OCR)

A continuación, se presenta el formato que debe tener el BODY, junto con el ejemplo de la respuesta esperada.

En el campo url, proporcione la imagen en uno de los siguientes formatos:

• URL de descarga accesible públicamente,

• Cadena base64 con formato: data:image/png;base64,<BASE64_DE_LA_IMAGEN>

• Nota: Las instrucciones deben enviarse como text dentro del mensaje del usuario, no como mensaje de sistema.

• Tokens totales (input + output): 8,192

• Tamaño máximo de la solicitud: 50 MB

• Dejar 1 MB libre en cada solicitud

• Resolución recomendada: 150–200 DPI para documentos sencillos; 300 DPI para imágenes con detalles pequeños.

Modelo:

Saptiva OCR

Body (URL)

{
    "model": "Saptiva OCR",
    "messages": [
        {"content": "Describe lo que encontraste en la imagen", "role": "system"},
        {"role": "user", "content": [
            {"type": "image_url", "image_url": 
                {"url": "https://drive.google.com/uc?export=download&id=1-EeTL10DJorpJsCnG5DCfS_7fx60pnGY"}
            }
        ]}
    ]
}

Respuesta (URL)

Body (Base64)

Respuesta (Base64)

---

Solicitudes (Modelo Embedding)

A continuación, se presenta el formato que debe tener el BODY, junto con el ejemplo de la respuesta esperada.

URL : https://api.saptiva.com/api/embed

POST /

Modelo:

Saptiva Embed

Body

{
  "model": "Saptiva Embed",
  "prompt": "Saptiva"
}

Respuesta

---

Respuestas

A continuación, se muestra un ejemplo de una respuesta exitosa y una de error.

Éxito

{
    "id": "chatcmpl-c1bf7e5c06b144fb9fc1f50b143633ba",
    "object": "chat.completion",
    "created": 1757647762,
    "model": "Saptiva Turbo",
    "system_fingerprint": "fp_saptiva",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "¡Hola! Soy Fer, tu agente servicial y siempre aquí para ayudarte. 😊  \nLa capital de México es **Ciudad de México**.  \n¿En qué más puedo ayudarte? 🌟",
                "reasoning_content": ""
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 35,
        "total_tokens": 81,
        "completion_tokens": 46
    }
}

Error

---

Errores

Para analizar y solucionar los errores a los que te puedes enfrentar al hacer uso de esta API, consulta nuestros códigos de errores junto con las soluciones que tenemos para ti.

Mejores Prácticas

• Proteja las credenciales: Nunca exponga tu API Key o tokens de autenticación en el código del lado del cliente. Utiliza variables de entorno o un backend seguro para manejar credenciales.

• Use HTTPS: Siempre realice solicitudes a la API a través de HTTPS para proteger la transmisión de datos.

• Verifique las respuestas de la API: Siempre maneje los códigos de estado HTTP correctamente (200, 400, 401, 422, 500, etc.).

• Gestione los tiempos de espera (timeouts): Establezca límites de tiempo adecuados para evitar que la aplicación se quede bloqueada en solicitudes prolongadas.

---

Ejemplos

cURL

curl --location 'https://api.saptiva.com/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TU_API_KEY>' \
--data '{
  "model": "Saptiva Turbo",
  "messages": [
    {
      "role": "system",
      "content": "Eres un agente servicial"
    },
    {
      "role": "user",
      "content": "¿Cuál es la capital de Francia?"
    }
  ],
  "max_tokens": 256,
  "temperature": 0.7,
  "top_p": 0.95
}'

Python

Javascript

---

Soporte

Para cualquier problema o pregunta técnica, comuníquese con el equipo de desarrollo.