Una tarea sobre 100.000 ítems
Algunos trabajos no son complicados, simplemente son enormes. La API de Procesamiento en Lote aplica una definición de tarea a hasta 100.000 ítems en un solo envío, así un catálogo, una lista de correos o un archivo de documentos se procesa como un solo trabajo en lugar de decenas de miles de solicitudes individuales.
El problema de la escala, no de la complejidad
Traducir la descripción de un producto es trivial; traducir 80.000 una por una significa manejar 80.000 task_ids, 80.000 webhooks y una estrategia de reintentos que tiene que construir usted mismo, además de llevar la cuenta de cuáles de esas 80.000 realmente terminaron. La tarea en sí no se volvió más difícil, solo más grande. POST /flow/batch está hecho exactamente para ese tipo de problema: una tarea, aplicada de forma uniforme, a gran volumen, con esa contabilidad resuelta del lado del servidor y no en su propia base de datos.
Cómo se estructura un lote
Envía un tipo de tarea, sus parámetros compartidos y una lista de ítems —hasta 100.000— cada uno con los datos particulares que la tarea necesita, como una fila de texto por traducir o la referencia de un archivo por transcribir. El lote se ejecuta en nuestra red perimetral global, procesando ítems de forma concurrente en vez de uno tras otro, lo que evita que un trabajo de 100.000 ítems tarde 100.000 veces más que uno solo, así que crecer la lista no se traduce directamente en crecer el tiempo de espera.
Un task_id, un conjunto de resultados
Todo el lote se rastrea bajo un único task_id desde el envío hasta la finalización. Al terminar, obtiene un solo resultado estructurado que cubre cada ítem, entregado por webhook firmado o mediante un enlace firmado válido por 24 horas, así no tiene que armar usted mismo miles de callbacks separados, y su código de integración solo necesita entender una forma de respuesta sin importar si el lote tenía diez ítems o cien mil.
Cómo se manejan los fallos por ítem
Los ítems individuales pueden fallar sin tumbar todo el lote: cada ítem con fallo recibe hasta tres reintentos propios, y el resultado final marca con precisión cuáles ítems tuvieron éxito y cuáles no, con errores claros por ítem que describen qué salió mal. Como en toda tarea del KIT, los ítems fallidos nunca se cobran, solo se paga el procesamiento exitoso, así que un puñado de filas mal formadas en un archivo por lo demás limpio no le cuesta nada más allá del tiempo de corregirlas y reenviarlas.
Por qué lote y no simplemente fan-out
El fan-out paralelo es para un puñado de pasos distintos y de forma diferente entre sí; el lote es para una misma operación repetida sobre una lista grande y uniforme. El precio refleja eso: el lote cuesta $0.002 por solicitud, cubriendo la orquestación de todo el conjunto, además de lo que cueste la tarea de base por cada ítem.
Qué puede hacer con ella
Traducción de catálogo de productos
Traduzca decenas de miles de títulos y descripciones de productos al idioma de un nuevo mercado en un solo trabajo por lote en vez de una solicitud por cada SKU.
Transcripción de un rezago de tickets de soporte
Transcriba de una vez un archivo grande de llamadas de soporte grabadas, recibiendo un solo conjunto de resultados consolidado en lugar de gestionar cada llamada por separado.
OCR masivo de documentos
Ejecute OCR sobre un archivo escaneado de decenas de miles de páginas en un solo trabajo, con resultados y reporte de errores por página.
Validación de listas de correo
Valide una lista grande de suscriptores en un solo lote en vez de recorrer solicitudes de verificación individuales fila por fila.
Preguntas frecuentes
¿Cuántos ítems puede procesar un solo lote?
Hasta 100.000 ítems por envío a POST /flow/batch, todos compartiendo el mismo tipo de tarea y procesados como un solo trabajo.
¿El procesamiento en lote es gratis?
No hay capa gratuita: las capas gratis se abusan y ralentizan a todos. El acceso funciona con un saldo prepago de ForHosting KIT: se recarga desde $10.00 (no caduca) y cada solicitud se cobra a su precio publicado, así que una llamada sin saldo devuelve HTTP 402. Sin suscripción, sin tokens ni créditos inventados, y una tarea fallida no se cobra.
¿Qué pasa si algunos ítems del lote fallan?
Cada ítem con fallo se reintenta hasta tres veces de forma independiente, y el resultado final indica con exactitud qué ítems tuvieron éxito y cuáles fallaron, sin cobro por los ítems fallidos.
¿Todos los ítems de un lote deben usar el mismo tipo de tarea?
Sí, un lote aplica una definición de tarea de forma uniforme a cada ítem; para mezclar distintos tipos de tarea en un mismo trabajo están las tareas de encadenamiento o fan-out.
¿Cuánto tarda un lote grande?
Los ítems se procesan de forma concurrente y no secuencial, así que el tiempo total depende del tipo de tarea y la carga en el momento del envío, no crece linealmente con la cantidad de ítems.
¿Cómo obtengo los resultados de un lote de 100.000 ítems?
El lote completado entrega un solo conjunto de resultados estructurado, ya sea mediante un webhook firmado apenas termina o un enlace firmado válido por 24 horas.
¿El procesamiento en lote es lo mismo que llamar la misma tarea 100.000 veces?
Funcionalmente sí, pero operativamente no: el lote rastrea todo bajo un único task_id y un solo resultado en vez de 100.000 task_ids y callbacks separados que tendría que gestionar.
¿Puedo ejecutar un lote de forma recurrente y programada?
Sí, una tarea en lote puede activarse mediante la API de tareas programadas, así un trabajo masivo recurrente —como una sincronización nocturna de catálogo— corre automáticamente sin envío manual.
Para desarrolladores — acceso por API
Todo lo de esta página está disponible por programación. Esta sección es para equipos que quieren integrarlo en sus sistemas; el resto puede usar la herramienta de arriba sin más.
Endpoint de API
¿Prefiere automatizarlo? Un POST autenticado crea la tarea; el resultado llega por webhook o enlace firmado. La misma capacidad también se ejecuta aquí en la web, y pronto desde nuestra app, el email y Telegram.
Llámela desde su stack
curl -X POST https://api.kit.forhosting.com/flow/batch \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"items":["valor-1","valor-2"]}'const res = await fetch("https://api.kit.forhosting.com/flow/batch", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"items": [
"valor-1",
"valor-2"
]
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/flow/batch",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"items": [
"valor-1",
"valor-2"
]
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/flow/batch", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"items":["valor-1","valor-2"]}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"items":["valor-1","valor-2"]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/flow/batch", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Ejemplo de solicitud
{
"items": [
"valor-1",
"valor-2"
]
}Ejemplo de respuesta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "flow.batch",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}La API es asíncrona: la llamada devuelve un task_id al instante y el resultado llega por webhook. El polling está limitado a 1 req/s por tarea.
Precio
Precio publicado — sin tokens ni créditos inventados. Una tarea fallida no se cobra.
Errores
| HTTP | Código | Significado |
|---|---|---|
401 | unauthorized | API key ausente o inválida. |
402 | insufficient_balance | El saldo no cubre el precio de la tarea. |
404 | unknown_type | El tipo de tarea no existe. |
429 | rate_limited | Demasiadas peticiones. Use el webhook en vez de sondear. |