Gestión de lotes
Envíe solicitudes masivas asíncronas e inspeccione el estado de ejecución por lotes.
Envíe solicitudes masivas asíncronas en los puntos de conexión admitidos mediante la API Batch compatible con OpenAI.
/openai/v1/batchesCuerpo de la solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
input_file_id | string | Sí | Identificador del archivo subido con el propósito establecido en batch. |
endpoint | string | Sí | Punto de conexión de destino (/v1/chat/completions, /v1/completions, /v1/responses o /v1/embeddings). |
completion_window | string | Sí | Ventana de finalización, fijada actualmente en 24h. |
metadata | object | No | Pares clave-valor opcionales para seguimiento. |
Los archivos de entrada deben ser JSONL en UTF-8 con un máximo de 50.000 elementos y hasta 200 MiB de tamaño. Cada línea debe ser un objeto JSON válido con un custom_id único no vacío, método POST, url coincidente con el endpoint del lote y un objeto body (con el campo model obligatorio para lotes de prepago nativos estrictos). Para lotes de prepago nativos, la pasarela valida la suma de comprobación del archivo y las políticas de ejecución de los elementos antes de la admisión; todas las retenciones de saldo se comprometen de forma atómica antes del envío al proveedor. Si los fondos totales son insuficientes, se devuelve HTTP 402 sin envíos parciales. Las configuraciones de proveedor incompatibles no pueden dividirse dentro del mismo lote y no se realiza conmutación por error entre proveedores a nivel de elemento.
Ciclo de vida del lote
/openai/v1/batches/{batch_id}/openai/v1/batches/{batch_id}/cancelvalidating: Comprueba el formato del archivo de entrada, la sintaxis JSONL y el cumplimiento del esquema.in_progress: Distribuye los elementos a las credenciales de proveedor asignadas sin conmutación por error entre proveedores.finalizing: Agrega las respuestas generadas y registra la liquidación de consumo.completed: Finaliza el procesamiento correctamente, generandooutput_file_idy elerror_file_idopcional.failed: Fallo terminal si la validación del archivo o la coordinación del lote fallan por completo.cancelling: Detiene el procesamiento a petición y pasa al estado cancelado.cancelled: Marca la ejecución del lote detenida antes de su finalización. Los resultados de elementos fallidos, cancelados o faltantes no demuestran un coste cero de proveedor; la liquidación retiene fondos para la conciliación con los registros del proveedor. El estado canónico en AnyInt escancelled.expired: Se activa cuando el procesamiento supera la ventana de 24 horas; las ejecuciones no confirmadas requieren conciliación con los registros del proveedor y no implican coste cero.
Operaciones de lotes y descarga de resultados
/openai/v1/batches- Listar lotes:
GET /openai/v1/batchesenumera las tareas por lotes activas e históricas para la organización o proyecto autorizado. - Almacenamiento de objetos y descarga: La admisión de archivos con propósito
batchy la ejecución de lotes requieren almacenamiento de objetos compartido (OBJECT_STORE_MODE). Una vez finalizado, los archivos JSONL de salida y errores se descargan medianteGET /openai/v1/files/{file_id}/content.
Alias de compatibilidad
- La pasarela acepta
/v1/batchespor compatibilidad. Use/openai/v1/batchespara nuevas integraciones.