Añadir solicitudes en JSON
En esta página
Actualizado el 2 de noviembre de 2026 según la documentación de xAI: el descuento por lotes es del 20 % en modelos de texto elegibles (no del 50 %); los ejemplos siguen la API REST y el
xai-sdkoficial (client.batch.*; la API de lotes de xAI no usa el formato de OpenAI, por lo que el SDK de OpenAI no aplica), y la API de Responses tiene prioridad sobre Chat Completions, un endpoint heredado en xAI. Fuentes: Batch API · Referencia REST · Precios de lotes.
Añadir mediante la API
Una vez creado el lote, añades solicitudes con POST /v1/batches/{batch_id}/requests. Cada llamada transporta una lista de solicitudes y puedes invocar el endpoint tantas veces como necesites mientras el lote no esté cancelado. Este enfoque funciona para lotes construidos de forma incremental.
Estructura de la solicitud
El cuerpo de la llamada contiene un array batch_requests. Cada elemento empareja un identificador (batch_request_id) con la solicitud en sí, almacenada bajo la clave correspondiente a su tipo: responses para la API de Responses:
{
"batch_requests": [
{
"batch_request_id": "avis-001",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Clasifica el sentimiento: positivo, negativo o neutro."},
{"role": "user", "content": "¡El producto superó mis expectativas!"}
]
}
}
}
]
}
batch_request_id: Tu identificador, único dentro del lote. Esta es la clave que vincula la solicitud con su resultado; si falta, xAI genera un UUID.batch_request: La solicitud, bajo la clave de su tipo; la referencia de la API documenta tambiénchat_get_completionpara el formato de Chat Completions.
Para imágenes y vídeos, usa el SDK (lección 9) o un archivo JSONL (siguiente lección).
Solicitud cURL
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batch_requests": [
{
"batch_request_id": "article-42",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "user", "content": "Clasifica este texto: positivo, neutro o negativo."}
]
}
}
}
]
}'
Añadir con el SDK de Python
Con el SDK, cada solicitud se construye como una conversación estándar, se le asigna un batch_request_id y luego se añaden en fragmentos:
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client()
documents = [
{"id": "doc-1", "text": "Primer documento a analizar..."},
{"id": "doc-2", "text": "Segundo documento a analizar..."},
{"id": "doc-3", "text": "Tercer documento a analizar..."},
]
batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"
requests = []
for doc in documents:
chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
chat.append(system("Resume el documento en dos frases."))
chat.append(user(doc["text"]))
requests.append(chat)
# Añadir en fragmentos de 100: una llamada a la API por fragmento
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
La documentación no establece un número máximo de solicitudes por llamada; unos tamaños de fragmento moderados limitan simplemente lo que hay que reenviar en caso de incidente de red.
Límites de tasa al añadir
Un equipo puede realizar hasta 1.000 llamadas de añadido cada 30 segundos, en una ventana deslizante compartida entre todos sus lotes. El límite se aplica a las llamadas, no a las solicitudes: con fragmentos de 100 solicitudes, esto ya permite más de 3.000 solicitudes por segundo. Otros dos límites son más relevantes:
- 25 MB máximo por solicitud individual, lo cual afecta principalmente a imágenes codificadas en base64.
- Más allá de 100.000 solicitudes en un lote, xAI puede ralentizar el procesamiento para preservar la estabilidad del servicio.
Cuándo usar el añadido por API
El añadido por API funciona siempre que la flexibilidad importe más que la preparación inicial. Se convierte en la opción natural cuando el lote se construye de forma incremental: las solicitudes que llegan desde una cola se añaden según van entrando, mientras que un archivo JSONL exigiría conocerlo todo de antemano —y cerraría el lote—. Es también la vía para la prototipia, para probar el flujo completo con cinco solicitudes antes de escalar, y para lotes heterogéneos.
Validación de solicitudes
Comprueba el código de estado de cada llamada de añadido: un error en esta fase significa que el fragmento no se guardó y debes reenviarlo. Una solicitud también puede fallar más tarde, durante el procesamiento; entonces aparece en los resultados con su mensaje de error. Un modelo que no acepta el lote se rechaza con el mensaje not supported for batch processing: verifica la elegibilidad en la página del modelo antes de lanzar un lote grande.
Puntos clave
- El añadido se realiza mediante
POST /v1/batches/{id}/requests, con una listabatch_requests. - Cada solicitud lleva un
batch_request_idúnico y su contenido bajo la clave de su tipo (responses,chat_get_completion). - El SDK construye solicitudes con
client.chat.create(..., batch_request_id=...)y las añade conclient.batch.add. - El límite es de 1.000 llamadas de añadido cada 30 segundos para el equipo; cada llamada puede transportar muchas solicitudes.
- A diferencia del archivo JSONL, el añadido por API mantiene el lote abierto a nuevas incorporaciones.