手元にあるソースを送れば、すぐにエンジンが返ってきます。POST /jobs/provisioning には新しいエンジン名と最大 10 件のソース（クロール対象のリンクまたは生テキスト）を渡し、レスポンスとしてエンジンIDを含む 202 Accepted を受け取ります。AI がコンテンツを読み終えるまで待つ必要はありません。呼び出しが返った瞬間にエンジンは作成されており、設定はジョブの進行に合わせて反映されます。
POST /jobs/provisioningこのページでは、作成リクエストのパラメータ、リクエスト形式、そして 202 レスポンスを扱います。非同期プロビジョニングが初めてなら、まずは Async Provisioning API overview で全体像をつかんでください。良いソースの条件は Source types、そこから AI が何を抽出するかは What the AI extracts で説明しています。
認証
API キーは X-API-Key ヘッダーで渡します。キーは組織スコープで、組織内のすべてのエンジンにアクセスできます。詳しくは Authentication をご覧ください。
パラメータ#
必須なのは engine.name だけです。それ以外はエンジンが何を学習するかを決める項目で、すべて省略すればデフォルト設定のままのクリーンなエンジンが作成されます。
| パラメータ | 型 | 説明 |
|---|---|---|
engine.name | string | 新しいローカライゼーションエンジンの名前。 |
engine.description | string（任意） | エンジンの説明を自由記述で指定します。 |
locales | string[]（任意） | 設定対象となる BCP-47 のターゲットロケール。例: ["es", "ja", "de"]。 |
sources | array（任意） | 解析対象のソースを最大 10 件まで指定できます。各ソースは link（プラットフォームがクロールする URL）または content（生テキストまたは markdown）です。詳しくは Source types を参照してください。 |
callbackUrl | string（任意） | 完了結果の受信用 HTTPS webhook URL。HTTPS のみ対応しており、HTTP のコールバック URL は拒否されます。詳しくは Webhook delivery を参照してください。 |
リクエスト#
ソースは { 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_ プレフィックス）。進行状況は connecting a WebSocket でリアルタイムに追跡でき、完了時には webhook で結果を受け取ることもできます。 |
engineId | 新しいエンジンのID（eng_ プレフィックス）。すぐに利用でき、AI が抽出した設定はジョブの進行中にこのエンジンへ反映されます。 |
status | ソースを指定した場合は in_progress、指定しない場合は completed です（下記参照）。 |
この非同期呼び出しの価値は、待たされないことにあります。engineId は同じ 202 の中で返され、その時点ですぐに使える実体のあるエンジンを指します。保存しておくことも、これを通して synchronous Localize リクエストを送ることも、AI がソースを 1 つも読み終えていない段階でアプリに組み込むこともできます。ブランドボイス、用語集項目、指示が抽出されるたびに、プラットフォームはそれらを同じエンジンへ順次反映していきます。つまり、設定が揃う前からエンジン自体は存在しています。ジョブによって実際に何が作成されるのかを正確に知りたい場合は、What the AI extracts をご覧ください。
ソースがなくても、待たずにエンジンを受け取れます。
sources を省略するとクロール対象がないため、エンジンはデフォルトのモデル設定で作成され、同じレスポンス内で status: "completed" と一緒に返されます。自分で設定する空のエンジンが欲しいときは、これが最短ルートです。1 回の呼び出しで、すぐ使える engineId が手に入り、追跡すべきバックグラウンドジョブも発生しません。
