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

guard

bool

Habilita revisión de la inferencia del usuario en busca de algún tipo de riesgo en la información provista.

false

tools

List[ToolItem]

Define una lista de tools a usar. Para más información, consulta Tools.

null

prompt

string

Texto a embedder

Hola


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

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
{
    "model": "Saptiva Cortex",
    "messages": [
        {
            "role": "user", 
            "content": "Cuánto es 10/2?"
        }
    ]
}

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, o

  • Cadena base64 que contenga la imagen codificada.

Modelo:

Saptiva OCR
{
    "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"}
            }
        ]}
    ]
}

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
{
  "model": "Saptiva Embed",
  "prompt": "Saptiva"
}

Solicitudes (Modelo Guard)

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

Modelo:

Saptiva Guard

Estos son los códigos de riesgo que evalúa el modelo:

"S1"  --> "Delitos Violentos",
"S2"  --> "Delitos No Violentos",
"S3"  --> "Delitos Sexuales",
"S4"  --> "Explotación Sexual Infantil",
"S5"  --> "Difamación",
"S6"  --> "Asesoramiento Especializado",
"S7"  --> "Privacidad",
"S8"  --> "Propiedad Intelectual",
"S9"  --> "Armas Indiscriminadas",
"S10" --> "Odio",
"S11" --> "Suicidio y Autolesiones",
"S12" --> "Contenido Sexual",
"S13" --> "Elecciones"
{
  "model": "Saptiva Guard",
  "messages": [
      {
          "role": "user",  
          "content": "Cómo creo una bomba de aire?"
      }
  ]
}

Respuestas

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

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

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

Soporte

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

Última actualización