이미 가진 소스를 제출하면 엔진이 바로 생성됩니다. POST /jobs/provisioning는 새 엔진의 이름과 최대 10개의 소스(크롤링할 링크 또는 원시 텍스트)를 받아 엔진 ID가 담긴 202 Accepted를 반환합니다. AI가 콘텐츠를 모두 읽을 때까지 기다릴 필요는 없습니다. 호출이 반환되는 순간 엔진이 생성되고, 작업이 진행되는 동안 구성이 차례로 적용됩니다.
POST /jobs/provisioning이 페이지에서는 생성 호출의 매개변수, 요청 형식, 그리고 202 응답을 설명합니다. 비동기 프로비저닝이 처음이라면 전체 흐름을 이해할 수 있도록 비동기 프로비저닝 API 개요부터 읽어보세요. 좋은 소스의 기준은 소스 유형에서, AI가 그 소스에서 무엇을 추출하는지는 AI가 추출하는 내용에서 다룹니다.
인증
X-API-Key 헤더에 API 키를 전달하세요. 키는 조직 단위로 범위가 적용되며 해당 조직의 모든 엔진에 접근할 수 있습니다. 자세한 내용은 인증을 참고하세요.
매개변수#
필수 항목은 engine.name뿐입니다. 그 외 항목은 엔진이 무엇을 학습할지 결정하며, 모두 생략하면 기본값이 적용된 비어 있는 엔진이 생성됩니다.
| 매개변수 | 유형 | 설명 |
|---|---|---|
engine.name | string | 새 로컬라이제이션 엔진의 이름입니다. |
engine.description | string (선택 사항) | 엔진에 대한 자유 형식 설명입니다. |
locales | string[] (선택 사항) | 구성할 BCP-47 대상 로캘입니다. 예: ["es", "ja", "de"]. |
sources | array (선택 사항) | 분석할 소스를 최대 10개까지 지정할 수 있습니다. 각 항목은 link(플랫폼이 크롤링하는 URL) 또는 content(원시 텍스트 또는 마크다운)입니다. 자세한 내용은 소스 유형을 참고하세요. |
callbackUrl | string (선택 사항) | 완료 결과를 받을 HTTPS 웹훅 URL입니다. HTTPS만 지원하며 HTTP 콜백 URL은 거부됩니다. 자세한 내용은 웹훅 전송을 참고하세요. |
요청#
소스는 { type, payload } 객체입니다. link 소스는 실제 맥락이 담긴 페이지(브랜드 가이드라인, 스타일 가이드, 제품 문서 등)를 가리키도록 하고, content는 바로 붙여 넣을 수 있는 용어 규칙과 톤 가이드에 활용하세요. 아래 요청 예시는 두 방식을 함께 사용합니다. 크롤링할 페이지 2개와 명시적인 규칙 블록 1개를 조합한 형태입니다.
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응답 (202 Accepted)#
이 호출은 크롤링이나 분석이 끝날 때까지 기다리지 않습니다. 대신 추적용 작업 ID와, 이 시점부터 바로 사용할 수 있는 엔진 ID를 반환합니다.
{
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"engineId": "eng_X1y2Z3a4B5c6D7e8",
"status": "in_progress"
}| 필드 | 설명 |
|---|---|
jobId | 프로비저닝 작업 ID(pjb_ 접두사)입니다. 실시간 진행 상황을 보려면 WebSocket을 연결해 작업을 추적하거나, 완료되면 웹훅으로 결과를 받을 수 있습니다. |
engineId | 새 엔진의 ID(eng_ 접두사)입니다. 즉시 사용할 수 있으며, AI가 추출한 구성은 작업이 진행되는 동안 이 엔진에 적용됩니다. |
status | 소스를 제공한 경우 in_progress, 제공하지 않은 경우 completed입니다(아래 참고). |
이 호출이 기다림 없이 비동기로 처리할 가치가 있는 이유는 engineId가 같은 202 응답으로 돌아오고, 그 즉시 실제 엔진을 가리키기 때문입니다. 이 ID를 저장해 두거나, 여기에 동기식 Localize 요청을 보내거나, AI가 소스를 하나도 읽기 전에 앱에 연결해 둘 수도 있습니다. 브랜드 보이스, 용어집 항목, 지침이 추출될 때마다 플랫폼은 그 결과를 같은 엔진에 순차적으로 적용합니다. 즉, 구성보다 엔진이 먼저 존재합니다. 작업이 정확히 무엇을 만들어냈는지 알고 싶다면 AI가 추출하는 내용을 확인하세요.
소스가 없어도 기다릴 필요는 없습니다.
sources를 생략하면 크롤링할 대상이 없으므로 엔진은 기본 모델 구성으로 생성되고, 같은 응답에서 status: "completed"와 함께 반환됩니다. 직접 구성할 비어 있는 엔진이 필요할 때 가장 빠른 경로입니다. 한 번의 호출로 바로 사용할 수 있는 engineId를 받고, 추적할 백그라운드 작업도 생기지 않습니다.
