Crear un trabajo de aprovisionamiento

Envía las fuentes que ya tienes y recibe un motor a cambio. POST /jobs/provisioning acepta un nombre para un motor nuevo y hasta 10 fuentes —enlaces para rastrear o texto sin procesar— y devuelve 202 Accepted con el ID del motor. No tienes que esperar a que la IA termine de leer tu contenido: el motor existe en cuanto la llamada devuelve la respuesta, y su configuración se va aplicando mientras se ejecuta el trabajo.

text

POST /jobs/provisioning

Esta página cubre la llamada de creación: sus parámetros, el formato de la solicitud y la respuesta 202. ¿Es la primera vez que usas el aprovisionamiento asíncrono? Empieza por la Descripción general de la API de aprovisionamiento asíncrono para hacerte una idea del funcionamiento. Qué se considera una buena fuente tiene su propia página: Tipos de fuente. Y lo que la IA extrae de ellas se explica en Qué extrae la IA.

Autenticación

Pasa tu clave de API en la cabecera X-API-Key. Las claves tienen alcance de organización y dan acceso a todos los motores de la organización. Consulta Autenticación para obtener más información.

Parámetros#

Solo engine.name es obligatorio. Todo lo demás define lo que aprende el motor o, si no incluyes nada más, te deja con un motor limpio con la configuración predeterminada.

Parámetro	Tipo	Descripción
`engine.name`	string	Nombre del nuevo motor de localización.
`engine.description`	string (opcional)	Descripción en texto libre del motor.
`locales`	string[] (opcional)	Idiomas de destino en formato BCP-47 para configurar, por ejemplo, `["es", "ja", "de"]`.
`sources`	array (opcional)	Hasta 10 fuentes para analizar. Cada una puede ser `link` (una URL que la plataforma rastrea) o `content` (texto sin procesar o markdown). Consulta Tipos de fuente.
`callbackUrl`	string (opcional)	URL HTTPS del webhook para recibir el resultado al completarse. Solo HTTPS: las URL de callback HTTP se rechazan. Consulta Entrega de webhooks.

Solicitud#

Una fuente es un objeto { type, payload }. Apunta las fuentes link a páginas con contexto real —guías de marca, guías de estilo, documentación del producto— y usa content para terminología y reglas de tono que puedas pegar directamente. La solicitud de ejemplo que aparece a continuación combina ambas: dos páginas para rastrear y un bloque de reglas explícitas.

javascript

const response = await fetch("https://api.lingo.dev/jobs/provisioning", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.LINGO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    engine: {
      name: "Acme Corp Engine",
      description: "Production localization engine for acme.com",
    },
    locales: ["de", "fr", "ja", "es"],
    sources: [
      { type: "link", payload: "https://acme.com/brand-guidelines" },
      { type: "link", payload: "https://acme.com/docs/style-guide" },
      {
        type: "content",
        payload:
          "Brand name 'Acme' is never translated. Use formal tone in German (Sie-form). Product names: AcmeFlow, AcmeSync, AcmeVault - always keep in English.",
      },
    ],
    callbackUrl: "https://your-app.com/webhooks/provisioning",
  }),
});

const { jobId, engineId, status } = await response.json();
// 202 back right away.
// status: "in_progress" – the AI is reading your sources.
console.log(engineId); // "eng_X1y2Z3a4B5c6D7e8" – usable right now

Respuesta (202 Accepted)#

La llamada devuelve la respuesta sin esperar al rastreo ni al análisis: te entrega un ID de trabajo para hacer seguimiento y un ID de motor que está activo desde ese mismo momento.

json

{
  "jobId": "pjb_A1b2C3d4E5f6G7h8",
  "engineId": "eng_X1y2Z3a4B5c6D7e8",
  "status": "in_progress"
}

Campo	Descripción
`jobId`	ID del trabajo de aprovisionamiento (prefijo `pjb_`). Haz seguimiento del trabajo conectando un WebSocket para ver el progreso en tiempo real, o recibe el resultado en tu webhook cuando termine.
`engineId`	ID del nuevo motor (prefijo `eng_`). Se puede usar de inmediato: la configuración que la IA extrae se le aplica mientras se ejecuta el trabajo.
`status`	`in_progress` cuando proporcionas fuentes; `completed` cuando no lo haces (ver más abajo).

El detalle que hace que merezca la pena usar esta llamada asíncrona, en lugar de esperar, es este: engineId vuelve en el mismo 202 y apunta desde el primer momento a un motor real. Puedes guardarlo, enviar a través de él una solicitud de Localize síncrona o integrarlo en tu aplicación antes de que la IA haya terminado de leer una sola fuente. A medida que se extraen voces de marca, elementos del glosario e instrucciones, la plataforma aplica cada uno al mismo motor: el motor existe antes que su configuración. Para saber exactamente qué ha creado el trabajo, consulta Qué extrae la IA.

¿Sin fuentes? Obtienes un motor, no una espera.

Omite sources y no habrá nada que rastrear, así que el motor se crea con la configuración predeterminada del modelo y se devuelve con status: "completed" en la misma respuesta. Es la vía rápida cuando quieres un motor vacío para configurarlo tú mismo: una llamada, un engineId listo, sin ningún trabajo en segundo plano que seguir.

Siguientes pasos#

Tipos de fuente

Fuentes de enlace frente a fuentes de contenido, y qué hace que una fuente merezca la pena analizarse.

Qué extrae la IA

Voces de marca, elementos del glosario e instrucciones, además del resumen que devuelve el trabajo.

Entrega de webhooks

Recibe el resultado final en tu URL de callback y verifica la firma.