Crear un trabajo de aprovisionamiento

Genera directrices para un motor nuevo o existente y guarda el ID del trabajo para consultar su progreso y recuperarlo si es necesario.

El aprovisionamiento se ejecuta en segundo plano y comienza cuando la API acepta la solicitud. Todas las rutas usan https://api.lingo.dev y autenticación de API.

Crear y completar un motor #

http
POST /v2/organizations/:orgId/provisioning/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
json
{
  "engine": { "name": "Acme support", "description": "Customer support content" },
  "kinds": {
    "glossary": { "name": "Product terminology" },
    "ruleset": { "name": "Support writing rules" },
    "brandVoice": { "name": "Support voice" }
  },
  "sources": [
    { "_tag": "Link", "url": "https://example.com/style-guide" },
    { "_tag": "Content", "text": "Use clear, direct sentences. Keep the product name Acme unchanged." }
  ]
}

Reemplaza la URL de ejemplo por la de una página accesible que contenga tus directrices, o proporciona texto en su lugar.

CampoContrato
engineObjeto obligatorio para crear el motor. name no puede estar vacío; description es opcional. También puede incluir configuraciones de modelos, cobertura y configuración del flujo de procesamiento.
kindsObjeto obligatorio que selecciona al menos uno de los siguientes elementos: glossary, ruleset o brandVoice. Cada valor seleccionado es {} o { "name": "Nonempty name" }.
sourcesArreglo obligatorio que no puede estar vacío, con un máximo de diez enlaces o fuentes de texto.

La configuración del motor sigue el contrato de creación del motor. sourceCoverage y targetCoverage son arreglos de idiomas, y [] abarca todos los idiomas. Si omites modelConfigs, se cargan los valores predeterminados de modelos de la plataforma; [] deja el motor sin configuraciones de modelos fijadas. Configura los modelos del motor antes de usarlo para traducir.

Quien realiza la llamada necesita permiso para crear motores y las directrices solicitadas. La cantidad de motores, las funciones del plan, el crédito de la cuenta y los límites de frecuencia de aprovisionamiento pueden hacer que se rechace la solicitud.

Completar un motor existente #

http
POST /v2/engines/:engineId/provisioning/jobs
Content-Type: application/json

Para completar solo los tipos que aún no tienen un conjunto asociado al motor:

json
{
  "kinds": { "_tag": "Empty" },
  "sources": [{ "_tag": "Content", "text": "Keep Acme unchanged. Use concise, friendly language." }]
}

Para solicitar nuevos conjuntos específicos:

json
{
  "kinds": {
    "_tag": "Requested",
    "glossary": { "name": "Support terminology" },
    "ruleset": {}
  },
  "sources": [{ "_tag": "Link", "url": "https://example.com/support" }]
}

Requested puede agregar un glosario o un conjunto de reglas además de los existentes. El aprovisionamiento nunca reemplaza una voz de marca asociada. Empty omite los tipos que ya tienen conjuntos asociados, incluidos los que se asocien mientras se ejecuta el trabajo. Revisa los resultados por tipo en lugar de dar por hecho que cada solicitud crea los tres tipos.

Solo puede ejecutarse un trabajo de aprovisionamiento a la vez en cada motor. ProvisioningJobRunning (409) incluye el jobId existente; consulta su progreso antes de enviar más trabajo. NothingToProvision (409) significa que nada de lo solicitado puede completar el motor en su estado actual.

Guardar la respuesta #

Ambas rutas de creación devuelven HTTP 200 con un trabajo de aprovisionamiento. Guarda id y engineId antes de empezar a consultar el estado periódicamente. El estado inicial suele ser status: { "_tag": "Running" }.

La creación no declara un encabezado de idempotencia. Si se pierde una respuesta, revisa los trabajos en ejecución y la lista de motores antes de repetir una solicitud para crear un motor, ya que podría crear otro. Recuperación explica estas comprobaciones y cómo reintentar los tipos que fallaron.